Darb Delivery

Darb is a delivery marketplace in Oman. This plugin connects your WordPress site
to it: you hand Darb a customer and a destination, Darb prices the delivery,
charges your Darb credit and assigns a courier.

It does not need WooCommerce. Deliveries can start from three places:

• A front-end form. Put [darb_delivery_form] on a page and customers can
  request a delivery themselves.
• The admin. Darb Delivery → New delivery — for orders taken by phone,
  WhatsApp or over the counter.
• Your own code. Call darb_send_delivery() from a theme, a form plugin, or
  any other integration.

Every request is written down locally before it is sent, so an order Darb
rejected — or one that never reached Darb at all — is visible under
Darb Delivery → Deliveries instead of disappearing.

Already selling with WooCommerce? Install Darb Delivery for WooCommerce
instead, which pushes orders automatically as their status changes. The two
plugins are designed to run side by side if you need both.

Where the delivery goes

Darb needs a map pin, not a street address. If the request carries a Google Maps
link the courier is dispatched straight away. Without one, Darb texts the
customer a link and asks them to share their location — the delivery waits until
they do. The wilaya is used in the meantime for the delivery-zone check, so set
a default under Settings even if you collect map links.

The wilaya is chosen from a list of the sixty wilayat Darb recognises, never
typed. Darb matches its delivery zones on the Arabic name, so a customer typing
“Al Seeb” or misspelling a wilaya would have had their delivery refused for a
reason nobody could see. Deliveries sent from code may use either spelling —
“Seeb”, “As Seeb” and “Al Seeb” all resolve to السيب — and anything
unrecognised is passed through for Darb itself to judge.

Sending from your own code

$result = darb_send_delivery( array(
    'name'        => 'Ahmed',
    'phone'       => '91234567',
    'wilaya'      => 'السيب',
    'maps_url'    => 'https://www.google.com/maps?q=23.6100,58.5450',  // optional
    'notes'       => 'Villa 5, second gate',
    'description' => 'Two cakes',
    'value'       => 12.500,                          // value of the goods
) );

if ( ! $result['sent'] ) {
    error_log( 'Darb: ' . $result['message'] );
}

Accepted keys: name, phone (required), wilaya, maps_url, notes,
description, value, items, external_ref.

items is an array of `array( 'name' => ..., 'qty' => ..., 'price' => ... )`.

When every item carries a price, the goods value is worked out for you.

To adjust the request just before it is signed — for example to add exact
coordinates your site already knows:

add_filter( 'darb_wp_delivery_payload', function ( $payload, $record ) {
    $payload['dropoff']['lat'] = 23.6100;
    $payload['dropoff']['lng'] = 58.5450;
    return $payload;
}, 10, 2 );

Wiring up a form plugin

Any form plugin that fires an action on submit can feed Darb. With Contact
Form 7, for instance:

add_action( 'wpcf7_mail_sent', function ( $form ) {
    $data = WPCF7_Submission::get_instance()->get_posted_data();
    darb_send_delivery( array(
        'name'  => $data['your-name'],
        'phone' => $data['your-phone'],
        'notes' => $data['your-address'],
    ) );
} );

External services

This plugin connects to the Darb delivery marketplace to create delivery
orders. Sending deliveries to Darb is what the plugin is for, so it cannot work
without contacting the service.

Only when you send a delivery — from the form after you approve it, from the
admin, or from your own code — does the plugin transmit to Darb’s API the
details needed to fulfil it: the customer’s name and phone number, the delivery
wilaya and, if provided, a map location or Google Maps link, order notes, and
item descriptions and values. Each request is signed with the secret key Darb
issued you. Nothing is sent until you enter your credentials, and the plugin
does not track usage or contact any other service.

• Service: Darb delivery marketplace — https://darbarise.com/
• API endpoint: https://us-central1-darb-42eca.cloudfunctions.net/shopApi
  (test mode uses https://us-central1-darbdev.cloudfunctions.net/shopApi)
• Terms of Service: https://darbarise.com/terms-of-use/
• Privacy Policy: https://darbarise.com/privacy-policy/

1. Upload the darb-delivery folder to /wp-content/plugins/, or install the
   zip from Plugins → Add New → Upload Plugin.
2. Activate it.
3. Go to Darb Delivery → Settings and enter the Shop ID and secret key Darb
   issued you. Leave Environment on Test to begin with.
4. Press Test connection. It verifies the credentials without creating a
   delivery or spending credit.
5. Tick Send orders to Darb, then create one delivery from
   Darb Delivery → New delivery and confirm it appears in your Darb account.
6. Switch Environment to Production when you are satisfied. Nothing else
   in the setup changes — but the credentials do, so enter the production pair.

Does this need WooCommerce?

No. Use Darb Delivery for WooCommerce if you want WooCommerce orders pushed
automatically; this plugin is for everything else.

Is the front-end form safe to make public?

Every delivery sent to Darb is charged to your Darb credit, so an open form is a
way to spend money. The form ships switched off, and when you switch it on it
holds requests for review by default — nothing reaches Darb until you press
Send to Darb. Choose Send to Darb immediately only if you understand that
each submission bills you.

The form also carries a nonce, a honeypot, a minimum fill-in time and a limit of
five submissions per IP address every ten minutes. Those raise the cost of abuse
but do not remove it; review mode is what actually protects the credit.

Logged-in administrators are exempt from the limit and the timing check, so
testing your own form does not lock you out of it.

My customers share one IP address and keep getting blocked

That happens with office networks and with mobile carriers, which put many
customers behind a single address. Raise the cap:

add_filter( 'darb_wp_form_max_per_ip', function () { return 30; } );

Return 0 to switch the limit off. darb_wp_form_rate_window changes the
window, in seconds.

Where is my secret key stored?

In the WordPress options table, like every other plugin setting. It is never
printed back into the settings page and never sent to Darb — it only signs
requests. Anyone with administrator access or database access can read it, so
treat it as you would a payment gateway key, and ask Darb to rotate it if a site
is compromised.

A delivery says “Failed”. What now?

The reason is shown next to it. Fix what it names — most often a missing phone
number, an unrecognised wilaya, or Darb credit that has run out — and press
Send to Darb again. Nothing is charged for a failed attempt.

Can I cancel a delivery from here?

No. Once Darb has accepted an order, cancel it in Darb. Trashing the local
record only removes your copy; the courier is still on the way.

Why does the same delivery not send twice?

Each record carries a reference that is unique to it, and Darb treats a repeat
of that reference as the same order. Pressing Send to Darb twice cannot
create two deliveries or charge you twice.

1.0.0

• First release: front-end request form, manual entry, darb_send_delivery(),
  signed (HMAC) requests, connection test, local record of every request.