=== Darb Delivery ===
Contributors: sulimanalsalmi
Tags: delivery, courier, oman, logistics, shipping
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send delivery orders from any WordPress site to the Darb delivery marketplace. No WooCommerce required.

== Description ==

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/

== Installation ==

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.

== Frequently Asked Questions ==

= 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.

== Screenshots ==

1. The deliveries list, showing what was sent and what failed.
2. Creating a delivery by hand.
3. Settings, with the connection test.

== Changelog ==

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