@mitumbadotafrica/logistics 0.0.0-stage → 0.0.0

package/dist/index.cjs

@@ -0,0 +1,221 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  HttpClient: () => HttpClient,
+  LogisticsError: () => LogisticsError,
+  MitumbaLogistics: () => MitumbaLogistics,
+  pollParcel: () => pollParcel
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var LogisticsError = class extends Error {
+  constructor(status, body) {
+    super(body.message ?? body.error);
+    this.name = "LogisticsError";
+    this.code = body.error;
+    this.status = status;
+    this.details = body.details;
+    this.reason = body.reason;
+  }
+  /** True for a temporary backend condition (503), e.g. no carriers configured. */
+  get isTemporary() {
+    return this.status === 503;
+  }
+};
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://api.mitumba.africa";
+
+// src/http.ts
+var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET"]);
+var HttpClient = class {
+  constructor(config = {}) {
+    this.baseUrl = stripTrailingSlashes(config.baseUrl ?? DEFAULT_BASE_URL);
+    this.maxRetries = config.maxRetries ?? 3;
+    this.fetchImpl = config.fetch ?? globalThis.fetch;
+    this.debug = config.debug ?? false;
+    this.tokenSource = config.token;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error(
+        "No fetch implementation available. Provide `fetch` in the config for this runtime."
+      );
+    }
+  }
+  async resolveToken() {
+    if (typeof this.tokenSource === "function") return this.tokenSource();
+    return this.tokenSource;
+  }
+  async get(path, options) {
+    return this.request("GET", path, void 0, options);
+  }
+  async post(path, body, options) {
+    return this.request("POST", path, body, options);
+  }
+  async request(method, path, body, options) {
+    const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    const token = options?.token ?? await this.resolveToken();
+    const headers = new Headers();
+    if (body !== void 0) headers.set("Content-Type", "application/json");
+    if (token) headers.set("Authorization", `Bearer ${token}`);
+    const init = {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal: options?.signal
+    };
+    const canRetry = RETRYABLE_METHODS.has(method);
+    let attempt = 0;
+    let response;
+    for (; ; ) {
+      if (this.debug) console.log(`[mitumba-logistics] ${method} ${url} (attempt ${attempt + 1})`);
+      try {
+        response = await this.fetchImpl(url, init);
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") throw err;
+        if (attempt < this.maxRetries) {
+          await backoff(++attempt);
+          continue;
+        }
+        throw new LogisticsError(0, {
+          error: "network_error",
+          message: err instanceof Error ? err.message : "Network request failed"
+        });
+      }
+      if (response.status >= 500 && canRetry && attempt < this.maxRetries) {
+        await backoff(++attempt);
+        continue;
+      }
+      break;
+    }
+    if (!response.ok) {
+      let errBody;
+      try {
+        errBody = await response.json();
+      } catch {
+        errBody = { error: "unknown_error", message: response.statusText };
+      }
+      throw new LogisticsError(response.status, errBody);
+    }
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+};
+function backoff(attempt) {
+  const ms = Math.min(2 ** attempt * 100, 2e3);
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end--;
+  return value.slice(0, end);
+}
+
+// src/client.ts
+var MitumbaLogistics = class {
+  constructor(config = {}) {
+    this.http = new HttpClient(config);
+  }
+  /** Public market discovery: markets, currencies, fulfilment methods. */
+  async getMarkets(options) {
+    return this.http.get("/logistics/markets", options);
+  }
+  /**
+   * Route and price a parcel for the chosen method. Returns the chosen (cheapest)
+   * option plus alternatives; each option carries its persisted `quote_id` to
+   * pass to {@link createParcel}.
+   */
+  async quote(input, options) {
+    return this.http.post("/logistics/quotes", input, options);
+  }
+  /** Book the carrier chosen by a prior quote and create the parcel. */
+  async createParcel(input, options) {
+    return this.http.post("/logistics/parcels", input, options);
+  }
+  /**
+   * Buyer-facing parcel view: the normalized status plus the dual-surface
+   * carrier tracking passthrough. The collection code is never returned — only
+   * whether one exists.
+   */
+  async getParcel(parcelId, options) {
+    return this.http.get(`/logistics/parcels/${encodeURIComponent(parcelId)}`, options);
+  }
+};
+
+// src/polling.ts
+var import_logistics_contract = require("@mitumbadotafrica/logistics-contract");
+async function pollParcel(client, parcelId, options = {}) {
+  const deadlineMs = options.deadlineMs ?? 6e5;
+  const intervalMs = options.intervalMs ?? 15e3;
+  const jitter = options.jitter ?? 0.2;
+  const stopOnAction = options.stopOnActionRequired ?? true;
+  const startedAt = Date.now();
+  let last = null;
+  for (; ; ) {
+    if (options.signal?.aborted) return last;
+    const reqOptions = options.signal ? { signal: options.signal } : {};
+    last = await client.getParcel(parcelId, reqOptions);
+    options.onUpdate?.(last);
+    if ((0, import_logistics_contract.isTerminalParcelStatus)(last.status)) return last;
+    if (stopOnAction && last.status === "action_required") return last;
+    if (Date.now() - startedAt >= deadlineMs) {
+      options.onTimeout?.(last);
+      return last;
+    }
+    const wait = applyJitter(intervalMs, jitter);
+    const remaining = deadlineMs - (Date.now() - startedAt);
+    await sleep(Math.min(wait, Math.max(remaining, 0)), options.signal);
+  }
+}
+function applyJitter(baseMs, jitter) {
+  if (jitter <= 0) return baseMs;
+  const delta = baseMs * jitter;
+  return Math.round(baseMs - delta + Math.random() * 2 * delta);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (ms <= 0) return resolve();
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/index.ts
+__reExport(index_exports, require("@mitumbadotafrica/logistics-contract"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_URL,
+  HttpClient,
+  LogisticsError,
+  MitumbaLogistics,
+  pollParcel,
+  ...require("@mitumbadotafrica/logistics-contract")
+});

package/dist/index.d.cts

@@ -0,0 +1,149 @@
+import { MarketsResponse, QuoteRequest, QuoteResponse, CreateParcelResponse, ParcelView, LogisticsErrorBody } from '@mitumbadotafrica/logistics-contract';
+export * from '@mitumbadotafrica/logistics-contract';
+
+/** Canonical public API base. Override for staging/self-hosting. */
+declare const DEFAULT_BASE_URL = "https://api.mitumba.africa";
+interface MitumbaLogisticsConfig {
+    /** API base URL. Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /**
+     * A bearer token, or a (possibly async) function returning one. The core
+     * client is auth-agnostic: it attaches the token as `Authorization: Bearer
+     * <token>`. Token acquisition and refresh are the host application's job.
+     */
+    token?: string | (() => string | undefined | Promise<string | undefined>);
+    /** Max retries on network errors and 5xx responses. Default 3. */
+    maxRetries?: number;
+    /** Custom fetch implementation (e.g. for RN or tests). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Log request/response lines to the console. Default false. */
+    debug?: boolean;
+}
+interface RequestOptions {
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
+    /** Per-request bearer override, sent instead of the client's configured token. */
+    token?: string;
+}
+
+/**
+ * Input to book a parcel against a prior quote. The sender is Mitumba's masked
+ * identity, supplied by the caller (the orders flow) — never a seller identity.
+ * `weight_grams` is the real parcel weight (the carrier books and bills by it).
+ */
+interface CreateParcelInput {
+    quote_id: string;
+    weight_grams: number;
+    sender: ShipmentPartyInput;
+    recipient: ShipmentPartyInput;
+}
+interface ShipmentPartyInput {
+    name: string;
+    phone: string;
+    city_id?: string | null;
+    node_id?: string;
+    address_line?: string;
+    point?: {
+        latitude: number;
+        longitude: number;
+    };
+}
+/**
+ * The headless, carrier-neutral Mitumba Logistics client. Knows the shape of the
+ * HTTP contract (via @mitumbadotafrica/logistics-contract) and nothing about how parcels
+ * are booked, routed, or tracked. No carrier implementations, no secrets.
+ *
+ * The buyer picks a fulfilment METHOD in {@link quote}; the backend chooses the
+ * carrier. Carrier identity returned in responses is observable metadata — never
+ * something the client switches on to drive the flow.
+ */
+declare class MitumbaLogistics {
+    private readonly http;
+    constructor(config?: MitumbaLogisticsConfig);
+    /** Public market discovery: markets, currencies, fulfilment methods. */
+    getMarkets(options?: RequestOptions): Promise<MarketsResponse>;
+    /**
+     * Route and price a parcel for the chosen method. Returns the chosen (cheapest)
+     * option plus alternatives; each option carries its persisted `quote_id` to
+     * pass to {@link createParcel}.
+     */
+    quote(input: QuoteRequest, options?: RequestOptions): Promise<QuoteResponse>;
+    /** Book the carrier chosen by a prior quote and create the parcel. */
+    createParcel(input: CreateParcelInput, options?: RequestOptions): Promise<CreateParcelResponse>;
+    /**
+     * Buyer-facing parcel view: the normalized status plus the dual-surface
+     * carrier tracking passthrough. The collection code is never returned — only
+     * whether one exists.
+     */
+    getParcel(parcelId: string, options?: RequestOptions): Promise<ParcelView>;
+}
+
+/**
+ * Minimal, framework-agnostic HTTP client. Token acquisition is the host's job
+ * (see {@link MitumbaLogisticsConfig.token}). Retries network errors and 5xx
+ * with exponential backoff; GET is idempotent-safe to retry, POST is only
+ * retried on network errors (never after a server response).
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly debug;
+    private readonly tokenSource;
+    constructor(config?: MitumbaLogisticsConfig);
+    private resolveToken;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    private request;
+}
+
+/**
+ * Thrown for any non-2xx API response and for network/transport failures.
+ * `code` is the machine-readable error code from the API envelope (`{ error }`).
+ * `status` is 0 for network-level failures. `reason` carries the backend's
+ * sub-reason where present (e.g. `no_route` → `not_serviceable`).
+ */
+declare class LogisticsError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+    readonly reason?: string;
+    constructor(status: number, body: LogisticsErrorBody);
+    /** True for a temporary backend condition (503), e.g. no carriers configured. */
+    get isTemporary(): boolean;
+}
+
+interface PollParcelOptions {
+    /** Fired on every successful status read. */
+    onUpdate?: (parcel: ParcelView) => void;
+    /**
+     * Client-side safety deadline (ms). When exceeded, polling stops and
+     * `onTimeout` fires. This is "still in transit" — it must NOT be treated as a
+     * delivery failure. Default 600000 (10 min); parcels are long-lived, so hosts
+     * typically poll a view open on screen rather than to completion.
+     */
+    deadlineMs?: number;
+    onTimeout?: (last: ParcelView | null) => void;
+    /** Abort signal to stop polling. */
+    signal?: AbortSignal;
+    /** Base interval between reads (ms). Default 15000. */
+    intervalMs?: number;
+    /** Fractional jitter applied to each interval. Default 0.2. */
+    jitter?: number;
+    /**
+     * Stop as soon as the parcel needs the buyer (status `action_required`), so the
+     * host can surface the NextAction. Default true. When false, polling continues
+     * through an action_required park (it is non-terminal and resumable).
+     */
+    stopOnActionRequired?: boolean;
+}
+/**
+ * Poll a parcel's status until it reaches a terminal state (delivered, returned,
+ * cancelled, lost), needs buyer action, the deadline passes, or the signal
+ * aborts. Keeps at most one request in flight. Critically, an UNKNOWN status is
+ * treated as non-terminal and keeps polling — elapsed client time never invents
+ * a terminal outcome. Resolves with the last view read.
+ */
+declare function pollParcel(client: MitumbaLogistics, parcelId: string, options?: PollParcelOptions): Promise<ParcelView | null>;
+
+export { type CreateParcelInput, DEFAULT_BASE_URL, HttpClient, LogisticsError, MitumbaLogistics, type MitumbaLogisticsConfig, type PollParcelOptions, type RequestOptions, type ShipmentPartyInput, pollParcel };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import { MarketsResponse, QuoteRequest, QuoteResponse, CreateParcelResponse, ParcelView, LogisticsErrorBody } from '@mitumbadotafrica/logistics-contract';
+export * from '@mitumbadotafrica/logistics-contract';
+
+/** Canonical public API base. Override for staging/self-hosting. */
+declare const DEFAULT_BASE_URL = "https://api.mitumba.africa";
+interface MitumbaLogisticsConfig {
+    /** API base URL. Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /**
+     * A bearer token, or a (possibly async) function returning one. The core
+     * client is auth-agnostic: it attaches the token as `Authorization: Bearer
+     * <token>`. Token acquisition and refresh are the host application's job.
+     */
+    token?: string | (() => string | undefined | Promise<string | undefined>);
+    /** Max retries on network errors and 5xx responses. Default 3. */
+    maxRetries?: number;
+    /** Custom fetch implementation (e.g. for RN or tests). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Log request/response lines to the console. Default false. */
+    debug?: boolean;
+}
+interface RequestOptions {
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
+    /** Per-request bearer override, sent instead of the client's configured token. */
+    token?: string;
+}
+
+/**
+ * Input to book a parcel against a prior quote. The sender is Mitumba's masked
+ * identity, supplied by the caller (the orders flow) — never a seller identity.
+ * `weight_grams` is the real parcel weight (the carrier books and bills by it).
+ */
+interface CreateParcelInput {
+    quote_id: string;
+    weight_grams: number;
+    sender: ShipmentPartyInput;
+    recipient: ShipmentPartyInput;
+}
+interface ShipmentPartyInput {
+    name: string;
+    phone: string;
+    city_id?: string | null;
+    node_id?: string;
+    address_line?: string;
+    point?: {
+        latitude: number;
+        longitude: number;
+    };
+}
+/**
+ * The headless, carrier-neutral Mitumba Logistics client. Knows the shape of the
+ * HTTP contract (via @mitumbadotafrica/logistics-contract) and nothing about how parcels
+ * are booked, routed, or tracked. No carrier implementations, no secrets.
+ *
+ * The buyer picks a fulfilment METHOD in {@link quote}; the backend chooses the
+ * carrier. Carrier identity returned in responses is observable metadata — never
+ * something the client switches on to drive the flow.
+ */
+declare class MitumbaLogistics {
+    private readonly http;
+    constructor(config?: MitumbaLogisticsConfig);
+    /** Public market discovery: markets, currencies, fulfilment methods. */
+    getMarkets(options?: RequestOptions): Promise<MarketsResponse>;
+    /**
+     * Route and price a parcel for the chosen method. Returns the chosen (cheapest)
+     * option plus alternatives; each option carries its persisted `quote_id` to
+     * pass to {@link createParcel}.
+     */
+    quote(input: QuoteRequest, options?: RequestOptions): Promise<QuoteResponse>;
+    /** Book the carrier chosen by a prior quote and create the parcel. */
+    createParcel(input: CreateParcelInput, options?: RequestOptions): Promise<CreateParcelResponse>;
+    /**
+     * Buyer-facing parcel view: the normalized status plus the dual-surface
+     * carrier tracking passthrough. The collection code is never returned — only
+     * whether one exists.
+     */
+    getParcel(parcelId: string, options?: RequestOptions): Promise<ParcelView>;
+}
+
+/**
+ * Minimal, framework-agnostic HTTP client. Token acquisition is the host's job
+ * (see {@link MitumbaLogisticsConfig.token}). Retries network errors and 5xx
+ * with exponential backoff; GET is idempotent-safe to retry, POST is only
+ * retried on network errors (never after a server response).
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly debug;
+    private readonly tokenSource;
+    constructor(config?: MitumbaLogisticsConfig);
+    private resolveToken;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    private request;
+}
+
+/**
+ * Thrown for any non-2xx API response and for network/transport failures.
+ * `code` is the machine-readable error code from the API envelope (`{ error }`).
+ * `status` is 0 for network-level failures. `reason` carries the backend's
+ * sub-reason where present (e.g. `no_route` → `not_serviceable`).
+ */
+declare class LogisticsError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+    readonly reason?: string;
+    constructor(status: number, body: LogisticsErrorBody);
+    /** True for a temporary backend condition (503), e.g. no carriers configured. */
+    get isTemporary(): boolean;
+}
+
+interface PollParcelOptions {
+    /** Fired on every successful status read. */
+    onUpdate?: (parcel: ParcelView) => void;
+    /**
+     * Client-side safety deadline (ms). When exceeded, polling stops and
+     * `onTimeout` fires. This is "still in transit" — it must NOT be treated as a
+     * delivery failure. Default 600000 (10 min); parcels are long-lived, so hosts
+     * typically poll a view open on screen rather than to completion.
+     */
+    deadlineMs?: number;
+    onTimeout?: (last: ParcelView | null) => void;
+    /** Abort signal to stop polling. */
+    signal?: AbortSignal;
+    /** Base interval between reads (ms). Default 15000. */
+    intervalMs?: number;
+    /** Fractional jitter applied to each interval. Default 0.2. */
+    jitter?: number;
+    /**
+     * Stop as soon as the parcel needs the buyer (status `action_required`), so the
+     * host can surface the NextAction. Default true. When false, polling continues
+     * through an action_required park (it is non-terminal and resumable).
+     */
+    stopOnActionRequired?: boolean;
+}
+/**
+ * Poll a parcel's status until it reaches a terminal state (delivered, returned,
+ * cancelled, lost), needs buyer action, the deadline passes, or the signal
+ * aborts. Keeps at most one request in flight. Critically, an UNKNOWN status is
+ * treated as non-terminal and keeps polling — elapsed client time never invents
+ * a terminal outcome. Resolves with the last view read.
+ */
+declare function pollParcel(client: MitumbaLogistics, parcelId: string, options?: PollParcelOptions): Promise<ParcelView | null>;
+
+export { type CreateParcelInput, DEFAULT_BASE_URL, HttpClient, LogisticsError, MitumbaLogistics, type MitumbaLogisticsConfig, type PollParcelOptions, type RequestOptions, type ShipmentPartyInput, pollParcel };

package/dist/index.js

@@ -0,0 +1,188 @@
+// src/errors.ts
+var LogisticsError = class extends Error {
+  constructor(status, body) {
+    super(body.message ?? body.error);
+    this.name = "LogisticsError";
+    this.code = body.error;
+    this.status = status;
+    this.details = body.details;
+    this.reason = body.reason;
+  }
+  /** True for a temporary backend condition (503), e.g. no carriers configured. */
+  get isTemporary() {
+    return this.status === 503;
+  }
+};
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://api.mitumba.africa";
+
+// src/http.ts
+var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET"]);
+var HttpClient = class {
+  constructor(config = {}) {
+    this.baseUrl = stripTrailingSlashes(config.baseUrl ?? DEFAULT_BASE_URL);
+    this.maxRetries = config.maxRetries ?? 3;
+    this.fetchImpl = config.fetch ?? globalThis.fetch;
+    this.debug = config.debug ?? false;
+    this.tokenSource = config.token;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error(
+        "No fetch implementation available. Provide `fetch` in the config for this runtime."
+      );
+    }
+  }
+  async resolveToken() {
+    if (typeof this.tokenSource === "function") return this.tokenSource();
+    return this.tokenSource;
+  }
+  async get(path, options) {
+    return this.request("GET", path, void 0, options);
+  }
+  async post(path, body, options) {
+    return this.request("POST", path, body, options);
+  }
+  async request(method, path, body, options) {
+    const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    const token = options?.token ?? await this.resolveToken();
+    const headers = new Headers();
+    if (body !== void 0) headers.set("Content-Type", "application/json");
+    if (token) headers.set("Authorization", `Bearer ${token}`);
+    const init = {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal: options?.signal
+    };
+    const canRetry = RETRYABLE_METHODS.has(method);
+    let attempt = 0;
+    let response;
+    for (; ; ) {
+      if (this.debug) console.log(`[mitumba-logistics] ${method} ${url} (attempt ${attempt + 1})`);
+      try {
+        response = await this.fetchImpl(url, init);
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") throw err;
+        if (attempt < this.maxRetries) {
+          await backoff(++attempt);
+          continue;
+        }
+        throw new LogisticsError(0, {
+          error: "network_error",
+          message: err instanceof Error ? err.message : "Network request failed"
+        });
+      }
+      if (response.status >= 500 && canRetry && attempt < this.maxRetries) {
+        await backoff(++attempt);
+        continue;
+      }
+      break;
+    }
+    if (!response.ok) {
+      let errBody;
+      try {
+        errBody = await response.json();
+      } catch {
+        errBody = { error: "unknown_error", message: response.statusText };
+      }
+      throw new LogisticsError(response.status, errBody);
+    }
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+};
+function backoff(attempt) {
+  const ms = Math.min(2 ** attempt * 100, 2e3);
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end--;
+  return value.slice(0, end);
+}
+
+// src/client.ts
+var MitumbaLogistics = class {
+  constructor(config = {}) {
+    this.http = new HttpClient(config);
+  }
+  /** Public market discovery: markets, currencies, fulfilment methods. */
+  async getMarkets(options) {
+    return this.http.get("/logistics/markets", options);
+  }
+  /**
+   * Route and price a parcel for the chosen method. Returns the chosen (cheapest)
+   * option plus alternatives; each option carries its persisted `quote_id` to
+   * pass to {@link createParcel}.
+   */
+  async quote(input, options) {
+    return this.http.post("/logistics/quotes", input, options);
+  }
+  /** Book the carrier chosen by a prior quote and create the parcel. */
+  async createParcel(input, options) {
+    return this.http.post("/logistics/parcels", input, options);
+  }
+  /**
+   * Buyer-facing parcel view: the normalized status plus the dual-surface
+   * carrier tracking passthrough. The collection code is never returned — only
+   * whether one exists.
+   */
+  async getParcel(parcelId, options) {
+    return this.http.get(`/logistics/parcels/${encodeURIComponent(parcelId)}`, options);
+  }
+};
+
+// src/polling.ts
+import { isTerminalParcelStatus } from "@mitumbadotafrica/logistics-contract";
+async function pollParcel(client, parcelId, options = {}) {
+  const deadlineMs = options.deadlineMs ?? 6e5;
+  const intervalMs = options.intervalMs ?? 15e3;
+  const jitter = options.jitter ?? 0.2;
+  const stopOnAction = options.stopOnActionRequired ?? true;
+  const startedAt = Date.now();
+  let last = null;
+  for (; ; ) {
+    if (options.signal?.aborted) return last;
+    const reqOptions = options.signal ? { signal: options.signal } : {};
+    last = await client.getParcel(parcelId, reqOptions);
+    options.onUpdate?.(last);
+    if (isTerminalParcelStatus(last.status)) return last;
+    if (stopOnAction && last.status === "action_required") return last;
+    if (Date.now() - startedAt >= deadlineMs) {
+      options.onTimeout?.(last);
+      return last;
+    }
+    const wait = applyJitter(intervalMs, jitter);
+    const remaining = deadlineMs - (Date.now() - startedAt);
+    await sleep(Math.min(wait, Math.max(remaining, 0)), options.signal);
+  }
+}
+function applyJitter(baseMs, jitter) {
+  if (jitter <= 0) return baseMs;
+  const delta = baseMs * jitter;
+  return Math.round(baseMs - delta + Math.random() * 2 * delta);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (ms <= 0) return resolve();
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/index.ts
+export * from "@mitumbadotafrica/logistics-contract";
+export {
+  DEFAULT_BASE_URL,
+  HttpClient,
+  LogisticsError,
+  MitumbaLogistics,
+  pollParcel
+};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@mitumbadotafrica/logistics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Asset-light carrier-orchestration SDK — carrier-neutral headless client for Kenyan couriers. Zero UI, zero carrier knowledge.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mitumba-Ltd/mitumba-logistics.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/Mitumba-Ltd/mitumba-logistics/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/Mitumba-Ltd/mitumba-logistics/issues"
+  },
+  "keywords": [
+    "logistics",
+    "shipping",
+    "courier",
+    "kenya",
+    "africa",
+    "pickup-mtaani",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rimraf dist .turbo"
+  },
+  "dependencies": {
+    "@mitumbadotafrica/logistics-contract": "0.0.0"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.1",
+    "vitest": "^2.1.1"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.