@fanfare-io/fanfare-sdk-shopify 0.16.0 → 0.18.0

package/README.md

@@ -15,16 +15,14 @@ from `@fanfare-io/fanfare-sdk-core/storefront`.
 ```tsx
 import { FanfareShopifyProvider } from "@fanfare-io/fanfare-sdk-shopify/react";
 
-function App() {
+// Hoisted so the config keeps one identity for the life of the page. The provider keys its
+// work on the values inside, so an inline literal is also safe — a constant is simply clearer.
+const SHOPIFY_CONFIG = { proxyBaseUrl: "https://shop.example.com/apps/fanfare/api" };
+
+function App({ children }: { children: React.ReactNode }) {
   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 organizationId="org_abc123" publishableKey="pk_live_..." shopify={SHOPIFY_CONFIG}>
+      {children}
     </FanfareShopifyProvider>
   );
 }
@@ -43,9 +41,59 @@ proxy** — verify, claim, AND experience resolution — so there are no Storefr
 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`). |
+| Field          | Required | Where to get it                                                                                                              |
+| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `proxyBaseUrl` | prod     | The Fanfare Shopify app's app-proxy URL on your Online Store's primary domain (`https://<primary-domain>/apps/fanfare/api`). |
+
+#### Use the Online Store's primary domain
+
+`proxyBaseUrl` must name the domain your Shopify **Online Store** serves from — the
+store's primary domain as shown under Settings → Domains. That is the host that
+answers the app-proxy path (`/apps/fanfare/api`) directly, with no redirect. It is
+not necessarily the host your headless page is served from; a headless
+application does not serve the app-proxy route.
+
+When the store has no custom domain, its primary domain is its `*.myshopify.com`
+host and that is the correct value. Once a custom domain is set as primary,
+Shopify answers every request on the myshopify host with a `301` to it, the
+app-proxy path included. A browser cannot follow a redirect on a cross-origin
+request, so every proxy call — experience resolution, `claim`, `reserve` — fails
+before a response is received and surfaces as an opaque "CORS error".
+
+Two independent conditions have to hold for browser calls to succeed:
+
+- `proxyBaseUrl` names the primary domain (answers `200`, not `301`).
+- The page's origin is permitted by the app's **Allowed Domains** setting (an
+  empty list permits every origin).
+
+A password-protected or development store additionally requires the storefront
+password before the app proxy answers. The SDK logs one console warning per base
+when a proxy request fails before a response is received; it names the host and
+both conditions, and cannot tell which one failed.
+
+## Resolve a product
+
+```tsx
+import { useFanfareExperience } from "@fanfare-io/fanfare-sdk-shopify/react";
+
+function ProductPage({ product }: { product: { handle: string; id: string } }) {
+  const experience = useFanfareExperience({ handle: product.handle, id: product.id });
+
+  switch (experience.status) {
+    case "loading":
+      return <Spinner />;
+    case "gated":
+      return <GatedPurchaseUI experienceId={experience.experienceId} />;
+    case "ungated":
+      return <NativePurchaseUI />;
+    case "error":
+      // Fail open: gating is unknown, so the native buy path renders and Shopify's checkout validation still enforces; a drop page may choose to hold instead.
+      return <NativePurchaseUI />;
+  }
+}
+```
+
+Pass onResolutionError={(error) => report(error)} to observe failed resolutions yourself; error.lookupKey is the product handle or id and error.reason is one of "network" | "http" | "malformed" | "unavailable" | "override". Without it the provider logs one console.warn per product and reason to the developer console — nothing is reported to Fanfare. Supplying a handler replaces that fallback. Separately, a request to an absolute proxy base that fails before a response gets one advisory per base naming the host and the configuration to check; that advisory is emitted by the resolver whether or not a handler is supplied, and the provider does not repeat it as a per-product warning.
 
 ## Modes: `production` (default) vs `demo`
 
@@ -62,10 +110,10 @@ A gated product renders a visible "demo — not production-safe" state in this m
 
 ## Entry points
 
-| 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"`)                                                                                               |
+| 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`, whose `onResolutionError` prop observes failed resolutions; `ExperienceSource`), `useFanfareExperience`, `ExperienceResolutionError`, `ExperienceResolutionErrorReason`, `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

package/dist/config.d.ts

@@ -27,10 +27,20 @@ export type FanfareMode = "production" | "demo";
  */
 export interface ShopifyAdapterConfig {
     /**
-     * App-proxy base, e.g. "https://shop.myshopify.com/apps/fanfare/api". The
+     * App-proxy base, e.g. "https://shop.example.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.
+     *
+     * Use the domain the Shopify Online Store serves from — its primary domain
+     * under Settings → Domains, which is `*.myshopify.com` until a custom domain
+     * is made primary. It is the host that answers the app-proxy path without
+     * redirecting, and is not necessarily the host of a headless page. Once a
+     * custom primary domain exists, the myshopify host answers with a redirect,
+     * and a browser cannot follow a redirect on a cross-origin request, so every
+     * proxy call fails before a response is received. The page's origin must
+     * also be permitted by the app's Allowed Domains setting. Such a failure logs
+     * one console warning naming the configured host and both conditions.
      */
     proxyBaseUrl?: string;
 }
@@ -77,14 +87,15 @@ export type ShopifyProductRef = {
  *    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
- *    normalized lookup key; an uncovered product resolves to `null`.
+ *    normalized lookup key; an uncovered product resolves `ungated`.
  *  - `{ 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[key]` (SSR fast path, no network); else a live app-proxy
  *    read (`GET {proxyBaseUrl}/experiences/ids-by-handle/{key}`) that resolves
- *    the `$app:` namespace server-side. Resolution is SSR-safe: any miss or
- *    failure yields `null`, never a throw.
+ *    the `$app:` namespace server-side. Resolution never throws: an uncovered
+ *    product resolves `ungated`; a failed live read resolves `error` with a typed
+ *    reason (see `resolveShopifyExperience`).
  *
  * Note the singular/plural asymmetry: `static`/`map` carry a single
  * `experienceId`, while the underlying metafield is `experienceIds` (plural, a

package/dist/proxy-base-warning.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One-time console diagnostic for an app-proxy request that never reached a
+ * response.
+ *
+ * A `fetch` that REJECTS — rather than resolving with a non-2xx `Response` — means
+ * the browser refused or could not complete the request: it failed before a
+ * response was received. On a Shopify storefront two independent conditions an
+ * integrator controls can each produce it — a `proxyBaseUrl` on a host that
+ * redirects elsewhere (a browser cannot follow a redirect on a cross-origin
+ * request), and a page origin not permitted by the app's Allowed Domains setting —
+ * and the SDK cannot observe which, if either, applies. The message therefore
+ * asks for both to be checked and asserts nothing about what was detected.
+ *
+ * The experience resolver's live read is the only warning site. When a product is
+ * not covered by a preloaded value or an override, it is the first proxy request a
+ * page makes, ahead of any verify or claim, so one site reports the condition for
+ * the whole adapter; the same warning on the verifier and claimer would only
+ * repeat it.
+ *
+ * Only an ABSOLUTE base can reach the condition. A relative base is same-origin by
+ * construction — never redirected to another origin, never subject to a
+ * cross-origin check — so a rejection there has some other cause and earns no
+ * advice.
+ */
+/**
+ * Warn that a request to the configured app-proxy base failed before a response
+ * was received. A no-op for a relative base and for a base already warned about.
+ */
+export declare function warnProxyRequestFailed(configuredBase: string): void;
+/** Drop the warned bases so a test starts from a page that has warned about nothing. */
+export declare function resetProxyRequestWarningForTests(): void;

package/dist/proxy-base-warning.js

@@ -0,0 +1 @@
+const e=/* @__PURE__ */new Set;function t(t){const r=function(e){return e.replace(/\/+$/,"")}(t);let o;try{o=new URL(r).host}catch{return}e.has(r)||(e.add(r),console.warn(`[fanfare] Request to ${o} failed before a response was received. Check both: proxyBaseUrl must be the Shopify Online Store's primary domain (a host that redirects there cannot be used, because a browser cannot follow a redirect on a cross-origin request), and this page's origin must be permitted by the app's Allowed Domains setting.`))}export{t as warnProxyRequestFailed};

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

@@ -1,2 +1,2 @@
 "use client";
-import{jsx as e,Fragment as r}from"react/jsx-runtime";import{useState as o,useRef as t,useMemo as n,useEffect as i}from"react";import{parseFirstExperienceId as s}from"../metafield.js";import{resolveProductLookupKey as a}from"../product-identifier.js";import{resolveShopifyExperienceId as l}from"../resolver.js";import{useShopifyAdapter as c}from"./shopify-provider.js";import{useFanfareGrant as d}from"./use-fanfare-grant.js";function u({cartItems:u,onDenied:m,fallback:f=null,children:p}){const{config:h}=c(),{experiences:v,shopify:g,mode:x}=h,[j,y]=o({phase:"resolving"}),k=t(0),P=n(()=>u.map(e=>`${e.handle} ${e.id}`).join(" "),[u]),w=t(u);w.current=u,i(()=>{const e=w.current,r=++k.current;if(y({phase:"resolving"}),0!==e.length)return Promise.all(e.map(e=>function(e,r,o){switch(r.source){case"static":return Promise.resolve(r.experienceId);case"map":{const o=a(e);return Promise.resolve((null===o?void 0:r.values[o])??null)}case"metafield":{const t=a(e),n=null===t?void 0:r.metafieldValues?.[t];return void 0===r.resolveExperience&&void 0!==n?Promise.resolve(s(n)):l(e,function(e,r){return{proxyBaseUrl:e.proxyBaseUrl??"",metafieldValues:r.metafieldValues,resolveExperience:r.resolveExperience}}(o,r))}}}(e,v,g))).then(e=>{if(k.current!==r)return;const o=e.some(e=>null!==e);y({phase:o?"gated":"ungated"})}),()=>{k.current++};y({phase:"ungated"})},[P,v,g]);const B=d();return"resolving"===j.phase?/* @__PURE__ */e(r,{children:f}):"ungated"===j.phase?/* @__PURE__ */e(r,{children:p}):"demo"===x?/* @__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"===B.state?/* @__PURE__ */e(r,{children:f}):"blocked"===B.state?/* @__PURE__ */e(r,{children:"function"==typeof m?m(B.reason):m}):/* @__PURE__ */e(r,{children:p})}export{u as FanfareCheckoutGate};
+import{jsx as e,Fragment as r}from"react/jsx-runtime";import{useRef as o,useMemo as t,useState as n,useEffect as i}from"react";import{parseFirstExperienceId as a}from"../metafield.js";import{resolveProductLookupKey as s}from"../product-identifier.js";import{resolveShopifyExperience as c}from"../resolver.js";import{useShopifyAdapter as u}from"./shopify-provider.js";import{useFanfareGrant as l}from"./use-fanfare-grant.js";function d({cartItems:d,onDenied:m,fallback:p=null,children:f}){const{config:h,inFlightResolutions:g,reportResolutionError:v}=u(),{experiences:x,shopify:y,mode:j}=h,b=o(0),I=t(()=>d.map(e=>`${e.handle} ${e.id}`).join(" "),[d]),$=o(d);$.current=d;const E=o(x);E.current=x;const k=x.source,w=y.proxyBaseUrl??"",P="metafield"===x.source&&void 0!==x.resolveExperience,V=t(()=>{switch(x.source){case"static":return x.experienceId;case"map":return d.map(e=>{const r=s(e);return null===r?"
":x.values[r]??""}).join("\0");case"metafield":return d.map(e=>{const r=s(e);return null===r?"
":x.metafieldValues?.[r]??""}).join("\0")}},[I,k,d,x]),B=t(()=>`${I}\n${w}\n${P}\n${k}`,[I,w,P,k]),[F,U]=n({boundary:B,phase:"resolving"});i(()=>{const e=$.current,r=E.current,o=++b.current;if(0!==e.length)return Promise.all(e.map(e=>function(e,r,o,t){switch(r.source){case"static":return Promise.resolve(r.experienceId?{outcome:"gated",experienceId:r.experienceId}:{outcome:"ungated"});case"map":{const o=s(e),t=null===o?void 0:r.values[o];return Promise.resolve(t?{outcome:"gated",experienceId:t}:{outcome:"ungated"})}case"metafield":{const n=s(e),i=null===n?void 0:r.metafieldValues?.[n];if(void 0===r.resolveExperience&&void 0!==i){const e=a(i);return Promise.resolve(null===e?{outcome:"ungated"}:{outcome:"gated",experienceId:e})}return c(e,{proxyBaseUrl:o,metafieldValues:r.metafieldValues,resolveExperience:r.resolveExperience,inFlight:t})}}}(e,r,w,g))).then(e=>{if(b.current!==o)return;const r=e.some(e=>"gated"===e.outcome)?"gated":e.some(e=>"error"===e.outcome)?"error":"ungated";U(e=>"error"===r&&e.boundary===B&&"resolving"!==e.phase&&"error"!==e.phase?e:{boundary:B,phase:r});for(const o of e)"error"===o.outcome&&v(o.error)}),()=>{b.current++};U({boundary:B,phase:"ungated"})},[B,I,k,w,P,V,g,v]);const R=l(),D=F.boundary===B?F.phase:"resolving";return"resolving"===D?/* @__PURE__ */e(r,{children:p}):"ungated"===D||"error"===D?/* @__PURE__ */e(r,{children:f}):"demo"===j?/* @__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"===R.state?/* @__PURE__ */e(r,{children:p}):"blocked"===R.state?/* @__PURE__ */e(r,{children:"function"==typeof m?m(R.reason):m}):/* @__PURE__ */e(r,{children:f})}export{d as FanfareCheckoutGate};

package/dist/react/index.d.ts

@@ -20,6 +20,7 @@ export type { FanfareCheckoutCode, FanfareCheckoutFailureKind, FanfareGatedCheck
 export type { ClaimRefusalReason, ClaimResult } from '../claimer';
 export type { ExperienceSource, FanfareMode, ShopifyAdapterConfig, ShopifyProductRef } from '../config';
 export { FanfareConfigurationError } from '../errors';
+export type { ExperienceResolutionError, ExperienceResolutionErrorReason } from '../resolver';
 export { FanfareCheckoutGate } from './fanfare-checkout-gate';
 export type { FanfareCheckoutGateProps } from './fanfare-checkout-gate';
 export { FanfareShopifyProvider } from './shopify-provider';

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

@@ -2,6 +2,7 @@ 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 { ExperienceResolutionError, ShopifyExperienceResolution } from '../resolver';
 import { ShopifyCheckoutContext } from '../verifier';
 export type { ExperienceSource } from '../config';
 /** The fully-resolved config the provider holds and exposes to the internal hooks. */
@@ -20,6 +21,14 @@ export interface ResolvedShopifyConfig {
 export interface ShopifyAdapterValue {
     /** The resolved provider config (mode + store + experience source). */
     config: ResolvedShopifyConfig;
+    /**
+     * Internal. Live reads in flight for this provider, keyed by request URL; both
+     * consumers share it so simultaneous asks for one product issue one request.
+     * Entries live only until their request settles.
+     */
+    inFlightResolutions: Map<string, Promise<ShopifyExperienceResolution>>;
+    /** Internal. Report a settled consumer failure without interrupting resolution. */
+    reportResolutionError(error: ExperienceResolutionError): void;
     /** Latest journey snapshot reported by the widget driving the journey. */
     snapshot: JourneySnapshot | null;
     /** Access status derived from the snapshot. */
@@ -58,11 +67,24 @@ export interface FanfareShopifyProviderProps {
      * by normalized lookup key, `"metafield"` via the preloaded fast path or a live read — by both
      * `useFanfareExperience` and `<FanfareCheckoutGate>`. See `ExperienceSource` for
      * the full resolution order per source.
+     * Resolution outcomes are `loading | gated | ungated | error`, and `error` is reported through `onResolutionError`.
+     * The resolveExperience override is keyed on presence, not identity — swapping one function for another does not re-resolve.
      */
     experiences?: ExperienceSource;
+    /**
+     * Called once per consumer resolution that fails: lookupKey is the product's
+     * handle or id and reason is the typed cause; two consumers of one product
+     * each receive a call. Supplying a handler replaces the default warn. A
+     * throwing handler is caught and falls through to the warn, never breaking
+     * resolution. When omitted, the SDK warns once per (product, reason) in the
+     * developer console only — nothing reaches Fanfare. A request to an absolute
+     * proxy base that fails before a response is received is reported by the
+     * resolver's once-per-base advisory whether or not a handler is supplied.
+     */
+    onResolutionError?: (error: ExperienceResolutionError) => void;
     children: ReactNode;
 }
-export declare function FanfareShopifyProvider({ organizationId, publishableKey, mode, shopify, experiences, children, }: FanfareShopifyProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function FanfareShopifyProvider({ organizationId, publishableKey, mode, shopify, experiences, onResolutionError, 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.

package/dist/react/shopify-provider.js

@@ -1,3 +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,useContext as i,createContext 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=u(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=i(m);if(null===r)throw new Error("useShopifyAdapter must be used within FanfareShopifyProvider");return r}export{y as FanfareShopifyProvider,g as useShopifyAdapter};
+import{jsx as r}from"react/jsx-runtime";import{useState as e,useMemo as n,useRef as t,useCallback as o,useContext as i,createContext as s}from"react";import{getParticipation as u,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",h=s(null);function m(){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:s,mode:y="production",shopify:w,experiences:v=d,onResolutionError:g,children:S}){l({mode:y,shopify:w});const[k,x]=e(null),[I,b]=e(()=>m()),[$]=e(()=>/* @__PURE__ */new Map),E=w.proxyBaseUrl,R=n(()=>function(r){if(void 0===r)return!1;try{return""!==new URL(r).href}catch{return!1}}(E),[E]),P=t(g);P.current=g;const[j]=e(()=>/* @__PURE__ */new Set),C=o(r=>{const e=P.current;if(void 0!==e)try{return void e(r)}catch{}if("network"===r.reason&&R)return;const{lookupKey:n,reason:t,status:o}=r,i=`${n}\n${t}`;j.has(i)||(j.add(i),console.warn(`[fanfare-sdk-shopify] Experience resolution failed for product "${n}" (${t}${void 0===o?"":` ${o}`}). Gating for this product is unknown until a later resolution succeeds. Pass onResolutionError to FanfareShopifyProvider to observe these failures.`))},[j,R]),F=t(null),G=t(null);G.current=k;const K=t(null);K.current=I;const U=o(r=>{x(r)},[]),z=o(r=>{b(r);try{window.sessionStorage.setItem(p,JSON.stringify(r))}catch{}},[]),A=o(()=>{b(null);try{window.sessionStorage.removeItem(p)}catch{}},[]),B=o(r=>{F.current=r},[]),J=o(()=>{const r=K.current?.token,e=function(r){if(null!==r)return u(r)?.id??a(r)?.id}(G.current),n=F.current;return void 0===r||void 0===e||null===n?null:{credential:r,distributionId:e,cartId:n}},[]),N=n(()=>f,[]),O=n(()=>({proxyBaseUrl:E}),[E]),_=n(()=>({organizationId:i,publishableKey:s,mode:y,shopify:O,experiences:v}),[i,s,y,O,v]),L=n(()=>({config:_,inFlightResolutions:$,reportResolutionError:C,snapshot:k,status:c(k),grant:I,reportSnapshot:U,recordGrant:z,clearGrant:A,verifier:N,setActiveCartId:B,getCheckoutContext:J}),[_,k,I,U,z,A,N,B,J,$,C]);/* @__PURE__ */
+return r(h.Provider,{value:L,children:S})}function w(){const r=i(h);if(null===r)throw new Error("useShopifyAdapter must be used within FanfareShopifyProvider");return r}export{y as FanfareShopifyProvider,w as useShopifyAdapter};

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

@@ -1,8 +1,14 @@
 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;
-}
+import { ExperienceResolutionError } from '../resolver';
+export type UseFanfareExperienceResult = {
+    status: "loading";
+} | {
+    status: "gated";
+    experienceId: string;
+} | {
+    status: "ungated";
+} | {
+    status: "error";
+    error: ExperienceResolutionError;
+};
 export declare function useFanfareExperience(shopifyProduct: ShopifyProductRef): UseFanfareExperienceResult;

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

@@ -1,2 +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{resolveProductLookupKey as o}from"../product-identifier.js";import{resolveShopifyExperienceId as d}from"../resolver.js";import{useShopifyAdapter as t}from"./shopify-provider.js";function s(s){const{config:l}=t(),{experiences:p,shopify:u}=l,{handle:a,id:f}=s,x=e(()=>void 0===a?{id:f??""}:{handle:a,id:f},[a,f]),m=e(()=>function(e,r){switch(r.source){case"static":return{sync:!0,experienceId:r.experienceId};case"map":{const n=o(e);return{sync:!0,experienceId:(null===n?void 0:r.values[n])??null}}case"metafield":{if(void 0!==r.resolveExperience)return{sync:!1};const n=o(e),i=null===n?void 0:r.metafieldValues?.[n];return void 0!==i?{sync:!0,experienceId:c(i)}:{sync:!1}}}}(x,p),[x,p]),[I,v]=r(()=>m.sync?{experienceId:m.experienceId,loading:!1}:{experienceId:null,loading:!0}),y=n(0);return i(()=>{if(m.sync)return void v({experienceId:m.experienceId,loading:!1});if("metafield"!==p.source)return;const e=++y.current;return v({experienceId:null,loading:!0}),d(x,function(e,r){return{proxyBaseUrl:e.proxyBaseUrl??"",metafieldValues:r.metafieldValues,resolveExperience:r.resolveExperience}}(u,p)).then(r=>{y.current===e&&v({experienceId:r,loading:!1})}),()=>{y.current++}},[m,x,p,u]),m.sync?{experienceId:m.experienceId,loading:!1}:I}export{s as useFanfareExperience};
+import{useMemo as e,useRef as r,useState as t,useCallback as s,useEffect as o}from"react";import{parseFirstExperienceId as u}from"../metafield.js";import{resolveProductLookupKey as l}from"../product-identifier.js";import{resolveShopifyExperience as i}from"../resolver.js";import{useShopifyAdapter as n}from"./shopify-provider.js";function a(a){const{config:c,inFlightResolutions:d,reportResolutionError:p}=n(),{experiences:m,shopify:f}=c,{handle:v,id:x}=a,g=e(()=>void 0===v?{id:x??""}:{handle:v,id:x},[v,x]),y=e(()=>l(g),[g]),h=m.source,B=f.proxyBaseUrl??"",U="static"===m.source?m.experienceId:void 0,I="map"===m.source&&null!==y?m.values[y]:void 0,k="metafield"===m.source&&null!==y?m.metafieldValues?.[y]:void 0,K="metafield"===m.source&&void 0!==m.resolveExperience,O=r(m);O.current=m;const j=e(()=>{switch(h){case"static":return U?{status:"gated",experienceId:U}:{status:"ungated"};case"map":return I?{status:"gated",experienceId:I}:{status:"ungated"};case"metafield":{if(void 0===k||K)return null;const e=u(k);return null===e?{status:"ungated"}:{status:"gated",experienceId:e}}}},[h,U,I,k,K]),[E,V]=t({lookupKey:y,proxyBaseUrl:B,hasOverride:K,source:h,result:null}),F=s(e=>e.lookupKey===y&&e.proxyBaseUrl===B&&e.hasOverride===K&&e.source===h,[y,B,K,h]),R=F(E)?E.result:null,w=r(0);return o(()=>{if(V(e=>F(e)?e:{lookupKey:y,proxyBaseUrl:B,hasOverride:K,source:h,result:null}),null!==j)return void V(e=>F(e)&&e.result===j?e:{lookupKey:y,proxyBaseUrl:B,hasOverride:K,source:h,result:j});const e=O.current;if("metafield"!==e.source)return;const r=++w.current;return i(g,{proxyBaseUrl:B,metafieldValues:e.metafieldValues,resolveExperience:e.resolveExperience,inFlight:d}).then(e=>{if(w.current!==r)return;const t="gated"===e.outcome?{status:"gated",experienceId:e.experienceId}:"ungated"===e.outcome?{status:"ungated"}:{status:"error",error:e.error};V(e=>{const r=F(e)?e.result:null;return"error"===t.status&&null!==r&&"error"!==r.status?e:{lookupKey:y,proxyBaseUrl:B,hasOverride:K,source:h,result:t}}),"error"===e.outcome&&p(e.error)}),()=>{w.current++}},[j,F,y,g,B,k,K,h,d,p]),j??R??{status:"loading"}}export{a as useFanfareExperience};

package/dist/resolver.d.ts

@@ -1,8 +1,28 @@
 import { ExperienceResolver } from '@fanfare-io/fanfare-sdk-core/storefront';
 import { ShopifyProductRef } from './config';
+export type ExperienceResolutionErrorReason = "network" | "http" | "malformed" | "unavailable" | "override";
+export interface ExperienceResolutionError {
+    /** The normalized product lookup key (a handle or product id — never a consumer identifier). */
+    lookupKey: string;
+    reason: ExperienceResolutionErrorReason;
+    /** HTTP status code when `reason === "http"`. */
+    status?: number;
+    /** The thrown value when `reason` is `"network"` or `"override"`. */
+    cause?: unknown;
+}
+export type ShopifyExperienceResolution = {
+    outcome: "gated";
+    experienceId: string;
+} | {
+    outcome: "ungated";
+} | {
+    outcome: "error";
+    error: ExperienceResolutionError;
+};
 export interface ShopifyExperienceResolverConfig {
     /**
-     * App-proxy base, e.g. "https://shop.myshopify.com/apps/fanfare/api". The live
+     * App-proxy base on the Online Store's primary domain, e.g.
+     * "https://shop.example.com/apps/fanfare/api". The live
      * resolution tier fetches `${proxyBaseUrl}/experiences/ids-by-handle/${key}`;
      * the proxy resolves the `$app:` namespace server-side, so no Storefront creds
      * or numeric app id are needed here.
@@ -32,28 +52,32 @@ export interface ShopifyExperienceResolverConfig {
      * the product.
      */
     fetchImpl?: typeof fetch;
+    /**
+     * Shared in-flight live reads keyed by request URL; an entry is removed when
+     * its request settles. Supply a shared map to coalesce concurrent live reads
+     * across callers; absent means no coalescing. A request that never settles keeps
+     * its entry, so every later read of the same URL joins it; no deadline is applied.
+     */
+    inFlight?: Map<string, Promise<ShopifyExperienceResolution>>;
 }
 /**
- * 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[key]` (SSR fast path, no network).
- *  3. else a live app-proxy read of the experience ids by key.
- *
- * The lookup key is normalized from the product ref by `resolveProductLookupKey`
- * (a handle as-is, a storefront URL reduced to its handle, a global/numeric id
- * forwarded for the proxy to classify), so an integrator passing the wrong shape
- * of "product id" still resolves. SSR-safe: returns `null` on any miss, an
- * unresolvable ref, or failure — never throws. Shared by
- * `createShopifyExperienceResolver` and the `useFanfareExperience` hook.
+ * Resolve a Shopify product to a gated, ungated, or typed error outcome.
+ * Resolution uses the override first, then a preloaded metafield value, then
+ * a live app-proxy read. The normalized lookup key accepts handles, storefront
+ * product URLs, and product ids. An unresolvable ref is ungated; failures are
+ * returned as error outcomes rather than thrown.
+ */
+export declare function resolveShopifyExperience(product: ShopifyProductRef, config: ShopifyExperienceResolverConfig): Promise<ShopifyExperienceResolution>;
+/**
+ * Core's `ExperienceResolver` seam has no error slot, so error outcomes collapse
+ * to `null` there.
  */
 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.
+ * Fanfare experience id (first id wins), or null when the product is not covered or resolution fails.
  *
- * Resolution follows the three-tier order in `resolveShopifyExperienceId`: a
+ * Resolution follows the three-tier order in `resolveShopifyExperience`: a
  * `resolveExperience` override, else a preloaded `metafieldValues[key]` (SSR
  * fast path, no network), else a live app-proxy read of
  * `GET {proxyBaseUrl}/experiences/ids-by-handle/{key}` via `fetchImpl`.

package/dist/resolver.js

@@ -1 +1 @@
-import{parseFirstExperienceId as e}from"./metafield.js";import{resolveProductLookupKey as n}from"./product-identifier.js";async function r(e,n){const r=n.fetchImpl??globalThis.fetch,t=`${n.proxyBaseUrl.replace(/\/+$/,"")}/experiences/ids-by-handle/${encodeURIComponent(e)}`;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 t(t,l){if(void 0!==l.resolveExperience)try{return await l.resolveExperience(t)??null}catch{return null}const o=n(t);if(null===o)return null;const i=l.metafieldValues?.[o];return void 0!==i?e(i):r(o,l)}export{t as resolveShopifyExperienceId};
+import{parseFirstExperienceId as e}from"./metafield.js";import{resolveProductLookupKey as r}from"./product-identifier.js";import{warnProxyRequestFailed as o}from"./proxy-base-warning.js";async function t(t,n){if(void 0!==n.resolveExperience)try{const e=await n.resolveExperience(t);return null==e?{outcome:"ungated"}:{outcome:"gated",experienceId:e}}catch(c){return{outcome:"error",error:{lookupKey:r(t)??"",reason:"override",cause:c}}}const u=r(t);if(null===u)return{outcome:"ungated"};const a=n.metafieldValues?.[u];if(void 0!==a){const r=e(a);return null===r?{outcome:"ungated"}:{outcome:"gated",experienceId:r}}return function(e,r){const t=r.fetchImpl??globalThis.fetch,n=r.proxyBaseUrl.replace(/\/+$/,""),u=`${n}/experiences/ids-by-handle/${encodeURIComponent(e)}`,a=r.inFlight?.get(u);if(void 0!==a)return a;const i=(async()=>{let r,a;try{if(r=await t(u,{method:"GET"}),!r.ok)return{outcome:"error",error:{lookupKey:e,reason:"http",status:r.status}}}catch(c){return o(n),{outcome:"error",error:{lookupKey:e,reason:"network",cause:c}}}try{a=await r.json()}catch{return{outcome:"error",error:{lookupKey:e,reason:"malformed"}}}if("object"!=typeof a||null===a)return{outcome:"error",error:{lookupKey:e,reason:"malformed"}};const{experienceIds:i,liveness:l}=a;if("unavailable"===l)return{outcome:"error",error:{lookupKey:e,reason:"unavailable"}};if(!Array.isArray(i))return{outcome:"error",error:{lookupKey:e,reason:"malformed"}};const s=i[0];return"string"==typeof s?{outcome:"gated",experienceId:s}:0===i.length?{outcome:"ungated"}:{outcome:"error",error:{lookupKey:e,reason:"malformed"}}})().finally(()=>{r.inFlight?.delete(u)});return r.inFlight?.set(u,i),i}(u,n)}export{t as resolveShopifyExperience};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-shopify",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Shopify storefront adapter for Fanfare SDK: product→experience resolver, checkout verifier, and experienceIds metafield primitives",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -46,7 +46,7 @@
   "peerDependencies": {
     "react": "^18.0.0 || ^19.1.1",
     "react-dom": "^18.0.0 || ^19.1.1",
-    "@fanfare-io/fanfare-sdk-core": "0.16.0"
+    "@fanfare-io/fanfare-sdk-core": "0.18.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -57,6 +57,7 @@
     }
   },
   "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.1.8",
     "@types/react": "^19.1.12",
     "@types/react-dom": "^19.1.9",
     "@vitejs/plugin-react": "^5.0.2",
@@ -66,13 +67,15 @@
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "rimraf": "^6.0.1",
+    "size-limit": "^11.1.8",
+    "terser": "^5.46.1",
     "typescript": "^5.9.2",
     "typescript-native": "npm:typescript@^7.0.2",
     "vite": "^7.3.5",
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^5.0.0",
-    "@fanfare-io/fanfare-sdk-core": "0.16.0"
+    "@fanfare-io/fanfare-sdk-core": "0.18.0"
   },
   "sideEffects": false,
   "keywords": [
@@ -84,8 +87,58 @@
     "headless"
   ],
   "license": "Apache-2.0",
+  "size-limit": [
+    {
+      "name": "Root (isomorphic)",
+      "path": "dist/index.js",
+      "limit": "3 KB",
+      "ignore": [
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+        "jose",
+        "@fanfare-io/fanfare-sdk-core",
+        "@fanfare-io/fanfare-sdk-core/admission-proof",
+        "@fanfare-io/fanfare-sdk-core/experiences",
+        "@fanfare-io/fanfare-sdk-core/internals",
+        "@fanfare-io/fanfare-sdk-core/storefront"
+      ]
+    },
+    {
+      "name": "React bindings",
+      "path": "dist/react/index.js",
+      "limit": "6 KB",
+      "ignore": [
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+        "jose",
+        "@fanfare-io/fanfare-sdk-core",
+        "@fanfare-io/fanfare-sdk-core/admission-proof",
+        "@fanfare-io/fanfare-sdk-core/experiences",
+        "@fanfare-io/fanfare-sdk-core/internals",
+        "@fanfare-io/fanfare-sdk-core/storefront"
+      ]
+    },
+    {
+      "name": "Auth (server-only)",
+      "path": "dist/auth/index.js",
+      "limit": "5 KB",
+      "ignore": [
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+        "jose",
+        "@fanfare-io/fanfare-sdk-core",
+        "@fanfare-io/fanfare-sdk-core/admission-proof",
+        "@fanfare-io/fanfare-sdk-core/experiences",
+        "@fanfare-io/fanfare-sdk-core/internals",
+        "@fanfare-io/fanfare-sdk-core/storefront"
+      ]
+    }
+  ],
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && pnpm size",
     "build:deps": "vite build --emptyOutDir false",
     "build:incremental": "vite build --emptyOutDir false",
     "build:dist": "rimraf dist && vite build",
@@ -100,6 +153,7 @@
     "test:watch": "vitest",
     "test:unit": "pnpm build:test-deps && vitest run .unit.test.ts --passWithNoTests",
     "test:contract": "pnpm build:test-deps && vitest run .contract.test.ts --passWithNoTests",
-    "typecheck": "./node_modules/typescript-native/bin/tsc --noEmit"
+    "typecheck": "./node_modules/typescript-native/bin/tsc --noEmit",
+    "size": "size-limit"
   }
 }