@fanfare-io/fanfare-sdk-shopify 0.2.0 → 0.4.0

package/README.md

@@ -1,35 +1,76 @@
 # @fanfare-io/fanfare-sdk-shopify
 
-The Shopify storefront surface for the Fanfare SDK: the product→experience
-resolver, the checkout verifier, and the `experienceIds` metafield primitives.
-It builds on the framework-free storefront-adapter contract published from
-`@fanfare-io/fanfare-sdk-core/storefront`.
+The Shopify storefront surface for the Fanfare SDK. An integrator configures one
+provider — `FanfareShopifyProvider` — with facts about their store, and the SDK
+assembles the product→experience resolution and checkout verify/claim paths
+internally. It builds on the framework-free storefront-adapter contract published
+from `@fanfare-io/fanfare-sdk-core/storefront`.
+
+> **Note:** the product→experience resolver and the checkout verifier/claimer
+> are now **internal** to `FanfareShopifyProvider`. They are no longer exported
+> as loose factories — there is nothing to wire by hand. Configure the provider.
+
+## Quick start
+
+```tsx
+import { FanfareShopifyProvider } from "@fanfare-io/fanfare-sdk-shopify/react";
+
+function App() {
+  return (
+    <FanfareShopifyProvider
+      organizationId="org_abc123"
+      publishableKey="pk_live_..."
+      shopify={{
+        proxyBaseUrl: "https://shop.myshopify.com/apps/fanfare/api",
+      }}
+    >
+      {/* your storefront tree; the Fanfare widget lives here, unchanged */}
+    </FanfareShopifyProvider>
+  );
+}
+```
+
+That is the whole integrator surface. `mode` defaults to `"production"` and
+`experiences` defaults to `{ source: "metafield" }`, so the snippet above is the
+complete production wiring. See the prop reference in
+`src/react/shopify-provider.tsx` (the `FanfareShopifyProviderProps` JSDoc) and
+the store-config field reference in `src/config.ts` (`ShopifyAdapterConfig`).
+
+### Where the `shopify` fields come from
+
+`proxyBaseUrl` is the only `shopify` field. **Everything routes through the app
+proxy** — verify, claim, AND experience resolution — so there are no Storefront-API
+credentials to manage and no numeric app id to be told. The proxy resolves the
+`$app:` metafield namespace server-side.
+
+| Field          | Required | Where to get it                                                                            |
+| -------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `proxyBaseUrl` | prod     | The Fanfare Shopify app's app-proxy URL on your store (`https://<shop>/apps/fanfare/api`). |
+
+## Modes: `production` (default) vs `demo`
+
+`mode` defaults to `"production"`: real verify + claim through the Fanfare
+Shopify app proxy. Production **requires** `shopify.proxyBaseUrl`; if it is
+missing, `FanfareShopifyProvider` throws `FanfareConfigurationError` at mount
+(fail-loud — it never silently degrades).
+
+`mode:"demo"` is the in-browser, harness-backed lane for **local development and
+Storybook only** — never a live storefront. In demo the checkout verifier is a
+client-only no-op: it enforces only client-side grant expiry and performs **no
+server-side checkout enforcement**, so a gated product is not actually protected.
+A gated product renders a visible "demo — not production-safe" state in this mode.
 
 ## Entry points
 
-| Import                                  | Runtime    | Contents                                                                                                                                                                                       |
-| --------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@fanfare-io/fanfare-sdk-shopify`       | isomorphic | `createShopifyExperienceResolver`, `shopifyCheckoutVerifier`, `FANFARE_PRODUCT_METAFIELD`, `parseExperienceIds`, `parseFirstExperienceId`, and a re-export of core's `./storefront` vocabulary |
-| `@fanfare-io/fanfare-sdk-shopify/react` | client     | `FanfareAdapterProvider`, `useFanfareAdapter`, `FanfareAdapterValue` (`"use client"`)                                                                                                          |
+| Import                                  | Runtime    | Contents                                                                                                                                                                                                                                                       |
+| --------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@fanfare-io/fanfare-sdk-shopify`       | isomorphic | `FanfareConfigurationError`, the `experienceIds` metafield primitives (`FANFARE_PRODUCT_METAFIELD`, `parseExperienceIds`, `parseFirstExperienceId`), config types (`FanfareMode`, `ShopifyAdapterConfig`), and a re-export of core's `./storefront` vocabulary |
+| `@fanfare-io/fanfare-sdk-shopify/react` | client     | `FanfareShopifyProvider` + its prop/type exports (`FanfareShopifyProviderProps`, `ExperienceSource`), `FanfareConfigurationError`, config types (`"use client"`)                                                                                               |
 
 The root entry imports zero React, so a server-only consumer (Hydrogen/Oxygen
 loader, Next/Remix server component) installs and uses it without React. React
 is an optional peer dependency, needed only for the `/react` subpath.
 
-## Placeholder seams (final-shaped signatures)
-
-Two seam bodies are honest local placeholders today; their **signatures are
-final** and the wiring lands behind them with no surface change:
-
-- **`createShopifyExperienceResolver(config)`** — `resolve(product)` resolves
-  from a config-supplied static `metafieldValues` map (handle → raw metafield
-  value) so the parser path is exercised end-to-end without a network. The live
-  Storefront-API read of the reified `app--<fanfareAppId>--product` /
-  `experienceIds` metafield is the only change that lands later.
-- **`shopifyCheckoutVerifier`** — `verify(grant)` enforces only client-side grant
-  expiry today. The ENG-913 server-validatable handoff (mint at claim, redeem +
-  validate at checkout entry) slots in behind the same `verify(grant)`
-  signature. `verify` is **total**: it resolves for every grant and never
-  rejects, so a future throwing redeem path must be wrapped into a denied result.
-
-No exported identifier says mock/demo.
+This provider is the **adapter** only. It does NOT subsume `fanfare-sdk-react`'s
+`FanfareProvider` / `ExperienceWidget` SDK init — the drop-journey widget stays
+the integrator's, exactly as today.

package/dist/claimer.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+/** 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
+ * breaking each other. */
+export interface ShopifyClaimContext {
+    /** The consumer's admission credential (the `admissionGrant` from the
+     * consumer-me snapshot). Relayed to the proxy; never persisted in Shopify. */
+    credential: string;
+    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.) */
+    cartId: string;
+}
+/**
+ * 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.
+ *  - `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
+ *    with no `proxyBaseUrl`. Wire up the widget + grant first; re-claiming only
+ *    helps once those are in place.
+ *  - `claim_malformed` / `claim_unreachable` / `proxy_<status>` — TERMINAL for
+ *    this attempt (a bad/unreadable mint response, a transport failure/timeout, or
+ *    a non-2xx proxy status other than the 409 above). Surface to the shopper; a
+ *    blind re-claim is unlikely to help.
+ */
+export type ClaimRefusalReason = "cart_not_materialized" | "no_claim_context" | "claim_malformed" | "claim_unreachable" | `proxy_${number}`;
+/**
+ * The result of a claim. On `{ ok: true }` the gate token was minted and written
+ * to your cart, and `expDate` is the token's ISO-8601 expiry — surface it as a
+ * continuity signal if you like. On `{ ok: false }` the claim was refused and
+ * `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.
+ */
+export type ClaimResult = {
+    ok: true;
+    expDate: string;
+} | {
+    ok: false;
+    reason: ClaimRefusalReason;
+};
+export interface ShopifyClaimConfig {
+    /** App-proxy base, e.g. "/apps/fanfare/api". `claim` POSTs to
+     * `${proxyBaseUrl}/${endpoint}`. */
+    proxyBaseUrl: string;
+    /**
+     * Supplies the live claim context. Returns `null` when the storefront is not
+     * ready to claim (no credential/cart yet), which `claim` surfaces as a benign
+     * denied result rather than a thrown error. Absent ⇒ always not-ready.
+     */
+    getClaimContext?: () => ShopifyClaimContext | null | Promise<ShopifyClaimContext | null>;
+    /** Proxy path under `proxyBaseUrl`. Defaults to the mint-only `admissions/claim`
+     * route. The React adapter's headless buy action overrides this to
+     * `admissions/reserve` (the #29 reserve-fold: validate + mint + write + RESERVE
+     * in one round-trip), which is body-compatible — the claimer reads only
+     * `expDate`. Direct callers (e.g. the Liquid theme) keep the default. */
+    endpoint?: string;
+    /** Injectable for SSR/test. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Abort the proxy request after this many ms so a stalled (connected but
+     * unresponsive) proxy can't leave `claim()` pending — every outcome must
+     * resolve. The abort surfaces as a denied result. Defaults to 10s.
+     */
+    timeoutMs?: number;
+}
+export interface ShopifyCheckoutClaimer {
+    claim(): Promise<ClaimResult>;
+}
+/**
+ * Build a Shopify checkout claimer. The proxy — not this client — is the trust
+ * boundary; a `{ ok:true }` means the authority validated the admission and the
+ * gate token was minted+written for this cart, never a client assertion.
+ *
+ * A 409 `cart_not_materialized` is surfaced verbatim as the reason (not a generic
+ * `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.
+ */
+export declare function createShopifyCheckoutClaimer(config: ShopifyClaimConfig): ShopifyCheckoutClaimer;

package/dist/claimer.js

@@ -0,0 +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};

package/dist/config.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Operating mode for the adapter (the mode state machine).
+ *
+ *  - `"production"` (the default): real verify + claim through the Fanfare
+ *    Shopify app proxy. Requires `shopify.proxyBaseUrl`; a missing proxy throws
+ *    `FanfareConfigurationError` at provider mount (fail-loud — never silently
+ *    degrade to the client-only no-op verifier).
+ *  - `"demo"`: for local development and Storybook ONLY — never a live
+ *    storefront. The checkout verifier is a client-only no-op: it enforces only
+ *    client-side grant expiry and does NO server-side checkout enforcement, so a
+ *    gated product is not actually protected. A gated product renders a visible
+ *    "demo — not production-safe" state in this mode, never a silent pass.
+ */
+export type FanfareMode = "production" | "demo";
+/**
+ * Facts about the integrator's Shopify store the adapter configures itself from.
+ * `proxyBaseUrl` is the single switch for the whole adapter: REAL verify + claim
+ * AND experience resolution all go through the Fanfare app proxy. When present the
+ * adapter drives the proxy; its absence is only valid in `"demo"`.
+ *
+ * In `mode:"production"` (the default), the default experience source is
+ * `{ source: "metafield" }`, whose live tier reads the product's experience ids
+ * through the app proxy (`GET {proxyBaseUrl}/experiences/ids-by-handle/{handle}`)
+ * — the proxy resolves the `$app:` namespace server-side, so NO Storefront creds
+ * or numeric app id are required. `proxyBaseUrl` is the only field and is
+ * mode-gated: required in production, optional in demo.
+ */
+export interface ShopifyAdapterConfig {
+    /**
+     * App-proxy base, e.g. "https://shop.myshopify.com/apps/fanfare/api". The
+     * single switch for the adapter: real verify + claim AND experience resolution
+     * all route through it. Required in `mode:"production"`; absent only in
+     * `mode:"demo"`. This is the Fanfare Shopify app's app-proxy URL on your store.
+     */
+    proxyBaseUrl?: string;
+}
+/**
+ * A Shopify product as the Storefront API hands it to the storefront. This is the
+ * ONLY product shape the Shopify adapter path deals in — a Fanfare
+ * product/experience id never appears here. The adapter's job is to map this to a
+ * Fanfare experience id.
+ *
+ * Experience resolution keys on `handle` only (the live app-proxy read and
+ * the `map` / `metafieldValues` lookups all index by handle), so `handle` is the
+ * one required field. `id` is OPTIONAL: it is carried for forward-compat (it flows
+ * through to the claim/checkout path and may matter to future resolution
+ * strategies) but no current path reads it, so you can pass `{ handle }` alone.
+ */
+export interface ShopifyProductRef {
+    /** The product handle, e.g. "limited-drop-tee". The key experience resolution
+     * uses. Required. */
+    handle: string;
+    /** The product GID, e.g. "gid://shopify/Product/123". Optional — carried for
+     * forward-compat; no current resolution path reads it. */
+    id?: string;
+}
+/**
+ * Where the Shopify→experience mapping comes from. The provider's `experiences`
+ * config; resolved by `useFanfareExperience(shopifyProduct)`.
+ *
+ * WHERE EXPERIENCE IDS COME FROM: a Fanfare experience id (e.g. `"exp_1"`) is
+ * minted in the Fanfare dashboard/admin when you create the experience. The
+ * Fanfare Shopify app writes the ids for a product into that product's
+ * `experienceIds` metafield. So for `"static"` / `"map"` you supply the id
+ * string yourself (copy it from the dashboard); for `"metafield"` the id is read
+ * back out of the metafield the app already wrote — you supply nothing.
+ *
+ *  - `{ source: "static", experienceId }` — one experience for the whole store.
+ *    `experienceId` is a BARE Fanfare id (`"exp_1"`). Resolves synchronously to
+ *    that id for every product.
+ *  - `{ source: "map", values }` — an SSR-preloaded `handle → experienceId` map.
+ *    Each VALUE is a BARE Fanfare id (`"exp_1"`), NOT a raw metafield string —
+ *    do not feed it the `["exp_1"]` JSON-array form (contrast `metafieldValues`
+ *    below, whose values are the raw metafield string). Resolves synchronously by
+ *    handle; an uncovered handle resolves to `null`.
+ *  - `{ source: "metafield", ... }` (the default) — reads the product's
+ *    `experienceIds` metafield (the one the Fanfare app wrote). Resolution order:
+ *    a `resolveExperience` override if supplied; else a preloaded
+ *    `metafieldValues[handle]` (SSR fast path, no network); else a live app-proxy
+ *    read (`GET {proxyBaseUrl}/experiences/ids-by-handle/{handle}`) that resolves
+ *    the `$app:` namespace server-side. Resolution is SSR-safe: any miss or
+ *    failure yields `null`, never a throw.
+ *
+ * Note the singular/plural asymmetry: `static`/`map` carry a single
+ * `experienceId`, while the underlying metafield is `experienceIds` (plural, a
+ * JSON array). Resolution always honors the FIRST id only — the platform is
+ * single-experience-per-product today (see `parseFirstExperienceId`).
+ *
+ * The per-product knobs (`metafieldValues`, `resolveExperience`) live ONLY on the
+ * `"metafield"` variant below — there is no top-level override; reach for them by
+ * choosing `source: "metafield"`.
+ */
+export type ExperienceSource = {
+    source: "static";
+    experienceId: string;
+} | {
+    source: "map";
+    values: Record<string, string>;
+} | {
+    source: "metafield";
+    /**
+     * SSR fast path: a preloaded `handle → raw experienceIds metafield value`
+     * map. Each VALUE is the RAW metafield string — a JSON array of ids like
+     * `'["exp_1"]'` (NOT a bare `"exp_1"`; contrast `map.values` above) — exactly
+     * as the Fanfare app wrote it / as you SSR-loaded it. Resolution parses it
+     * with `parseFirstExperienceId` (the first id wins) and performs NO network
+     * call when the handle is present; when absent, it falls through to the live
+     * app-proxy read.
+     */
+    metafieldValues?: Record<string, string>;
+    /**
+     * The escape hatch: your own product → experienceId mapping function. Use it
+     * when neither a static id, a handle map, nor the metafield read fits — e.g.
+     * you resolve from your own catalog/CMS. Return a BARE Fanfare id (`"exp_1"`)
+     * or `null` for an uncovered product. When supplied it takes precedence over
+     * both the preloaded map and the live metafield read. May be sync or async.
+     *
+     * It lives under `source: "metafield"` (rather than a separate top-level
+     * source) because it overrides the metafield resolution chain and composes
+     * with `metafieldValues` as the fallback path.
+     */
+    resolveExperience?: (product: ShopifyProductRef) => string | null | Promise<string | null>;
+};
+/** The mode + store config the guard inspects. The provider calls this at mount
+ * before constructing the internal verifier/claimer. */
+export interface ShopifyConfigGuardInput {
+    mode: FanfareMode;
+    shopify: ShopifyAdapterConfig;
+}
+/**
+ * Pure fail-loud guard for the mode state machine. Throws
+ * `FanfareConfigurationError` when `mode:"production"` lacks
+ * `shopify.proxyBaseUrl` — the one invariant that must hold before the provider
+ * builds the real verifier/claimer. Internal: `FanfareShopifyProvider` calls it
+ * at mount; it is not part of the public surface itself.
+ */
+export declare function assertShopifyConfig(config: ShopifyConfigGuardInput): void;

package/dist/config.js

@@ -0,0 +1 @@
+import{FanfareConfigurationError as r}from"./errors.js";function o(o){if("production"!==o.mode)return;const e=o.shopify.proxyBaseUrl;if(void 0===e||""===e.trim())throw new r('FanfareShopifyProvider: mode "production" requires shopify.proxyBaseUrl for real verify + claim. Set shopify.proxyBaseUrl, or use mode "demo" for the harness-backed lane.')}export{o as assertShopifyConfig};

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Adapter error surface.
+ *
+ * `FanfareConfigurationError` is the fail-loud artifact of the mode state
+ * machine: `FanfareShopifyProvider` throws it at mount when `mode:"production"`
+ * is missing the `shopify.proxyBaseUrl` it needs for real verify + claim. A
+ * thrown configuration error is deliberate — the no-op verifier path exists only
+ * in `mode:"demo"`, so production never silently degrades to a client-only check.
+ *
+ * It is its own subclass (not a bare `Error`) so integrators can branch on
+ * `instanceof FanfareConfigurationError` — e.g. surface a setup-time banner —
+ * without string-matching the message.
+ */
+export declare class FanfareConfigurationError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1 @@
+class r extends Error{constructor(t){super(t),this.name="FanfareConfigurationError",Object.setPrototypeOf(this,r.prototype)}}export{r as FanfareConfigurationError};

package/dist/index.d.ts

@@ -1,20 +1,20 @@
 /**
  * @fanfare-io/fanfare-sdk-shopify — the real Shopify storefront surface.
  *
- * ISOMORPHIC (SSR-safe) root barrel: the product→experience resolver, the
- * checkout verifier, and the `experienceIds` metafield primitives. Imports zero
- * React, so a server-only consumer (Hydrogen/Oxygen loader, Next/Remix server
- * component) installs and uses this package without React. The React provider /
- * hooks live in `@fanfare-io/fanfare-sdk-shopify/react`.
+ * ISOMORPHIC (SSR-safe) root barrel. Imports zero React, so a server-only
+ * consumer (Hydrogen/Oxygen loader, Next/Remix server component) installs and
+ * uses this package without React. The React provider / hooks live in
+ * `@fanfare-io/fanfare-sdk-shopify/react`.
  *
- * The resolver/verifier bodies are honest local placeholders pending the live
- * Storefront-API metafield read and the ENG-913 handoff (see the JSDoc on
- * createShopifyExperienceResolver / shopifyCheckoutVerifier) — their signatures
- * are final and the wiring lands behind them with no surface change.
+ * The resolver, verifier, and claimer are now INTERNAL: the
+ * `FanfareShopifyProvider` (in `./react`) assembles them from store config, so
+ * an integrator configures one provider rather than wiring loose factories. The
+ * public surface here is the `experienceIds` metafield primitives,
+ * `FanfareConfigurationError`, and the framework-free seam vocabulary.
  */
+export type { ClaimRefusalReason, ClaimResult } from './claimer';
+export type { ExperienceSource, FanfareMode, ShopifyAdapterConfig, ShopifyProductRef } from './config';
+export { FanfareConfigurationError } from './errors';
 export { FANFARE_PRODUCT_METAFIELD, parseExperienceIds, parseFirstExperienceId } from './metafield';
-export { createShopifyExperienceResolver } from './resolver';
-export type { ShopifyExperienceResolverConfig } from './resolver';
-export { shopifyCheckoutVerifier } from './verifier';
 export { ACCESS_STATUSES, snapshotToAccessStatus } from '@fanfare-io/fanfare-sdk-core/storefront';
 export type { AccessStatus, CheckoutAccess, CheckoutVerifier, ExperienceResolver, GrantRecord, VerificationResult, } from '@fanfare-io/fanfare-sdk-core/storefront';

package/dist/index.js

@@ -1 +1 @@
-import{FANFARE_PRODUCT_METAFIELD as r,parseExperienceIds as o,parseFirstExperienceId as e}from"./metafield.js";import{createShopifyExperienceResolver as f}from"./resolver.js";import{shopifyCheckoutVerifier as m}from"./verifier.js";import{ACCESS_STATUSES as i,snapshotToAccessStatus as t}from"@fanfare-io/fanfare-sdk-core/storefront";export{i as ACCESS_STATUSES,r as FANFARE_PRODUCT_METAFIELD,f as createShopifyExperienceResolver,o as parseExperienceIds,e as parseFirstExperienceId,m as shopifyCheckoutVerifier,t as snapshotToAccessStatus};
+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};

package/dist/metafield.d.ts

@@ -1,13 +1,14 @@
 /**
  * The experienceIds product metafield. The Fanfare app DEFINES it under the
  * reserved namespace `$app:product`, which Shopify rewrites at runtime to
- * `app--<numericAppId>--product`. A headless Storefront-API caller must use the
- * reified namespace — the literal form returns null. The numeric app id is not
- * storefront-readable and is provisioned out-of-band.
+ * `app--<numericAppId>--product`. The `$app:` namespace is resolved SERVER-SIDE
+ * by the Fanfare app proxy; the storefront never addresses the reified numeric
+ * namespace directly.
  *
- * PLACEHOLDER NOTE: the reified-namespace read against the live Storefront API is
- * wired by createShopifyExperienceResolver; the constant and parser below are the
- * stable, final-shaped primitives that read does not change.
+ * The live read is an app-proxy fetch
+ * (`GET {proxyBaseUrl}/experiences/ids-by-handle/{handle}`) performed by
+ * createShopifyExperienceResolver; the constant and parser below are the stable
+ * primitives the preload tier builds on.
  */
 export declare const FANFARE_PRODUCT_METAFIELD: {
     readonly key: "experienceIds";
@@ -15,12 +16,13 @@ export declare const FANFARE_PRODUCT_METAFIELD: {
     readonly appRelativeNamespace: "$app:product";
 };
 /**
- * Parse the raw metafield value into an ordered experience-id list. PURE and
- * SSR-safe, TOTAL (never throws):
+ * Parse the raw metafield value into an ordered experience-id list. Pure,
+ * SSR-safe, and never throws — every input yields a list (empty on anything
+ * unusable):
  *  - JSON array of strings → that array, order preserved
  *  - array containing any non-string entry → [] (the platform contract is a
  *    list of single-line text fields; a structurally mixed array is unusable)
- *  - non-array / pre-migration scalar / malformed JSON → []
+ *  - non-array / bare scalar / malformed JSON → []
  *  - absent / empty → []
  */
 export declare function parseExperienceIds(metafieldValue: string | null | undefined): string[];

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

@@ -0,0 +1,39 @@
+import { ReactNode } from 'react';
+import { ShopifyProductRef } from '../config';
+import { FanfareDenialReason } from './use-fanfare-grant';
+export interface FanfareCheckoutGateProps {
+    /**
+     * Your cart's line items — each a Shopify product reference (the same
+     * `ShopifyProductRef` shape `useFanfareExperience` takes). The gate resolves
+     * each to its Fanfare experience to find out whether any line is gated.
+     *
+     * The gating decision is keyed on `handle` only — the live app-proxy read
+     * and the `map`/`metafieldValues` lookups all index by handle. `id` is optional
+     * (carried for forward-compat with the claim/checkout path); the gate never
+     * reads it, so omitting it — or an imprecise value — does NOT affect the gating
+     * decision here. `{ handle }` per line is enough.
+     */
+    cartItems: ShopifyProductRef[];
+    /**
+     * Rendered when a gated line is present but the shopper has no valid grant. A
+     * node, or a render prop passed the verifier's denial reason.
+     *
+     * `reason` is a `FanfareDenialReason` (an OPEN union) — a short machine-readable
+     * code you can branch on for tailored copy. The gate emits only the three
+     * client-side codes: `"no_grant"`, `"grant_expired"`, and `"verify_failed"`.
+     * The proxy/transport family (`"no_checkout_context"`, `"verify_unreachable"`,
+     * and the DYNAMIC `` `proxy_${status}` ``) is surfaced by `claim()` / the opt-in
+     * reserve verifier, NOT by this gate. `reason` is `undefined` only if a future
+     * verifier denies without a code. Send the shopper back to clear the drop.
+     */
+    onDenied: ReactNode | ((reason: FanfareDenialReason) => ReactNode);
+    /**
+     * Rendered while the gate is resolving the cart / verifying the grant. Keep it
+     * quiet (a spinner, or nothing) — defaults to rendering nothing so the gate does
+     * not flash. Never let the shopper proceed during this state.
+     */
+    fallback?: ReactNode;
+    /** Rendered once the shopper is allowed (no gated line, or a valid grant). */
+    children: ReactNode;
+}
+export declare function FanfareCheckoutGate({ cartItems, onDenied, fallback, children }: FanfareCheckoutGateProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as e,Fragment as r}from"react/jsx-runtime";import{useState as n,useRef as t,useMemo as o,useEffect as a}from"react";import{parseFirstExperienceId as i}from"../metafield.js";import{resolveShopifyExperienceId as s}from"../resolver.js";import{useShopifyAdapter as l}from"./shopify-provider.js";import{useFanfareGrant as c}from"./use-fanfare-grant.js";function d({cartItems:d,onDenied:m,fallback:u=null,children:f}){const{config:p}=l(),{experiences:h,shopify:g,mode:v}=p,[x,y]=n({phase:"resolving"}),j=t(0),k=o(()=>d.map(e=>`${e.handle} ${e.id}`).join(" "),[d]),P=t(d);P.current=d,a(()=>{const e=P.current,r=++j.current;if(y({phase:"resolving"}),0!==e.length)return Promise.all(e.map(e=>function(e,r,n){switch(r.source){case"static":return Promise.resolve(r.experienceId);case"map":return Promise.resolve(r.values[e.handle]??null);case"metafield":{const t=r.metafieldValues?.[e.handle];return void 0===r.resolveExperience&&void 0!==t?Promise.resolve(i(t)):s(e,function(e,r){return{proxyBaseUrl:e.proxyBaseUrl??"",metafieldValues:r.metafieldValues,resolveExperience:r.resolveExperience}}(n,r))}}}(e,h,g))).then(e=>{if(j.current!==r)return;const n=e.some(e=>null!==e);y({phase:n?"gated":"ungated"})}),()=>{j.current++};y({phase:"ungated"})},[k,h,g]);const w=c();return"resolving"===x.phase?/* @__PURE__ */e(r,{children:u}):"ungated"===x.phase?/* @__PURE__ */e(r,{children:f}):"demo"===v?/* @__PURE__ */e("div",{"data-testid":"fanfare-demo-gate-warning",role:"alert",children:'Fanfare demo mode — this gate is not production-safe. The checkout is not actually enforced; set mode="production" with a proxyBaseUrl for real gating.'}):"checking"===w.state?/* @__PURE__ */e(r,{children:u}):"blocked"===w.state?/* @__PURE__ */e(r,{children:"function"==typeof m?m(w.reason):m}):/* @__PURE__ */e(r,{children:f})}export{d as FanfareCheckoutGate};

package/dist/react/index.d.ts

@@ -2,6 +2,29 @@
  * React bindings for the Shopify storefront adapter. Carries the React peer dep
  * and the `"use client"` boundary; the isomorphic resolver/verifier/metafield
  * surface lives at the package root (`@fanfare-io/fanfare-sdk-shopify`).
+ *
+ * `FanfareShopifyProvider` is the single provider the integrator configures with
+ * 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.
  */
-export { FanfareAdapterProvider, useFanfareAdapter } from './adapter-context';
-export type { FanfareAdapterValue } from './adapter-context';
+export type { ClaimRefusalReason, ClaimResult } from '../claimer';
+export type { ExperienceSource, FanfareMode, ShopifyAdapterConfig, ShopifyProductRef } from '../config';
+export { FanfareConfigurationError } from '../errors';
+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 { useFanfareClaim } from './use-fanfare-claim';
+export type { 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';
+export type { FanfareDenialReason, FanfareGrantState } from './use-fanfare-grant';
+export { useFanfareWidgetBridge } from './use-fanfare-widget-bridge';
+export type { FanfareWidgetBridge } from './use-fanfare-widget-bridge';

package/dist/react/index.js

@@ -1,2 +1,2 @@
 "use client";
-import{FanfareAdapterProvider as t,useFanfareAdapter as o}from"./adapter-context.js";export{t as FanfareAdapterProvider,o as useFanfareAdapter};
+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};

package/dist/react/shopify-provider.d.ts

@@ -0,0 +1,71 @@
+import { ReactNode } from 'react';
+import { JourneySnapshot } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { AccessStatus, CheckoutVerifier, GrantRecord } from '@fanfare-io/fanfare-sdk-core/storefront';
+import { ExperienceSource, FanfareMode, ShopifyAdapterConfig } from '../config';
+import { ShopifyCheckoutContext } from '../verifier';
+export type { ExperienceSource } from '../config';
+/** The fully-resolved config the provider holds and exposes to the internal hooks. */
+export interface ResolvedShopifyConfig {
+    organizationId: string;
+    publishableKey: string;
+    mode: FanfareMode;
+    shopify: ShopifyAdapterConfig;
+    experiences: ExperienceSource;
+}
+/**
+ * The INTERNAL adapter value. Carried by an internal context and read via the
+ * internal `useShopifyAdapter` hook — NOT a public `useFanfareAdapter`. The
+ * public hooks consume this; integrators never touch it.
+ */
+export interface ShopifyAdapterValue {
+    /** The resolved provider config (mode + store + experience source). */
+    config: ResolvedShopifyConfig;
+    /** Latest journey snapshot reported by the widget driving the journey. */
+    snapshot: JourneySnapshot | null;
+    /** Access status derived from the snapshot. */
+    status: AccessStatus;
+    /** Grant recorded when the shopper cleared the drop (survives reloads). */
+    grant: GrantRecord | null;
+    reportSnapshot(snapshot: JourneySnapshot): void;
+    recordGrant(grant: GrantRecord): void;
+    clearGrant(): void;
+    /** The internal client-only verifier (the checkout gate consumes it). */
+    verifier: CheckoutVerifier;
+    /**
+     * Internal cart/checkout-context plumbing. `useFanfareClaim` sets the active
+     * cart here so the filled checkout context has a cartId to pair with.
+     */
+    setActiveCartId(cartId: string | null): void;
+    /**
+     * Returns the live checkout context `{ credential, distributionId, cartId }`
+     * from internal state, or `null` when any piece is missing (not yet ready).
+     * `credential` = the recorded grant token; `distributionId` = captured from the
+     * journey snapshot; `cartId` = the active cart slot.
+     */
+    getCheckoutContext(): ShopifyCheckoutContext | null;
+}
+export interface FanfareShopifyProviderProps {
+    organizationId: string;
+    publishableKey: string;
+    /** Operating mode. Defaults to `"production"` (real verify + claim via proxy). */
+    mode?: FanfareMode;
+    shopify: ShopifyAdapterConfig;
+    /**
+     * Where the Shopify→experience mapping comes from. Defaults to
+     * `{ source: "metafield" }`, whose live tier reads the product's `experienceIds`
+     * through the app proxy (`GET {proxyBaseUrl}/experiences/ids-by-handle/{handle}`).
+     * All three variants are fully resolved — `"static"` and `"map"` synchronously
+     * by handle, `"metafield"` via the preloaded fast path or a live read — by both
+     * `useFanfareExperience` and `<FanfareCheckoutGate>`. See `ExperienceSource` for
+     * the full resolution order per source.
+     */
+    experiences?: ExperienceSource;
+    children: ReactNode;
+}
+export declare function FanfareShopifyProvider({ organizationId, publishableKey, mode, shopify, experiences, children, }: FanfareShopifyProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * INTERNAL hook over the adapter context. NOT public — the public hooks
+ * (`useFanfareExperience` / `useFanfareGrant` / `useFanfareClaim`) build on it.
+ * Throws when used outside `FanfareShopifyProvider`.
+ */
+export declare function useShopifyAdapter(): ShopifyAdapterValue;

package/dist/react/shopify-provider.js

@@ -0,0 +1,3 @@
+"use client";
+import{jsx as r}from"react/jsx-runtime";import{useState as e,useRef as n,useCallback as t,useMemo as o,createContext as i,useContext as u}from"react";import{getParticipation as s,getDistribution as a}from"@fanfare-io/fanfare-sdk-core/internals";import{snapshotToAccessStatus as c}from"@fanfare-io/fanfare-sdk-core/storefront";import{assertShopifyConfig as l}from"../config.js";import{shopifyCheckoutVerifier as f}from"../verifier.js";const d={source:"metafield"},p="storefront_adapter_grant",m=i(null);function h(){if("undefined"==typeof window)return null;try{return function(r){if(null===r)return null;try{return JSON.parse(r)}catch{return null}}(window.sessionStorage.getItem(p))}catch{return null}}function y({organizationId:i,publishableKey:u,mode:y="production",shopify:g,experiences:w=d,children:v}){l({mode:y,shopify:g});const[I,S]=e(null),[b,x]=e(()=>h()),k=n(null),j=n(null);j.current=I;const C=n(null);C.current=b;const z=t(r=>{S(r)},[]),A=t(r=>{x(r);try{window.sessionStorage.setItem(p,JSON.stringify(r))}catch{}},[]),G=t(()=>{x(null);try{window.sessionStorage.removeItem(p)}catch{}},[]),J=t(r=>{k.current=r},[]),K=t(()=>{const r=C.current?.token,e=function(r){if(null!==r)return s(r)?.id??a(r)?.id}(j.current),n=k.current;return void 0===r||void 0===e||null===n?null:{credential:r,distributionId:e,cartId:n}},[]),N=o(()=>f,[]),O=o(()=>({organizationId:i,publishableKey:u,mode:y,shopify:g,experiences:w}),[i,u,y,g,w]),P=o(()=>({config:O,snapshot:I,status:c(I),grant:b,reportSnapshot:z,recordGrant:A,clearGrant:G,verifier:N,setActiveCartId:J,getCheckoutContext:K}),[O,I,b,z,A,G,N,J,K]);/* @__PURE__ */
+return r(m.Provider,{value:P,children:v})}function g(){const r=u(m);if(null===r)throw new Error("useShopifyAdapter must be used within FanfareShopifyProvider");return r}export{y as FanfareShopifyProvider,g as useShopifyAdapter};

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

@@ -0,0 +1,21 @@
+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;
+     * `no_claim_context` means not-yet-ready). Never rejects — every outcome
+     * resolves to a `ClaimResult`.
+     */
+    claim(cartId: string): Promise<ClaimResult>;
+    /** `"idle"` → `"claiming"` → `"claimed"` | `"error"`. */
+    state: FanfareClaimState;
+}
+export declare function useFanfareClaim(): UseFanfareClaimResult;

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

@@ -0,0 +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};

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

@@ -0,0 +1,8 @@
+import { ShopifyProductRef } from '../config';
+export interface UseFanfareExperienceResult {
+    /** The Fanfare experience id for this product, or `null` when not gated. */
+    experienceId: string | null;
+    /** `true` while an async (live-fetch / override) resolution is in flight. */
+    loading: boolean;
+}
+export declare function useFanfareExperience(shopifyProduct: ShopifyProductRef): UseFanfareExperienceResult;

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

@@ -0,0 +1,2 @@
+"use client";
+import{useMemo as e,useState as r,useRef as n,useEffect as i}from"react";import{parseFirstExperienceId as c}from"../metafield.js";import{resolveShopifyExperienceId as d}from"../resolver.js";import{useShopifyAdapter as o}from"./shopify-provider.js";function s(s){const{config:t}=o(),{experiences:l,shopify:a}=t,{handle:p,id:u}=s,x=e(()=>function(e,r){switch(r.source){case"static":return{sync:!0,experienceId:r.experienceId};case"map":return{sync:!0,experienceId:r.values[e.handle]??null};case"metafield":{if(void 0!==r.resolveExperience)return{sync:!1};const n=r.metafieldValues?.[e.handle];return void 0!==n?{sync:!0,experienceId:c(n)}:{sync:!1}}}}({handle:p},l),[p,u,l]),[f,m]=r(()=>x.sync?{experienceId:x.experienceId,loading:!1}:{experienceId:null,loading:!0}),I=n(0);return i(()=>{if(x.sync)return void m({experienceId:x.experienceId,loading:!1});if("metafield"!==l.source)return;const e=++I.current;return m({experienceId:null,loading:!0}),d({handle:p,id:u},function(e,r){return{proxyBaseUrl:e.proxyBaseUrl??"",metafieldValues:r.metafieldValues,resolveExperience:r.resolveExperience}}(a,l)).then(r=>{I.current===e&&m({experienceId:r,loading:!1})}),()=>{I.current++}},[x,p,u,l,a]),x.sync?{experienceId:x.experienceId,loading:!1}:f}export{s as useFanfareExperience};

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

@@ -0,0 +1,44 @@
+/**
+ * The short denial codes carried on a `"blocked"` grant. Use these to branch on
+ * WHY a shopper was denied (e.g. distinct copy for "never cleared the drop" vs.
+ * "grant expired").
+ *
+ * REACHABLE VIA THE GATE (the client-only verifier this hook wires):
+ *  - `"no_grant"` — no grant was ever recorded (the shopper never cleared the drop).
+ *  - `"grant_expired"` — the recorded grant's `expiresAt` is in the past, compared
+ *    against `Date.now()`. CLOCK-SKEW CAVEAT: a fast client clock can mark a still-
+ *    server-valid grant expired here. This is a defense-in-depth client pre-check
+ *    only — `claim()` re-validates the grant server-side, so a skewed client cannot
+ *    grant access it shouldn't, only deny access it might have had.
+ *  - `"verify_failed"` — the client-only verifier threw while reading the grant.
+ *
+ * NOT reachable via the gate — surfaced by `claim()` / the opt-in reserve verifier
+ * (`createShopifyCheckoutVerifier`), which drives the app proxy:
+ *  - `"no_checkout_context"` — no live checkout context (no credential/cart yet —
+ *    the storefront is not ready to check out / reserve).
+ *  - `"verify_unreachable"` — the proxy request threw / timed out (transport
+ *    failure); the proxy could not be reached.
+ *  - `` `proxy_${number}` `` — a non-2xx proxy response, templated on the HTTP
+ *    status (e.g. `"proxy_403"`, `"proxy_500"`). DYNAMIC, so it is not
+ *    exhaustively enumerable — match it with `reason?.startsWith("proxy_")`,
+ *    not an equality case.
+ *
+ * The string fallback keeps this open for a future verifier that denies with a
+ * code not listed here; the literal members exist so an editor can autocomplete
+ * the known codes and so a `switch` over them is meaningful.
+ */
+export type FanfareDenialReason = "no_grant" | "grant_expired" | "verify_failed" | "no_checkout_context" | "verify_unreachable" | `proxy_${number}` | (string & {}) | undefined;
+/** The shopper's access state for the gated drop. */
+export interface FanfareGrantState {
+    /**
+     * `"checking"` while verifying; `"allowed"` once a valid grant is confirmed;
+     * `"blocked"` when there is no valid grant.
+     */
+    state: "checking" | "allowed" | "blocked";
+    /**
+     * A short denial code from the verifier when `state === "blocked"`. See
+     * `FanfareDenialReason` for the canonical codes (note `proxy_*` is dynamic).
+     */
+    reason?: FanfareDenialReason;
+}
+export declare function useFanfareGrant(): FanfareGrantState;

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

@@ -0,0 +1,2 @@
+"use client";
+import{useState as r,useRef as t,useEffect as e}from"react";import{useShopifyAdapter as n}from"./shopify-provider.js";const o={state:"checking"};function c(){const{grant:c,verifier:s}=n(),[a,i]=r(o),u=t(0);return e(()=>{if(null===c)return u.current++,void i({state:"blocked",reason:"no_grant"});const r=++u.current;return i(o),s.verify(c).then(t=>{u.current===r&&i(t.ok?{state:"allowed"}:{state:"blocked",reason:t.reason})}),()=>{u.current++}},[c,s]),a}export{c as useFanfareGrant};

package/dist/react/use-fanfare-widget-bridge.d.ts

@@ -0,0 +1,16 @@
+import { JourneySnapshot } from '@fanfare-io/fanfare-sdk-core/experiences';
+/**
+ * The handler set to spread onto your drop journey widget. Today this is a single
+ * `onJourneyChange`; it is returned as an object so the wiring is a stable
+ * `{...bridge}` spread that can carry additional widget handlers in future without
+ * an integrator-visible change.
+ */
+export interface FanfareWidgetBridge {
+    /**
+     * Spread onto `<ExperienceWidget onJourneyChange={...} />`. Called with the
+     * latest `JourneySnapshot` on every journey update; it reports the snapshot to
+     * the provider and records the grant once the journey is granted.
+     */
+    onJourneyChange(snapshot: JourneySnapshot): void;
+}
+export declare function useFanfareWidgetBridge(): FanfareWidgetBridge;

package/dist/react/use-fanfare-widget-bridge.js

@@ -0,0 +1,2 @@
+"use client";
+import{useCallback as r,useMemo as e}from"react";import{getSequencePhase as o,getAdmissionGrant as n,getAdmissionGrantExpiresAt as t}from"@fanfare-io/fanfare-sdk-core/internals";import{useShopifyAdapter as i}from"./shopify-provider.js";function p(){const{reportSnapshot:p,recordGrant:a}=i(),f=r(r=>{if(p(r),"granted"!==o(r))return;const e=n(r);void 0!==e&&a({token:e,experienceId:r.experienceId,expiresAt:t(r)})},[p,a]);return e(()=>({onJourneyChange:f}),[f])}export{p as useFanfareWidgetBridge};

package/dist/resolver.d.ts

@@ -1,43 +1,57 @@
 import { ExperienceResolver } from '@fanfare-io/fanfare-sdk-core/storefront';
+import { ShopifyProductRef } from './config';
 export interface ShopifyExperienceResolverConfig {
-    /** Shop domain, e.g. "shop.myshopify.com". */
-    shopDomain: string;
-    /** Storefront API version, e.g. "2024-10". */
-    apiVersion: string;
-    /** PUBLIC Storefront-API access token (experienceIds is PUBLIC_READ). */
-    storefrontAccessToken: string;
-    /** Numeric Shopify app id, provisioned out-of-band; reifies the namespace. */
-    fanfareAppId: string;
     /**
-     * PLACEHOLDER-ONLY static map of product `handle` → raw `experienceIds`
-     * metafield value. The placeholder body resolves `resolve(product)` from this
-     * map via `parseFirstExperienceId`, so the contract + parser path is exercised
-     * end-to-end without a network. The live Storefront-API read of the reified
-     * `app--<fanfareAppId>--product` / `experienceIds` metafield replaces this map
-     * (the only body change that lands later) — `resolve(product)`'s signature does
-     * NOT change. Omit it once the live read is wired.
+     * App-proxy base, e.g. "https://shop.myshopify.com/apps/fanfare/api". The live
+     * resolution tier fetches `${proxyBaseUrl}/experiences/ids-by-handle/${handle}`;
+     * the proxy resolves the `$app:` namespace server-side, so no Storefront creds
+     * or numeric app id are needed here.
+     */
+    proxyBaseUrl: string;
+    /**
+     * SSR fast path: a preloaded map of product `handle` → raw `experienceIds`
+     * metafield value (the JSON-array string like `'["exp_1"]'`, not a bare id).
+     * When the product's handle is present, `resolve(product)` parses it via
+     * `parseFirstExperienceId` and performs NO network call. When the handle is
+     * absent, `resolve(product)` falls through to the live app-proxy read below.
+     * Provide it to resolve from values you have already SSR-loaded; omit it to
+     * always go to the network.
      */
     metafieldValues?: Record<string, string>;
     /**
-     * RESERVED — not read by the placeholder body. The live Storefront-API read
-     * will use this injectable (SSR/test seam) and default to `globalThis.fetch`.
-     * Until that read lands, supplying it is a no-op: the placeholder resolves
-     * from `metafieldValues` and never performs a network call. A contract test
-     * pins this (a supplied `fetchImpl` is never invoked).
+     * Full-control override: your own product → experienceId function. When supplied
+     * it takes precedence over both the preloaded map and the live read. May be sync
+     * or async; return a bare Fanfare id (`"exp_1"`) or `null` for an uncovered
+     * product.
+     */
+    resolveExperience?: (product: ShopifyProductRef) => string | null | Promise<string | null>;
+    /**
+     * Injectable fetch (SSR/test seam) for the live app-proxy read of the product's
+     * experience ids by handle. Defaults to `globalThis.fetch`. Only exercised when
+     * neither `resolveExperience` nor a preloaded `metafieldValues[handle]` covers
+     * the product.
      */
     fetchImpl?: typeof fetch;
 }
 /**
- * Build a Shopify ExperienceResolver. `resolve(product)` returns the experience
- * id carried by the product's `experienceIds` metafield (first id wins), or null
- * when the product is not covered.
+ * Resolve a Shopify product to its Fanfare experience id (first id wins), or
+ * `null` when the product is not covered. The three-tier resolution:
+ *
+ *  1. `resolveExperience` override, if supplied — used verbatim.
+ *  2. else a preloaded `metafieldValues[handle]` (SSR fast path, no network).
+ *  3. else a live app-proxy read of the experience ids by handle.
+ *
+ * SSR-safe: returns `null` on any miss or failure, never throws. Shared by
+ * `createShopifyExperienceResolver` and the `useFanfareExperience` hook.
+ */
+export declare function resolveShopifyExperienceId(product: ShopifyProductRef, config: ShopifyExperienceResolverConfig): Promise<string | null>;
+/**
+ * Build a Shopify ExperienceResolver. `resolve(product)` returns the product's
+ * Fanfare experience id (first id wins), or null when the product is not covered.
  *
- * PLACEHOLDER (no signature impact): the body currently resolves from the
- * in-config static `metafieldValues` map (handle → raw metafield value) via
- * `parseFirstExperienceId`, so the contract and parser path are exercised
- * end-to-end without a network. Wiring the live Storefront-API read of the
- * reified `app--<fanfareAppId>--product` / `experienceIds` metafield is the only
- * change that lands later — the returned resolver's `resolve(product)` signature
- * does NOT change. See ENG-931 metafield-wiring TODO.
+ * Resolution follows the three-tier order in `resolveShopifyExperienceId`: a
+ * `resolveExperience` override, else a preloaded `metafieldValues[handle]` (SSR
+ * fast path, no network), else a live app-proxy read of
+ * `GET {proxyBaseUrl}/experiences/ids-by-handle/{handle}` via `fetchImpl`.
  */
 export declare function createShopifyExperienceResolver(config: ShopifyExperienceResolverConfig): ExperienceResolver;

package/dist/resolver.js

@@ -1 +1 @@
-import{parseFirstExperienceId as e}from"./metafield.js";function r(r){if(!r.shopDomain||""===r.shopDomain.trim())throw new Error("createShopifyExperienceResolver: shopDomain is required");if(!r.apiVersion||""===r.apiVersion.trim())throw new Error("createShopifyExperienceResolver: apiVersion is required");if(!r.storefrontAccessToken||""===r.storefrontAccessToken.trim())throw new Error("createShopifyExperienceResolver: storefrontAccessToken is required");if(!r.fanfareAppId||!/^\d+$/.test(r.fanfareAppId))throw new Error("createShopifyExperienceResolver: fanfareAppId must be a non-empty numeric string");r.fanfareAppId,r.fetchImpl;const o=r.metafieldValues??{};return{resolve(r){const i=o[r.handle];return e(i)}}}export{r as createShopifyExperienceResolver};
+import{parseFirstExperienceId as e}from"./metafield.js";async function n(e,n){const r=n.fetchImpl??globalThis.fetch,t=`${n.proxyBaseUrl.replace(/\/+$/,"")}/experiences/ids-by-handle/${encodeURIComponent(e.handle)}`;try{const e=await r(t,{method:"GET"});if(!e.ok)return null;return function(e){if("object"!=typeof e||null===e)return null;const n=e.experienceIds;if(!Array.isArray(n))return null;const r=n[0];return"string"==typeof r?r:null}(await e.json())}catch{return null}}async function r(r,t){if(void 0!==t.resolveExperience)try{return await t.resolveExperience(r)??null}catch{return null}const l=t.metafieldValues?.[r.handle];return void 0!==l?e(l):n(r,t)}export{r as resolveShopifyExperienceId};

package/dist/verifier.d.ts

@@ -3,19 +3,72 @@ import { CheckoutVerifier } from '@fanfare-io/fanfare-sdk-core/storefront';
  * Shopify checkout verifier. Called at checkout entry with the grant the adapter
  * recorded when the shopper cleared the drop.
  *
- * TOTAL: resolves for every grant — never rejects (the checkout gate consumes it
- * with `.then()` only, so a thrown failure would strand the gate in "checking" or
- * surface as an unhandled rejection). An expired grant resolves
+ * Never throws — it always resolves to a result for every grant (the checkout
+ * gate consumes it with `.then()` only, so a thrown failure would strand the gate
+ * in "checking" or surface as an unhandled rejection). An expired grant resolves
  * { ok:false, reason:"grant_expired" }; any unexpected throw is caught and
  * resolves { ok:false, reason:"verify_failed" }.
  *
- * PLACEHOLDER (no signature impact): the body currently enforces only client-side
- * expiry (rejects an expired grant, accepts an unexpired one). The ENG-913
- * server-validatable handoff — mint at claim, redeem + validate at checkout entry
- * — slots in behind this exact `verify(grant)` signature later; callers do not
- * change. The ENG-913 body redeems `grant.token` (the minted handoff token,
- * marked by `grant.handoffToken === true`) via core's `processHandoffToken`, which
- * THROWS on invalid/expired/replayed — the verifier MUST catch that and return
- * { ok:false, reason } so the contract stays total. See ENG-913.
+ * This zero-config default enforces only client-side grant expiry, so a
+ * storefront can render the gate without any server wiring. For server-side
+ * enforcement, use `createShopifyCheckoutVerifier(config)` below, which drives
+ * the Fanfare Shopify app proxy.
  */
 export declare const shopifyCheckoutVerifier: CheckoutVerifier;
+/**
+ * The live checkout context the `verify(grant)` seam does not itself carry. The
+ * `CheckoutVerifier.verify` contract receives only a `GrantRecord` (UX/continuity
+ * state), but driving the proxy needs the consumer's admission credential, the
+ * distribution being checked out, and the cart to gate. The integration supplies
+ * these from its own journey state via `config.getCheckoutContext` — keeping the
+ * credential out of `GrantRecord` and the published surface minimal.
+ */
+export interface ShopifyCheckoutContext {
+    /** The consumer's admission credential (the `admissionGrant` from the
+     * consumer-me snapshot). Proof of admission — relayed to the proxy, never
+     * persisted in Shopify. */
+    credential: string;
+    distributionId: string;
+    /** Ajax cart token (including `?key=`) for Liquid themes, or the Storefront
+     * cart GID for headless. The proxy/cart-bridge resolves it to a cart GID. */
+    cartId: string;
+}
+export interface ShopifyCheckoutVerifierConfig {
+    /** App-proxy base, e.g. "/apps/fanfare/api". `verify` POSTs to
+     * `${proxyBaseUrl}/${endpoint}`. */
+    proxyBaseUrl: string;
+    /**
+     * Supplies the live checkout context the grant seam omits. Returns `null` when
+     * the storefront is not ready to check out (no credential/cart yet), which
+     * `verify` surfaces as a denied result rather than a thrown error.
+     */
+    getCheckoutContext: () => ShopifyCheckoutContext | null | Promise<ShopifyCheckoutContext | null>;
+    /**
+     * Proxy path under `proxyBaseUrl`. Defaults to the checkout-entry reserve
+     * endpoint (validate + reserve + gate-token re-mint). A pre-reservation
+     * eligibility check can point this at the non-consuming claim/validate path.
+     */
+    endpoint?: string;
+    /** Injectable for SSR/test. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Abort the proxy request after this many ms. Without it, a proxy that accepts
+     * the connection but stalls (never responds) leaves `verify()` pending forever
+     * — and the consumer is stuck in `checking`. The abort surfaces as a denied
+     * result so `verify()` always resolves. Defaults to 10s.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Build a Shopify `CheckoutVerifier` that drives the Fanfare app proxy at
+ * checkout entry: it relays the admission credential + cart to the proxy, which
+ * validates against the admission authority, reserves the admission, and
+ * re-mints the platform gate token into the cart metafield. The proxy — not this
+ * client — is the trust boundary; a positive result means "the authority
+ * currently accepts this admission for this cart", never a client assertion.
+ *
+ * Never throws — it always resolves to a result: client-side expiry is a cheap
+ * pre-check; a missing context, a non-2xx proxy response, and any transport throw
+ * all resolve to a denied `{ ok:false, reason }`.
+ */
+export declare function createShopifyCheckoutVerifier(config: ShopifyCheckoutVerifierConfig): CheckoutVerifier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-shopify",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0"
+    "@fanfare-io/fanfare-sdk-core": "0.4.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.2.0"
+    "@fanfare-io/fanfare-sdk-core": "0.4.0"
   },
   "sideEffects": false,
   "keywords": [

package/dist/react/adapter-context.d.ts

@@ -1,26 +0,0 @@
-import { ReactNode } from 'react';
-import { JourneySnapshot } from '@fanfare-io/fanfare-sdk-core/experiences';
-import { AccessStatus, CheckoutVerifier, GrantRecord } from '@fanfare-io/fanfare-sdk-core/storefront';
-export interface FanfareAdapterValue {
-    /** Latest journey snapshot (reported by whatever drives the journey). */
-    snapshot: JourneySnapshot | null;
-    status: AccessStatus;
-    /** Grant recorded when the shopper cleared the drop (survives reloads). */
-    grant: GrantRecord | null;
-    reportSnapshot(snapshot: JourneySnapshot): void;
-    recordGrant(grant: GrantRecord): void;
-    clearGrant(): void;
-    verifier: CheckoutVerifier;
-}
-export declare function FanfareAdapterProvider({ verifier, legacyStorageKeys, children, }: {
-    verifier?: CheckoutVerifier;
-    /**
-     * Prior sessionStorage keys to hydrate a grant from one time, on mount, when
-     * the current key is empty. Lets a drop-in replacement of a bespoke adapter
-     * preserve already-recorded grants. The matched legacy entry is migrated to
-     * the current key and removed. Defaults to none.
-     */
-    legacyStorageKeys?: readonly string[];
-    children: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
-export declare function useFanfareAdapter(): FanfareAdapterValue;

package/dist/react/adapter-context.js

@@ -1,3 +0,0 @@
-"use client";
-import{jsx as r}from"react/jsx-runtime";import{useState as e,useCallback as t,useMemo as n,createContext as o,useContext as i}from"react";import{snapshotToAccessStatus as s}from"@fanfare-io/fanfare-sdk-core/storefront";import{shopifyCheckoutVerifier as a}from"../verifier.js";const u="storefront_adapter_grant",f=o(null);function l(r){if(null===r)return null;try{return JSON.parse(r)}catch{return null}}function c({verifier:o=a,legacyStorageKeys:i=[],children:c}){const[d,m]=e(null),[w,g]=e(()=>function(r){if("undefined"==typeof window)return null;try{const e=l(window.sessionStorage.getItem(u));if(null!==e)return e;for(const t of r){if(t===u)continue;const r=window.sessionStorage.getItem(t),e=l(r);if(null!==e)return window.sessionStorage.setItem(u,r),window.sessionStorage.removeItem(t),e}return null}catch{return null}}(i)),p=t(r=>{m(r)},[]),S=t(r=>{g(r);try{window.sessionStorage.setItem(u,JSON.stringify(r))}catch{}},[]),h=t(()=>{g(null);try{window.sessionStorage.removeItem(u);for(const r of i)r!==u&&window.sessionStorage.removeItem(r)}catch{}},[i]),v=n(()=>({snapshot:d,status:s(d),grant:w,reportSnapshot:p,recordGrant:S,clearGrant:h,verifier:o}),[d,w,p,S,h,o]);/* @__PURE__ */
-return r(f.Provider,{value:v,children:c})}function d(){const r=i(f);if(null===r)throw new Error("useFanfareAdapter must be used within FanfareAdapterProvider");return r}export{c as FanfareAdapterProvider,d as useFanfareAdapter};