darb_delivery

Client for the Darb delivery marketplace in Oman. Hand Darb a customer and a destination; Darb prices the delivery, charges your Darb credit and assigns a courier.

Pure Dart — works in a Flutter app, a Dart backend, or a CLI.

Install

dependencies:
  darb_delivery: ^0.1.0

Use

import 'package:darb_delivery/darb_delivery.dart';

final darb = DarbClient(
  shopId: 'your shop id',          // issued by Darb
  auth: HmacAuth('your secret key'),
  environment: DarbEnvironment.test,
);

final result = await darb.createDelivery(DeliveryRequest(
  externalOrderId: 'POS-1042',      // your id — also the idempotency key
  customerName: 'أحمد',
  customerPhone: '91234567',
  dropoff: Dropoff.wilayaOnly('السيب'),
  items: [OrderItem(name: 'كعكة', qty: 1, price: 8.5)],
  notes: 'فيلا ٥، الخوض',
));

print(result.orderId);        // sapi_…
print(result.status);         // pending | awaiting_location
print(result.deliveryPrice);  // 1.5 (OMR)

Where the delivery goes

Give Darb as much as you have:

You provide Order status What happens
Dropoff.coordinates(lat:, lng:) or Dropoff.mapsUrl(…) pending Courier dispatched immediately
Dropoff.wilayaOnly('السيب') or nothing awaiting_location Darb messages the customer for their pin, then dispatches

Use the Arabic wilaya name — that is what Darb's delivery zones match on.

Errors

Every refusal is a DarbApiException with a stable code. Switch on the code, show messageAr to people, log requestId for support.

try {
  await darb.createDelivery(request);
} on DarbApiException catch (e) {
  switch (e.code) {
    case DarbErrorCode.insufficientCredit: // top up
    case DarbErrorCode.outOfZone:          // Darb does not deliver there
    case DarbErrorCode.validationError:    // e.fields names what is wrong
    default:
      if (e.isRetryable) { /* try again later */ }
  }
} on DarbTransportException catch (e) {
  // Darb could not be reached.
}

A bad DeliveryRequest throws ArgumentError from its constructor, naming the field, before anything is sent. The limits match the server's exactly.

Safe to retry

externalOrderId is the idempotency key. Send the same one twice and Darb returns the original order with result.duplicate == true — nothing is created or charged again. A retry after a timeout is always safe.

Checking credentials

await darb.testConnection(); // throws if the shop id or key is wrong

Creates nothing and charges nothing.

Production

DarbClient(…, environment: DarbEnvironment.production)

Production credentials are issued separately from test ones.

Getting credentials

Ask Darb. You receive a shop id, a secret key (for HmacAuth, recommended) and an API key (for ApiKeyAuth, only if enabled for your shop). The secret key signs every request and never leaves your process.

Libraries

darb_delivery
Client for the Darb delivery marketplace (Oman).