@frontdesk-africa/store-js 0.2.0 → 0.3.0

package/README.md

@@ -88,6 +88,10 @@ const checkout = await store.createCheckout(
 redirect(checkout.hostedUrl)
 ```
 
+Every `variantRef` must be a live one from the catalogue. An unknown or unpublished ref is refused
+with `400 VALIDATION_ERROR` listing the bad refs in `error.details.invalid`, so a typo fails on your
+server instead of in front of your buyer.
+
 Then, when the buyer comes back:
 
 ```ts
@@ -152,15 +156,39 @@ the check will fail in a way that looks like a key mismatch.
 Payloads are thin — refs only. Re-fetch through the API for detail, so a replayed delivery can never
 present stale figures as current.
 
+## Orders + keeping a local copy in sync
+
+`orders()` (server only, secret key) lists your own orders as a **delta read**: pass the largest
+`updatedAt` you have seen back as `updatedSince` and upsert by `ref` — the `>=` comparison repeats
+the boundary row on purpose so a same-second tie can never drop one. `products({ updatedSince })`
+works the same way for the catalogue.
+
+```ts
+let cursor = loadCursor() // null on first run = full backfill
+for (;;) {
+  const page = await store.orders(cursor ? { updatedSince: cursor, limit: 200 } : { limit: 200 })
+  for (const order of page) upsertByRef(order)
+  if (page.length < 200) break
+  cursor = page[page.length - 1].updatedAt
+}
+```
+
+Deletions never show up as absence in a delta page: they arrive as the `product.deleted` and
+`order.deleted` webhooks — remove those refs from your copy when they land. FrontDesk stays the
+source of truth; on any conflict, its row wins.
+
+Confirming a single purchase is still `getCheckout(ref)`, not a scan of `orders()`.
+
 ## Test mode
 
-A `fd_sk_test_…` key opens a test checkout. The hosted page shows a test banner and a
-**Simulate a successful payment** button, so you can build the whole loop with no bank account and no
-spend.
+A `fd_sk_test_…` key opens a test checkout that completes with a **real charge on the provider's
+sandbox** — pay it with a Paystack test card (the popup offers a Success option). There is exactly
+one way to finish a checkout in either mode.
 
-A simulated payment completes the session, sets a synthetic `test_ord_…` ref, and fires
-`checkout.completed` with `"test": true`. It creates **no order**, credits nobody and posts no ledger
-entry — so do not try to fetch that order ref. Test mode proves your integration, not fulfilment.
+The order it creates is REAL and marked `test` everywhere: no money moves, nothing is held from
+stock, and `checkout.completed` fires with the real `orderRef`. Test orders show under a Test badge
+in the portal, only a test key can read them (`orders()` never mixes envs), and they are
+hard-deleted after 90 days — the `order.deleted` webhook tells your mirror when that happens.
 
 ---
 

package/dist/index.d.mts

@@ -852,6 +852,9 @@ interface PublicProductSummary {
     ratingAvg?: number;
     /** Published review count behind `ratingAvg`. Absent under the floor, for the same reason. */
     ratingCount?: number;
+    /** Last change to the product or its variants (ISO). On GET /v1/store/products this is the
+     *  `updatedSince` delta cursor: pass the largest value you have seen back to get what changed. */
+    updatedAt?: string;
 }
 type CollectionCoverKind = 'image' | 'video';
 /** Buyer-facing collection in the storefront payload / public endpoints. */
@@ -890,6 +893,14 @@ interface DeliveryZone {
      *  payloads and on single-currency stores. */
     prices?: ZoneFee[];
 }
+/**
+ * Store order lifecycle — the union of the standard product-cart axis (pending → paid → fulfilled) and
+ * the package-BOOKING axis (requested → awaiting_payment → confirmed → in_progress → completed). One
+ * table (store_orders) carries both since Unified Products; the DB enum matches this set.
+ */
+type StoreOrderStatus = 'pending' | 'awaiting_payment' | 'requested' | 'accepted' | 'declined' | 'confirmed' | 'in_progress' | 'paid' | 'completed' | 'fulfilled' | 'cancelled' | 'expired' | 'refunded' | 'archived'
+/** Held while a Save For It plan funds toward this product (no stock reserved); flips to `paid` on completion. */
+ | 'saving';
 interface StoreCheckoutItem {
     variantRef: string;
     quantity: number;
@@ -909,6 +920,14 @@ interface StoreShippingAddress {
     lat?: number | null;
     lng?: number | null;
 }
+/** `awaiting_stock` = paid, but the item was sold out when the Save For It plan completed. The merchant
+ *  owes a unit they do not have; the order must stay OUT of the ship-now queue until they restock, at
+ *  which point it clears back to `unfulfilled` on its own. */
+/** `preordered` = the buyer deliberately bought something the merchant does not have yet (PO-1). Kept
+ *  distinct from `awaiting_stock` because the merchant's queue has to tell "a saver's plan completed and
+ *  I owe them" apart from "I pre-sold this on purpose", and because a part-paid pre-order must NOT rejoin
+ *  the ship-now queue on restock. */
+type StoreOrderFulfillmentStatus = 'unfulfilled' | 'fulfilled' | 'shipped' | 'delivered' | 'awaiting_stock' | 'preordered';
 
 /**
  * Packages — sellable offerings + priced tiers (options). Spec §13.1, §10.18 (PV-012/054).
@@ -996,7 +1015,12 @@ interface StoreTicketItem {
  */
 interface StoreEventCheckoutInput {
     tickets: StoreTicketItem[];
-    /** Products already attached to this event. Not the general catalogue. */
+    /**
+     * 🔴 NOT SUPPORTED YET — a non-empty array is refused with 400. It was declared with D18 and never
+     * wired: the hosted ticket page has no product concept, so anything sent here reached the buyer as
+     * neither a line nor a charge. Kept on the type because the contract is frozen (D13). Sell
+     * merchandise with a separate POST /v1/store/checkouts until the hosted page can carry it.
+     */
     products?: StoreCheckoutItem[] | null;
     contact: StoreCheckoutContact;
     /** Buyer DOB, when the event uses order-level age checks. YYYY-MM-DD. */
@@ -1072,6 +1096,64 @@ interface StoreCheckoutSessionView {
     createdAt: string;
 }
 
+/**
+ * GET /v1/store/orders — the merchant's own store orders, over their SECRET key.
+ *
+ * Built for delta sync (the Supabase mirror pulls through `updatedSince`), which is why the shape
+ * is a snapshot a mirror can upsert whole: refs, money in minor units, line snapshots that survive
+ * product edits. Live and test orders never mix — the key's env picks the set, exactly like
+ * checkouts. What is NOT here is deliberate: no provider references, no ledger refs, no wallet or
+ * payout figures — the standing constraint (no money surface behind an installed key) applies to
+ * this read exactly as it does to mirrors.
+ */
+interface StoreOrderRecordLine {
+    /** Snapshot refs: null when the product/variant was deleted after purchase. */
+    productRef: string | null;
+    productName: string;
+    variantRef: string | null;
+    variantName: string;
+    imageUrl: string | null;
+    quantity: number;
+    unitPriceMinor: number;
+    subtotalMinor: number;
+}
+interface StoreOrderRecord {
+    ref: string;
+    /** The short human reference shown to the buyer (receipts, support). */
+    shortReference: string;
+    /** The full lifecycle union covers BOTH axes: product carts (pending → paid → fulfilled) and
+     *  package bookings (requested → awaiting_payment → confirmed → in_progress → completed).
+     *  `saving` (an in-progress savings plan) never appears here — it is not an order yet. */
+    status: Exclude<StoreOrderStatus, 'saving'>;
+    fulfillmentStatus: StoreOrderFulfillmentStatus;
+    /** Paid with a test key: no real money moved, hard-deleted after 90 days (`order.deleted`). */
+    test: boolean;
+    currency: string;
+    subtotalMinor: number;
+    deliveryFeeMinor: number;
+    totalMinor: number;
+    buyer: {
+        name: string;
+        email: string | null;
+        phone: string | null;
+    };
+    needsDelivery: boolean;
+    shipping: {
+        address1: string | null;
+        address2: string | null;
+        city: string | null;
+        state: string | null;
+        country: string | null;
+        zoneRef: string | null;
+        zoneName: string | null;
+    } | null;
+    lines: StoreOrderRecordLine[];
+    paidAt: string | null;
+    createdAt: string;
+    /** The delta cursor: pass the largest value you have seen back as `updatedSince`. */
+    updatedAt: string;
+}
+
 /**
  * `POST /v1/store/customers/link` — attach the caller's own signed-in user to this workspace's
  * contacts (Supabase Phase 1c; design doc §7.6).
@@ -2399,7 +2481,16 @@ declare function createStoreClient(opts: StoreClientOptions): {
         idempotencyKey?: string;
     }) => Promise<T>;
     storefront: () => Promise<Storefront>;
-    products: () => Promise<PublicProductSummary[]>;
+    /**
+     * Every public product. With `updatedSince` (ISO 8601) it becomes a delta read for keeping a
+     * local copy fresh: ordered oldest change first, `limit` pages it (max 200), and each summary's
+     * `updatedAt` is the next cursor. The comparison is >= so the boundary row repeats — upsert by
+     * ref. Deleted products arrive as the `product.deleted` webhook, not as an absence here.
+     */
+    products: (params?: {
+        updatedSince?: string;
+        limit?: number;
+    }) => Promise<PublicProductSummary[]>;
     product: (slug: string) => Promise<PublicProduct>;
     productSlots: (slug: string, opts: {
         variantRef: string;
@@ -2462,6 +2553,17 @@ declare function createStoreClient(opts: StoreClientOptions): {
      * the contact existed before — it cannot be used to probe who is already a customer.
      */
     linkCustomer: (input: StoreCustomerLinkInput) => Promise<StoreCustomerLinkView>;
+    /**
+     * Your own store orders, as a delta read. SERVER ONLY — needs a secret key, and the key's env
+     * picks the set (a live key never sees test orders). Page forward on `updatedSince` using each
+     * order's `updatedAt` as the next cursor and upsert by ref (the >= comparison repeats the
+     * boundary row). A page shorter than `limit` means you are caught up. This is a sync and
+     * back-office read: to confirm a single purchase, keep using `getCheckout`.
+     */
+    orders: (params?: {
+        updatedSince?: string;
+        limit?: number;
+    }) => Promise<StoreOrderRecord[]>;
 };
 type StoreClient = ReturnType<typeof createStoreClient>;
 /**

package/dist/index.d.ts

@@ -852,6 +852,9 @@ interface PublicProductSummary {
     ratingAvg?: number;
     /** Published review count behind `ratingAvg`. Absent under the floor, for the same reason. */
     ratingCount?: number;
+    /** Last change to the product or its variants (ISO). On GET /v1/store/products this is the
+     *  `updatedSince` delta cursor: pass the largest value you have seen back to get what changed. */
+    updatedAt?: string;
 }
 type CollectionCoverKind = 'image' | 'video';
 /** Buyer-facing collection in the storefront payload / public endpoints. */
@@ -890,6 +893,14 @@ interface DeliveryZone {
      *  payloads and on single-currency stores. */
     prices?: ZoneFee[];
 }
+/**
+ * Store order lifecycle — the union of the standard product-cart axis (pending → paid → fulfilled) and
+ * the package-BOOKING axis (requested → awaiting_payment → confirmed → in_progress → completed). One
+ * table (store_orders) carries both since Unified Products; the DB enum matches this set.
+ */
+type StoreOrderStatus = 'pending' | 'awaiting_payment' | 'requested' | 'accepted' | 'declined' | 'confirmed' | 'in_progress' | 'paid' | 'completed' | 'fulfilled' | 'cancelled' | 'expired' | 'refunded' | 'archived'
+/** Held while a Save For It plan funds toward this product (no stock reserved); flips to `paid` on completion. */
+ | 'saving';
 interface StoreCheckoutItem {
     variantRef: string;
     quantity: number;
@@ -909,6 +920,14 @@ interface StoreShippingAddress {
     lat?: number | null;
     lng?: number | null;
 }
+/** `awaiting_stock` = paid, but the item was sold out when the Save For It plan completed. The merchant
+ *  owes a unit they do not have; the order must stay OUT of the ship-now queue until they restock, at
+ *  which point it clears back to `unfulfilled` on its own. */
+/** `preordered` = the buyer deliberately bought something the merchant does not have yet (PO-1). Kept
+ *  distinct from `awaiting_stock` because the merchant's queue has to tell "a saver's plan completed and
+ *  I owe them" apart from "I pre-sold this on purpose", and because a part-paid pre-order must NOT rejoin
+ *  the ship-now queue on restock. */
+type StoreOrderFulfillmentStatus = 'unfulfilled' | 'fulfilled' | 'shipped' | 'delivered' | 'awaiting_stock' | 'preordered';
 
 /**
  * Packages — sellable offerings + priced tiers (options). Spec §13.1, §10.18 (PV-012/054).
@@ -996,7 +1015,12 @@ interface StoreTicketItem {
  */
 interface StoreEventCheckoutInput {
     tickets: StoreTicketItem[];
-    /** Products already attached to this event. Not the general catalogue. */
+    /**
+     * 🔴 NOT SUPPORTED YET — a non-empty array is refused with 400. It was declared with D18 and never
+     * wired: the hosted ticket page has no product concept, so anything sent here reached the buyer as
+     * neither a line nor a charge. Kept on the type because the contract is frozen (D13). Sell
+     * merchandise with a separate POST /v1/store/checkouts until the hosted page can carry it.
+     */
     products?: StoreCheckoutItem[] | null;
     contact: StoreCheckoutContact;
     /** Buyer DOB, when the event uses order-level age checks. YYYY-MM-DD. */
@@ -1072,6 +1096,64 @@ interface StoreCheckoutSessionView {
     createdAt: string;
 }
 
+/**
+ * GET /v1/store/orders — the merchant's own store orders, over their SECRET key.
+ *
+ * Built for delta sync (the Supabase mirror pulls through `updatedSince`), which is why the shape
+ * is a snapshot a mirror can upsert whole: refs, money in minor units, line snapshots that survive
+ * product edits. Live and test orders never mix — the key's env picks the set, exactly like
+ * checkouts. What is NOT here is deliberate: no provider references, no ledger refs, no wallet or
+ * payout figures — the standing constraint (no money surface behind an installed key) applies to
+ * this read exactly as it does to mirrors.
+ */
+interface StoreOrderRecordLine {
+    /** Snapshot refs: null when the product/variant was deleted after purchase. */
+    productRef: string | null;
+    productName: string;
+    variantRef: string | null;
+    variantName: string;
+    imageUrl: string | null;
+    quantity: number;
+    unitPriceMinor: number;
+    subtotalMinor: number;
+}
+interface StoreOrderRecord {
+    ref: string;
+    /** The short human reference shown to the buyer (receipts, support). */
+    shortReference: string;
+    /** The full lifecycle union covers BOTH axes: product carts (pending → paid → fulfilled) and
+     *  package bookings (requested → awaiting_payment → confirmed → in_progress → completed).
+     *  `saving` (an in-progress savings plan) never appears here — it is not an order yet. */
+    status: Exclude<StoreOrderStatus, 'saving'>;
+    fulfillmentStatus: StoreOrderFulfillmentStatus;
+    /** Paid with a test key: no real money moved, hard-deleted after 90 days (`order.deleted`). */
+    test: boolean;
+    currency: string;
+    subtotalMinor: number;
+    deliveryFeeMinor: number;
+    totalMinor: number;
+    buyer: {
+        name: string;
+        email: string | null;
+        phone: string | null;
+    };
+    needsDelivery: boolean;
+    shipping: {
+        address1: string | null;
+        address2: string | null;
+        city: string | null;
+        state: string | null;
+        country: string | null;
+        zoneRef: string | null;
+        zoneName: string | null;
+    } | null;
+    lines: StoreOrderRecordLine[];
+    paidAt: string | null;
+    createdAt: string;
+    /** The delta cursor: pass the largest value you have seen back as `updatedSince`. */
+    updatedAt: string;
+}
+
 /**
  * `POST /v1/store/customers/link` — attach the caller's own signed-in user to this workspace's
  * contacts (Supabase Phase 1c; design doc §7.6).
@@ -2399,7 +2481,16 @@ declare function createStoreClient(opts: StoreClientOptions): {
         idempotencyKey?: string;
     }) => Promise<T>;
     storefront: () => Promise<Storefront>;
-    products: () => Promise<PublicProductSummary[]>;
+    /**
+     * Every public product. With `updatedSince` (ISO 8601) it becomes a delta read for keeping a
+     * local copy fresh: ordered oldest change first, `limit` pages it (max 200), and each summary's
+     * `updatedAt` is the next cursor. The comparison is >= so the boundary row repeats — upsert by
+     * ref. Deleted products arrive as the `product.deleted` webhook, not as an absence here.
+     */
+    products: (params?: {
+        updatedSince?: string;
+        limit?: number;
+    }) => Promise<PublicProductSummary[]>;
     product: (slug: string) => Promise<PublicProduct>;
     productSlots: (slug: string, opts: {
         variantRef: string;
@@ -2462,6 +2553,17 @@ declare function createStoreClient(opts: StoreClientOptions): {
      * the contact existed before — it cannot be used to probe who is already a customer.
      */
     linkCustomer: (input: StoreCustomerLinkInput) => Promise<StoreCustomerLinkView>;
+    /**
+     * Your own store orders, as a delta read. SERVER ONLY — needs a secret key, and the key's env
+     * picks the set (a live key never sees test orders). Page forward on `updatedSince` using each
+     * order's `updatedAt` as the next cursor and upsert by ref (the >= comparison repeats the
+     * boundary row). A page shorter than `limit` means you are caught up. This is a sync and
+     * back-office read: to confirm a single purchase, keep using `getCheckout`.
+     */
+    orders: (params?: {
+        updatedSince?: string;
+        limit?: number;
+    }) => Promise<StoreOrderRecord[]>;
 };
 type StoreClient = ReturnType<typeof createStoreClient>;
 /**

package/dist/index.js

@@ -83,7 +83,19 @@ function createStoreClient(opts) {
     request,
     // ------------------------------------------------------------- read (fd_pk_)
     storefront: /* @__PURE__ */ __name(() => request("/store/storefront"), "storefront"),
-    products: /* @__PURE__ */ __name(() => request("/store/products"), "products"),
+    /**
+    * Every public product. With `updatedSince` (ISO 8601) it becomes a delta read for keeping a
+    * local copy fresh: ordered oldest change first, `limit` pages it (max 200), and each summary's
+    * `updatedAt` is the next cursor. The comparison is >= so the boundary row repeats — upsert by
+    * ref. Deleted products arrive as the `product.deleted` webhook, not as an absence here.
+    */
+    products: /* @__PURE__ */ __name((params) => {
+      const q = new URLSearchParams();
+      if (params?.updatedSince) q.set("updatedSince", params.updatedSince);
+      if (params?.limit) q.set("limit", String(params.limit));
+      const qs = q.toString();
+      return request(`/store/products${qs ? `?${qs}` : ""}`);
+    }, "products"),
     product: /* @__PURE__ */ __name((slug) => request(`/store/products/${enc(slug)}`), "product"),
     productSlots: /* @__PURE__ */ __name((slug, opts2) => request(`/store/products/${enc(slug)}/slots?variantRef=${enc(opts2.variantRef)}&date=${enc(opts2.date)}`), "productSlots"),
     collections: /* @__PURE__ */ __name(() => request("/store/collections"), "collections"),
@@ -160,7 +172,21 @@ function createStoreClient(opts) {
     linkCustomer: /* @__PURE__ */ __name((input) => request("/store/customers/link", {
       method: "POST",
       body: JSON.stringify(input)
-    }), "linkCustomer")
+    }), "linkCustomer"),
+    /**
+    * Your own store orders, as a delta read. SERVER ONLY — needs a secret key, and the key's env
+    * picks the set (a live key never sees test orders). Page forward on `updatedSince` using each
+    * order's `updatedAt` as the next cursor and upsert by ref (the >= comparison repeats the
+    * boundary row). A page shorter than `limit` means you are caught up. This is a sync and
+    * back-office read: to confirm a single purchase, keep using `getCheckout`.
+    */
+    orders: /* @__PURE__ */ __name((params) => {
+      const q = new URLSearchParams();
+      if (params?.updatedSince) q.set("updatedSince", params.updatedSince);
+      if (params?.limit) q.set("limit", String(params.limit));
+      const qs = q.toString();
+      return request(`/store/orders${qs ? `?${qs}` : ""}`);
+    }, "orders")
   };
 }
 __name(createStoreClient, "createStoreClient");

package/dist/index.mjs

@@ -49,7 +49,19 @@ function createStoreClient(opts) {
     request,
     // ------------------------------------------------------------- read (fd_pk_)
     storefront: /* @__PURE__ */ __name(() => request("/store/storefront"), "storefront"),
-    products: /* @__PURE__ */ __name(() => request("/store/products"), "products"),
+    /**
+    * Every public product. With `updatedSince` (ISO 8601) it becomes a delta read for keeping a
+    * local copy fresh: ordered oldest change first, `limit` pages it (max 200), and each summary's
+    * `updatedAt` is the next cursor. The comparison is >= so the boundary row repeats — upsert by
+    * ref. Deleted products arrive as the `product.deleted` webhook, not as an absence here.
+    */
+    products: /* @__PURE__ */ __name((params) => {
+      const q = new URLSearchParams();
+      if (params?.updatedSince) q.set("updatedSince", params.updatedSince);
+      if (params?.limit) q.set("limit", String(params.limit));
+      const qs = q.toString();
+      return request(`/store/products${qs ? `?${qs}` : ""}`);
+    }, "products"),
     product: /* @__PURE__ */ __name((slug) => request(`/store/products/${enc(slug)}`), "product"),
     productSlots: /* @__PURE__ */ __name((slug, opts2) => request(`/store/products/${enc(slug)}/slots?variantRef=${enc(opts2.variantRef)}&date=${enc(opts2.date)}`), "productSlots"),
     collections: /* @__PURE__ */ __name(() => request("/store/collections"), "collections"),
@@ -126,7 +138,21 @@ function createStoreClient(opts) {
     linkCustomer: /* @__PURE__ */ __name((input) => request("/store/customers/link", {
       method: "POST",
       body: JSON.stringify(input)
-    }), "linkCustomer")
+    }), "linkCustomer"),
+    /**
+    * Your own store orders, as a delta read. SERVER ONLY — needs a secret key, and the key's env
+    * picks the set (a live key never sees test orders). Page forward on `updatedSince` using each
+    * order's `updatedAt` as the next cursor and upsert by ref (the >= comparison repeats the
+    * boundary row). A page shorter than `limit` means you are caught up. This is a sync and
+    * back-office read: to confirm a single purchase, keep using `getCheckout`.
+    */
+    orders: /* @__PURE__ */ __name((params) => {
+      const q = new URLSearchParams();
+      if (params?.updatedSince) q.set("updatedSince", params.updatedSince);
+      if (params?.limit) q.set("limit", String(params.limit));
+      const qs = q.toString();
+      return request(`/store/orders${qs ? `?${qs}` : ""}`);
+    }, "orders")
   };
 }
 __name(createStoreClient, "createStoreClient");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontdesk-africa/store-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed client for the FrontDesk Storefront API: catalogue, events, forms, hosted checkout and signed webhooks.",
   "license": "MIT",
   "homepage": "https://api.frontdesk.africa/v1/store/docs",