@frontdesk-africa/store-js 0.1.0 → 0.2.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

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[];
@@ -1042,6 +1072,34 @@ interface StoreCheckoutSessionView {
     createdAt: 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). */
@@ -2398,6 +2456,12 @@ 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>;
 };
 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[];
@@ -1042,6 +1072,34 @@ interface StoreCheckoutSessionView {
     createdAt: 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). */
@@ -2398,6 +2456,12 @@ 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>;
 };
 type StoreClient = ReturnType<typeof createStoreClient>;
 /**

package/dist/index.js

@@ -151,7 +151,16 @@ 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")
   };
 }
 __name(createStoreClient, "createStoreClient");

package/dist/index.mjs

@@ -117,7 +117,16 @@ 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")
   };
 }
 __name(createStoreClient, "createStoreClient");

package/package.json

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