@beyondplusmm/doehpos-sdk 0.1.0

package/src/modules/experimental/kitchen.ts

@@ -0,0 +1,51 @@
+/**
+ * Kitchen — EXPERIMENTAL.
+ *
+ * @experimental Schema/golden-client-derived; not yet exercised by the Expo
+ * reference app. Shapes may change before they graduate to the stable contract.
+ * Promotion rule: experimental -> reference-app exercised -> stable.
+ */
+import type { Transport } from "../../transport.js";
+import type { CallOptions } from "../../types.js";
+import { generateIdempotencyKey } from "../../idempotency.js";
+
+export interface TicketCreate {
+  station: string;
+  items: string[];
+}
+export interface TicketResponse {
+  ok: boolean;
+  idempotent?: boolean;
+  ticket: { id: string; [k: string]: unknown };
+}
+
+const PATH_ID = /^[A-Za-z0-9_]+$/;
+
+export class KitchenModule {
+  constructor(private readonly transport: Transport) {}
+
+  /** @experimental */
+  async createTicket(input: TicketCreate, opts: CallOptions = {}): Promise<TicketResponse> {
+    const { body } = await this.transport.request<TicketResponse>({
+      method: "POST",
+      path: "/v1/kitchen/tickets",
+      body: input,
+      idempotencyKey: opts.idempotencyKey ?? generateIdempotencyKey("kitchen"),
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+
+  /** @experimental */
+  async getTicket(id: string, opts: CallOptions = {}): Promise<TicketResponse> {
+    if (!PATH_ID.test(id)) throw new RangeError(`invalid ticket id ${JSON.stringify(id)}`);
+    const { body } = await this.transport.request<TicketResponse>({
+      method: "GET",
+      path: `/v1/kitchen/tickets/${id}`,
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+}

package/src/modules/experimental/loyalty.ts

@@ -0,0 +1,52 @@
+/**
+ * Loyalty — EXPERIMENTAL.
+ *
+ * @experimental Schema/golden-client-derived; not yet exercised by the Expo
+ * reference app. `earn` auto-provisions the member account. Member ids must
+ * match [A-Za-z0-9_]+ (no hyphens).
+ */
+import type { Transport } from "../../transport.js";
+import type { CallOptions } from "../../types.js";
+import { generateIdempotencyKey } from "../../idempotency.js";
+
+export interface EarnInput {
+  points: number;
+  reason?: string;
+}
+export interface AccountResponse {
+  ok: boolean;
+  idempotent?: boolean;
+  account: { balance: number; [k: string]: unknown };
+}
+
+const MEMBER_ID = /^[A-Za-z0-9_]+$/;
+
+export class LoyaltyModule {
+  constructor(private readonly transport: Transport) {}
+
+  /** @experimental */
+  async earn(memberId: string, input: EarnInput, opts: CallOptions = {}): Promise<AccountResponse> {
+    if (!MEMBER_ID.test(memberId)) throw new RangeError(`invalid member id ${JSON.stringify(memberId)}`);
+    const { body } = await this.transport.request<AccountResponse>({
+      method: "POST",
+      path: `/v1/loyalty/members/${memberId}/earn`,
+      body: input,
+      idempotencyKey: opts.idempotencyKey ?? generateIdempotencyKey("loyalty"),
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+
+  /** @experimental */
+  async getMember(memberId: string, opts: CallOptions = {}): Promise<AccountResponse> {
+    if (!MEMBER_ID.test(memberId)) throw new RangeError(`invalid member id ${JSON.stringify(memberId)}`);
+    const { body } = await this.transport.request<AccountResponse>({
+      method: "GET",
+      path: `/v1/loyalty/members/${memberId}`,
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+}

package/src/modules/experimental/marketplace.ts

@@ -0,0 +1,52 @@
+/**
+ * Marketplace — EXPERIMENTAL.
+ *
+ * @experimental Schema/golden-client-derived; not yet exercised by the Expo
+ * reference app. Money is integer minor units.
+ */
+import type { Transport } from "../../transport.js";
+import type { CallOptions, Currency } from "../../types.js";
+import { generateIdempotencyKey } from "../../idempotency.js";
+
+export interface ListingCreate {
+  title: string;
+  currency: Currency;
+  price_minor: number;
+  stock: number;
+}
+export interface ListingResponse {
+  ok: boolean;
+  idempotent?: boolean;
+  listing: { id: string; [k: string]: unknown };
+}
+
+const PATH_ID = /^[A-Za-z0-9_]+$/;
+
+export class MarketplaceModule {
+  constructor(private readonly transport: Transport) {}
+
+  /** @experimental */
+  async createListing(input: ListingCreate, opts: CallOptions = {}): Promise<ListingResponse> {
+    const { body } = await this.transport.request<ListingResponse>({
+      method: "POST",
+      path: "/v1/marketplace/listings",
+      body: input,
+      idempotencyKey: opts.idempotencyKey ?? generateIdempotencyKey("market"),
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+
+  /** @experimental */
+  async getListing(id: string, opts: CallOptions = {}): Promise<ListingResponse> {
+    if (!PATH_ID.test(id)) throw new RangeError(`invalid listing id ${JSON.stringify(id)}`);
+    const { body } = await this.transport.request<ListingResponse>({
+      method: "GET",
+      path: `/v1/marketplace/listings/${id}`,
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+}

package/src/modules/experimental/rider.ts

@@ -0,0 +1,50 @@
+/**
+ * Rider — EXPERIMENTAL.
+ *
+ * @experimental Schema/golden-client-derived; not yet exercised by the Expo
+ * reference app.
+ */
+import type { Transport } from "../../transport.js";
+import type { CallOptions } from "../../types.js";
+import { generateIdempotencyKey } from "../../idempotency.js";
+
+export interface JobCreate {
+  pickup: string;
+  dropoff: string;
+}
+export interface JobResponse {
+  ok: boolean;
+  idempotent?: boolean;
+  job: { id: string; [k: string]: unknown };
+}
+
+const PATH_ID = /^[A-Za-z0-9_]+$/;
+
+export class RiderModule {
+  constructor(private readonly transport: Transport) {}
+
+  /** @experimental */
+  async createJob(input: JobCreate, opts: CallOptions = {}): Promise<JobResponse> {
+    const { body } = await this.transport.request<JobResponse>({
+      method: "POST",
+      path: "/v1/rider/jobs",
+      body: input,
+      idempotencyKey: opts.idempotencyKey ?? generateIdempotencyKey("rider"),
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+
+  /** @experimental */
+  async getJob(id: string, opts: CallOptions = {}): Promise<JobResponse> {
+    if (!PATH_ID.test(id)) throw new RangeError(`invalid job id ${JSON.stringify(id)}`);
+    const { body } = await this.transport.request<JobResponse>({
+      method: "GET",
+      path: `/v1/rider/jobs/${id}`,
+      traceId: opts.traceId,
+      signal: opts.signal,
+    });
+    return body;
+  }
+}

package/src/queue.ts

@@ -0,0 +1,157 @@
+/**
+ * OfflineQueue — durable, idempotency-owning mutation queue.
+ *
+ * This is the heart of the mobile design. The rule it enforces:
+ *
+ *   The idempotency key is minted ONCE at enqueue() time, persisted with the
+ *   payload, and reused on EVERY flush attempt — forever, until the server
+ *   accepts it. This is what makes "press create in airplane mode, reconnect,
+ *   sync" produce exactly one order rather than one-per-retry.
+ *
+ * Retry policy mirrors the SDK transport:
+ *   - transport failure / 429  -> keep the item, try again next flush
+ *   - any other non-2xx (4xx validation, etc.) -> the item can NEVER succeed,
+ *     so it is removed and surfaced as a dead letter (do not loop forever)
+ *
+ * Storage is pluggable (AsyncStorage on RN, a file/Map in Node/tests) so the
+ * SDK core stays runtime-agnostic.
+ */
+import type { DeliveryModule } from "./modules/delivery.js";
+import type { OrderCreate, OrderResponse } from "./types.js";
+import { DoehApiError, isRetryable } from "./errors.js";
+import { generateIdempotencyKey } from "./idempotency.js";
+
+export interface QueueStorage {
+  load(): Promise<string | null>;
+  save(serialized: string): Promise<void>;
+}
+
+/** An in-memory storage — handy for tests and as a reference implementation. */
+export class MemoryStorage implements QueueStorage {
+  private value: string | null = null;
+  async load(): Promise<string | null> {
+    return this.value;
+  }
+  async save(serialized: string): Promise<void> {
+    this.value = serialized;
+  }
+}
+
+export interface QueuedMutation {
+  /** Local id (also the user-visible "pending order" handle). */
+  id: string;
+  /** Minted once at enqueue; reused on every attempt. */
+  idempotencyKey: string;
+  module: "delivery";
+  payload: OrderCreate;
+  createdAt: string;
+  attempts: number;
+  lastError?: string;
+}
+
+export interface DeadLetter {
+  mutation: QueuedMutation;
+  error: DoehApiError;
+}
+
+export interface FlushResult {
+  /** Mutations the server accepted this flush. */
+  succeeded: { mutation: QueuedMutation; response: OrderResponse }[];
+  /** Mutations that can never succeed — removed from the queue. */
+  deadLettered: DeadLetter[];
+  /** Mutations still pending (transport/429) — remain queued. */
+  remaining: QueuedMutation[];
+}
+
+export class OfflineQueue {
+  constructor(
+    private readonly delivery: DeliveryModule,
+    private readonly storage: QueueStorage,
+  ) {}
+
+  private async read(): Promise<QueuedMutation[]> {
+    const raw = await this.storage.load();
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? (parsed as QueuedMutation[]) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  private async write(items: QueuedMutation[]): Promise<void> {
+    await this.storage.save(JSON.stringify(items));
+  }
+
+  /** Current pending items (read-only snapshot). */
+  async pending(): Promise<QueuedMutation[]> {
+    return this.read();
+  }
+
+  /**
+   * Enqueue a delivery create. Mints and persists the idempotency key now;
+   * that key is never regenerated. Returns the local handle.
+   */
+  async enqueue(payload: OrderCreate): Promise<QueuedMutation> {
+    const mutation: QueuedMutation = {
+      id: generateIdempotencyKey("local"),
+      idempotencyKey: generateIdempotencyKey("delivery"),
+      module: "delivery",
+      payload,
+      createdAt: new Date().toISOString(),
+      attempts: 0,
+    };
+    const items = await this.read();
+    items.push(mutation);
+    await this.write(items);
+    return mutation;
+  }
+
+  /**
+   * Attempt every pending mutation in FIFO order, reusing each stored key.
+   * Stops draining on the first retryable failure (likely still offline) so we
+   * don't hammer a dead network, but always persists progress.
+   */
+  async flush(): Promise<FlushResult> {
+    const items = await this.read();
+    const result: FlushResult = { succeeded: [], deadLettered: [], remaining: [] };
+    const keep: QueuedMutation[] = [];
+    let networkDown = false;
+
+    for (const m of items) {
+      if (networkDown) {
+        keep.push(m);
+        continue;
+      }
+      m.attempts += 1;
+      try {
+        const response = await this.delivery.create(m.payload, {
+          idempotencyKey: m.idempotencyKey, // SAME key, every attempt
+        });
+        result.succeeded.push({ mutation: m, response });
+      } catch (err) {
+        if (isRetryable(err)) {
+          // Still offline / rate-limited — keep it and stop draining.
+          m.lastError = (err as Error).message;
+          keep.push(m);
+          networkDown = true;
+        } else if (err instanceof DoehApiError) {
+          // Terminal: this payload will never be accepted. Dead-letter it.
+          result.deadLettered.push({ mutation: m, error: err });
+        } else {
+          // A client-side guard (e.g. bad amount) — also terminal.
+          m.lastError = (err as Error).message;
+          result.deadLettered.push({
+            mutation: m,
+            error: new DoehApiError(0, "CLIENT_VALIDATION", { body: m.lastError }),
+          });
+        }
+      }
+    }
+
+    result.remaining = keep;
+    await this.write(keep);
+    return result;
+  }
+}

package/src/transport.ts

@@ -0,0 +1,140 @@
+/**
+ * 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";
+
+/** Pluggable fetch (defaults to global; inject for RN or tests). */
+export type FetchLike = typeof fetch;
+
+export interface TransportConfig {
+  baseUrl: string;
+  apiKey: string;
+  userAgent: string;
+  fetch: FetchLike;
+  timeoutMs: number;
+  maxRetries: number;
+  backoffBaseMs: number;
+  /** Hook for tests to make backoff instant. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface RequestSpec {
+  method: "GET" | "POST";
+  path: string;
+  body?: unknown;
+  idempotencyKey?: string;
+  traceId?: string;
+  signal?: AbortSignal;
+  /** Send no Authorization header (used only to prove the auth gate). */
+  anonymous?: boolean;
+}
+
+export interface RawResponse<T> {
+  status: number;
+  body: T;
+  traceId: string;
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+function parseBody(text: string): unknown {
+  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(private readonly cfg: TransportConfig) {}
+
+  /** Send one logical request, retrying transport errors and 429 only. */
+  async request<T>(spec: RequestSpec): Promise<RawResponse<T>> {
+    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<T>(spec, traceId);
+      } catch (err) {
+        if (isRetryable(err) && attempt < max) {
+          attempt += 1;
+          await sleep(this.cfg.backoffBaseMs * attempt);
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  private async attempt<T>(spec: RequestSpec, traceId: string): Promise<RawResponse<T>> {
+    const url = this.cfg.baseUrl.replace(/\/$/, "") + spec.path;
+    const headers: Record<string, string> = {
+      "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: Response;
+    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 as { name?: string })?.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 as T, traceId };
+    }
+    throw mapApiError(res.status, body, traceId);
+  }
+}
+
+/** Minimal AbortSignal.any polyfill (not available on all RN runtimes). */
+function anySignal(signals: AbortSignal[]): AbortSignal {
+  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;
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+/**
+ * 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;
+}