@frontdesk-africa/store-js 0.3.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
@@ -102,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
@@ -208,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

@@ -984,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;
@@ -1083,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.
@@ -2447,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.
  *
@@ -2514,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.
      *

package/dist/index.d.ts

@@ -984,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;
@@ -1083,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.
@@ -2447,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.
  *
@@ -2514,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.
      *

package/dist/index.js

@@ -116,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.

package/dist/index.mjs

@@ -82,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontdesk-africa/store-js",
-  "version": "0.3.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",