@frontdesk-africa/store-js 0.1.0 → 0.3.0

package/README.md

@@ -49,6 +49,27 @@ const item = await store.product('blue-mug')
 
 You never choose the workspace: the key does. Any workspace ref you send is ignored.
 
+### Products sold in several dimensions
+
+A product whose merchant sells it by Size *and* Colour carries an `options` array: one entry per
+group, each with its own `display` (`dropdown`, `text`, `color`, `image`) and its list of values.
+The buyer picks one value per group, and that set resolves to a single variant — the one whose
+`optionValueRefs` holds exactly those value refs. Checkout is unchanged: you still send that
+variant's `ref`.
+
+```ts
+const item = await store.product('shirt-dress')
+
+// options is absent on an ordinary product — render item.variants as a flat list then.
+const picked = { [item.options![0].ref]: 'value-ref-small', [item.options![1].ref]: 'value-ref-teal' }
+const chosen = item.variants.find(
+  (v) => v.optionValueRefs?.length === 2 && v.optionValueRefs.every((r) => Object.values(picked).includes(r)),
+)
+```
+
+Dim a value when every variant still holding it is `soldOut` (or has no price in the buyer's
+currency), and swap your gallery to a value's `media` when it is selected.
+
 ## Checkout (server)
 
 You never handle card details and you never price a cart. The buyer pays on a FrontDesk-hosted page
@@ -67,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
@@ -131,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

@@ -576,7 +576,13 @@ type PublicProductInfo = Omit<ProductInfoView, 'hsCode'>;
 /** How a package product's options are chosen: one tier (radio) vs a menu (pick many + quantity). */
 type SelectionMode = 'choose_one' | 'choose_many';
 /** How the storefront draws a product's option picker. A variant missing an image/hex falls back to text. */
-type VariantDisplay = 'text' | 'image' | 'color';
+type VariantDisplay = 'text' | 'image' | 'color' | 'dropdown';
+/**
+ * Multi-group variations: how ONE variation group's picker is drawn. Per-group (Size = dropdown,
+ * Color = swatches), unlike the legacy product-level VariantDisplay, which keeps governing products
+ * that have no groups. A value missing its hex/image falls back to a text chip.
+ */
+type OptionGroupDisplay = 'dropdown' | 'text' | 'color' | 'image';
 /** Product/option payment modes: the shipped package modes + Pay Later (Save-For-It deferred). */
 type ProductPricingMode = PackagePricingMode | 'pay_later';
 interface ProductAddonOption {
@@ -645,6 +651,23 @@ interface StoreAvailabilitySummary {
     leadTimeMinutes: number;
 }
 type PreorderDepositType = 'percent' | 'fixed';
+interface PublicProductOptionValue {
+    ref: string;
+    label: string;
+    /** '#RRGGBB' for the colour swatch under display 'color'; absent/null falls back to a text chip. */
+    swatchHex?: string | null;
+    /** Selecting this value swaps the product gallery to these images. Absent = keep the gallery. */
+    media?: string[];
+}
+/** One variation axis of a multi-group product (e.g. Size, Color). The buyer picks one value per
+ *  group; the picked set resolves to exactly one variant (see PublicProductVariant.optionValueRefs). */
+interface PublicProductOptionGroup {
+    ref: string;
+    name: string;
+    /** How to draw THIS group's picker: a select, text chips, colour swatches, or image tiles. */
+    display: OptionGroupDisplay;
+    values: PublicProductOptionValue[];
+}
 interface PublicProductVariant {
     ref: string;
     name: string;
@@ -668,6 +691,9 @@ interface PublicProductVariant {
     availableQty?: number | null;
     /** '#RRGGBB' for the colour swatch; null under 'color' mode falls back to a text chip. */
     swatchHex?: string | null;
+    /** Multi-group products: the option values this combination is made of (one value ref per group,
+     *  in group sort order). Absent on ungrouped products — render the flat `variants` picker then. */
+    optionValueRefs?: string[];
     description?: string | null;
     badge?: string | null;
     features?: PackageFeature[];
@@ -702,6 +728,10 @@ interface PublicProduct {
     selectionMode?: SelectionMode;
     /** How the option picker is drawn: text chips (default), image swatches, or colour swatches. */
     variantDisplay?: VariantDisplay;
+    /** Multi-group variations: one picker per group, each drawn per its `display`. When present, the
+     *  buyer picks one value per group and the picks resolve to a variant via `optionValueRefs`; when
+     *  absent, render the flat `variants` list exactly as before (existing storefronts keep working). */
+    options?: PublicProductOptionGroup[];
     schedulingEnabled?: boolean;
     /** Add-on groups the buyer can pick from (option-scoped groups carry variantRef). */
     addonGroups?: ProductAddonGroup[];
@@ -822,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. */
@@ -860,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;
@@ -879,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).
@@ -966,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. */
@@ -1042,6 +1096,92 @@ 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).
+ *
+ * TRUST MODEL: the caller holds a secret key, i.e. IS the merchant (or their installed backend).
+ * They can already create and edit their own contacts in the portal, so accepting their assertion
+ * that `email` was verified by THEIR auth system delegates nothing they do not have. The identity
+ * being asserted must still be verified on the caller's side — that is stated at the API boundary,
+ * not enforced here, because we cannot see their auth system.
+ */
+interface StoreCustomerLinkInput {
+    /** The email the CALLER's auth system verified. Never a guessed or user-typed-but-unverified one. */
+    email: string;
+    /** The caller's own user id (e.g. a Supabase Auth user id). Idempotency key: same ref, same link. */
+    externalRef: string;
+    /** Optional display name; wins over an empty contact name, never overwrites a set one. */
+    name?: string;
+    phone?: string;
+}
+interface StoreCustomerLinkView {
+    /** The buyer's account ref — what `customer.linked` carries and checkout accepts. */
+    customerRef: string;
+    /** The workspace contact this landed on. */
+    contactRef: string;
+    /** True when this call created the link; false when the externalRef was already linked. */
+    alreadyLinked: boolean;
+}
+
 /** A resolved commission rate (after applying any per-workspace override over the platform default). */
 interface EventCommissionConfig {
     /** Percentage cut on the gross (0..100). */
@@ -2341,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;
@@ -2398,6 +2547,23 @@ declare function createStoreClient(opts: StoreClientOptions): {
      * stock until the session lapses. Cancelling an already-paid checkout returns 409.
      */
     cancelCheckout: (ref: string) => Promise<StoreCheckoutSessionView>;
+    /**
+     * Attach YOUR OWN signed-in user to this workspace's contacts. SERVER ONLY. Only send an email
+     * your auth system verified. Idempotent per externalRef, and the response is identical whether
+     * 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

@@ -576,7 +576,13 @@ type PublicProductInfo = Omit<ProductInfoView, 'hsCode'>;
 /** How a package product's options are chosen: one tier (radio) vs a menu (pick many + quantity). */
 type SelectionMode = 'choose_one' | 'choose_many';
 /** How the storefront draws a product's option picker. A variant missing an image/hex falls back to text. */
-type VariantDisplay = 'text' | 'image' | 'color';
+type VariantDisplay = 'text' | 'image' | 'color' | 'dropdown';
+/**
+ * Multi-group variations: how ONE variation group's picker is drawn. Per-group (Size = dropdown,
+ * Color = swatches), unlike the legacy product-level VariantDisplay, which keeps governing products
+ * that have no groups. A value missing its hex/image falls back to a text chip.
+ */
+type OptionGroupDisplay = 'dropdown' | 'text' | 'color' | 'image';
 /** Product/option payment modes: the shipped package modes + Pay Later (Save-For-It deferred). */
 type ProductPricingMode = PackagePricingMode | 'pay_later';
 interface ProductAddonOption {
@@ -645,6 +651,23 @@ interface StoreAvailabilitySummary {
     leadTimeMinutes: number;
 }
 type PreorderDepositType = 'percent' | 'fixed';
+interface PublicProductOptionValue {
+    ref: string;
+    label: string;
+    /** '#RRGGBB' for the colour swatch under display 'color'; absent/null falls back to a text chip. */
+    swatchHex?: string | null;
+    /** Selecting this value swaps the product gallery to these images. Absent = keep the gallery. */
+    media?: string[];
+}
+/** One variation axis of a multi-group product (e.g. Size, Color). The buyer picks one value per
+ *  group; the picked set resolves to exactly one variant (see PublicProductVariant.optionValueRefs). */
+interface PublicProductOptionGroup {
+    ref: string;
+    name: string;
+    /** How to draw THIS group's picker: a select, text chips, colour swatches, or image tiles. */
+    display: OptionGroupDisplay;
+    values: PublicProductOptionValue[];
+}
 interface PublicProductVariant {
     ref: string;
     name: string;
@@ -668,6 +691,9 @@ interface PublicProductVariant {
     availableQty?: number | null;
     /** '#RRGGBB' for the colour swatch; null under 'color' mode falls back to a text chip. */
     swatchHex?: string | null;
+    /** Multi-group products: the option values this combination is made of (one value ref per group,
+     *  in group sort order). Absent on ungrouped products — render the flat `variants` picker then. */
+    optionValueRefs?: string[];
     description?: string | null;
     badge?: string | null;
     features?: PackageFeature[];
@@ -702,6 +728,10 @@ interface PublicProduct {
     selectionMode?: SelectionMode;
     /** How the option picker is drawn: text chips (default), image swatches, or colour swatches. */
     variantDisplay?: VariantDisplay;
+    /** Multi-group variations: one picker per group, each drawn per its `display`. When present, the
+     *  buyer picks one value per group and the picks resolve to a variant via `optionValueRefs`; when
+     *  absent, render the flat `variants` list exactly as before (existing storefronts keep working). */
+    options?: PublicProductOptionGroup[];
     schedulingEnabled?: boolean;
     /** Add-on groups the buyer can pick from (option-scoped groups carry variantRef). */
     addonGroups?: ProductAddonGroup[];
@@ -822,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. */
@@ -860,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;
@@ -879,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).
@@ -966,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. */
@@ -1042,6 +1096,92 @@ 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).
+ *
+ * TRUST MODEL: the caller holds a secret key, i.e. IS the merchant (or their installed backend).
+ * They can already create and edit their own contacts in the portal, so accepting their assertion
+ * that `email` was verified by THEIR auth system delegates nothing they do not have. The identity
+ * being asserted must still be verified on the caller's side — that is stated at the API boundary,
+ * not enforced here, because we cannot see their auth system.
+ */
+interface StoreCustomerLinkInput {
+    /** The email the CALLER's auth system verified. Never a guessed or user-typed-but-unverified one. */
+    email: string;
+    /** The caller's own user id (e.g. a Supabase Auth user id). Idempotency key: same ref, same link. */
+    externalRef: string;
+    /** Optional display name; wins over an empty contact name, never overwrites a set one. */
+    name?: string;
+    phone?: string;
+}
+interface StoreCustomerLinkView {
+    /** The buyer's account ref — what `customer.linked` carries and checkout accepts. */
+    customerRef: string;
+    /** The workspace contact this landed on. */
+    contactRef: string;
+    /** True when this call created the link; false when the externalRef was already linked. */
+    alreadyLinked: boolean;
+}
+
 /** A resolved commission rate (after applying any per-workspace override over the platform default). */
 interface EventCommissionConfig {
     /** Percentage cut on the gross (0..100). */
@@ -2341,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;
@@ -2398,6 +2547,23 @@ declare function createStoreClient(opts: StoreClientOptions): {
      * stock until the session lapses. Cancelling an already-paid checkout returns 409.
      */
     cancelCheckout: (ref: string) => Promise<StoreCheckoutSessionView>;
+    /**
+     * Attach YOUR OWN signed-in user to this workspace's contacts. SERVER ONLY. Only send an email
+     * your auth system verified. Idempotent per externalRef, and the response is identical whether
+     * 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"),
@@ -151,7 +163,30 @@ function createStoreClient(opts) {
     */
     cancelCheckout: /* @__PURE__ */ __name((ref) => request(`/store/checkouts/${enc(ref)}/cancel`, {
       method: "POST"
-    }), "cancelCheckout")
+    }), "cancelCheckout"),
+    /**
+    * Attach YOUR OWN signed-in user to this workspace's contacts. SERVER ONLY. Only send an email
+    * your auth system verified. Idempotent per externalRef, and the response is identical whether
+    * the contact existed before — it cannot be used to probe who is already a customer.
+    */
+    linkCustomer: /* @__PURE__ */ __name((input) => request("/store/customers/link", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }), "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"),
@@ -117,7 +129,30 @@ function createStoreClient(opts) {
     */
     cancelCheckout: /* @__PURE__ */ __name((ref) => request(`/store/checkouts/${enc(ref)}/cancel`, {
       method: "POST"
-    }), "cancelCheckout")
+    }), "cancelCheckout"),
+    /**
+    * Attach YOUR OWN signed-in user to this workspace's contacts. SERVER ONLY. Only send an email
+    * your auth system verified. Idempotent per externalRef, and the response is identical whether
+    * the contact existed before — it cannot be used to probe who is already a customer.
+    */
+    linkCustomer: /* @__PURE__ */ __name((input) => request("/store/customers/link", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }), "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.1.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",