@fanfare-io/fanfare-sdk-shopify 0.5.0 → 0.7.0

package/dist/cart-adapter.d.ts

@@ -0,0 +1,23 @@
+import { GatedLine } from './checkout-types';
+/**
+ * Integrator-supplied cart I/O for the recommended `gatedCheckout` path. `TCart`
+ * is the integrator's own Storefront cart type — the SDK never inspects it except
+ * through `readCart`. The adapter is passed to `useFanfareCheckout`, so the SDK
+ * owns the create→claim→add-line ordering while the integrator owns the Shopify
+ * Storefront calls (cart create / `cartLinesAdd`).
+ */
+export interface FanfareCartAdapter<TCart> {
+    /**
+     * Create or locate an EMPTY cart. Takes NO line — there is deliberately nothing
+     * to add the gated product with here, so it cannot precede the claim that writes
+     * the gate token.
+     */
+    createCart(): Promise<TCart>;
+    /** Add one line to the cart AFTER the gate token is written; returns the updated cart. */
+    addLine(cart: TCart, line: GatedLine): Promise<TCart>;
+    /** Extract the claim-target cart id and the post-add checkout URL. */
+    readCart(cart: TCart): {
+        id: string;
+        checkoutUrl?: string;
+    };
+}

package/dist/checkout-types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Public checkout vocabulary shared by the low-level `claim` and the recommended
+ * `gatedCheckout`. Isomorphic (no React) so the package root can export it.
+ *
+ * The two Shopify identifiers a gated line carries are BOTH opaque
+ * `gid://shopify/...` strings, so they are branded to make a transposition a
+ * compile error rather than a silent admission-authority mismatch:
+ *  - `shopifyProductId` (a `ProductGID`) is the gate's policy anchor.
+ *  - `merchandiseId` (a `VariantGID`) is Shopify's Storefront `cartLinesAdd` id.
+ */
+declare const gidBrand: unique symbol;
+/** A Shopify Product GID, e.g. `gid://shopify/Product/123`. Construct via `productGid`. */
+export type ProductGID = string & {
+    readonly [gidBrand]: "Product";
+};
+/** A Shopify ProductVariant GID, e.g. `gid://shopify/ProductVariant/456`. Construct via `variantGid`. */
+export type VariantGID = string & {
+    readonly [gidBrand]: "ProductVariant";
+};
+export declare function productGid(gid: string): ProductGID;
+export declare function variantGid(gid: string): VariantGID;
+/**
+ * One purchase intent the gate evaluates. `shopifyProductId` drives the gate's
+ * (currently server-deferred) product policy; `merchandiseId` is the variant the
+ * integrator's `cartLinesAdd` consumes. Both required — the admission authority
+ * keys on the product and has no variant→product derivation path.
+ */
+export interface GatedLine {
+    shopifyProductId: ProductGID;
+    merchandiseId: VariantGID;
+    quantity: number;
+}
+/**
+ * The intended-purchase payload relayed to the app proxy. INTERNAL wire shape:
+ * `merchandiseId` maps to the authority's `variantId`. The fields stay branded so
+ * the mapping below cannot transpose them.
+ */
+export interface ShopifyRequestedPurchase {
+    productId: ProductGID;
+    variantId?: VariantGID;
+    quantity: number;
+}
+/** Map a `GatedLine` to the authority's requested-purchase wire shape. */
+export declare function gatedLineToRequestedPurchase(line: GatedLine): ShopifyRequestedPurchase;
+/**
+ * Closed refusal vocabulary for `gatedCheckout`. The load-bearing distinction is
+ * whether a fresh `gatedCheckout` is safe (nothing reserved) or would
+ * double-reserve (a slot is already held) — see `kind` + the docs on
+ * `FanfareGatedCheckoutResult`.
+ *
+ *  - `cart_create_failed` — `createCart` threw; nothing claimed, safe to restart.
+ *  - `no_claim_context` — not yet ready (no grant/distribution, or demo mode).
+ *  - `cart_not_materialized` — the proxy could not find a real cart; safe to restart.
+ *  - `claim_failed` — the claim was refused/unreachable; nothing reserved, safe to restart.
+ *  - `add_line_failed` — RESERVED. The token is minted and the slot held; resume the
+ *    add via `retry()`, never re-claim (that double-reserves).
+ *  - `reservation_expired` — the reservation lapsed mid-add; a fresh `gatedCheckout` is required.
+ *  - `cart_id_mismatch` — the cart `addLine` returned is not the one claimed (adapter bug).
+ *  - `checkout_url_missing` — every line was added but the cart exposed no checkout URL (adapter bug).
+ *  - `busy` — a `gatedCheckout` is already in flight; disable the buy button on `pending`.
+ *
+ * Only `add_line_failed` carries a `retry()`; branch on `retryable` (or the presence
+ * of `retry`), never on `code` alone, to decide whether to retry.
+ */
+export type FanfareCheckoutCode = "cart_create_failed" | "no_claim_context" | "cart_not_materialized" | "claim_failed" | "add_line_failed" | "reservation_expired" | "cart_id_mismatch" | "checkout_url_missing" | "busy";
+/** Which phase the failure came from, for coarse UI/metric bucketing. */
+export type FanfareCheckoutFailureKind = "create_cart" | "claim" | "add_line" | "busy";
+/**
+ * The closed result of `gatedCheckout`. Never rejects. On `{ ok: true }` the cart
+ * carries the gate token plus every line, and `checkoutUrl` is ready to redirect.
+ *
+ * On `{ ok: false }`, branch on `code`. The only RESUMABLE failure is
+ * `add_line_failed`: the claim already minted the token and reserved the slot, so
+ * `retry()` re-runs the remaining `addLine`s on the SAME cart — it never re-claims.
+ * `cart` is the half-built cart and `expDate` the reservation expiry, so a caller
+ * can decide to `retry()` or, once expired (`reservation_expired`), start fresh.
+ */
+export type FanfareGatedCheckoutResult<TCart> = {
+    ok: true;
+    cart: TCart;
+    checkoutUrl: string;
+    expDate: string;
+} | {
+    ok: false;
+    code: FanfareCheckoutCode;
+    retryable: boolean;
+    kind: FanfareCheckoutFailureKind;
+    /** The reservation expiry, when a claim succeeded before the failure. */
+    expDate?: string;
+    /** The index into `[gatedLine, ...ungatedLines]` whose `addLine` failed. */
+    failedLineIndex?: number;
+    /** The claimed (possibly half-built) cart, when one exists. */
+    cart?: TCart;
+    /** Present only on `add_line_failed`: resume the remaining adds on the same cart. */
+    retry?: () => Promise<FanfareGatedCheckoutResult<TCart>>;
+};
+export {};

package/dist/checkout-types.js

@@ -0,0 +1 @@
+function t(t,r){const n="Product"===r?"ProductVariant":"Product";if(t.startsWith(`gid://shopify/${n}/`))throw new Error(`Expected a Shopify ${r} id but received a ${n} GID: ${t}`);return t}function r(r){return t(r,"Product")}function n(r){return t(r,"ProductVariant")}function i(t){return{productId:t.shopifyProductId,variantId:t.merchandiseId,quantity:t.quantity}}export{i as gatedLineToRequestedPurchase,r as productGid,n as variantGid};

package/dist/claimer.d.ts

@@ -1,40 +1,4 @@
-/**
- * Shopify checkout CLAIMER — the on-grant, NON-CONSUMING sibling of
- * `createShopifyCheckoutVerifier`.
- *
- * The claimer and the verifier relay the same `{ credential, distributionId,
- * cartId }` body to the same proxy host, but they are deliberately SEPARATE
- * factories — not one factory with an endpoint flag — because their result
- * shapes and readiness policies diverge (see below). They differ in WHICH route
- * they POST to, and that route is configurable per caller:
- *
- *  - The CLAIMER's factory default is the `admissions/claim` route, which
- *    validates the credential, mints a short-lived gate token, and writes it to
- *    the cart metafield (mint-only; reserves and spends nothing). It returns the
- *    minted token's `expDate` so the storefront can surface a continuity signal
- *    — so its result carries a body the caller reads. Direct callers (e.g. the
- *    Liquid theme path) use this default.
- *  - The React adapter's headless buy action OVERRIDES `endpoint` to
- *    `admissions/reserve` (the #29 reserve-fold — see `react/use-fanfare-claim`).
- *    Reserve is a strict superset: it validates + mints + writes the gate token
- *    AND reserves the slot, so the slot can't be re-drawn mid-checkout. Its body
- *    is shape-compatible — the claimer reads only `expDate` (reserve's extra
- *    `reservationId` is ignored here), so `ClaimResult` is unchanged.
- *  - The VERIFIER fires *at checkout entry* against the `admissions/reserve`
- *    route as a separate factory and returns a bare gate decision whose body it
- *    ignores. (Reserve is not exclusively the verifier's route — the reserve-fold
- *    above points the claimer at it for the headless mint+reserve round-trip.)
- *
- * The claimer is NOT a `CheckoutVerifier`: different result shape (carries
- * `expDate`), different context-readiness policy (a missing context is a benign
- * no-op, not a construction error — the claimer fires automatically on every
- * grant), and it is invoked directly by the storefront, never threaded through
- * the React adapter's `recordGrant` seam.
- *
- * Fails closed by construction: a missing/`null` context, a non-2xx proxy
- * response, a 2xx body without a parseable `expDate`, and any transport throw all
- * resolve to a denied `{ ok:false, reason }`. It NEVER rejects.
- */
+import { ShopifyRequestedPurchase } from './checkout-types';
 /** The live context a claim needs. INTERNAL — the React adapter fills it for you
  * from provider state; you never construct one. Separate from
  * `ShopifyCheckoutContext` so the claim and verify seams can diverge without
@@ -46,20 +10,30 @@ export interface ShopifyClaimContext {
     distributionId: string;
     /**
      * The cart identifier the gate token is written to. For the React adapter's
-     * headless path this is the Storefront cart GID you materialized and handed to
-     * `useFanfareClaim().claim(cartId)`. (Liquid-theme callers that build a claimer
-     * directly may instead pass an Ajax cart token incl. `?key=`; the proxy/cart
-     * bridge resolves either form to a cart GID.) */
+     * headless path this is the real Storefront cart GID you materialized and
+     * handed to `useFanfareClaim().claim(cartId)`. This identifies the cart
+     * metafield write target; product/variant/quantity policy must still be
+     * represented by the integration's purchase context. (Liquid-theme callers
+     * that build a claimer directly may instead pass an Ajax cart token incl.
+     * `?key=`; the proxy/cart bridge resolves either form to a cart GID.) */
     cartId: string;
+    /**
+     * Optional intended-purchase payload. The cart id names WHERE the gate token is
+     * written; this names WHAT is being bought, so the admission authority can apply
+     * product/quantity policy. Omitted by the bare `claim(cartId)` form. The server
+     * ignores it today (order-limit enforcement is deferred), but the SDK forwards
+     * it so the contract is in place.
+     */
+    requestedPurchase?: ShopifyRequestedPurchase;
 }
 /**
  * A machine-readable refusal code on `{ ok: false }`. The codes split into two
  * groups for the integrator deciding whether to retry:
  *
  *  - `cart_not_materialized` — RECOVERABLE. The proxy could not find a real cart
- *    behind your `cartId`. Materialize the Storefront cart (with the gated line on
- *    it), then call `claim(cart.id)` again. This is the one reason that maps to a
- *    concrete retry the integrator owns.
+ *    behind your `cartId`. Materialize a real Storefront cart, then call
+ *    `claim(cart.id)` again. This is the one reason that maps to a concrete
+ *    retry the integrator owns.
  *  - `no_claim_context` — NOT-YET-READY (not a bug in your `cartId`). The provider
  *    has no admission credential / distribution id to claim with: the shopper
  *    hasn't cleared the drop, the journey hasn't routed, or you're in demo mode
@@ -78,9 +52,10 @@ export type ClaimRefusalReason = "cart_not_materialized" | "no_claim_context" |
  * `reason` is a stable `ClaimRefusalReason` code — see that type for which codes
  * are retryable (`cart_not_materialized` → re-materialize + re-claim) vs terminal.
  *
- * Note: this result does NOT carry a checkout URL. You already hold
- * `cart.checkoutUrl` from the cart you materialized; on `{ ok: true }` redirect
- * the shopper there to enter the gated checkout.
+ * Note: this result does NOT carry a checkout URL. You own the cart mutation and
+ * redirect: on `{ ok: true }`, redirect to the checkout URL for the same cart
+ * after your integration has added any gated lines that were waiting for the
+ * gate token.
  */
 export type ClaimResult = {
     ok: true;
@@ -126,6 +101,8 @@ export interface ShopifyCheckoutClaimer {
  * `proxy_409`) so the storefront can materialize a real cart and re-claim — the
  * claimer does NOT own materialization, which is context-specific (the Ajax cart
  * bridge for themes vs the Storefront cart GID for headless) and lives in the
- * caller that holds that knowledge.
+ * caller that holds that knowledge. For headless, the cart reference identifies
+ * where to write the gate token; it does not replace the intended product/
+ * variant/quantity context needed to validate purchase policy.
  */
 export declare function createShopifyCheckoutClaimer(config: ShopifyClaimConfig): ShopifyCheckoutClaimer;

package/dist/claimer.js

@@ -1 +1 @@
-function t(t){if(!t.proxyBaseUrl||""===t.proxyBaseUrl.trim())throw new Error("createShopifyCheckoutClaimer: proxyBaseUrl is required");const e=`${t.proxyBaseUrl.replace(/\/+$/,"")}/${(t.endpoint??"admissions/claim").replace(/^\/+/,"")}`,r=t.fetchImpl??globalThis.fetch;return{async claim(){try{const a=t.getClaimContext?await t.getClaimContext():null;if(null==a)return{ok:!1,reason:"no_claim_context"};const n=await r(e,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({credential:a.credential,distributionId:a.distributionId,cartId:a.cartId}),signal:AbortSignal.timeout(t.timeoutMs??1e4)});if(!n.ok){const t=await async function(t){if(409===t.status)try{const e=await t.json();if("cart_not_materialized"===e?.error)return"cart_not_materialized"}catch{}return`proxy_${t.status}`}(n);return{ok:!1,reason:t}}const o=await async function(t){try{const e=await t.json();return"string"==typeof e?.expDate&&e.expDate.length>0?e.expDate:null}catch{return null}}(n);return null===o?{ok:!1,reason:"claim_malformed"}:{ok:!0,expDate:o}}catch{return{ok:!1,reason:"claim_unreachable"}}}}}export{t as createShopifyCheckoutClaimer};
+function t(t){if(!t.proxyBaseUrl||""===t.proxyBaseUrl.trim())throw new Error("createShopifyCheckoutClaimer: proxyBaseUrl is required");const e=`${t.proxyBaseUrl.replace(/\/+$/,"")}/${(t.endpoint??"admissions/claim").replace(/^\/+/,"")}`,r=t.fetchImpl??globalThis.fetch;return{async claim(){try{const a=t.getClaimContext?await t.getClaimContext():null;if(null==a)return{ok:!1,reason:"no_claim_context"};const n=await r(e,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({credential:a.credential,distributionId:a.distributionId,cartId:a.cartId,...void 0===a.requestedPurchase?{}:{requestedPurchase:a.requestedPurchase}}),signal:AbortSignal.timeout(t.timeoutMs??1e4)});if(!n.ok){const t=await async function(t){if(409===t.status)try{const e=await t.json();if("cart_not_materialized"===e?.error)return"cart_not_materialized"}catch{}return`proxy_${t.status}`}(n);return{ok:!1,reason:t}}const o=await async function(t){try{const e=await t.json();return"string"==typeof e?.expDate&&e.expDate.length>0?e.expDate:null}catch{return null}}(n);return null===o?{ok:!1,reason:"claim_malformed"}:{ok:!0,expDate:o}}catch{return{ok:!1,reason:"claim_unreachable"}}}}}export{t as createShopifyCheckoutClaimer};

package/dist/index.d.ts

@@ -12,6 +12,8 @@
  * public surface here is the `experienceIds` metafield primitives,
  * `FanfareConfigurationError`, and the framework-free seam vocabulary.
  */
+export { productGid, variantGid } from './checkout-types';
+export type { FanfareCheckoutCode, FanfareCheckoutFailureKind, FanfareGatedCheckoutResult, GatedLine, ProductGID, VariantGID, } from './checkout-types';
 export type { ClaimRefusalReason, ClaimResult } from './claimer';
 export type { ExperienceSource, FanfareMode, ShopifyAdapterConfig, ShopifyProductRef } from './config';
 export { FanfareConfigurationError } from './errors';

package/dist/index.js

@@ -1 +1 @@
-import{FanfareConfigurationError as r}from"./errors.js";import{FANFARE_PRODUCT_METAFIELD as o,parseExperienceIds as f,parseFirstExperienceId as e}from"./metafield.js";import{ACCESS_STATUSES as m,snapshotToAccessStatus as t}from"@fanfare-io/fanfare-sdk-core/storefront";export{m as ACCESS_STATUSES,o as FANFARE_PRODUCT_METAFIELD,r as FanfareConfigurationError,f as parseExperienceIds,e as parseFirstExperienceId,t as snapshotToAccessStatus};
+import{productGid as r,variantGid as o}from"./checkout-types.js";import{FanfareConfigurationError as e}from"./errors.js";import{FANFARE_PRODUCT_METAFIELD as f,parseExperienceIds as t,parseFirstExperienceId as m}from"./metafield.js";import{ACCESS_STATUSES as s,snapshotToAccessStatus as i}from"@fanfare-io/fanfare-sdk-core/storefront";export{s as ACCESS_STATUSES,f as FANFARE_PRODUCT_METAFIELD,e as FanfareConfigurationError,t as parseExperienceIds,m as parseFirstExperienceId,r as productGid,i as snapshotToAccessStatus,o as variantGid};

package/dist/react/index.d.ts

@@ -7,12 +7,16 @@
  * store facts. `useFanfareExperience` is the Shopify→experience mapping the PDP
  * calls. `useFanfareWidgetBridge` connects the drop journey widget to the provider
  * (spread its `onJourneyChange` onto your `<ExperienceWidget>`), so the grant the
- * shopper earns reaches the gate + claim. `useFanfareClaim` is the on-buy claim
- * that writes the gate token onto a cart you materialized. `<FanfareCheckoutGate>`
- * is the drop-in checkout guard, with `useFanfareGrant` exposed for manual control
- * of the loading/allowed/blocked states. The internal `useShopifyAdapter` hook they
- * build on is intentionally NOT exported.
+ * shopper earns reaches the gate + checkout. `useFanfareCheckout` is the recommended
+ * on-buy path — its `gatedCheckout` owns the create→claim→add-line ordering — and it
+ * also exposes the low-level `claim` (= `useFanfareClaim`) for bring-your-own-cart.
+ * `<FanfareCheckoutGate>` is the drop-in checkout guard, with `useFanfareGrant` exposed
+ * for manual control of the loading/allowed/blocked states. The internal
+ * `useShopifyAdapter` hook they build on is intentionally NOT exported.
  */
+export type { FanfareCartAdapter } from '../cart-adapter';
+export { productGid, variantGid } from '../checkout-types';
+export type { FanfareCheckoutCode, FanfareCheckoutFailureKind, FanfareGatedCheckoutResult, GatedLine, ProductGID, VariantGID, } from '../checkout-types';
 export type { ClaimRefusalReason, ClaimResult } from '../claimer';
 export type { ExperienceSource, FanfareMode, ShopifyAdapterConfig, ShopifyProductRef } from '../config';
 export { FanfareConfigurationError } from '../errors';
@@ -20,8 +24,10 @@ export { FanfareCheckoutGate } from './fanfare-checkout-gate';
 export type { FanfareCheckoutGateProps } from './fanfare-checkout-gate';
 export { FanfareShopifyProvider } from './shopify-provider';
 export type { FanfareShopifyProviderProps } from './shopify-provider';
+export { useFanfareCheckout } from './use-fanfare-checkout';
+export type { FanfareGatedCheckoutInput, UseFanfareCheckoutResult } from './use-fanfare-checkout';
 export { useFanfareClaim } from './use-fanfare-claim';
-export type { FanfareClaimState, UseFanfareClaimResult } from './use-fanfare-claim';
+export type { FanfareClaimInput, FanfareClaimState, UseFanfareClaimResult } from './use-fanfare-claim';
 export { useFanfareExperience } from './use-fanfare-experience';
 export type { UseFanfareExperienceResult } from './use-fanfare-experience';
 export { useFanfareGrant } from './use-fanfare-grant';

package/dist/react/index.js

@@ -1,2 +1,2 @@
 "use client";
-import{FanfareConfigurationError as r}from"../errors.js";import{FanfareCheckoutGate as e}from"./fanfare-checkout-gate.js";import{FanfareShopifyProvider as o}from"./shopify-provider.js";import{useFanfareClaim as f}from"./use-fanfare-claim.js";import{useFanfareExperience as m}from"./use-fanfare-experience.js";import{useFanfareGrant as a}from"./use-fanfare-grant.js";import{useFanfareWidgetBridge as i}from"./use-fanfare-widget-bridge.js";export{e as FanfareCheckoutGate,r as FanfareConfigurationError,o as FanfareShopifyProvider,f as useFanfareClaim,m as useFanfareExperience,a as useFanfareGrant,i as useFanfareWidgetBridge};
+import{productGid as r,variantGid as e}from"../checkout-types.js";import{FanfareConfigurationError as o}from"../errors.js";import{FanfareCheckoutGate as f}from"./fanfare-checkout-gate.js";import{FanfareShopifyProvider as m}from"./shopify-provider.js";import{useFanfareCheckout as s}from"./use-fanfare-checkout.js";import{useFanfareClaim as t}from"./use-fanfare-claim.js";import{useFanfareExperience as a}from"./use-fanfare-experience.js";import{useFanfareGrant as i}from"./use-fanfare-grant.js";import{useFanfareWidgetBridge as p}from"./use-fanfare-widget-bridge.js";export{f as FanfareCheckoutGate,o as FanfareConfigurationError,m as FanfareShopifyProvider,r as productGid,s as useFanfareCheckout,t as useFanfareClaim,a as useFanfareExperience,i as useFanfareGrant,p as useFanfareWidgetBridge,e as variantGid};

package/dist/react/use-fanfare-checkout.d.ts

@@ -0,0 +1,18 @@
+import { FanfareCartAdapter } from '../cart-adapter';
+import { FanfareGatedCheckoutResult, GatedLine } from '../checkout-types';
+import { UseFanfareClaimResult } from './use-fanfare-claim';
+/** What to check out: the one gated line, plus optional convenience lines that ride the same cart. */
+export interface FanfareGatedCheckoutInput {
+    gatedLine: GatedLine;
+    /** Added to the cart but NOT policy-checked today — the gate covers `gatedLine` only. */
+    ungatedLines?: GatedLine[];
+}
+export interface UseFanfareCheckoutResult<TCart> {
+    /** Recommended one-call path: create → claim → add line(s) → checkout URL. Never rejects. */
+    gatedCheckout(input: FanfareGatedCheckoutInput): Promise<FanfareGatedCheckoutResult<TCart>>;
+    /** Advanced escape hatch — the low-level claim (see `useFanfareClaim`). */
+    claim: UseFanfareClaimResult["claim"];
+    /** True while a `gatedCheckout` run is in flight (drives the buy-button spinner). */
+    pending: boolean;
+}
+export declare function useFanfareCheckout<TCart>(adapter: FanfareCartAdapter<TCart>): UseFanfareCheckoutResult<TCart>;

package/dist/react/use-fanfare-checkout.js

@@ -0,0 +1,2 @@
+"use client";
+import{useState as e,useRef as r,useCallback as t}from"react";import{useFanfareClaim as a}from"./use-fanfare-claim.js";function c(c){const{claim:n}=a(),[i,o]=e(!1),d=r(c);d.current=c;const l=r(null),u=t(e=>{if(null!==l.current){const e={ok:!1,code:"busy",retryable:!0,kind:"busy"};return Promise.resolve(e)}const r=(async()=>{o(!0);try{return await e()}finally{l.current=null,o(!1)}})();return l.current=r,r},[]),s=t(async(e,r,t,a,c)=>{const n=d.current;if(function(e){const r=Date.parse(e);return!Number.isNaN(r)&&Date.now()>r}(c))return{ok:!1,code:"reservation_expired",retryable:!1,kind:"add_line",cart:e,expDate:c};let i=e;for(const[d,l]of r.slice(t).entries()){const e=t+d;try{i=await n.addLine(i,l)}catch{const t=i;return{ok:!1,code:"add_line_failed",retryable:!0,kind:"add_line",failedLineIndex:e,cart:t,expDate:c,retry:()=>u(()=>s(t,r,e,a,c))}}}const o=n.readCart(i);return o.id!==a?{ok:!1,code:"cart_id_mismatch",retryable:!1,kind:"add_line",cart:i,expDate:c}:void 0===o.checkoutUrl||""===o.checkoutUrl?{ok:!1,code:"checkout_url_missing",retryable:!1,kind:"add_line",cart:i,expDate:c}:{ok:!0,cart:i,checkoutUrl:o.checkoutUrl,expDate:c}},[u]);return{gatedCheckout:t(e=>{const{gatedLine:r,ungatedLines:t}=e,a=void 0===t?[r]:[r,...t];return u(async()=>{const e=d.current;let t;try{t=await e.createCart()}catch{return{ok:!1,code:"cart_create_failed",retryable:!0,kind:"create_cart"}}const c=e.readCart(t).id,i=await n({cartId:c,purchase:r});return i.ok?s(t,a,0,c,i.expDate):"no_claim_context"===(o=i.reason)?{ok:!1,code:"no_claim_context",retryable:!1,kind:"claim"}:"cart_not_materialized"===o?{ok:!1,code:"cart_not_materialized",retryable:!0,kind:"claim"}:{ok:!1,code:"claim_failed",retryable:!0,kind:"claim"};var o})},[n,u,s]),claim:n,pending:i}}export{c as useFanfareCheckout};

package/dist/react/use-fanfare-claim.d.ts

@@ -1,21 +1,38 @@
+import { GatedLine } from '../checkout-types';
 import { ClaimResult } from '../claimer';
 /** The claim lifecycle, for driving buy-button UI (e.g. a spinner). */
 export type FanfareClaimState = "idle" | "claiming" | "claimed" | "error";
 export interface UseFanfareClaimResult {
     /**
-     * Claim the spot for a cart you already materialized. In one post-cart
-     * round-trip this validates the admission, mints + writes the gate token to the
-     * cart, AND reserves the slot (so it can't be re-drawn mid-checkout). `cartId`
-     * is your Storefront cart's GID (the cart carrying the gated line). On
-     * `{ ok: true }`, redirect the shopper to that cart's `checkoutUrl`; `expDate`
-     * is the token's expiry (the reserve route's `reservationId` is handled
-     * internally and not surfaced). On `{ ok: false }`, branch on `result.reason`
-     * (a `ClaimRefusalReason` — `cart_not_materialized` is retryable;
+     * Claim the spot for a cart you already materialized. In one round-trip this
+     * validates the admission, mints + writes the gate token to the cart, AND
+     * reserves the slot (so it can't be re-drawn mid-checkout). `cartId` is your
+     * Storefront cart's GID: it identifies where the gate token is written, but it
+     * does not by itself validate product/variant/quantity policy. On `{ ok: true
+     * }`, add the gated line to that same cart if it is not already present, then
+     * redirect the shopper to that cart's `checkoutUrl`; `expDate` is the token's
+     * expiry (the reserve route's `reservationId` is handled internally and not
+     * surfaced). On `{ ok: false }`, branch on `result.reason` (a
+     * `ClaimRefusalReason` — `cart_not_materialized` is retryable;
      * `no_claim_context` means not-yet-ready). Never rejects — every outcome
      * resolves to a `ClaimResult`.
+     *
+     * Pass `{ cartId, purchase }` to forward product/variant/quantity context to the
+     * gate, or a bare `cartId` string for a product-less drop (the body omits the
+     * purchase). `useFanfareCheckout().gatedCheckout` is the recommended path that
+     * owns the create→claim→add-line ordering for you.
      */
-    claim(cartId: string): Promise<ClaimResult>;
+    claim(input: string | FanfareClaimInput): Promise<ClaimResult>;
     /** `"idle"` → `"claiming"` → `"claimed"` | `"error"`. */
     state: FanfareClaimState;
 }
+/**
+ * The object form of `claim`. `purchase` is REQUIRED here so the gate receives the
+ * intended `GatedLine`; for a genuinely product-less drop use the bare
+ * `claim(cartId: string)` form instead.
+ */
+export interface FanfareClaimInput {
+    cartId: string;
+    purchase: GatedLine;
+}
 export declare function useFanfareClaim(): UseFanfareClaimResult;

package/dist/react/use-fanfare-claim.js

@@ -1,2 +1,2 @@
 "use client";
-import{useState as r,useRef as t,useMemo as o,useCallback as e}from"react";import{createShopifyCheckoutClaimer as i}from"../claimer.js";import{useShopifyAdapter as n}from"./shopify-provider.js";function c(){const{config:c,setActiveCartId:a,getCheckoutContext:s}=n(),[m,l]=r("idle"),p=t(s);p.current=s;const u=c.shopify.proxyBaseUrl,f=o(()=>void 0===u||""===u.trim()?null:i({proxyBaseUrl:u,endpoint:"admissions/reserve",getClaimContext:()=>p.current()}),[u]);return{claim:e(async r=>{if(null===f)return l("error"),{ok:!1,reason:"no_claim_context"};a(r),l("claiming");const t=await f.claim();return l(t.ok?"claimed":"error"),t},[f,a]),state:m}}export{c as useFanfareClaim};
+import{useState as r,useRef as t,useMemo as e,useCallback as o}from"react";import{gatedLineToRequestedPurchase as n}from"../checkout-types.js";import{createShopifyCheckoutClaimer as i}from"../claimer.js";import{useShopifyAdapter as c}from"./shopify-provider.js";function s(){const{config:s,setActiveCartId:a,getCheckoutContext:u}=c(),[l,m]=r("idle"),p=t(u);p.current=u;const d=t(void 0),f=s.shopify.proxyBaseUrl,y=e(()=>void 0===f||""===f.trim()?null:i({proxyBaseUrl:f,endpoint:"admissions/reserve",getClaimContext:()=>{const r=p.current();if(null===r)return null;const t=d.current;return void 0===t?r:{...r,requestedPurchase:t}}}),[f]);return{claim:o(async r=>{if(null===y)return m("error"),{ok:!1,reason:"no_claim_context"};const t="string"==typeof r?r:r.cartId;d.current="string"==typeof r?void 0:n(r.purchase),a(t),m("claiming");const e=await y.claim();return m(e.ok?"claimed":"error"),e},[y,a]),state:l}}export{s as useFanfareClaim};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-shopify",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Shopify storefront adapter for Fanfare SDK: product→experience resolver, checkout verifier, and experienceIds metafield primitives",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -39,7 +39,7 @@
   "peerDependencies": {
     "react": "^18.0.0 || ^19.1.1",
     "react-dom": "^18.0.0 || ^19.1.1",
-    "@fanfare-io/fanfare-sdk-core": "0.5.0"
+    "@fanfare-io/fanfare-sdk-core": "0.7.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -64,7 +64,7 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4",
-    "@fanfare-io/fanfare-sdk-core": "0.5.0"
+    "@fanfare-io/fanfare-sdk-core": "0.7.0"
   },
   "sideEffects": false,
   "keywords": [