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:

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.