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

package/README.md

@@ -95,6 +95,30 @@ function ProductPage({ product }: { product: { handle: string; id: string } }) {
 
 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.
 
+## Checkout identity from widget details
+
+React's `ExperienceWidget.onCheckoutClick` receives optional
+`SelectionCheckoutDetails`. When present, its product and variant are the catalogue
+objects for the committed Fanfare pair, not necessarily the current PDP's pair.
+
+For Shopify checkout, use `details.product.externalReference.id` as
+`gatedLine.shopifyProductId` and `details.variant.externalReference.id` as
+`gatedLine.merchandiseId`, through the existing `productGid` and `variantGid` helpers.
+First require both references, `provider === "shopify"`, and the appropriate complete
+Product/ProductVariant GID shapes. Those helpers normalize IDs; they are not substitutes
+for validating an optional external reference. Reject missing or invalid identity
+before calling `gatedCheckout`.
+
+Do not reconstruct identity from handles, SKUs, option labels, or a local variant list.
+A Shopify default variant has `optionValues: []` but still has a variant reference.
+The same checkout call applies to fixed, consumer-selected, and system-assigned pairs.
+The cart adapter still owns Storefront API calls; `gatedCheckout` still owns the
+create-cart → claim → add-line ordering and returns the checkout result.
+
+This requires a backend and SDK that retain external references. SDK 0.19.0 strips
+the fields. Details remain optional while the catalogue is unavailable or when no
+catalogue pair can be resolved; this change does not redesign catalogue readiness.
+
 ## Modes: `production` (default) vs `demo`
 
 `mode` defaults to `"production"`: real verify + claim through the Fanfare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-shopify",
-  "version": "0.18.0",
+  "version": "0.20.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.18.0"
+    "@fanfare-io/fanfare-sdk-core": "0.20.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -75,7 +75,7 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^5.0.0",
-    "@fanfare-io/fanfare-sdk-core": "0.18.0"
+    "@fanfare-io/fanfare-sdk-core": "0.20.0"
   },
   "sideEffects": false,
   "keywords": [