@beyondplusmm/doehpos-sdk 0.1.0

package/dist/transport.js

@@ -0,0 +1,105 @@
+/**
+ * The transport: one place that knows how to shape, send, and retry a request.
+ *
+ * Faithful to the validated golden client:
+ *   - Authorization: Bearer <key>
+ *   - User-Agent is MANDATORY (the edge/WAF rejects default library agents
+ *     before they ever reach the API).
+ *   - Trace-Id is sent and echoed; surfaced on errors for log correlation.
+ *   - Idempotency-Key (NOT X-Idempotency-Key) enables safe create retries.
+ *   - 429 and transport failures are retried with linear backoff; nothing else.
+ */
+import { DEFAULTS } from "./config.js";
+import { DoehTransportError, mapApiError, isRetryable } from "./errors.js";
+import { generateIdempotencyKey } from "./idempotency.js";
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function parseBody(text) {
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // A non-JSON body (e.g. a WAF/proxy HTML error) — surface it structured.
+        return { ok: false, code: "NON_JSON_RESPONSE", raw: text.slice(0, 200) };
+    }
+}
+export class Transport {
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Send one logical request, retrying transport errors and 429 only. */
+    async request(spec) {
+        const sleep = this.cfg.sleep ?? defaultSleep;
+        const traceId = spec.traceId ?? generateIdempotencyKey("trace");
+        const max = this.cfg.maxRetries;
+        let attempt = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            try {
+                return await this.attempt(spec, traceId);
+            }
+            catch (err) {
+                if (isRetryable(err) && attempt < max) {
+                    attempt += 1;
+                    await sleep(this.cfg.backoffBaseMs * attempt);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    async attempt(spec, traceId) {
+        const url = this.cfg.baseUrl.replace(/\/$/, "") + spec.path;
+        const headers = {
+            "Content-Type": "application/json",
+            "User-Agent": this.cfg.userAgent,
+            "Trace-Id": traceId,
+        };
+        if (!spec.anonymous)
+            headers["Authorization"] = `Bearer ${this.cfg.apiKey}`;
+        if (spec.idempotencyKey)
+            headers["Idempotency-Key"] = spec.idempotencyKey;
+        // Compose the caller signal with our timeout.
+        const timeout = new AbortController();
+        const timer = setTimeout(() => timeout.abort(), this.cfg.timeoutMs);
+        const signal = spec.signal
+            ? anySignal([spec.signal, timeout.signal])
+            : timeout.signal;
+        let res;
+        try {
+            res = await this.cfg.fetch(url, {
+                method: spec.method,
+                headers,
+                body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
+                signal,
+            });
+        }
+        catch (cause) {
+            const aborted = cause?.name === "AbortError";
+            throw new DoehTransportError(aborted ? `request timed out after ${this.cfg.timeoutMs}ms` : "network request failed", { cause, timeout: aborted });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        const body = parseBody(text);
+        if (res.status >= 200 && res.status < 300) {
+            return { status: res.status, body: body, traceId };
+        }
+        throw mapApiError(res.status, body, traceId);
+    }
+}
+/** Minimal AbortSignal.any polyfill (not available on all RN runtimes). */
+function anySignal(signals) {
+    const controller = new AbortController();
+    for (const s of signals) {
+        if (s.aborted) {
+            controller.abort();
+            break;
+        }
+        s.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    return controller.signal;
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Wire types, mirrored from the public OpenAPI specs and the golden client.
+ *
+ * Money is ALWAYS integer minor units (1500 == 15.00). Never a decimal.
+ */
+export type Currency = "MMK" | "THB" | "USD" | "CNY" | "SGD" | "INR";
+export type OrderStatus = "pending" | "confirmed" | "dispatched" | "delivered" | "cancelled";
+/** Request body for POST /v1/delivery/orders. */
+export interface OrderCreate {
+    currency: Currency;
+    /** Integer minor units, >= 1. e.g. 1500 = 15.00. */
+    amount_minor: number;
+}
+export interface Order {
+    id: string;
+    status: OrderStatus;
+    shop_id: number;
+    branch_id: number;
+    currency: Currency;
+    amount_minor: number;
+    created_at_utc: string;
+    /** created_at rendered in the branch's native timezone. */
+    created_at_local: string;
+    idempotency_key?: string;
+}
+export interface OrderResponse {
+    ok: boolean;
+    /** true if this was an idempotent replay (HTTP 200 instead of 201). */
+    idempotent?: boolean;
+    order: Order;
+}
+/** The stable error envelope returned for every non-2xx response. */
+export interface ErrorBody {
+    ok: false;
+    /** Stable, append-only error code (part of the API ABI). */
+    code: string;
+    /** Internal verification step (diagnostic only). */
+    step?: string;
+}
+/** Per-call options that map onto request headers. */
+export interface CallOptions {
+    /**
+     * Idempotency key. STRONGLY recommended on every create. For offline-safe
+     * retries the key must be minted once when the mutation is created and reused
+     * on every attempt — see OfflineQueue. If omitted on a create, the SDK mints
+     * one for this single call only.
+     */
+    idempotencyKey?: string;
+    /** Caller trace id, propagated and echoed on the response. */
+    traceId?: string;
+    /** Per-call AbortSignal (in addition to the configured timeout). */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAErE,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,WAAW,GACX,YAAY,GACZ,WAAW,GACX,WAAW,CAAC;AAEhB,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,KAAK,CAAC;IACV,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Wire types, mirrored from the public OpenAPI specs and the golden client.
+ *
+ * Money is ALWAYS integer minor units (1500 == 15.00). Never a decimal.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@beyondplusmm/doehpos-sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the Doeh POS public API — a typed port of the validated golden client.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "tsc -p tsconfig.json",
+    "test": "pnpm build && node --test test/",
+    "test:integration": "pnpm build && node test/golden.integration.mjs"
+  },
+  "keywords": [
+    "doeh",
+    "pos",
+    "sdk",
+    "delivery",
+    "expo",
+    "react-native"
+  ],
+  "license": "MIT",
+  "author": "bplusmyanmar <bplusmyanmar@gmail.com>",
+  "homepage": "https://github.com/beyondplusmyanmar-lab/doeh-sdk/tree/main/packages/sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beyondplusmyanmar-lab/doeh-sdk.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/beyondplusmyanmar-lab/doeh-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}

package/src/client.ts

@@ -0,0 +1,92 @@
+/**
+ * DoehClient — the public entry point.
+ *
+ *     const client = new DoehClient({ apiKey: "sk_test_…", environment: "sandbox" });
+ *     const { order } = await client.delivery.create({ currency: "MMK", amount_minor: 1500 });
+ *
+ * There is intentionally NO shop concept: scope is derived from the key. To act
+ * as a different shop, construct a client with a different key. Cutover from
+ * sandbox to production is `environment: "production"` + a `sk_live_` key — no
+ * code change.
+ */
+import { BASE_URLS, DEFAULTS, SDK_VERSION, type Environment } from "./config.js";
+import { Transport, type FetchLike } from "./transport.js";
+import { DeliveryModule } from "./modules/delivery.js";
+import { KitchenModule } from "./modules/experimental/kitchen.js";
+import { LoyaltyModule } from "./modules/experimental/loyalty.js";
+import { MarketplaceModule } from "./modules/experimental/marketplace.js";
+import { RiderModule } from "./modules/experimental/rider.js";
+
+export interface DoehClientOptions {
+  apiKey: string;
+  /** "sandbox" (default) or "production". Ignored if baseUrl is given. */
+  environment?: Environment;
+  /** Override the base URL entirely (advanced / self-host / tests). */
+  baseUrl?: string;
+  /**
+   * Override the (mandatory) User-Agent. The SDK always sends one; supplying
+   * your own is encouraged so your app is identifiable in server logs, e.g.
+   * "MyMerchantApp/2.1". The SDK token is appended automatically.
+   */
+  userAgent?: string;
+  /** Inject a fetch implementation (RN / undici / mock). Defaults to global. */
+  fetch?: FetchLike;
+  timeoutMs?: number;
+  maxRetries?: number;
+  /** Test hook to make backoff instant. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export class DoehClient {
+  readonly delivery: DeliveryModule;
+
+  /** @experimental Not yet exercised by the reference app. */
+  readonly kitchen: KitchenModule;
+  /** @experimental Not yet exercised by the reference app. */
+  readonly loyalty: LoyaltyModule;
+  /** @experimental Not yet exercised by the reference app. */
+  readonly marketplace: MarketplaceModule;
+  /** @experimental Not yet exercised by the reference app. */
+  readonly rider: RiderModule;
+
+  private readonly transport: Transport;
+
+  constructor(opts: DoehClientOptions) {
+    if (!opts.apiKey) throw new Error("DoehClient requires an apiKey");
+    const env = opts.environment ?? "sandbox";
+    const baseUrl = opts.baseUrl ?? BASE_URLS[env];
+    const userAgent = opts.userAgent
+      ? `${opts.userAgent} doeh-sdk/${SDK_VERSION}`
+      : `doeh-sdk/${SDK_VERSION}`;
+
+    const fetchImpl = opts.fetch ?? (globalThis.fetch as FetchLike | undefined);
+    if (typeof fetchImpl !== "function") {
+      throw new Error(
+        "No fetch implementation available. Pass `fetch` in DoehClientOptions " +
+          "(e.g. from undici on older Node, or the RN global).",
+      );
+    }
+
+    this.transport = new Transport({
+      baseUrl,
+      apiKey: opts.apiKey,
+      userAgent,
+      fetch: fetchImpl,
+      timeoutMs: opts.timeoutMs ?? DEFAULTS.timeoutMs,
+      maxRetries: opts.maxRetries ?? DEFAULTS.maxRetries,
+      backoffBaseMs: DEFAULTS.backoffBaseMs,
+      sleep: opts.sleep,
+    });
+
+    this.delivery = new DeliveryModule(this.transport);
+    this.kitchen = new KitchenModule(this.transport);
+    this.loyalty = new LoyaltyModule(this.transport);
+    this.marketplace = new MarketplaceModule(this.transport);
+    this.rider = new RiderModule(this.transport);
+  }
+
+  /** Internal: the configured transport (used by OfflineQueue wiring/tests). */
+  get _transport(): Transport {
+    return this.transport;
+  }
+}

package/src/config.ts

@@ -0,0 +1,30 @@
+/**
+ * Environment configuration.
+ *
+ * "single shop" is NOT a config concept here. The shop/branch scope is derived
+ * from the API key server-side — the client never sends scope. One key == one
+ * shop. To act as a different shop, use a different key.
+ */
+export type Environment = "sandbox" | "production";
+
+/** Base URLs per environment, taken verbatim from the validated golden client. */
+export const BASE_URLS: Record<Environment, string> = {
+  sandbox: "https://sandbox-api.doehpos.com",
+  production: "https://api.doehpos.com",
+};
+
+/** Default SDK version string surfaced in the (mandatory) User-Agent. */
+export const SDK_VERSION = "0.1.0";
+
+export const DEFAULTS = {
+  /** Per-request timeout. */
+  timeoutMs: 15_000,
+  /**
+   * Max retry attempts. Retries apply ONLY to transport failures and HTTP 429
+   * (the fleet rate limiter is a deliberately tight shared token bucket).
+   * No other status is ever retried.
+   */
+  maxRetries: 4,
+  /** Linear backoff base; attempt N waits roughly backoffBaseMs * N. */
+  backoffBaseMs: 1_000,
+} as const;

package/src/errors.ts

@@ -0,0 +1,119 @@
+/**
+ * Typed error ABI.
+ *
+ * The public API's error codes are a stable, append-only contract. Consumers
+ * should NEVER parse `code` strings — they catch typed classes instead:
+ *
+ *     try { await client.delivery.create(...) }
+ *     catch (e) {
+ *       if (e instanceof InvalidAmountError) { ... }
+ *       if (e instanceof ApiKeyRevokedError) { ... }
+ *     }
+ */
+import type { ErrorBody } from "./types.js";
+
+/** Base for everything thrown by the SDK. */
+export class DoehError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+    // Restore prototype chain for transpiled-to-ES5 consumers.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * The request never produced an HTTP response (network down, DNS, TLS, timeout,
+ * aborted). These are the failures the SDK retries.
+ */
+export class DoehTransportError extends DoehError {
+  readonly cause?: unknown;
+  /** True if the failure was a timeout/abort. */
+  readonly timeout: boolean;
+  constructor(message: string, opts: { cause?: unknown; timeout?: boolean } = {}) {
+    super(message);
+    this.cause = opts.cause;
+    this.timeout = opts.timeout ?? false;
+  }
+}
+
+/** Any non-2xx HTTP response, carrying the stable `code` and correlation ids. */
+export class DoehApiError extends DoehError {
+  readonly status: number;
+  readonly code: string;
+  readonly step?: string;
+  readonly traceId?: string;
+  readonly body: unknown;
+  constructor(
+    status: number,
+    code: string,
+    opts: { step?: string; traceId?: string; body?: unknown } = {},
+  ) {
+    super(`HTTP ${status} ${code}`);
+    this.status = status;
+    this.code = code;
+    this.step = opts.step;
+    this.traceId = opts.traceId;
+    this.body = opts.body;
+  }
+}
+
+// ── 401 — authentication (API_KEY_* ABI) ─────────────────────────────────────
+export class ApiKeyInvalidError extends DoehApiError {}
+export class ApiKeyExpiredError extends DoehApiError {}
+export class ApiKeyRevokedError extends DoehApiError {}
+export class EnvMismatchError extends DoehApiError {} // API_KEY_ENV_MISMATCH
+
+// ── 403 — authenticated but not permitted ────────────────────────────────────
+export class ScopeDeniedError extends DoehApiError {} // API_KEY_SCOPE_DENIED
+export class TransportDisabledError extends DoehApiError {} // EDGE_TRANSPORT_DISABLED
+
+// ── 404 / 409 / 422 / 400 ────────────────────────────────────────────────────
+export class OrderNotFoundError extends DoehApiError {} // EDGE_ORDER_NOT_FOUND
+export class ReplayError extends DoehApiError {} // EDGE_REPLAYED
+export class InvalidAmountError extends DoehApiError {} // EDGE_INVALID_AMOUNT
+export class UnsupportedCurrencyError extends DoehApiError {} // EDGE_UNSUPPORTED_CURRENCY
+export class BadBodyError extends DoehApiError {} // EDGE_BAD_BODY
+
+// ── 429 — rate limited (retried internally; only surfaced when retries exhaust)
+export class RateLimitedError extends DoehApiError {}
+
+/** Map a stable error code to its typed class. Unknown codes -> DoehApiError. */
+const CODE_TO_CLASS: Record<string, typeof DoehApiError> = {
+  API_KEY_INVALID: ApiKeyInvalidError,
+  API_KEY_EXPIRED: ApiKeyExpiredError,
+  API_KEY_REVOKED: ApiKeyRevokedError,
+  API_KEY_ENV_MISMATCH: EnvMismatchError,
+  API_KEY_SCOPE_DENIED: ScopeDeniedError,
+  EDGE_TRANSPORT_DISABLED: TransportDisabledError,
+  EDGE_ORDER_NOT_FOUND: OrderNotFoundError,
+  EDGE_REPLAYED: ReplayError,
+  EDGE_INVALID_AMOUNT: InvalidAmountError,
+  EDGE_UNSUPPORTED_CURRENCY: UnsupportedCurrencyError,
+  EDGE_BAD_BODY: BadBodyError,
+};
+
+/** Build the right typed error from an HTTP status + parsed body. */
+export function mapApiError(
+  status: number,
+  body: unknown,
+  traceId?: string,
+): DoehApiError {
+  const envelope = (body ?? {}) as Partial<ErrorBody>;
+  const code = typeof envelope.code === "string" ? envelope.code : `HTTP_${status}`;
+  const opts = { step: envelope.step, traceId, body };
+  if (status === 429) return new RateLimitedError(status, code, opts);
+  const Cls = CODE_TO_CLASS[code] ?? DoehApiError;
+  return new Cls(status, code, opts);
+}
+
+/**
+ * The retry predicate, faithful to the golden client: retry ONLY transport
+ * failures and HTTP 429. Every other status (incl. 4xx validation and 5xx) is
+ * terminal and surfaces immediately.
+ */
+export function isRetryable(err: unknown): boolean {
+  if (err instanceof DoehTransportError) return true;
+  if (err instanceof RateLimitedError) return true;
+  return false;
+}

package/src/idempotency.ts

@@ -0,0 +1,33 @@
+/**
+ * Idempotency keys.
+ *
+ * The single most important mobile invariant: a create's idempotency key is
+ * minted ONCE — when the mutation is first created — and reused on every
+ * attempt, across process restarts and network boundaries. Regenerating a key
+ * per attempt produces duplicate orders the instant a retry happens. The
+ * OfflineQueue enforces this; callers doing manual retries must do the same.
+ */
+
+/** A UUID source. Defaults to the platform crypto; injectable for RN/tests. */
+export type UuidFn = () => string;
+
+function platformUuid(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  // Last-resort fallback (e.g. older RN without a crypto polyfill). Not
+  // cryptographically strong, but collision-safe enough for an idempotency key.
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = (Math.random() * 16) | 0;
+    const v = ch === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * Generate an idempotency key. The optional prefix makes server logs readable
+ * (e.g. "delivery"). Stays within the 200-char header limit.
+ */
+export function generateIdempotencyKey(prefix?: string, uuid: UuidFn = platformUuid): string {
+  const id = uuid();
+  return prefix ? `${prefix}-${id}` : id;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * @beyondplusmm/doehpos-sdk — official TypeScript SDK for the Doeh POS public API.
+ *
+ * A typed port of the validated golden client. The stable surface is `delivery`;
+ * kitchen/loyalty/marketplace/rider are @experimental until exercised by the
+ * reference app.
+ */
+export { DoehClient } from "./client.js";
+export type { DoehClientOptions } from "./client.js";
+
+export { BASE_URLS, SDK_VERSION, type Environment } from "./config.js";
+
+export { generateIdempotencyKey, type UuidFn } from "./idempotency.js";
+
+export {
+  OfflineQueue,
+  MemoryStorage,
+  type QueueStorage,
+  type QueuedMutation,
+  type DeadLetter,
+  type FlushResult,
+} from "./queue.js";
+
+export type {
+  Currency,
+  OrderStatus,
+  OrderCreate,
+  Order,
+  OrderResponse,
+  ErrorBody,
+  CallOptions,
+} from "./types.js";
+
+// Error ABI — consumers catch these classes, never parse `code` strings.
+export {
+  DoehError,
+  DoehTransportError,
+  DoehApiError,
+  ApiKeyInvalidError,
+  ApiKeyExpiredError,
+  ApiKeyRevokedError,
+  EnvMismatchError,
+  ScopeDeniedError,
+  TransportDisabledError,
+  OrderNotFoundError,
+  ReplayError,
+  InvalidAmountError,
+  UnsupportedCurrencyError,
+  BadBodyError,
+  RateLimitedError,
+  isRetryable,
+  mapApiError,
+} from "./errors.js";
+
+// Module classes + their types (handy for typing app code).
+export { DeliveryModule } from "./modules/delivery.js";
+export { KitchenModule, type TicketCreate, type TicketResponse } from "./modules/experimental/kitchen.js";
+export { LoyaltyModule, type EarnInput, type AccountResponse } from "./modules/experimental/loyalty.js";
+export {
+  MarketplaceModule,
+  type ListingCreate,
+  type ListingResponse,
+} from "./modules/experimental/marketplace.js";
+export { RiderModule, type JobCreate, type JobResponse } from "./modules/experimental/rider.js";

package/src/modules/delivery.ts

@@ -0,0 +1,57 @@
+/**
+ * Delivery — the stable, reference-app-exercised vertical.
+ *
+ *   POST /v1/delivery/orders        create (idempotent with an Idempotency-Key)
+ *   GET  /v1/delivery/orders/{id}   read back
+ *
+ * Scope is derived from the key server-side; there is no shop/branch argument.
+ */
+import type { Transport } from "../transport.js";
+import type { CallOptions, OrderCreate, OrderResponse } from "../types.js";
+import { generateIdempotencyKey } from "../idempotency.js";
+
+/** Path ids must match this server-side pattern; we fail fast client-side. */
+const PATH_ID = /^[A-Za-z0-9_]+$/;
+
+export class DeliveryModule {
+  constructor(private readonly transport: Transport) {}
+
+  /**
+   * Create a delivery order. Returns 201 on first write, or 200 with
+   * `idempotent: true` when an Idempotency-Key replays an existing order.
+   *
+   * If you do not pass `idempotencyKey`, the SDK mints one for THIS call only —
+   * which is not retry-safe across a process restart. For offline-safe creates,
+   * mint and persist the key yourself (or use OfflineQueue).
+   */
+  async create(input: OrderCreate, opts: CallOptions = {}): Promise<OrderResponse> {
+    if (!Number.isInteger(input.amount_minor) || input.amount_minor < 1) {
+      // Mirror the server's EDGE_INVALID_AMOUNT rule so obvious mistakes fail
+      // locally without burning a rate-limited request. Server remains the SoT.
+      throw new RangeError("amount_minor must be an integer >= 1 (minor units)");
+    }
+    const { body } = await this.transport.request<OrderResponse>({
+      method: "POST",
+      path: "/v1/delivery/orders",
+      body: input,
+      idempotencyKey: opts.idempotencyKey ?? generateIdempotencyKey("delivery"),
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+
+  /** Read a delivery order by id. */
+  async get(id: string, opts: CallOptions = {}): Promise<OrderResponse> {
+    if (!PATH_ID.test(id)) {
+      throw new RangeError(`invalid order id ${JSON.stringify(id)} (must match ${PATH_ID})`);
+    }
+    const { body } = await this.transport.request<OrderResponse>({
+      method: "GET",
+      path: `/v1/delivery/orders/${id}`,
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+}