@frontdesk-africa/store-js 0.2.0 → 0.4.0

package/README.md

@@ -16,7 +16,7 @@ MCP: `POST /v1/store/mcp`.
 
 | Key | Where it goes | What it does |
 |---|---|---|
-| `fd_pk_…` | your **page**, safe to ship | read-only, and only from origins the merchant registered |
+| `fd_pk_…` | your **page**, safe to ship | reads, plus free event registration, and only from origins the merchant registered |
 | `fd_sk_…` | your **server**, never a page | opens checkouts |
 
 A publishable key is designed to be public. It is locked to exact origins, and an empty origin list
@@ -70,6 +70,28 @@ const chosen = item.variants.find(
 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.
 
+## Free event registration (browser)
+
+A free RSVP page needs no server. Read the event, offer the tiers whose `kind` is `free`, ask the
+questions in each tier's `formFields`, and post the registration with the publishable key.
+
+```ts
+const event = await store.event('open-house')
+const tier = event.ticketTypes.find((t) => t.kind === 'free')!
+
+const done = await store.registerForEvent(event.slug, {
+  tickets: [{ ticketTypeRef: tier.ref, quantity: 2, attendees: [{}, { name: 'Tunde Obi', email: 'tunde@example.com' }] }],
+  contact: { name: 'Ada Obi', email: 'ada@example.com', phone: '+2348120700080' },
+  responses: { piggyvest_user: 'Yes', first_time: 'No' }, // keyed by formFields[].key
+})
+// done.status → 'confirmed' | 'pending_approval' | 'waitlisted'; done.reference → 'EV-7F3A2C'
+```
+
+FrontDesk emails the guest their confirmation, calendar invite and ticket. A paid tier is refused
+with `TIER_REQUIRES_PAYMENT`: open a checkout for it from your server. Registering the same email
+twice returns the same answer and re-sends the confirmation instead of issuing a second seat, so a
+retry is safe. To read registrations back, subscribe to the `attendee.registered` webhook.
+
 ## Checkout (server)
 
 You never handle card details and you never price a cart. The buyer pays on a FrontDesk-hosted page
@@ -88,6 +110,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
@@ -98,6 +124,10 @@ if (done.status === 'completed') fulfil(done.orderRef)
 **Do not fulfil on the redirect itself.** It is a browser navigation: it can be lost, replayed or
 forged. `getCheckout` or the `checkout.completed` webhook are the only proof.
 
+Only a paid checkout reaches `returnUrl`. A buyer who backs out of a payment comes back to the hosted
+page with the same cart and a link to your site, a retry there pays the same order rather than opening
+another, and reopening `hostedUrl` resumes it, including a bank transfer already started.
+
 Event tickets work the same way, with the event telling you what to collect first:
 
 ```ts
@@ -152,15 +182,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.
 
 ---
 
@@ -180,6 +234,10 @@ Paste this, with your key:
 > Pages: home rendering `GET /v1/store/storefront`, a product list from `GET /v1/store/products`, and
 > a product page from `GET /v1/store/products/{slug}`.
 >
+> For a free event RSVP page, call `POST /v1/store/events/{slug}/register` straight from the
+> browser with the publishable key, sending `tickets`, `contact` and `responses` keyed by each
+> tier's `formFields[].key`. FrontDesk sends the confirmation email itself.
+>
 > For checkout, call `POST /v1/store/checkouts` **from a server route, never the browser**, using the
 > secret key, with an `Idempotency-Key` header derived from the cart id. Redirect the buyer to the
 > `hostedUrl` you get back. Do not build a payment form and do not ask for card details.

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).
@@ -965,7 +984,8 @@ interface StoreCheckoutSessionInput {
     contact?: Partial<StoreCheckoutContact> | null;
     deliveryZoneRef?: string | null;
     shipping?: StoreShippingAddress | null;
-    /** Must be a currency the store accepts. Omit for the store primary. */
+    /** The currency the buyer pays in. Must be one the store accepts, with every item priced in it, else
+     *  VALIDATION_ERROR. Omit for the store primary. Fixed at open; never re-priced in another currency. */
     currency?: string | null;
     /** Where we send the buyer after payment. Must be https (or localhost while testing). */
     returnUrl: string;
@@ -996,7 +1016,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. */
@@ -1059,6 +1084,7 @@ interface StoreCheckoutSessionView {
     /** Send the buyer here. Valid until `expiresAt`. */
     hostedUrl: string;
     returnUrl: string;
+    /** The currency the checkout is priced and charged in. Always set on a product checkout; immutable. */
     currency: string | null;
     /**
      * The order this became, once the buyer paid. Null while open.
@@ -1072,6 +1098,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).
@@ -2365,6 +2449,52 @@ interface PublicForm {
     uploadToken?: string;
 }
 
+/**
+ * FrontDesk public storefront contract (Storefront API §3.2). These shapes are what a
+ * merchant-built frontend receives, so they are additive-only: never remove a field, never retype
+ * one, never narrow an enum. Guarded by `pnpm --filter pro-api store-contract:check`.
+ */
+
+type StoreEventRegistrationStatus = 'confirmed' | 'pending_approval' | 'waitlisted';
+/** Like StoreCheckoutContact, except a phone may stand in for the email. One of the two is required. */
+interface StoreEventRegistrationContact {
+    name: string;
+    /** Receives the confirmation, the calendar invite and the ticket. */
+    email?: string | null;
+    /** Receives an SMS confirmation when the event sends them, or when there is no email. */
+    phone?: string | null;
+}
+/**
+ * A subset of StoreEventCheckoutInput: the same `tickets[]` (positional `attendees`, length
+ * quantity x groupSize, a blank entry keeps that seat under the registrant), no returnUrl, no
+ * currency, no discountCode. Every tier must be FREE.
+ */
+interface StoreEventRegistrationInput {
+    tickets: StoreTicketItem[];
+    contact: StoreEventRegistrationContact;
+    /** YYYY-MM-DD. Required when a chosen tier sets minAge and the event dobMode is order. */
+    dateOfBirth?: string | null;
+    /** Answers to the chosen tiers' formFields, keyed by each field's `key`. */
+    responses?: Record<string, unknown> | null;
+    /** Codes that reveal hidden or invite-only tiers. */
+    unlockCodes?: string[] | null;
+    /** Affiliate code from a share link. Ignored if unknown. */
+    promoterCode?: string | null;
+}
+interface StoreEventRegistrationView {
+    eventSlug: string;
+    eventRef: string;
+    ticketTypeRef: string;
+    status: StoreEventRegistrationStatus;
+    /** The guest's short reference (EV-XXXXXX), the same one printed on their email. Never a ticket token. */
+    reference: string;
+    /** Seats issued by this registration (quantity x groupSize across the lines). */
+    attendeeCount: number;
+    /** True from a test key: everything was validated, nothing was written, nothing was sent. */
+    test: boolean;
+    message: string;
+}
+
 /**
  * Typed client for the FrontDesk Storefront API.
  *
@@ -2399,7 +2529,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;
@@ -2423,6 +2562,16 @@ declare function createStoreClient(opts: StoreClientOptions): {
     availability: (variantRefs: string[]) => Promise<PublicStoreAvailability>;
     /** The payment rails this workspace can charge, for rendering your own picker (headless only). */
     paymentMethods: (currency?: string) => Promise<string[]>;
+    /**
+     * Register a guest for a FREE event tier. The one write a publishable key may make, so call it
+     * straight from the page. `tickets` has the checkout shape (positional `attendees`, length
+     * quantity x groupSize); `responses` answers the tier's `formFields` by `key`. A paid tier is
+     * refused with TIER_REQUIRES_PAYMENT: open a checkout for it from your server. Duplicates are
+     * quiet (an email that already holds a seat gets the same answer and its confirmation again,
+     * never a second seat), so retrying is safe and no idempotency key is needed. FrontDesk sends
+     * the confirmation, the .ics invite and the ticket itself.
+     */
+    registerForEvent: (slug: string, input: StoreEventRegistrationInput) => Promise<StoreEventRegistrationView>;
     /**
      * Open a hosted checkout. SERVER ONLY — needs a secret key.
      *
@@ -2462,6 +2611,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).
@@ -965,7 +984,8 @@ interface StoreCheckoutSessionInput {
     contact?: Partial<StoreCheckoutContact> | null;
     deliveryZoneRef?: string | null;
     shipping?: StoreShippingAddress | null;
-    /** Must be a currency the store accepts. Omit for the store primary. */
+    /** The currency the buyer pays in. Must be one the store accepts, with every item priced in it, else
+     *  VALIDATION_ERROR. Omit for the store primary. Fixed at open; never re-priced in another currency. */
     currency?: string | null;
     /** Where we send the buyer after payment. Must be https (or localhost while testing). */
     returnUrl: string;
@@ -996,7 +1016,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. */
@@ -1059,6 +1084,7 @@ interface StoreCheckoutSessionView {
     /** Send the buyer here. Valid until `expiresAt`. */
     hostedUrl: string;
     returnUrl: string;
+    /** The currency the checkout is priced and charged in. Always set on a product checkout; immutable. */
     currency: string | null;
     /**
      * The order this became, once the buyer paid. Null while open.
@@ -1072,6 +1098,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).
@@ -2365,6 +2449,52 @@ interface PublicForm {
     uploadToken?: string;
 }
 
+/**
+ * FrontDesk public storefront contract (Storefront API §3.2). These shapes are what a
+ * merchant-built frontend receives, so they are additive-only: never remove a field, never retype
+ * one, never narrow an enum. Guarded by `pnpm --filter pro-api store-contract:check`.
+ */
+
+type StoreEventRegistrationStatus = 'confirmed' | 'pending_approval' | 'waitlisted';
+/** Like StoreCheckoutContact, except a phone may stand in for the email. One of the two is required. */
+interface StoreEventRegistrationContact {
+    name: string;
+    /** Receives the confirmation, the calendar invite and the ticket. */
+    email?: string | null;
+    /** Receives an SMS confirmation when the event sends them, or when there is no email. */
+    phone?: string | null;
+}
+/**
+ * A subset of StoreEventCheckoutInput: the same `tickets[]` (positional `attendees`, length
+ * quantity x groupSize, a blank entry keeps that seat under the registrant), no returnUrl, no
+ * currency, no discountCode. Every tier must be FREE.
+ */
+interface StoreEventRegistrationInput {
+    tickets: StoreTicketItem[];
+    contact: StoreEventRegistrationContact;
+    /** YYYY-MM-DD. Required when a chosen tier sets minAge and the event dobMode is order. */
+    dateOfBirth?: string | null;
+    /** Answers to the chosen tiers' formFields, keyed by each field's `key`. */
+    responses?: Record<string, unknown> | null;
+    /** Codes that reveal hidden or invite-only tiers. */
+    unlockCodes?: string[] | null;
+    /** Affiliate code from a share link. Ignored if unknown. */
+    promoterCode?: string | null;
+}
+interface StoreEventRegistrationView {
+    eventSlug: string;
+    eventRef: string;
+    ticketTypeRef: string;
+    status: StoreEventRegistrationStatus;
+    /** The guest's short reference (EV-XXXXXX), the same one printed on their email. Never a ticket token. */
+    reference: string;
+    /** Seats issued by this registration (quantity x groupSize across the lines). */
+    attendeeCount: number;
+    /** True from a test key: everything was validated, nothing was written, nothing was sent. */
+    test: boolean;
+    message: string;
+}
+
 /**
  * Typed client for the FrontDesk Storefront API.
  *
@@ -2399,7 +2529,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;
@@ -2423,6 +2562,16 @@ declare function createStoreClient(opts: StoreClientOptions): {
     availability: (variantRefs: string[]) => Promise<PublicStoreAvailability>;
     /** The payment rails this workspace can charge, for rendering your own picker (headless only). */
     paymentMethods: (currency?: string) => Promise<string[]>;
+    /**
+     * Register a guest for a FREE event tier. The one write a publishable key may make, so call it
+     * straight from the page. `tickets` has the checkout shape (positional `attendees`, length
+     * quantity x groupSize); `responses` answers the tier's `formFields` by `key`. A paid tier is
+     * refused with TIER_REQUIRES_PAYMENT: open a checkout for it from your server. Duplicates are
+     * quiet (an email that already holds a seat gets the same answer and its confirmation again,
+     * never a second seat), so retrying is safe and no idempotency key is needed. FrontDesk sends
+     * the confirmation, the .ics invite and the ticket itself.
+     */
+    registerForEvent: (slug: string, input: StoreEventRegistrationInput) => Promise<StoreEventRegistrationView>;
     /**
      * Open a hosted checkout. SERVER ONLY — needs a secret key.
      *
@@ -2462,6 +2611,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"),
@@ -104,6 +116,20 @@ function createStoreClient(opts) {
     availability: /* @__PURE__ */ __name((variantRefs) => request(`/store/availability?variantRefs=${enc(variantRefs.join(","))}`), "availability"),
     /** The payment rails this workspace can charge, for rendering your own picker (headless only). */
     paymentMethods: /* @__PURE__ */ __name((currency) => request(`/store/payment-methods${currency ? `?currency=${enc(currency)}` : ""}`), "paymentMethods"),
+    // ------------------------------------------ register (fd_pk_ in the browser, or fd_sk_)
+    /**
+    * Register a guest for a FREE event tier. The one write a publishable key may make, so call it
+    * straight from the page. `tickets` has the checkout shape (positional `attendees`, length
+    * quantity x groupSize); `responses` answers the tier's `formFields` by `key`. A paid tier is
+    * refused with TIER_REQUIRES_PAYMENT: open a checkout for it from your server. Duplicates are
+    * quiet (an email that already holds a seat gets the same answer and its confirmation again,
+    * never a second seat), so retrying is safe and no idempotency key is needed. FrontDesk sends
+    * the confirmation, the .ics invite and the ticket itself.
+    */
+    registerForEvent: /* @__PURE__ */ __name((slug, input) => request(`/store/events/${enc(slug)}/register`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    }), "registerForEvent"),
     // --------------------------------------------------- checkout (fd_sk_, server)
     /**
     * Open a hosted checkout. SERVER ONLY — needs a secret key.
@@ -160,7 +186,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"),
@@ -70,6 +82,20 @@ function createStoreClient(opts) {
     availability: /* @__PURE__ */ __name((variantRefs) => request(`/store/availability?variantRefs=${enc(variantRefs.join(","))}`), "availability"),
     /** The payment rails this workspace can charge, for rendering your own picker (headless only). */
     paymentMethods: /* @__PURE__ */ __name((currency) => request(`/store/payment-methods${currency ? `?currency=${enc(currency)}` : ""}`), "paymentMethods"),
+    // ------------------------------------------ register (fd_pk_ in the browser, or fd_sk_)
+    /**
+    * Register a guest for a FREE event tier. The one write a publishable key may make, so call it
+    * straight from the page. `tickets` has the checkout shape (positional `attendees`, length
+    * quantity x groupSize); `responses` answers the tier's `formFields` by `key`. A paid tier is
+    * refused with TIER_REQUIRES_PAYMENT: open a checkout for it from your server. Duplicates are
+    * quiet (an email that already holds a seat gets the same answer and its confirmation again,
+    * never a second seat), so retrying is safe and no idempotency key is needed. FrontDesk sends
+    * the confirmation, the .ics invite and the ticket itself.
+    */
+    registerForEvent: /* @__PURE__ */ __name((slug, input) => request(`/store/events/${enc(slug)}/register`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    }), "registerForEvent"),
     // --------------------------------------------------- checkout (fd_sk_, server)
     /**
     * Open a hosted checkout. SERVER ONLY — needs a secret key.
@@ -126,7 +152,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.4.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",