@vtex/faststore 0.0.8 → 0.0.11

package/dist/sdk/session/use-session-actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-session-actions.js","names":[],"sources":["../../../src/sdk/session/use-session-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport {\n  SESSION_LOGIN_WITH_PASSWORD,\n  SESSION_LOGOUT,\n  SESSION_REQUEST_ACCESS_CODE,\n  SESSION_VALIDATE_ACCESS_CODE,\n  type SessionAccessCodeRequestResult,\n  type SessionPasswordLoginPayload,\n  type SessionRequestAccessCodePayload,\n  type SessionUserError,\n  type SessionValidateAccessCodePayload,\n} from './auth-operations.js';\n\n/**\n * The `session` action namespace — the one sanctioned client write surface for authentication\n * (docs/storefront-core/reference-free-particle-model.md § Write side — actions, docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * Every action is async/pessimistic (Decision 1): the handler awaits the mutation and only the\n * server-confirmed payload changes the cache — authentication cannot be guessed client-side. The\n * handlers are stateless: no reactive vars, no module state; the access-code `authenticationToken`\n * is returned to the caller, which owns it as UI flow state (Decision 4). Each action resolves its\n * payload `userErrors` (empty on success) and never throws for expected outcomes; infrastructure\n * failures resolve as the synthetic `NETWORK_ERROR` (Decision 5). The credentials pass through\n * mutation variables only — never logged, never stored.\n */\nexport type SessionActions = Readonly<{\n  /** Password sign-in. Async/pessimistic; resolves the payload userErrors (empty on success). */\n  loginWithPassword: (payload: SessionPasswordLoginPayload) => Promise<readonly SessionUserError[]>;\n  /** Email an access code; resolves the opaque authenticationToken to round-trip into validate. */\n  requestAccessCode: (payload: SessionRequestAccessCodePayload) => Promise<SessionAccessCodeRequestResult>;\n  /** Validate an access code + token; logs the shopper in exactly as a password login would. */\n  validateAccessCode: (payload: SessionValidateAccessCodePayload) => Promise<readonly SessionUserError[]>;\n  /** Sign out. Idempotent for guests. */\n  logout: () => Promise<readonly SessionUserError[]>;\n}>;\n\nconst NETWORK_USER_ERROR: SessionUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/**\n * The `session` namespace hook. Registered with the first-party action registry via `sessionActions`\n * below; the compiler-emitted `SessionActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.session`. Login/validate/logout refresh the session purely through the\n * normalized-cache merge of the mutation response (Decision 2) — no refetch, no imperative write.\n */\nexport function useSessionActions(): SessionActions {\n  const [loginMutation] = useMutation(SESSION_LOGIN_WITH_PASSWORD);\n  const [requestMutation] = useMutation(SESSION_REQUEST_ACCESS_CODE);\n  const [validateMutation] = useMutation(SESSION_VALIDATE_ACCESS_CODE);\n  const [logoutMutation] = useMutation(SESSION_LOGOUT);\n\n  const loginWithPassword = useCallback<SessionActions['loginWithPassword']>(\n    async (payload) => {\n      try {\n        const result = await loginMutation({ variables: { input: payload } });\n        return result.data?.sessionLoginWithPassword.userErrors ?? [];\n      } catch (error) {\n        console.error('[session.loginWithPassword] sessionLoginWithPassword failed', loggableErrorName(error));\n        return [NETWORK_USER_ERROR];\n      }\n    },\n    [loginMutation],\n  );\n\n  const requestAccessCode = useCallback<SessionActions['requestAccessCode']>(\n    async (payload) => {\n      try {\n        const result = await requestMutation({ variables: { input: payload } });\n        const data = result.data?.sessionRequestAccessCode;\n        return { authenticationToken: data?.authenticationToken ?? null, userErrors: data?.userErrors ?? [] };\n      } catch (error) {\n        console.error('[session.requestAccessCode] sessionRequestAccessCode failed', loggableErrorName(error));\n        return { authenticationToken: null, userErrors: [NETWORK_USER_ERROR] };\n      }\n    },\n    [requestMutation],\n  );\n\n  const validateAccessCode = useCallback<SessionActions['validateAccessCode']>(\n    async (payload) => {\n      try {\n        const result = await validateMutation({ variables: { input: payload } });\n        return result.data?.sessionValidateAccessCode.userErrors ?? [];\n      } catch (error) {\n        console.error('[session.validateAccessCode] sessionValidateAccessCode failed', loggableErrorName(error));\n        return [NETWORK_USER_ERROR];\n      }\n    },\n    [validateMutation],\n  );\n\n  const logout = useCallback<SessionActions['logout']>(async () => {\n    try {\n      const result = await logoutMutation();\n      return result.data?.sessionLogout.userErrors ?? [];\n    } catch (error) {\n      console.error('[session.logout] sessionLogout failed', loggableErrorName(error));\n      return [NETWORK_USER_ERROR];\n    }\n  }, [logoutMutation]);\n\n  return useMemo(\n    () => ({ loginWithPassword, requestAccessCode, validateAccessCode, logout }),\n    [loginWithPassword, requestAccessCode, validateAccessCode, logout],\n  );\n}\n\n/**\n * Declares the `session` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`). The native catalog builder\n * (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `SessionActionProvider` calls `useSessionActions` directly.\n */\nexport const sessionActions = defineActions({\n  namespace: 'session',\n  description: 'Mutation-backed authentication writes against the VTEX ID session (login, access code, logout).',\n  provider: { name: 'SessionActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    loginWithPassword: {\n      description: 'Sign in with email and password (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'email', type: 'string' },\n        { name: 'password', type: 'string' },\n      ],\n    },\n    requestAccessCode: {\n      description: 'Email the shopper an access code; resolves the opaque authenticationToken to round-trip.',\n      payload: [{ name: 'email', type: 'string' }],\n    },\n    validateAccessCode: {\n      description: 'Validate an access code with its authenticationToken (async/pessimistic); logs the shopper in.',\n      payload: [\n        { name: 'email', type: 'string' },\n        { name: 'accessCode', type: 'string' },\n        { name: 'authenticationToken', type: 'string' },\n      ],\n    },\n    logout: {\n      description: 'Sign out, clearing the auth cookies (async/pessimistic). Idempotent for guests.',\n      payload: [],\n    },\n  },\n  use: useSessionActions,\n});\n"],"mappings":";;;;;;;;AAyCA,MAAM,qBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;;;;;;;AAQA,SAAgB,oBAAoC;CAClD,MAAM,CAAC,iBAAiB,YAAY,2BAA2B;CAC/D,MAAM,CAAC,mBAAmB,YAAY,2BAA2B;CACjE,MAAM,CAAC,oBAAoB,YAAY,4BAA4B;CACnE,MAAM,CAAC,kBAAkB,YAAY,cAAc;CAEnD,MAAM,oBAAoB,YACxB,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,cAAc,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACtD,MAAM,yBAAyB,cAAc,CAAC;EAC9D,SAAS,OAAO;GACd,QAAQ,MAAM,+DAA+D,kBAAkB,KAAK,CAAC;GACrG,OAAO,CAAC,kBAAkB;EAC5B;CACF,GACA,CAAC,aAAa,CAChB;CAEA,MAAM,oBAAoB,YACxB,OAAO,YAAY;EACjB,IAAI;GAEF,MAAM,QAAO,MADQ,gBAAgB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CAClD,MAAM;GAC1B,OAAO;IAAE,qBAAqB,MAAM,uBAAuB;IAAM,YAAY,MAAM,cAAc,CAAC;GAAE;EACtG,SAAS,OAAO;GACd,QAAQ,MAAM,+DAA+D,kBAAkB,KAAK,CAAC;GACrG,OAAO;IAAE,qBAAqB;IAAM,YAAY,CAAC,kBAAkB;GAAE;EACvE;CACF,GACA,CAAC,eAAe,CAClB;CAEA,MAAM,qBAAqB,YACzB,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,iBAAiB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACzD,MAAM,0BAA0B,cAAc,CAAC;EAC/D,SAAS,OAAO;GACd,QAAQ,MAAM,iEAAiE,kBAAkB,KAAK,CAAC;GACvG,OAAO,CAAC,kBAAkB;EAC5B;CACF,GACA,CAAC,gBAAgB,CACnB;CAEA,MAAM,SAAS,YAAsC,YAAY;EAC/D,IAAI;GAEF,QAAO,MADc,eAAe,EAAA,CACtB,MAAM,cAAc,cAAc,CAAC;EACnD,SAAS,OAAO;GACd,QAAQ,MAAM,yCAAyC,kBAAkB,KAAK,CAAC;GAC/E,OAAO,CAAC,kBAAkB;EAC5B;CACF,GAAG,CAAC,cAAc,CAAC;CAEnB,OAAO,eACE;EAAE;EAAmB;EAAmB;EAAoB;CAAO,IAC1E;EAAC;EAAmB;EAAmB;EAAoB;CAAM,CACnE;AACF;AAQ8B,cAAc;CAC1C,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAAyB,YAAY;CAAkC;CACzF,SAAS;EACP,mBAAmB;GACjB,aAAa;GACb,SAAS,CACP;IAAE,MAAM;IAAS,MAAM;GAAS,GAChC;IAAE,MAAM;IAAY,MAAM;GAAS,CACrC;EACF;EACA,mBAAmB;GACjB,aAAa;GACb,SAAS,CAAC;IAAE,MAAM;IAAS,MAAM;GAAS,CAAC;EAC7C;EACA,oBAAoB;GAClB,aAAa;GACb,SAAS;IACP;KAAE,MAAM;KAAS,MAAM;IAAS;IAChC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAuB,MAAM;IAAS;GAChD;EACF;EACA,QAAQ;GACN,aAAa;GACb,SAAS,CAAC;EACZ;CACF;CACA,KAAK;AACP,CAAC"}
+{"version":3,"file":"use-session-actions.js","names":[],"sources":["../../../src/sdk/session/use-session-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport {\n  SESSION_LOGIN_WITH_PASSWORD,\n  SESSION_LOGOUT,\n  SESSION_REQUEST_ACCESS_CODE,\n  SESSION_VALIDATE_ACCESS_CODE,\n  type SessionAccessCodeRequestResult,\n  type SessionPasswordLoginPayload,\n  type SessionRequestAccessCodePayload,\n  type SessionUserError,\n  type SessionValidateAccessCodePayload,\n} from './auth-operations.js';\n\n/**\n * The `session` action namespace — the one sanctioned client write surface for authentication\n * (docs/storefront-core/reference-free-particle-model.md § Write side — actions, docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * Every action is async/pessimistic (Decision 1): the handler awaits the mutation and only the\n * server-confirmed payload changes the cache — authentication cannot be guessed client-side. The\n * handlers are stateless: no reactive vars, no module state; the access-code `authenticationToken`\n * is returned to the caller, which owns it as UI flow state (Decision 4). Each action resolves its\n * payload `userErrors` (empty on success) and never throws for expected outcomes; infrastructure\n * failures resolve as the synthetic `NETWORK_ERROR` (Decision 5). The credentials pass through\n * mutation variables only — never logged, never stored.\n */\nexport type SessionActions = Readonly<{\n  /** Password sign-in. Async/pessimistic; resolves the payload userErrors (empty on success). */\n  loginWithPassword: (payload: SessionPasswordLoginPayload) => Promise<readonly SessionUserError[]>;\n  /** Email an access code; resolves the opaque authenticationToken to round-trip into validate. */\n  requestAccessCode: (payload: SessionRequestAccessCodePayload) => Promise<SessionAccessCodeRequestResult>;\n  /** Validate an access code + token; logs the shopper in exactly as a password login would. */\n  validateAccessCode: (payload: SessionValidateAccessCodePayload) => Promise<readonly SessionUserError[]>;\n  /** Sign out. Idempotent for guests. */\n  logout: () => Promise<readonly SessionUserError[]>;\n}>;\n\n// A diagnostic message: components word this code from their own `$content`.\nconst NETWORK_USER_ERROR: SessionUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/**\n * The `session` namespace hook. Registered with the first-party action registry via `sessionActions`\n * below; the compiler-emitted `SessionActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.session`. Login/validate/logout refresh the session purely through the\n * normalized-cache merge of the mutation response (Decision 2) — no refetch, no imperative write.\n */\nexport function useSessionActions(): SessionActions {\n  const [loginMutation] = useMutation(SESSION_LOGIN_WITH_PASSWORD);\n  const [requestMutation] = useMutation(SESSION_REQUEST_ACCESS_CODE);\n  const [validateMutation] = useMutation(SESSION_VALIDATE_ACCESS_CODE);\n  const [logoutMutation] = useMutation(SESSION_LOGOUT);\n\n  const loginWithPassword = useCallback<SessionActions['loginWithPassword']>(\n    async (payload) => {\n      try {\n        const result = await loginMutation({ variables: { input: payload } });\n        return result.data?.sessionLoginWithPassword.userErrors ?? [];\n      } catch (error) {\n        console.error('[session.loginWithPassword] sessionLoginWithPassword failed', loggableErrorName(error));\n        return [NETWORK_USER_ERROR];\n      }\n    },\n    [loginMutation],\n  );\n\n  const requestAccessCode = useCallback<SessionActions['requestAccessCode']>(\n    async (payload) => {\n      try {\n        const result = await requestMutation({ variables: { input: payload } });\n        const data = result.data?.sessionRequestAccessCode;\n        return { authenticationToken: data?.authenticationToken ?? null, userErrors: data?.userErrors ?? [] };\n      } catch (error) {\n        console.error('[session.requestAccessCode] sessionRequestAccessCode failed', loggableErrorName(error));\n        return { authenticationToken: null, userErrors: [NETWORK_USER_ERROR] };\n      }\n    },\n    [requestMutation],\n  );\n\n  const validateAccessCode = useCallback<SessionActions['validateAccessCode']>(\n    async (payload) => {\n      try {\n        const result = await validateMutation({ variables: { input: payload } });\n        return result.data?.sessionValidateAccessCode.userErrors ?? [];\n      } catch (error) {\n        console.error('[session.validateAccessCode] sessionValidateAccessCode failed', loggableErrorName(error));\n        return [NETWORK_USER_ERROR];\n      }\n    },\n    [validateMutation],\n  );\n\n  const logout = useCallback<SessionActions['logout']>(async () => {\n    try {\n      const result = await logoutMutation();\n      return result.data?.sessionLogout.userErrors ?? [];\n    } catch (error) {\n      console.error('[session.logout] sessionLogout failed', loggableErrorName(error));\n      return [NETWORK_USER_ERROR];\n    }\n  }, [logoutMutation]);\n\n  return useMemo(\n    () => ({ loginWithPassword, requestAccessCode, validateAccessCode, logout }),\n    [loginWithPassword, requestAccessCode, validateAccessCode, logout],\n  );\n}\n\n/**\n * Declares the `session` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`). The native catalog builder\n * (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `SessionActionProvider` calls `useSessionActions` directly.\n */\nexport const sessionActions = defineActions({\n  namespace: 'session',\n  description: 'Mutation-backed authentication writes against the VTEX ID session (login, access code, logout).',\n  provider: { name: 'SessionActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    loginWithPassword: {\n      description: 'Sign in with email and password (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'email', type: 'string' },\n        { name: 'password', type: 'string' },\n      ],\n    },\n    requestAccessCode: {\n      description: 'Email the shopper an access code; resolves the opaque authenticationToken to round-trip.',\n      payload: [{ name: 'email', type: 'string' }],\n    },\n    validateAccessCode: {\n      description: 'Validate an access code with its authenticationToken (async/pessimistic); logs the shopper in.',\n      payload: [\n        { name: 'email', type: 'string' },\n        { name: 'accessCode', type: 'string' },\n        { name: 'authenticationToken', type: 'string' },\n      ],\n    },\n    logout: {\n      description: 'Sign out, clearing the auth cookies (async/pessimistic). Idempotent for guests.',\n      payload: [],\n    },\n  },\n  use: useSessionActions,\n});\n"],"mappings":";;;;;;;;AA0CA,MAAM,qBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;;;;;;;AAQA,SAAgB,oBAAoC;CAClD,MAAM,CAAC,iBAAiB,YAAY,2BAA2B;CAC/D,MAAM,CAAC,mBAAmB,YAAY,2BAA2B;CACjE,MAAM,CAAC,oBAAoB,YAAY,4BAA4B;CACnE,MAAM,CAAC,kBAAkB,YAAY,cAAc;CAEnD,MAAM,oBAAoB,YACxB,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,cAAc,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACtD,MAAM,yBAAyB,cAAc,CAAC;EAC9D,SAAS,OAAO;GACd,QAAQ,MAAM,+DAA+D,kBAAkB,KAAK,CAAC;GACrG,OAAO,CAAC,kBAAkB;EAC5B;CACF,GACA,CAAC,aAAa,CAChB;CAEA,MAAM,oBAAoB,YACxB,OAAO,YAAY;EACjB,IAAI;GAEF,MAAM,QAAO,MADQ,gBAAgB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CAClD,MAAM;GAC1B,OAAO;IAAE,qBAAqB,MAAM,uBAAuB;IAAM,YAAY,MAAM,cAAc,CAAC;GAAE;EACtG,SAAS,OAAO;GACd,QAAQ,MAAM,+DAA+D,kBAAkB,KAAK,CAAC;GACrG,OAAO;IAAE,qBAAqB;IAAM,YAAY,CAAC,kBAAkB;GAAE;EACvE;CACF,GACA,CAAC,eAAe,CAClB;CAEA,MAAM,qBAAqB,YACzB,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,iBAAiB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACzD,MAAM,0BAA0B,cAAc,CAAC;EAC/D,SAAS,OAAO;GACd,QAAQ,MAAM,iEAAiE,kBAAkB,KAAK,CAAC;GACvG,OAAO,CAAC,kBAAkB;EAC5B;CACF,GACA,CAAC,gBAAgB,CACnB;CAEA,MAAM,SAAS,YAAsC,YAAY;EAC/D,IAAI;GAEF,QAAO,MADc,eAAe,EAAA,CACtB,MAAM,cAAc,cAAc,CAAC;EACnD,SAAS,OAAO;GACd,QAAQ,MAAM,yCAAyC,kBAAkB,KAAK,CAAC;GAC/E,OAAO,CAAC,kBAAkB;EAC5B;CACF,GAAG,CAAC,cAAc,CAAC;CAEnB,OAAO,eACE;EAAE;EAAmB;EAAmB;EAAoB;CAAO,IAC1E;EAAC;EAAmB;EAAmB;EAAoB;CAAM,CACnE;AACF;AAQ8B,cAAc;CAC1C,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAAyB,YAAY;CAAkC;CACzF,SAAS;EACP,mBAAmB;GACjB,aAAa;GACb,SAAS,CACP;IAAE,MAAM;IAAS,MAAM;GAAS,GAChC;IAAE,MAAM;IAAY,MAAM;GAAS,CACrC;EACF;EACA,mBAAmB;GACjB,aAAa;GACb,SAAS,CAAC;IAAE,MAAM;IAAS,MAAM;GAAS,CAAC;EAC7C;EACA,oBAAoB;GAClB,aAAa;GACb,SAAS;IACP;KAAE,MAAM;KAAS,MAAM;IAAS;IAChC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAuB,MAAM;IAAS;GAChD;EACF;EACA,QAAQ;GACN,aAAa;GACb,SAAS,CAAC;EACZ;CACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/shipping/shipping-operations.d.ts

@@ -24,7 +24,7 @@ export type ShippingAddressUpdateErrorEntity = Readonly<{
 }>;
 export type ShippingAddressInput = Readonly<{
   savedAddressId?: string;
-  recipientName: string;
+  recipientName?: string;
   postalCode: string;
   country: string;
   street?: string;

package/dist/sdk/shipping/shipping-operations.js

@@ -62,6 +62,19 @@ const SHIPPING_ADDRESS_UPDATE = gql`
       }
       cart {
         ...CartFragment
+        freeShippingProgress {
+          threshold {
+            __typename
+            amount
+            currencyCode
+          }
+          remaining {
+            __typename
+            amount
+            currencyCode
+          }
+          qualified
+        }
       }
       userErrors {
         code

package/dist/sdk/shipping/shipping-operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"shipping-operations.js","names":[],"sources":["../../../src/sdk/shipping/shipping-operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { type CartEntity, CartFragment } from '../cart/operations.js';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Shipping address mutation documents (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n *\n * Authored with the hand `gql` tag — the codegen `graphql()` factory is reserved for the reactive\n * read path (`operations.ts`) — and explicitly excluded from the codegen `documents` glob (see\n * `codegen.ts`): the `gql` tag alone is still plucked by `graphql-codegen`, which would duplicate\n * these hand-written types in `sdk/generated/`. The mutation stays hand-typed as a\n * `TypedDocumentNode` (Decision 3 in the spec). The payload projects the full refreshed `shipping`\n * and `cart` state, so the response write into the cache *is* the post-update refresh: `Shipping`'s\n * reactive read flips with no refetch and no imperative cache write.\n *\n * Failures follow ADR-00007's two-path contract: domain outcomes arrive as payload `userErrors`\n * (`ShippingAddressUpdateError`); transport and top-level GraphQL failures are infrastructure,\n * mapped by the handlers in `use-shipping-actions.ts` to the one client-synthesized code,\n * `NETWORK_USER_ERROR`.\n */\n\n/** A typed address-update failure; NETWORK_USER_ERROR is the one client-synthesized code. */\nexport type ShippingAddressUpdateErrorEntity = Readonly<{ code: string; message: string }>;\n\n/**\n * The one client-synthesized error code, carried by the userError that `setAddress` *resolves*\n * (never throws) when the mutation fails at the transport/top-level-GraphQL layer. Consumers use\n * it to route the resolved synthetic failure to the generic upstream error state (Decision 5),\n * distinct from the domain `userErrors` codes that render inline.\n */\nexport const SHIPPING_NETWORK_ERROR_CODE = 'NETWORK_ERROR';\n\nexport type ShippingAddressInput = Readonly<{\n  savedAddressId?: string;\n  recipientName: string;\n  postalCode: string;\n  country: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  state?: string;\n}>;\n\n/** The full shippingAddressUpdate mutation payload. */\nexport type ShippingAddressUpdatePayloadEntity = Readonly<{\n  __typename: 'ShippingAddressUpdatePayload';\n  shipping: {\n    __typename: 'Shipping';\n    id: string;\n    address: {\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    } | null;\n    savedAddresses: ReadonlyArray<{\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    }>;\n    options: ReadonlyArray<{\n      __typename: 'ShippingOption';\n      id: string;\n      name: string;\n      channel: string;\n      shippingEstimate: { __typename: 'ShippingEstimate'; value: number; unit: string };\n      price: { __typename: 'Money'; amount: number; currencyCode: string };\n      listPrice: { __typename: 'Money'; amount: number; currencyCode: string };\n    }>;\n    selectedOptionId?: string | null;\n  } | null;\n  cart: CartEntity;\n  userErrors: readonly ShippingAddressUpdateErrorEntity[];\n}>;\n\ntype ShippingAddressUpdateData = Readonly<{ shippingAddressUpdate: ShippingAddressUpdatePayloadEntity }>;\n\nexport const SHIPPING_ADDRESS_UPDATE: TypedDocumentNode<ShippingAddressUpdateData, { input: ShippingAddressInput }> =\n  gql`\n  mutation ShippingAddressUpdate($input: ShippingAddressUpdateInput!) {\n    shippingAddressUpdate(input: $input) {\n      shipping {\n        __typename\n        id\n        address {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        savedAddresses {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        options {\n          __typename\n          id\n          name\n          channel\n          shippingEstimate {\n            value\n            unit\n          }\n          price {\n            amount\n            currencyCode\n          }\n          listPrice {\n            amount\n            currencyCode\n          }\n        }\n        selectedOptionId\n      }\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${CartFragment}\n`;\n"],"mappings":";;;;;;;;;AA8BA,MAAa,8BAA8B;AAgE3C,MAAa,0BACX,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA6DD,aAAa"}
+{"version":3,"file":"shipping-operations.js","names":[],"sources":["../../../src/sdk/shipping/shipping-operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { type CartEntity, CartFragment, type CartFreeShippingProgress } from '../cart/operations.js';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Shipping address mutation documents (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n *\n * Authored with the hand `gql` tag — the codegen `graphql()` factory is reserved for the reactive\n * read path (`operations.ts`) — and explicitly excluded from the codegen `documents` glob (see\n * `codegen.ts`): the `gql` tag alone is still plucked by `graphql-codegen`, which would duplicate\n * these hand-written types in `sdk/generated/`. The mutation stays hand-typed as a\n * `TypedDocumentNode` (Decision 3 in the spec). The payload projects the full refreshed `shipping`\n * and `cart` state, so the response write into the cache *is* the post-update refresh: `Shipping`'s\n * reactive read flips with no refetch and no imperative cache write.\n *\n * Failures follow ADR-00007's two-path contract: domain outcomes arrive as payload `userErrors`\n * (`ShippingAddressUpdateError`); transport and top-level GraphQL failures are infrastructure,\n * mapped by the handlers in `use-shipping-actions.ts` to the one client-synthesized code,\n * `NETWORK_USER_ERROR`.\n */\n\n/** A typed address-update failure; NETWORK_USER_ERROR is the one client-synthesized code. */\nexport type ShippingAddressUpdateErrorEntity = Readonly<{ code: string; message: string }>;\n\n/**\n * The one client-synthesized error code, carried by the userError that `setAddress` *resolves*\n * (never throws) when the mutation fails at the transport/top-level-GraphQL layer. Consumers use\n * it to route the resolved synthetic failure to the generic upstream error state (Decision 5),\n * distinct from the domain `userErrors` codes that render inline.\n */\nexport const SHIPPING_NETWORK_ERROR_CODE = 'NETWORK_ERROR';\n\nexport type ShippingAddressInput = Readonly<{\n  savedAddressId?: string;\n  recipientName?: string;\n  postalCode: string;\n  country: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  state?: string;\n}>;\n\n/** The full shippingAddressUpdate mutation payload. */\nexport type ShippingAddressUpdatePayloadEntity = Readonly<{\n  __typename: 'ShippingAddressUpdatePayload';\n  shipping: {\n    __typename: 'Shipping';\n    id: string;\n    address: {\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    } | null;\n    savedAddresses: ReadonlyArray<{\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    }>;\n    options: ReadonlyArray<{\n      __typename: 'ShippingOption';\n      id: string;\n      name: string;\n      channel: string;\n      shippingEstimate: { __typename: 'ShippingEstimate'; value: number; unit: string };\n      price: { __typename: 'Money'; amount: number; currencyCode: string };\n      listPrice: { __typename: 'Money'; amount: number; currencyCode: string };\n    }>;\n    selectedOptionId?: string | null;\n  } | null;\n  cart: CartEntity & { freeShippingProgress: CartFreeShippingProgress | null };\n  userErrors: readonly ShippingAddressUpdateErrorEntity[];\n}>;\n\ntype ShippingAddressUpdateData = Readonly<{ shippingAddressUpdate: ShippingAddressUpdatePayloadEntity }>;\n\nexport const SHIPPING_ADDRESS_UPDATE: TypedDocumentNode<ShippingAddressUpdateData, { input: ShippingAddressInput }> =\n  gql`\n  mutation ShippingAddressUpdate($input: ShippingAddressUpdateInput!) {\n    shippingAddressUpdate(input: $input) {\n      shipping {\n        __typename\n        id\n        address {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        savedAddresses {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        options {\n          __typename\n          id\n          name\n          channel\n          shippingEstimate {\n            value\n            unit\n          }\n          price {\n            amount\n            currencyCode\n          }\n          listPrice {\n            amount\n            currencyCode\n          }\n        }\n        selectedOptionId\n      }\n      cart {\n        ...CartFragment\n        freeShippingProgress {\n          threshold {\n            __typename\n            amount\n            currencyCode\n          }\n          remaining {\n            __typename\n            amount\n            currencyCode\n          }\n          qualified\n        }\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${CartFragment}\n`;\n"],"mappings":";;;;;;;;;AA8BA,MAAa,8BAA8B;AAgE3C,MAAa,0BACX,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0ED,aAAa"}

package/dist/sdk/shipping/use-cart-shipping-simulation.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-cart-shipping-simulation.js","names":[],"sources":["../../../src/sdk/shipping/use-cart-shipping-simulation.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport type {\n  ShippingOption,\n  ShippingSimulateError,\n  ShippingSimulationPayload,\n} from '../../matter/shipping-simulator/shipping-simulator.js';\nimport type { CartShippingSimulationQuery, ShippingSimulateErrorCode } from '../generated/graphql.js';\nimport { CART_SHIPPING_SIMULATION, type CartShippingSimulateInput } from './cart-operations.js';\nimport { withRequestTimeout } from './request-timeout.js';\n\n/**\n * Cart-scoped shipping-simulation SDK hook.\n *\n * Returns the calculator's `onSimulate(input) => Promise<payload>` callback. It runs the\n * `CartShippingSimulation` query imperatively per submit via the Apollo client read from\n * `getApolloContext()` (a non-throwing read, mirroring `useShippingSimulation`). The input carries\n * a destination only — items come from the cart via `x-order-form-id`, resolved server-side. The\n * mapping matches the PDP hook: the structured `ShippingEstimate { value, unit }` is carried through\n * untouched (the component localizes it), the API `Money` is carried as `{ amount, currencyCode }`,\n * and any transport/GraphQL failure is collapsed to one `UNKNOWN` userError so the calculator's\n * success/error transition stays deterministic.\n */\n\n// The calculator's domain payload is the seam's own type, imported from the component so the\n// binding is a direct assignment and the types never drift from the contract the component's tests\n// assert.\ntype RawOption = NonNullable<CartShippingSimulationQuery['cartShippingSimulation']['shippingOptions']>[number];\n\nconst UNKNOWN_ERROR: ShippingSimulateError = {\n  code: 'UNKNOWN',\n  message: 'Unable to calculate shipping. Try again.',\n};\n\nfunction mapErrorCode(code: ShippingSimulateErrorCode): ShippingSimulateError['code'] {\n  return code === 'INVALID_POSTAL_CODE' ? 'INVALID_POSTAL_CODE' : 'UNKNOWN';\n}\n\nfunction mapOption(option: RawOption): ShippingOption {\n  return {\n    id: option.id,\n    name: option.name,\n    channel: option.channel,\n    shippingEstimate: option.shippingEstimate,\n    price: { amount: option.price.amount, currencyCode: option.price.currencyCode },\n    listPrice: { amount: option.listPrice.amount, currencyCode: option.listPrice.currencyCode },\n  };\n}\n\nexport function useCartShippingSimulation(): (input: CartShippingSimulateInput) => Promise<ShippingSimulationPayload> {\n  // Read the client off Apollo's context directly rather than via `useApolloClient`, which throws at\n  // render when no provider is present. The hook is the calculator's default `onSimulate` and runs\n  // in every Root render, including presentational tests/stories that mount the Root with their own\n  // callback and no ApolloProvider; a missing client only matters when the default callback is\n  // actually invoked, where it is mapped to the same UNKNOWN userError as any other failure.\n  const { client } = useContext(getApolloContext());\n\n  return useCallback(\n    async (input: CartShippingSimulateInput): Promise<ShippingSimulationPayload> => {\n      if (!client) {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n      try {\n        const result = await withRequestTimeout((signal) =>\n          client.query({\n            query: CART_SHIPPING_SIMULATION,\n            variables: { input },\n            fetchPolicy: 'no-cache',\n            context: { fetchOptions: { signal } },\n          }),\n        );\n\n        if (result.error || !result.data) {\n          return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n        }\n\n        const payload = result.data.cartShippingSimulation;\n        const userErrors = payload.userErrors.map((error) => ({\n          code: mapErrorCode(error.code),\n          message: error.message,\n        }));\n\n        if (userErrors.length > 0) {\n          return { shippingOptions: null, userErrors };\n        }\n\n        return {\n          shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,\n          userErrors: [],\n        };\n      } catch {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n    },\n    [client],\n  );\n}\n"],"mappings":";;;;;;AA+BA,MAAM,gBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;AAEA,SAAS,aAAa,MAAgE;CACpF,OAAO,SAAS,wBAAwB,wBAAwB;AAClE;AAEA,SAAS,UAAU,QAAmC;CACpD,OAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,SAAS,OAAO;EAChB,kBAAkB,OAAO;EACzB,OAAO;GAAE,QAAQ,OAAO,MAAM;GAAQ,cAAc,OAAO,MAAM;EAAa;EAC9E,WAAW;GAAE,QAAQ,OAAO,UAAU;GAAQ,cAAc,OAAO,UAAU;EAAa;CAC5F;AACF;AAEA,SAAgB,4BAAsG;CAMpH,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,OAAO,YACL,OAAO,UAAyE;EAC9E,IAAI,CAAC,QACH,OAAO;GAAE,iBAAiB;GAAM,YAAY,CAAC,aAAa;EAAE;EAE9D,IAAI;GACF,MAAM,SAAS,MAAM,oBAAoB,WACvC,OAAO,MAAM;IACX,OAAO;IACP,WAAW,EAAE,MAAM;IACnB,aAAa;IACb,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE;GACtC,CAAC,CACH;GAEA,IAAI,OAAO,SAAS,CAAC,OAAO,MAC1B,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;GAG9D,MAAM,UAAU,OAAO,KAAK;GAC5B,MAAM,aAAa,QAAQ,WAAW,KAAK,WAAW;IACpD,MAAM,aAAa,MAAM,IAAI;IAC7B,SAAS,MAAM;GACjB,EAAE;GAEF,IAAI,WAAW,SAAS,GACtB,OAAO;IAAE,iBAAiB;IAAM;GAAW;GAG7C,OAAO;IACL,iBAAiB,QAAQ,iBAAiB,IAAI,SAAS,KAAK;IAC5D,YAAY,CAAC;GACf;EACF,QAAQ;GACN,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;EAC9D;CACF,GACA,CAAC,MAAM,CACT;AACF"}
+{"version":3,"file":"use-cart-shipping-simulation.js","names":[],"sources":["../../../src/sdk/shipping/use-cart-shipping-simulation.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport type {\n  ShippingOption,\n  ShippingSimulateError,\n  ShippingSimulationPayload,\n} from '../../matter/shipping-simulator/shipping-simulator.js';\nimport type { CartShippingSimulationQuery, ShippingSimulateErrorCode } from '../generated/graphql.js';\nimport { CART_SHIPPING_SIMULATION, type CartShippingSimulateInput } from './cart-operations.js';\nimport { withRequestTimeout } from './request-timeout.js';\n\n/**\n * Cart-scoped shipping-simulation SDK hook.\n *\n * Returns the calculator's `onSimulate(input) => Promise<payload>` callback. It runs the\n * `CartShippingSimulation` query imperatively per submit via the Apollo client read from\n * `getApolloContext()` (a non-throwing read, mirroring `useShippingSimulation`). The input carries\n * a destination only — items come from the cart via `x-order-form-id`, resolved server-side. The\n * mapping matches the PDP hook: the structured `ShippingEstimate { value, unit }` is carried through\n * untouched (the component localizes it), the API `Money` is carried as `{ amount, currencyCode }`,\n * and any transport/GraphQL failure is collapsed to one `UNKNOWN` userError so the calculator's\n * success/error transition stays deterministic.\n */\n\n// The calculator's domain payload is the seam's own type, imported from the component so the\n// binding is a direct assignment and the types never drift from the contract the component's tests\n// assert.\ntype RawOption = NonNullable<CartShippingSimulationQuery['cartShippingSimulation']['shippingOptions']>[number];\n\n// Diagnostic text for logs and `onResult`: `ShippingSimulatorError` words this code from its own `$content`.\nconst UNKNOWN_ERROR: ShippingSimulateError = {\n  code: 'UNKNOWN',\n  message: 'Unable to calculate shipping. Try again.',\n};\n\nfunction mapErrorCode(code: ShippingSimulateErrorCode): ShippingSimulateError['code'] {\n  return code === 'INVALID_POSTAL_CODE' ? 'INVALID_POSTAL_CODE' : 'UNKNOWN';\n}\n\nfunction mapOption(option: RawOption): ShippingOption {\n  return {\n    id: option.id,\n    name: option.name,\n    channel: option.channel,\n    shippingEstimate: option.shippingEstimate,\n    price: { amount: option.price.amount, currencyCode: option.price.currencyCode },\n    listPrice: { amount: option.listPrice.amount, currencyCode: option.listPrice.currencyCode },\n  };\n}\n\nexport function useCartShippingSimulation(): (input: CartShippingSimulateInput) => Promise<ShippingSimulationPayload> {\n  // Read the client off Apollo's context directly rather than via `useApolloClient`, which throws at\n  // render when no provider is present. The hook is the calculator's default `onSimulate` and runs\n  // in every Root render, including presentational tests/stories that mount the Root with their own\n  // callback and no ApolloProvider; a missing client only matters when the default callback is\n  // actually invoked, where it is mapped to the same UNKNOWN userError as any other failure.\n  const { client } = useContext(getApolloContext());\n\n  return useCallback(\n    async (input: CartShippingSimulateInput): Promise<ShippingSimulationPayload> => {\n      if (!client) {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n      try {\n        const result = await withRequestTimeout((signal) =>\n          client.query({\n            query: CART_SHIPPING_SIMULATION,\n            variables: { input },\n            fetchPolicy: 'no-cache',\n            context: { fetchOptions: { signal } },\n          }),\n        );\n\n        if (result.error || !result.data) {\n          return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n        }\n\n        const payload = result.data.cartShippingSimulation;\n        const userErrors = payload.userErrors.map((error) => ({\n          code: mapErrorCode(error.code),\n          message: error.message,\n        }));\n\n        if (userErrors.length > 0) {\n          return { shippingOptions: null, userErrors };\n        }\n\n        return {\n          shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,\n          userErrors: [],\n        };\n      } catch {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n    },\n    [client],\n  );\n}\n"],"mappings":";;;;;;AAgCA,MAAM,gBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;AAEA,SAAS,aAAa,MAAgE;CACpF,OAAO,SAAS,wBAAwB,wBAAwB;AAClE;AAEA,SAAS,UAAU,QAAmC;CACpD,OAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,SAAS,OAAO;EAChB,kBAAkB,OAAO;EACzB,OAAO;GAAE,QAAQ,OAAO,MAAM;GAAQ,cAAc,OAAO,MAAM;EAAa;EAC9E,WAAW;GAAE,QAAQ,OAAO,UAAU;GAAQ,cAAc,OAAO,UAAU;EAAa;CAC5F;AACF;AAEA,SAAgB,4BAAsG;CAMpH,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,OAAO,YACL,OAAO,UAAyE;EAC9E,IAAI,CAAC,QACH,OAAO;GAAE,iBAAiB;GAAM,YAAY,CAAC,aAAa;EAAE;EAE9D,IAAI;GACF,MAAM,SAAS,MAAM,oBAAoB,WACvC,OAAO,MAAM;IACX,OAAO;IACP,WAAW,EAAE,MAAM;IACnB,aAAa;IACb,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE;GACtC,CAAC,CACH;GAEA,IAAI,OAAO,SAAS,CAAC,OAAO,MAC1B,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;GAG9D,MAAM,UAAU,OAAO,KAAK;GAC5B,MAAM,aAAa,QAAQ,WAAW,KAAK,WAAW;IACpD,MAAM,aAAa,MAAM,IAAI;IAC7B,SAAS,MAAM;GACjB,EAAE;GAEF,IAAI,WAAW,SAAS,GACtB,OAAO;IAAE,iBAAiB;IAAM;GAAW;GAG7C,OAAO;IACL,iBAAiB,QAAQ,iBAAiB,IAAI,SAAS,KAAK;IAC5D,YAAY,CAAC;GACf;EACF,QAAQ;GACN,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;EAC9D;CACF,GACA,CAAC,MAAM,CACT;AACF"}

package/dist/sdk/shipping/use-shipping-actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-shipping-actions.js","names":[],"sources":["../../../src/sdk/shipping/use-shipping-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { SHIPPING_OPTION_SELECT, type ShippingOptionSelectUserError } from './option-select-operations.js';\nimport {\n  SHIPPING_ADDRESS_UPDATE,\n  SHIPPING_NETWORK_ERROR_CODE,\n  type ShippingAddressInput,\n  type ShippingAddressUpdateErrorEntity,\n} from './shipping-operations.js';\n\n/**\n * The `shipping` action namespace — the sanctioned client write surface against the VTEX orderForm\n * shippingData: delivery-address updates (docs/storefront-core/reference-free-particle-model.md § The cart write contract;\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md) and cart-scoped delivery-option\n * selection (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Per Decision 4 the two tasks share this one\n * namespace — T2 (`setAddress`) merged first and owns the registration, T3 extends it with\n * `selectOption` here.\n *\n * Both actions are async/pessimistic (Decision 1 of the address spec): the handler awaits the\n * mutation and only the server-confirmed payload changes the cache. Each is stateless (no reactive\n * vars, no module state), resolves its payload `userErrors` (empty on success), and never throws for\n * expected outcomes; an infrastructure failure (network or an upstream GraphQLError) is caught and\n * collapsed to one synthetic network `userError` — no per-code branching (US-4, FR-5). Inputs pass\n * through mutation variables only — never logged, never stored beyond the cache.\n */\nexport type ShippingActions = Readonly<{\n  /** Persist the single delivery address (async/pessimistic). Resolves the payload userErrors. */\n  setAddress: (address: ShippingAddressInput) => Promise<readonly ShippingAddressUpdateErrorEntity[]>;\n  /** Select a delivery option for the whole cart. Resolves the payload userErrors (empty on success). */\n  selectOption: (optionId: string) => Promise<readonly ShippingOptionSelectUserError[]>;\n}>;\n\nconst SET_ADDRESS_NETWORK_ERROR: ShippingAddressUpdateErrorEntity = {\n  code: SHIPPING_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\nconst SELECT_OPTION_NETWORK_ERROR: ShippingOptionSelectUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to update the delivery option. Please try again.',\n};\n\n/**\n * The `shipping` namespace hook. Registered with the first-party action registry via `shippingActions`\n * below; the compiler-emitted `ShippingActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.shipping`. Writes persist purely through the normalized-cache merge of\n * each mutation response (Decision 2 of the address spec) — no refetch, no imperative write.\n */\nexport function useShippingActions(): ShippingActions {\n  const [addressMutation] = useMutation(SHIPPING_ADDRESS_UPDATE);\n  const [selectOptionMutation] = useMutation(SHIPPING_OPTION_SELECT);\n\n  const setAddress = useCallback<ShippingActions['setAddress']>(\n    async (address) => {\n      try {\n        const result = await addressMutation({ variables: { input: address } });\n        return result.data?.shippingAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        console.error('[shipping.setAddress] shippingAddressUpdate failed', loggableErrorName(error));\n        return [SET_ADDRESS_NETWORK_ERROR];\n      }\n    },\n    [addressMutation],\n  );\n\n  const selectOption = useCallback<ShippingActions['selectOption']>(\n    async (optionId) => {\n      try {\n        const result = await selectOptionMutation({ variables: { input: { optionId } } });\n        return result.data?.shippingOptionSelect.userErrors ?? [];\n      } catch (error) {\n        console.error('[shipping.selectOption] shippingOptionSelect failed', loggableErrorName(error));\n        return [SELECT_OPTION_NETWORK_ERROR];\n      }\n    },\n    [selectOptionMutation],\n  );\n\n  return useMemo(() => ({ setAddress, selectOption }), [setAddress, selectOption]);\n}\n\n/**\n * Declares the `shipping` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`, `sessionActions`). The native\n * catalog builder (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`;\n * at runtime `ShippingActionProvider` calls `useShippingActions` directly.\n */\nexport const shippingActions = defineActions({\n  namespace: 'shipping',\n  description: 'Mutation-backed delivery writes against the VTEX orderForm shippingData (address in T2; option in T3).',\n  provider: { name: 'ShippingActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setAddress: {\n      description:\n        'Persist the single delivery address in one submit (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'savedAddressId', type: 'string' },\n        { name: 'recipientName', type: 'string' },\n        { name: 'postalCode', type: 'string' },\n        { name: 'country', type: 'string' },\n        { name: 'street', type: 'string' },\n        { name: 'number', type: 'string' },\n        { name: 'complement', type: 'string' },\n        { name: 'neighborhood', type: 'string' },\n        { name: 'city', type: 'string' },\n        { name: 'state', type: 'string' },\n      ],\n    },\n    selectOption: {\n      description: 'Select a delivery option for the whole cart (async/pessimistic). Resolves the payload userErrors.',\n      payload: [{ name: 'optionId', type: 'string' }],\n    },\n  },\n  use: useShippingActions,\n});\n"],"mappings":";;;;;;;;;AAoCA,MAAM,4BAA8D;CAClE,MAAM;CACN,SAAS;AACX;AAEA,MAAM,8BAA6D;CACjE,MAAM;CACN,SAAS;AACX;;;;;;;AAQA,SAAgB,qBAAsC;CACpD,MAAM,CAAC,mBAAmB,YAAY,uBAAuB;CAC7D,MAAM,CAAC,wBAAwB,YAAY,sBAAsB;CAEjE,MAAM,aAAa,YACjB,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,gBAAgB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACxD,MAAM,sBAAsB,cAAc,CAAC;EAC3D,SAAS,OAAO;GACd,QAAQ,MAAM,sDAAsD,kBAAkB,KAAK,CAAC;GAC5F,OAAO,CAAC,yBAAyB;EACnC;CACF,GACA,CAAC,eAAe,CAClB;CAEA,MAAM,eAAe,YACnB,OAAO,aAAa;EAClB,IAAI;GAEF,QAAO,MADc,qBAAqB,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,EAAA,CAClE,MAAM,qBAAqB,cAAc,CAAC;EAC1D,SAAS,OAAO;GACd,QAAQ,MAAM,uDAAuD,kBAAkB,KAAK,CAAC;GAC7F,OAAO,CAAC,2BAA2B;EACrC;CACF,GACA,CAAC,oBAAoB,CACvB;CAEA,OAAO,eAAe;EAAE;EAAY;CAAa,IAAI,CAAC,YAAY,YAAY,CAAC;AACjF;AAQ+B,cAAc;CAC3C,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAA0B,YAAY;CAAkC;CAC1F,SAAS;EACP,YAAY;GACV,aACE;GACF,SAAS;IACP;KAAE,MAAM;KAAkB,MAAM;IAAS;IACzC;KAAE,MAAM;KAAiB,MAAM;IAAS;IACxC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAW,MAAM;IAAS;IAClC;KAAE,MAAM;KAAU,MAAM;IAAS;IACjC;KAAE,MAAM;KAAU,MAAM;IAAS;IACjC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAgB,MAAM;IAAS;IACvC;KAAE,MAAM;KAAQ,MAAM;IAAS;IAC/B;KAAE,MAAM;KAAS,MAAM;IAAS;GAClC;EACF;EACA,cAAc;GACZ,aAAa;GACb,SAAS,CAAC;IAAE,MAAM;IAAY,MAAM;GAAS,CAAC;EAChD;CACF;CACA,KAAK;AACP,CAAC"}
+{"version":3,"file":"use-shipping-actions.js","names":[],"sources":["../../../src/sdk/shipping/use-shipping-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { SHIPPING_OPTION_SELECT, type ShippingOptionSelectUserError } from './option-select-operations.js';\nimport {\n  SHIPPING_ADDRESS_UPDATE,\n  SHIPPING_NETWORK_ERROR_CODE,\n  type ShippingAddressInput,\n  type ShippingAddressUpdateErrorEntity,\n} from './shipping-operations.js';\n\n/**\n * The `shipping` action namespace — the sanctioned client write surface against the VTEX orderForm\n * shippingData: delivery-address updates (docs/storefront-core/reference-free-particle-model.md § The cart write contract;\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md) and cart-scoped delivery-option\n * selection (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Per Decision 4 the two tasks share this one\n * namespace — T2 (`setAddress`) merged first and owns the registration, T3 extends it with\n * `selectOption` here.\n *\n * Both actions are async/pessimistic (Decision 1 of the address spec): the handler awaits the\n * mutation and only the server-confirmed payload changes the cache. Each is stateless (no reactive\n * vars, no module state), resolves its payload `userErrors` (empty on success), and never throws for\n * expected outcomes; an infrastructure failure (network or an upstream GraphQLError) is caught and\n * collapsed to one synthetic network `userError` — no per-code branching (US-4, FR-5). Inputs pass\n * through mutation variables only — never logged, never stored beyond the cache.\n */\nexport type ShippingActions = Readonly<{\n  /** Persist the single delivery address (async/pessimistic). Resolves the payload userErrors. */\n  setAddress: (address: ShippingAddressInput) => Promise<readonly ShippingAddressUpdateErrorEntity[]>;\n  /** Select a delivery option for the whole cart. Resolves the payload userErrors (empty on success). */\n  selectOption: (optionId: string) => Promise<readonly ShippingOptionSelectUserError[]>;\n}>;\n\n// The `message` of both constants is diagnostic: every component that shows these codes words them from its\n// own `$content`.\nconst SET_ADDRESS_NETWORK_ERROR: ShippingAddressUpdateErrorEntity = {\n  code: SHIPPING_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\nconst SELECT_OPTION_NETWORK_ERROR: ShippingOptionSelectUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to update the delivery option. Please try again.',\n};\n\n/**\n * The `shipping` namespace hook. Registered with the first-party action registry via `shippingActions`\n * below; the compiler-emitted `ShippingActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.shipping`. Writes persist purely through the normalized-cache merge of\n * each mutation response (Decision 2 of the address spec) — no refetch, no imperative write.\n */\nexport function useShippingActions(): ShippingActions {\n  const [addressMutation] = useMutation(SHIPPING_ADDRESS_UPDATE);\n  const [selectOptionMutation] = useMutation(SHIPPING_OPTION_SELECT);\n\n  const setAddress = useCallback<ShippingActions['setAddress']>(\n    async (address) => {\n      try {\n        const result = await addressMutation({ variables: { input: address } });\n        return result.data?.shippingAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        console.error('[shipping.setAddress] shippingAddressUpdate failed', loggableErrorName(error));\n        return [SET_ADDRESS_NETWORK_ERROR];\n      }\n    },\n    [addressMutation],\n  );\n\n  const selectOption = useCallback<ShippingActions['selectOption']>(\n    async (optionId) => {\n      try {\n        const result = await selectOptionMutation({ variables: { input: { optionId } } });\n        return result.data?.shippingOptionSelect.userErrors ?? [];\n      } catch (error) {\n        console.error('[shipping.selectOption] shippingOptionSelect failed', loggableErrorName(error));\n        return [SELECT_OPTION_NETWORK_ERROR];\n      }\n    },\n    [selectOptionMutation],\n  );\n\n  return useMemo(() => ({ setAddress, selectOption }), [setAddress, selectOption]);\n}\n\n/**\n * Declares the `shipping` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`, `sessionActions`). The native\n * catalog builder (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`;\n * at runtime `ShippingActionProvider` calls `useShippingActions` directly.\n */\nexport const shippingActions = defineActions({\n  namespace: 'shipping',\n  description: 'Mutation-backed delivery writes against the VTEX orderForm shippingData (address in T2; option in T3).',\n  provider: { name: 'ShippingActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setAddress: {\n      description:\n        'Persist the single delivery address in one submit (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'savedAddressId', type: 'string' },\n        { name: 'recipientName', type: 'string' },\n        { name: 'postalCode', type: 'string' },\n        { name: 'country', type: 'string' },\n        { name: 'street', type: 'string' },\n        { name: 'number', type: 'string' },\n        { name: 'complement', type: 'string' },\n        { name: 'neighborhood', type: 'string' },\n        { name: 'city', type: 'string' },\n        { name: 'state', type: 'string' },\n      ],\n    },\n    selectOption: {\n      description: 'Select a delivery option for the whole cart (async/pessimistic). Resolves the payload userErrors.',\n      payload: [{ name: 'optionId', type: 'string' }],\n    },\n  },\n  use: useShippingActions,\n});\n"],"mappings":";;;;;;;;;AAsCA,MAAM,4BAA8D;CAClE,MAAM;CACN,SAAS;AACX;AAEA,MAAM,8BAA6D;CACjE,MAAM;CACN,SAAS;AACX;;;;;;;AAQA,SAAgB,qBAAsC;CACpD,MAAM,CAAC,mBAAmB,YAAY,uBAAuB;CAC7D,MAAM,CAAC,wBAAwB,YAAY,sBAAsB;CAEjE,MAAM,aAAa,YACjB,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,gBAAgB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACxD,MAAM,sBAAsB,cAAc,CAAC;EAC3D,SAAS,OAAO;GACd,QAAQ,MAAM,sDAAsD,kBAAkB,KAAK,CAAC;GAC5F,OAAO,CAAC,yBAAyB;EACnC;CACF,GACA,CAAC,eAAe,CAClB;CAEA,MAAM,eAAe,YACnB,OAAO,aAAa;EAClB,IAAI;GAEF,QAAO,MADc,qBAAqB,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,EAAA,CAClE,MAAM,qBAAqB,cAAc,CAAC;EAC1D,SAAS,OAAO;GACd,QAAQ,MAAM,uDAAuD,kBAAkB,KAAK,CAAC;GAC7F,OAAO,CAAC,2BAA2B;EACrC;CACF,GACA,CAAC,oBAAoB,CACvB;CAEA,OAAO,eAAe;EAAE;EAAY;CAAa,IAAI,CAAC,YAAY,YAAY,CAAC;AACjF;AAQ+B,cAAc;CAC3C,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAA0B,YAAY;CAAkC;CAC1F,SAAS;EACP,YAAY;GACV,aACE;GACF,SAAS;IACP;KAAE,MAAM;KAAkB,MAAM;IAAS;IACzC;KAAE,MAAM;KAAiB,MAAM;IAAS;IACxC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAW,MAAM;IAAS;IAClC;KAAE,MAAM;KAAU,MAAM;IAAS;IACjC;KAAE,MAAM;KAAU,MAAM;IAAS;IACjC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAgB,MAAM;IAAS;IACvC;KAAE,MAAM;KAAQ,MAAM;IAAS;IAC/B;KAAE,MAAM;KAAS,MAAM;IAAS;GAClC;EACF;EACA,cAAc;GACZ,aAAa;GACb,SAAS,CAAC;IAAE,MAAM;IAAY,MAAM;GAAS,CAAC;EAChD;CACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/shipping/use-shipping-simulation.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-shipping-simulation.js","names":[],"sources":["../../../src/sdk/shipping/use-shipping-simulation.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport type {\n  ShippingOption,\n  ShippingSimulateError,\n  ShippingSimulationPayload,\n} from '../../matter/shipping-simulator/shipping-simulator.js';\nimport type { ShippingSimulateErrorCode, ShippingSimulationQuery } from '../generated/graphql.js';\nimport { SHIPPING_SIMULATION, type ShippingSimulateInput } from './operations.js';\nimport { withRequestTimeout } from './request-timeout.js';\n\n/**\n * Shipping-simulation SDK hook (FSPG-815 / specs/fspg-815-minicart-wire-shipping-simulator-pdp.md).\n *\n * Returns the simulator's `onSimulate(input) => Promise<payload>` callback. It runs the\n * `ShippingSimulation` query imperatively per submit via the Apollo client read from\n * `getApolloContext()` (a non-throwing read; see the inline note below). The mapping is thin: the\n * structured `ShippingEstimate { value, unit }` is carried through untouched (the component\n * localizes it, where the `locale` lives), the API `Money` is carried as `{ amount, currencyCode }`,\n * and any transport/GraphQL failure is collapsed to one `UNKNOWN` userError so the component's\n * success/error transition stays deterministic.\n */\n\n// The simulator's domain payload is the seam's own type, imported from the component so the binding\n// is a direct assignment and the types never drift from the contract the component's tests assert.\ntype RawOption = NonNullable<ShippingSimulationQuery['shippingSimulation']['shippingOptions']>[number];\n\nconst UNKNOWN_ERROR: ShippingSimulateError = {\n  code: 'UNKNOWN',\n  message: 'Unable to calculate shipping. Try again.',\n};\n\nfunction mapErrorCode(code: ShippingSimulateErrorCode): ShippingSimulateError['code'] {\n  return code === 'INVALID_POSTAL_CODE' ? 'INVALID_POSTAL_CODE' : 'UNKNOWN';\n}\n\nfunction mapOption(option: RawOption): ShippingOption {\n  return {\n    id: option.id,\n    name: option.name,\n    channel: option.channel,\n    shippingEstimate: option.shippingEstimate,\n    price: { amount: option.price.amount, currencyCode: option.price.currencyCode },\n    listPrice: { amount: option.listPrice.amount, currencyCode: option.listPrice.currencyCode },\n  };\n}\n\nexport function useShippingSimulation(): (input: ShippingSimulateInput) => Promise<ShippingSimulationPayload> {\n  // Read the client off Apollo's context directly rather than via `useApolloClient`, which throws\n  // at render when no provider is present. The hook is the default `onSimulate` and runs in every\n  // Root render, including presentational tests/stories that mount the Root with their own callback\n  // and no ApolloProvider; a missing client only matters when the default callback is actually\n  // invoked, where it is mapped to the same UNKNOWN userError as any other failure.\n  const { client } = useContext(getApolloContext());\n\n  return useCallback(\n    async (input: ShippingSimulateInput): Promise<ShippingSimulationPayload> => {\n      if (!client) {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n      try {\n        const result = await withRequestTimeout((signal) =>\n          client.query({\n            query: SHIPPING_SIMULATION,\n            variables: { input },\n            fetchPolicy: 'no-cache',\n            context: { fetchOptions: { signal } },\n          }),\n        );\n\n        if (result.error || !result.data) {\n          return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n        }\n\n        const payload = result.data.shippingSimulation;\n        const userErrors = payload.userErrors.map((error) => ({\n          code: mapErrorCode(error.code),\n          message: error.message,\n        }));\n\n        if (userErrors.length > 0) {\n          return { shippingOptions: null, userErrors };\n        }\n\n        return {\n          shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,\n          userErrors: [],\n        };\n      } catch {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n    },\n    [client],\n  );\n}\n"],"mappings":";;;;;;AA6BA,MAAM,gBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;AAEA,SAAS,aAAa,MAAgE;CACpF,OAAO,SAAS,wBAAwB,wBAAwB;AAClE;AAEA,SAAS,UAAU,QAAmC;CACpD,OAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,SAAS,OAAO;EAChB,kBAAkB,OAAO;EACzB,OAAO;GAAE,QAAQ,OAAO,MAAM;GAAQ,cAAc,OAAO,MAAM;EAAa;EAC9E,WAAW;GAAE,QAAQ,OAAO,UAAU;GAAQ,cAAc,OAAO,UAAU;EAAa;CAC5F;AACF;AAEA,SAAgB,wBAA8F;CAM5G,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,OAAO,YACL,OAAO,UAAqE;EAC1E,IAAI,CAAC,QACH,OAAO;GAAE,iBAAiB;GAAM,YAAY,CAAC,aAAa;EAAE;EAE9D,IAAI;GACF,MAAM,SAAS,MAAM,oBAAoB,WACvC,OAAO,MAAM;IACX,OAAO;IACP,WAAW,EAAE,MAAM;IACnB,aAAa;IACb,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE;GACtC,CAAC,CACH;GAEA,IAAI,OAAO,SAAS,CAAC,OAAO,MAC1B,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;GAG9D,MAAM,UAAU,OAAO,KAAK;GAC5B,MAAM,aAAa,QAAQ,WAAW,KAAK,WAAW;IACpD,MAAM,aAAa,MAAM,IAAI;IAC7B,SAAS,MAAM;GACjB,EAAE;GAEF,IAAI,WAAW,SAAS,GACtB,OAAO;IAAE,iBAAiB;IAAM;GAAW;GAG7C,OAAO;IACL,iBAAiB,QAAQ,iBAAiB,IAAI,SAAS,KAAK;IAC5D,YAAY,CAAC;GACf;EACF,QAAQ;GACN,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;EAC9D;CACF,GACA,CAAC,MAAM,CACT;AACF"}
+{"version":3,"file":"use-shipping-simulation.js","names":[],"sources":["../../../src/sdk/shipping/use-shipping-simulation.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport type {\n  ShippingOption,\n  ShippingSimulateError,\n  ShippingSimulationPayload,\n} from '../../matter/shipping-simulator/shipping-simulator.js';\nimport type { ShippingSimulateErrorCode, ShippingSimulationQuery } from '../generated/graphql.js';\nimport { SHIPPING_SIMULATION, type ShippingSimulateInput } from './operations.js';\nimport { withRequestTimeout } from './request-timeout.js';\n\n/**\n * Shipping-simulation SDK hook (FSPG-815 / specs/fspg-815-minicart-wire-shipping-simulator-pdp.md).\n *\n * Returns the simulator's `onSimulate(input) => Promise<payload>` callback. It runs the\n * `ShippingSimulation` query imperatively per submit via the Apollo client read from\n * `getApolloContext()` (a non-throwing read; see the inline note below). The mapping is thin: the\n * structured `ShippingEstimate { value, unit }` is carried through untouched (the component\n * localizes it, where the `locale` lives), the API `Money` is carried as `{ amount, currencyCode }`,\n * and any transport/GraphQL failure is collapsed to one `UNKNOWN` userError so the component's\n * success/error transition stays deterministic.\n */\n\n// The simulator's domain payload is the seam's own type, imported from the component so the binding\n// is a direct assignment and the types never drift from the contract the component's tests assert.\ntype RawOption = NonNullable<ShippingSimulationQuery['shippingSimulation']['shippingOptions']>[number];\n\n// Diagnostic text for logs and `onResult`: `ShippingSimulatorError` words this code from its own `$content`.\nconst UNKNOWN_ERROR: ShippingSimulateError = {\n  code: 'UNKNOWN',\n  message: 'Unable to calculate shipping. Try again.',\n};\n\nfunction mapErrorCode(code: ShippingSimulateErrorCode): ShippingSimulateError['code'] {\n  return code === 'INVALID_POSTAL_CODE' ? 'INVALID_POSTAL_CODE' : 'UNKNOWN';\n}\n\nfunction mapOption(option: RawOption): ShippingOption {\n  return {\n    id: option.id,\n    name: option.name,\n    channel: option.channel,\n    shippingEstimate: option.shippingEstimate,\n    price: { amount: option.price.amount, currencyCode: option.price.currencyCode },\n    listPrice: { amount: option.listPrice.amount, currencyCode: option.listPrice.currencyCode },\n  };\n}\n\nexport function useShippingSimulation(): (input: ShippingSimulateInput) => Promise<ShippingSimulationPayload> {\n  // Read the client off Apollo's context directly rather than via `useApolloClient`, which throws\n  // at render when no provider is present. The hook is the default `onSimulate` and runs in every\n  // Root render, including presentational tests/stories that mount the Root with their own callback\n  // and no ApolloProvider; a missing client only matters when the default callback is actually\n  // invoked, where it is mapped to the same UNKNOWN userError as any other failure.\n  const { client } = useContext(getApolloContext());\n\n  return useCallback(\n    async (input: ShippingSimulateInput): Promise<ShippingSimulationPayload> => {\n      if (!client) {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n      try {\n        const result = await withRequestTimeout((signal) =>\n          client.query({\n            query: SHIPPING_SIMULATION,\n            variables: { input },\n            fetchPolicy: 'no-cache',\n            context: { fetchOptions: { signal } },\n          }),\n        );\n\n        if (result.error || !result.data) {\n          return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n        }\n\n        const payload = result.data.shippingSimulation;\n        const userErrors = payload.userErrors.map((error) => ({\n          code: mapErrorCode(error.code),\n          message: error.message,\n        }));\n\n        if (userErrors.length > 0) {\n          return { shippingOptions: null, userErrors };\n        }\n\n        return {\n          shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,\n          userErrors: [],\n        };\n      } catch {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n    },\n    [client],\n  );\n}\n"],"mappings":";;;;;;AA8BA,MAAM,gBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;AAEA,SAAS,aAAa,MAAgE;CACpF,OAAO,SAAS,wBAAwB,wBAAwB;AAClE;AAEA,SAAS,UAAU,QAAmC;CACpD,OAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,SAAS,OAAO;EAChB,kBAAkB,OAAO;EACzB,OAAO;GAAE,QAAQ,OAAO,MAAM;GAAQ,cAAc,OAAO,MAAM;EAAa;EAC9E,WAAW;GAAE,QAAQ,OAAO,UAAU;GAAQ,cAAc,OAAO,UAAU;EAAa;CAC5F;AACF;AAEA,SAAgB,wBAA8F;CAM5G,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,OAAO,YACL,OAAO,UAAqE;EAC1E,IAAI,CAAC,QACH,OAAO;GAAE,iBAAiB;GAAM,YAAY,CAAC,aAAa;EAAE;EAE9D,IAAI;GACF,MAAM,SAAS,MAAM,oBAAoB,WACvC,OAAO,MAAM;IACX,OAAO;IACP,WAAW,EAAE,MAAM;IACnB,aAAa;IACb,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE;GACtC,CAAC,CACH;GAEA,IAAI,OAAO,SAAS,CAAC,OAAO,MAC1B,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;GAG9D,MAAM,UAAU,OAAO,KAAK;GAC5B,MAAM,aAAa,QAAQ,WAAW,KAAK,WAAW;IACpD,MAAM,aAAa,MAAM,IAAI;IAC7B,SAAS,MAAM;GACjB,EAAE;GAEF,IAAI,WAAW,SAAS,GACtB,OAAO;IAAE,iBAAiB;IAAM;GAAW;GAG7C,OAAO;IACL,iBAAiB,QAAQ,iBAAiB,IAAI,SAAS,KAAK;IAC5D,YAAY,CAAC;GACf;EACF,QAAQ;GACN,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;EAC9D;CACF,GACA,CAAC,MAAM,CACT;AACF"}

package/dist/sdk/state/cart.d.ts

@@ -2,8 +2,12 @@
 export declare const orderFormIdVar: import("@apollo/client").ReactiveVar<string | null>;
 /**
  * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes
- * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it
+ * here on every call and `CartError` reads it
  * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.
+ *
+ * Lifetime: each item write (add, remove, quantity) clears this var as it starts; coupon writes and
+ * `validate` leave it alone. A CartRoot mount clears it too, never a re-render. The var is module-level,
+ * so without the mount clear an error from another page would show on the next one.
  */
 export declare const cartUserErrorsVar: import("@apollo/client").ReactiveVar<readonly Readonly<{
   code: string;
@@ -30,8 +34,11 @@ export declare const miniCartOpenVar: import("@apollo/client").ReactiveVar<boole
  * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.
  * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form
  * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon
- * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`
+ * actions publish here on every call and `CartCouponError`
  * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.
+ *
+ * Lifetime: each coupon write (apply, remove) clears this var as it starts; item writes and `validate`
+ * leave it alone. A CartRoot mount clears it too, never a re-render.
  */
 export declare const cartCouponErrorsVar: import("@apollo/client").ReactiveVar<readonly Readonly<{
   code: string;

package/dist/sdk/state/cart.js

@@ -3,8 +3,12 @@ import { makeVar } from "@apollo/client";
 const orderFormIdVar = makeVar(null);
 /**
 * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes
-* here on every call (cleared synchronously at the start of the next call) and `CartError` reads it
+* here on every call and `CartError` reads it
 * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.
+*
+* Lifetime: each item write (add, remove, quantity) clears this var as it starts; coupon writes and
+* `validate` leave it alone. A CartRoot mount clears it too, never a re-render. The var is module-level,
+* so without the mount clear an error from another page would show on the next one.
 */
 const cartUserErrorsVar = makeVar([]);
 /**
@@ -28,8 +32,11 @@ const miniCartOpenVar = makeVar(false);
 * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.
 * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form
 * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon
-* actions publish here on every call (cleared at the start of the next call) and `CartCouponError`
+* actions publish here on every call and `CartCouponError`
 * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.
+*
+* Lifetime: each coupon write (apply, remove) clears this var as it starts; item writes and `validate`
+* leave it alone. A CartRoot mount clears it too, never a re-render.
 */
 const cartCouponErrorsVar = makeVar([]);
 /**

package/dist/sdk/state/cart.js.map

@@ -1 +1 @@
-{"version":3,"file":"cart.js","names":[],"sources":["../../../src/sdk/state/cart.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\nimport type { CartUserError } from '../cart/operations.js';\n\n// Session-scoped cart identifier (`Cart.id` from the cart query response). Client state only —\n// never sent as a query variable or request header; the x-order-form-id cookie carries cart\n// context on the transport. Starts null; hydrated when the cart entity arrives, which opens the\n// cart action ready gate. See docs/storefront-core/reference-cart.md § Cart context; docs/storefront-core/reference-free-particle-model.md § The cart write contract.\nexport const orderFormIdVar = makeVar<string | null>(null);\n\n/**\n * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes\n * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it\n * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.\n */\nexport const cartUserErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the\n * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key\n * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when\n * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value\n * (docs/storefront-core/reference-free-particle-model.md § Read side — state). Client state only — never a query variable\n * or request header.\n */\nexport const cartLastAddVar = makeVar<number>(0);\n\n/**\n * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`\n * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and\n * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the\n * controlled drawer; `addItem` never writes it. Client state only — never a query variable or\n * request header.\n */\nexport const miniCartOpenVar = makeVar<boolean>(false);\n\n/**\n * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.\n * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form\n * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon\n * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`\n * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.\n */\nexport const cartCouponErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Count of cart writes currently in flight (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Every mutating\n * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a\n * write is outstanding. The stock-validation open call reads this to skip while a write is running —\n * that write's own response already carries current availability, so re-validating would be\n * redundant. `validate` itself is read-only upstream and never registers here. Client state only —\n * never a query variable or request header.\n */\nexport const cartWritesInFlightVar = makeVar<number>(0);\n\n/**\n * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on\n * a successful `validate` and on every successful cart write, because a write's response already\n * carries recomputed availability (docs/storefront-core/reference-cart.md § Validation). The\n * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against\n * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or\n * opening it right after an add — does not re-validate. Client state only.\n */\nexport const cartAvailabilityFreshAtVar = makeVar<number>(0);\n\n/**\n * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:\n * the platform's rate limits under real traffic are not known yet, so this value is a starting point,\n * not a contract (docs/storefront-core/reference-cart.md § Validation). The pre-checkout call ignores it and always\n * runs.\n */\nexport const CART_VALIDATE_STALENESS_MS = 30_000;\n"],"mappings":";;AAOA,MAAa,iBAAiB,QAAuB,IAAI;;;;;;AAOzD,MAAa,oBAAoB,QAAkC,CAAC,CAAC;;;;;;;;;AAUrE,MAAa,iBAAiB,QAAgB,CAAC;;;;;;;;AAS/C,MAAa,kBAAkB,QAAiB,KAAK;;;;;;;;AASrD,MAAa,sBAAsB,QAAkC,CAAC,CAAC;;;;;;;;;AAUvE,MAAa,wBAAwB,QAAgB,CAAC;;;;;;;;;AAUtD,MAAa,6BAA6B,QAAgB,CAAC;;;;;;;AAQ3D,MAAa,6BAA6B"}
+{"version":3,"file":"cart.js","names":[],"sources":["../../../src/sdk/state/cart.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\nimport type { CartUserError } from '../cart/operations.js';\n\n// Session-scoped cart identifier (`Cart.id` from the cart query response). Client state only —\n// never sent as a query variable or request header; the x-order-form-id cookie carries cart\n// context on the transport. Starts null; hydrated when the cart entity arrives, which opens the\n// cart action ready gate. See docs/storefront-core/reference-cart.md § Cart context; docs/storefront-core/reference-free-particle-model.md § The cart write contract.\nexport const orderFormIdVar = makeVar<string | null>(null);\n\n/**\n * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes\n * here on every call and `CartError` reads it\n * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Stays in client state — never a query variable or request header.\n *\n * Lifetime: each item write (add, remove, quantity) clears this var as it starts; coupon writes and\n * `validate` leave it alone. A CartRoot mount clears it too, never a re-render. The var is module-level,\n * so without the mount clear an error from another page would show on the next one.\n */\nexport const cartUserErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the\n * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key\n * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when\n * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value\n * (docs/storefront-core/reference-free-particle-model.md § Read side — state). Client state only — never a query variable\n * or request header.\n */\nexport const cartLastAddVar = makeVar<number>(0);\n\n/**\n * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`\n * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and\n * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the\n * controlled drawer; `addItem` never writes it. Client state only — never a query variable or\n * request header.\n */\nexport const miniCartOpenVar = makeVar<boolean>(false);\n\n/**\n * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.\n * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form\n * and never collides with item-write errors (docs/storefront-core/reference-free-particle-model.md § The cart write contract). The coupon\n * actions publish here on every call and `CartCouponError`\n * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.\n *\n * Lifetime: each coupon write (apply, remove) clears this var as it starts; item writes and `validate`\n * leave it alone. A CartRoot mount clears it too, never a re-render.\n */\nexport const cartCouponErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Count of cart writes currently in flight (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Every mutating\n * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a\n * write is outstanding. The stock-validation open call reads this to skip while a write is running —\n * that write's own response already carries current availability, so re-validating would be\n * redundant. `validate` itself is read-only upstream and never registers here. Client state only —\n * never a query variable or request header.\n */\nexport const cartWritesInFlightVar = makeVar<number>(0);\n\n/**\n * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on\n * a successful `validate` and on every successful cart write, because a write's response already\n * carries recomputed availability (docs/storefront-core/reference-cart.md § Validation). The\n * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against\n * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or\n * opening it right after an add — does not re-validate. Client state only.\n */\nexport const cartAvailabilityFreshAtVar = makeVar<number>(0);\n\n/**\n * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:\n * the platform's rate limits under real traffic are not known yet, so this value is a starting point,\n * not a contract (docs/storefront-core/reference-cart.md § Validation). The pre-checkout call ignores it and always\n * runs.\n */\nexport const CART_VALIDATE_STALENESS_MS = 30_000;\n"],"mappings":";;AAOA,MAAa,iBAAiB,QAAuB,IAAI;;;;;;;;;;AAWzD,MAAa,oBAAoB,QAAkC,CAAC,CAAC;;;;;;;;;AAUrE,MAAa,iBAAiB,QAAgB,CAAC;;;;;;;;AAS/C,MAAa,kBAAkB,QAAiB,KAAK;;;;;;;;;;;AAYrD,MAAa,sBAAsB,QAAkC,CAAC,CAAC;;;;;;;;;AAUvE,MAAa,wBAAwB,QAAgB,CAAC;;;;;;;;;AAUtD,MAAa,6BAA6B,QAAgB,CAAC;;;;;;;AAQ3D,MAAa,6BAA6B"}

package/dist/utils/safe-href.d.ts

@@ -1,5 +1,7 @@
 import { PageRef } from "../sdk/navigation/types.js";
 //#region src/utils/safe-href.d.ts
+/** The parameter carrying the shopper's way back, read by the sign-in route and the platform's login. */
+export declare const RETURN_URL_PARAM = "returnUrl";
 /**
  * The sign-in page, carrying the current logical path so the shopper can be returned where they
  * started. The sender's half only: nothing stops a hand-crafted link, so the sign-in route is to narrow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore",
-  "version": "0.0.8",
+  "version": "0.0.11",
   "description": "FastStore AI Native component library built on Base UI with AI-editable styles",
   "license": "MIT",
   "homepage": "https://developers.vtex.com/docs/guides/faststore",
@@ -45,7 +45,6 @@
     "./catalog.json": "./dist/catalog.json",
     "./actions.json": "./dist/actions.json",
     "./content-types.json": "./dist/content-types.json",
-    "./message-locales.json": "./dist/message-locales.json",
     "./tailwind.css": "./src/styles/tailwind.css"
   },
   "files": [
@@ -56,11 +55,13 @@
   ],
   "dependencies": {
     "@base-ui/react": "^1.3.0",
+    "@formatjs/icu-messageformat-parser": "^3.5.17",
     "@graphql-typed-document-node/core": "^3.2.0",
     "@vtex/country-forms": "1.14.0",
-    "@vtex/faststore-catalog": "0.0.8",
+    "@vtex/faststore-catalog": "0.0.11",
     "esbuild": "~0.27.3",
     "graphql": "^16.13.1",
+    "intl-messageformat": "^11.2.14",
     "react-hook-form": "^7.85.0",
     "react-intl": "^10.1.22",
     "rxjs": "^7.8.2",

package/skills/storefront-asset/SKILL.md

@@ -50,7 +50,7 @@ green.
 ## Layout
 
 The provider reads an Asset's sides from `package.json` and two paths. A storefront `asset.yaml`
-holds the envelope and an empty body, so nothing in it changes the layout.
+holds the envelope and, at most, a `secrets` list, so nothing in it changes the layout.
 
 | Side | What marks it | Entry |
 | --- | --- | --- |
@@ -80,7 +80,7 @@ A store lists the Asset's package as a dependency and compiles its components fr
 
 `dev` needs `VTEX_ACCOUNT` in the repo root's `.env`, or `STOREFRONT_CORE_URL` to override the core
 URL derived from the account. `VTEX_WORKSPACE` defaults to `master`. `VTEX_TOKEN`, which is
-optional, and the value of every secret a declaration lists go in the root's `.env.local`, which
+optional, and the value of every secret the Asset's `asset.yaml` lists go in the root's `.env.local`, which
 git ignores. Keep the Asset's folder free of `.env` files, so one place holds every value.
 `validate` reads none of them.
 

package/skills/storefront-asset/references/api-side.md

@@ -13,8 +13,6 @@ const REVIEWS_BY_SLUG: Record<string, Array<{ id: string; rating: number; text:
 };
 
 export default defineSubgraph({
-  vendor: 'acme',
-
   typeDefs: gql`
     extend type Product @key(fields: "slug") {
       slug: String! @external
@@ -44,18 +42,22 @@ provider builds the schema from it.
 
 | Field | What it is |
 | --- | --- |
-| `vendor` | Required. Matches `^[a-z][a-z0-9]*$`: lowercase letters and digits, starting with a letter. It prefixes every name the Asset contributes. |
 | `typeDefs` | SDL in a `gql` tag, with bare names. Write `@key` and `@external` on the entity you extend; the provider injects the federation preamble. |
 | `extends` | The core entities the SDL extends. `Product`, keyed by `slug`, is the only one. |
 | `resolvers` | Keyed by bare names. The provider renames the keys to the prefixed names and adds each entity's `__resolveReference`. |
-| `secrets` | Optional. The environment names the resolvers read; see Secrets. |
 | `name` | Optional. The subgraph name; the package name by default. |
 
+The vendor and the secret names are not in the declaration. The extension's `extension.yaml`
+declares the vendor, and the Asset's `asset.yaml` lists the secrets; see Secrets.
+
 ## The vendor prefix
 
-The build prefixes every name the Asset contributes with `<vendor>_`: fields added to `Product`,
-root `Query` and `Mutation` fields, and each declared type with every reference to it. The
-declaration above exposes `Product.acme_reviews` of type `[acme_Review!]!`. Write bare names in the
+The build prefixes every name the Asset contributes with the vendor's token, the vendor from
+`extension.yaml` with each `-` turned into `_`: fields added to `Product`, root `Query` and
+`Mutation` fields, and each declared type with every reference to it. Under vendor `acme` the
+declaration above exposes `Product.acme_reviews` of type `[acme_Review!]!`; under `acme-corp` it is
+`Product.acme_corp_reviews`. A vendor that starts with a digit has no token, and `validate` reports
+`storefront-vendor-invalid` on `extension.yaml`. Write bare names in the
 declaration and let the build add the prefix. The `@key` field of an extended entity keeps its core
 name.
 
@@ -80,10 +82,20 @@ const reviews = (product: { slug: string }, _args: unknown, ctx: SubgraphContext
 
 ## Secrets
 
-`secrets: ['ACME_API_KEY']` declares the environment names the Asset reads. Each name matches
-`^[A-Z][A-Z0-9_]*$`. The provider rejects `PATH`, `HOME`, `PWD`, `SHELL`, `TMPDIR` and any name
-that starts with `VTEX_` or `NODE_`. A declared name that is not set is absent from `ctx.secrets`;
-`dev` logs one warning for each. Values come from the repo root's `.env` and `.env.local`; keep
+The `secrets` list in the Asset's `asset.yaml` declares the environment names the Asset reads:
+
+```yaml
+apiVersion: assets.vtex.com/v1alpha1
+name: api
+kind: storefront
+secrets:
+  - ACME_API_KEY
+```
+
+Each name matches `^[A-Z][A-Z0-9_]*$`. The provider rejects `PATH`, `HOME`, `PWD`, `SHELL`,
+`TMPDIR` and any name that starts with `VTEX_` or `NODE_` with `storefront-secret-reserved` on
+`asset.yaml`. A declared name that is not set is absent from `ctx.secrets`; `dev` logs one warning
+for each. Values come from the repo root's `.env` and `.env.local`; keep
 secret values in `.env.local`, which git ignores. A resolver reads them through `ctx.secrets` only.
 
 ## The capability boundary
@@ -93,7 +105,7 @@ Finding at the line it flags:
 
 | Rule | What it flags | What to write instead |
 | --- | --- | --- |
-| `process-env` | Any `process.env` member access | Declare the name in `secrets` and read `ctx.secrets` |
+| `process-env` | Any `process.env` member access | List the name under `secrets` in `asset.yaml` and read `ctx.secrets` |
 | `fs-import` | A runtime import of `fs` or `fs/promises`, bare or `node:` | Fetch the data from a service |
 | `child-process-import` | A runtime import of `child_process` | Call a service over HTTP |
 
@@ -105,7 +117,8 @@ environment after boot.
 ## The test
 
 `src/index.test.ts` sits beside the declaration. It builds the subgraph with `buildSubgraph` from
-`@vtex/faststore/cli` and resolves the field through `_entities`, the join a federated query makes:
+`@vtex/faststore/cli`, under the extension's vendor, and resolves the field through `_entities`, the
+join a federated query makes:
 
 ```ts
 import { buildSubgraph } from '@vtex/faststore/cli';
@@ -115,7 +128,7 @@ import definition from './index';
 
 describe('acme extension', () => {
   it('builds a subgraph and resolves the sample field via _entities', async () => {
-    const schema = buildSubgraph(definition);
+    const schema = buildSubgraph(definition, 'acme');
 
     const result = await graphql({
       schema,

package/skills/storefront-asset/references/findings.md

@@ -11,14 +11,17 @@ it writes, plus `storefront-build-failed`.
 | Code | Trigger | On | Fix |
 | --- | --- | --- | --- |
 | `storefront-typescript-unsupported` | The Asset's `typescript` is missing or has no TypeScript 5 compiler API, so the capability lint did not run | `package.json` | `pnpm add -D typescript@^5.9.3` in the Asset's folder |
-| `storefront-capability-process-env` | A `process.env` member access in the declaration or a module it imports | The source line | Declare the name in `secrets` and read `ctx.secrets` |
+| `storefront-capability-process-env` | A `process.env` member access in the declaration or a module it imports | The source line | List the name under `secrets` in `asset.yaml` and read `ctx.secrets` |
 | `storefront-capability-fs-import` | A runtime import of `fs` or `fs/promises` | The source line | Fetch the data from a service; a resolver has no filesystem |
 | `storefront-capability-child-process-import` | A runtime import of `child_process` | The source line | Call a service; a resolver spawns no process |
-| `storefront-declaration-invalid` | `main` names no file; the declaration does not bundle or import; it does not `export default defineSubgraph(...)`; or the build rejects it: a `vendor` outside `^[a-z][a-z0-9]*$`, an `extends` entry other than `Product`, a `@key` other than `slug`, a secret name outside the grammar, or SDL that does not parse | The declaration entry | The message names the field or the SDL error. On a UI-only Asset's `src/index.ts`, add `exports["./catalog.json"]`: without it the barrel was read as a declaration |
+| `storefront-declaration-invalid` | `main` names no file; the declaration does not bundle or import; it does not `export default defineSubgraph(...)`; or the build rejects it: an `extends` entry other than `Product`, a `@key` other than `slug`, or SDL that does not parse | The declaration entry | The message names the field or the SDL error. On a UI-only Asset's `src/index.ts`, add `exports["./catalog.json"]`: without it the barrel was read as a declaration |
 | `storefront-composition-failed` | The built slice does not compose with the storefront core schema: a type or field that collides with core's, or a federation directive the composer rejects. In `dev`, also a conflict between two Assets' slices | The declaration entry | Change the SDL as the message says. Keep `@key(fields: "slug")` on `Product` and bare names elsewhere |
 | `storefront-catalog-export-missing` | The Asset has `src/components/` and `package.json#exports` has no `./catalog.json` key | `package.json` | Add `"./catalog.json": "./dist/catalog.json"` and `".": "./src/index.ts"` to `exports` |
 | `storefront-catalog-export-invalid` | The `./catalog.json` export names no file, or a path that is not `./`-relative, has `..` or resolves outside the Asset through a link; `dev` and `build` write where it points, so the catalog goes to `dist/` meanwhile | `package.json` | Point the export at a file inside the Asset: `"./catalog.json": "./dist/catalog.json"` |
 | `storefront-catalog-invalid` | The catalog build threw: no component under `src/components/` (`NoExtensionComponents`), two components with one name, a fragment spread with no definition (`UnresolvedSpread`), no `package.json#name` (`MissingPackageName`), or a top-level `defineActions` | `package.json` | The message names the file or component. Add a `defineComponent`, rename the duplicate, drop the spread, set `name`, or remove `defineActions` |
+| `storefront-vendor-missing` | The extension's `extension.yaml` declares no `vendor` | `extension.yaml` | Add `vendor: <kebab-case>` to the extension |
+| `storefront-vendor-invalid` | The vendor is not kebab-case or starts with a digit, so it has no GraphQL prefix | `extension.yaml` | Choose a vendor that starts with a letter |
+| `storefront-secret-reserved` | A name under `secrets` is `PATH`, `HOME`, `PWD`, `SHELL` or `TMPDIR`, or starts with `VTEX_` or `NODE_` | `asset.yaml` | Rename the secret; the message names the rule |
 | `storefront-build-failed` | The build step after `validate` passed failed: no or invalid `tsconfig.json`, a TypeScript diagnostic, the `server.mjs` bundle, two component docs sharing a basename, or the catalog | `package.json` | The message is the runner's error. Fix what it names and run `pnpm extension build` again |
 
 `storefront-declaration-invalid`, `storefront-catalog-invalid` and `storefront-build-failed` carry

package/src/styles/tailwind.css

@@ -1,8 +1,7 @@
 @import "tailwindcss";
 
 @theme {
-  --color-brand: #2953b2;
-  --color-brand-light: #4a7ae0;
+  --color-primary: #2953b2;
   --color-text: #171a1f;
   --color-text-inverse: #ffffff;
   --color-bg: #ffffff;
@@ -90,4 +89,12 @@
     min-height: 0;
     overflow-y: auto;
   }
+
+  /* A CartAllUnavailable that holds no rendered CartAllUnavailableMessage (blank copy renders none) would
+     show the store's box empty. `!important` in `@layer base` outranks every store utility, `!flex`
+     included, because important declarations reverse the layer order, as preflight's `[hidden]` rule
+     does. A rule of its own so a browser without `:has` drops only this selector. */
+  [data-fs-cart-all-unavailable]:not(:has([data-fs-cart-all-unavailable-message])) {
+    display: none !important;
+  }
 }

package/dist/matter/shipping-address/country-descriptors.d.ts

@@ -1 +0,0 @@
-import "../../particles/field/field.js";

package/dist/message-locales.json

@@ -1,7 +0,0 @@
-{
-  "locales": [
-    "en-US",
-    "es-ES",
-    "pt-BR"
-  ]
-}

package/dist/sdk/i18n/client.d.ts

@@ -1,4 +0,0 @@
-import { MessageId, Messages } from "./locales.js";
-import "./provider.js";
-import { FormattedMessage, useIntl } from "react-intl";
-export { FormattedMessage, type MessageId, type Messages, useIntl };

package/dist/sdk/i18n/client.js

@@ -1,4 +0,0 @@
-"use client";
-import "./provider.js";
-import { FormattedMessage, useIntl } from "react-intl";
-export { FormattedMessage, useIntl };

package/dist/sdk/i18n/locales.d.ts

@@ -1,8 +0,0 @@
-import _exports from "./messages/en-US.json.js";
-//#region src/sdk/i18n/locales.d.ts
-/** The resolved record a render formats against: what crosses the RSC boundary and what `IntlProvider` takes. */
-export type Messages = Readonly<Record<string, string>>;
-/** Every id in the source catalog. Exported for the `Record<string, MessageId>` escape hatch. */
-export type MessageId = keyof typeof _exports;
-//#endregion
-//# sourceMappingURL=locales.d.ts.map

package/dist/sdk/i18n/locales.js

@@ -1,57 +0,0 @@
-//#region src/sdk/i18n/locales.ts
-/** The locales this package ships a catalog for. */
-const SUPPORTED_LOCALES = [
-	"en-US",
-	"es-ES",
-	"pt-BR"
-];
-/** The hand-authored source catalog and the implicit floor of every fallback chain. */
-const DEFAULT_LOCALE = "en-US";
-/** Locale tag → catalog loader. An explicit table, never string formatting. */
-const CATALOG_FILES = Object.freeze({
-	"en-US": () => import("./messages/en-US.js").then((module) => module.default),
-	"es-ES": () => import("./messages/es-ES.js").then((module) => module.default),
-	"pt-BR": () => import("./messages/pt-BR.js").then((module) => module.default)
-});
-/**
-* The supported locale a tag names, matched against the table's keys case-insensitively.
-* `undefined` for anything else — no truncation, no language-only fallback.
-*/
-function normalizeLocale(tag) {
-	const wanted = tag.toLowerCase();
-	return SUPPORTED_LOCALES.find((locale) => locale.toLowerCase() === wanted);
-}
-/**
-* The merged record as `react-intl` types it.
-*
-* The id augmentation in `intl.d.ts` makes `messages` require *every* id in the union, which a
-* record merged from up to four catalogs cannot prove structurally — and typing `Messages` by the
-* union instead would push the same gap out to every caller that serializes it. What actually holds
-* is Invariant 4: `loadMessages` merges the source catalog underneath every chain, and
-* `locales.test.ts` asserts the result is a superset of its keys for every supported locale. This is
-* the one place that gap is crossed.
-*
-* An assertion and never a copy: `IntlProvider` compares `messages` by reference to decide whether
-* to rebuild `intl`, so handing it a fresh object would invalidate every `useIntl()` in the tree on
-* each render of the provider above it.
-*/
-function asIntlMessages(messages) {
-	return messages;
-}
-/**
-* How both entries answer a formatting error.
-*
-* A missing id is impossible — the id union rejects one at `pnpm typecheck` — and a missing
-* translation is the build warning's business, not a shopper's console. What is left is a malformed
-* ICU string from a translator, which the parity test already fails CI over. Logging it in
-* development keeps it findable while a catalog is being edited; staying silent in production keeps
-* a shopper's console clean.
-*/
-function onIntlError(error) {
-	if (process.env.NODE_ENV === "production") return;
-	console.error(error);
-}
-//#endregion
-export { CATALOG_FILES, DEFAULT_LOCALE, SUPPORTED_LOCALES, asIntlMessages, normalizeLocale, onIntlError };
-
-//# sourceMappingURL=locales.js.map

package/dist/sdk/i18n/locales.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"locales.js","names":[],"sources":["../../../src/sdk/i18n/locales.ts"],"sourcesContent":["/**\n * The message catalogs this package ships, and the table that finds one.\n *\n * ## Adding a key\n *\n * Every id is prefixed `fs/` and uses at most three dot-separated levels after the prefix, in one of\n * two tiers: generic (`fs/a11y.*`, `fs/action.*`, `fs/error.*`) or `domain.area.leaf`\n * (`fs/shipping.estimate.in-hours`). **A component name never appears in a key.**\n *\n * Crowdin treats a renamed key as a new string and orphans its translations, and component names are\n * the most-renamed thing in this repository — a component moving between `particles/` and `matter/`,\n * being absorbed, or being renamed would force a choice between a lying key and paying for\n * retranslation. Domain names are more stable. The `fs/` prefix earns nothing mechanically today; it\n * buys the option of a second catalog owner later, and adding it afterwards costs a retranslation.\n *\n * Add the key to `messages/en-US.json` — the hand-authored source, never a build artifact — and the\n * id union picks it up. The translated catalogs follow through Crowdin; the package build warns about\n * the gap and does not fail on it.\n *\n * ## Adding a locale\n *\n * Three edits, all in this directory: the JSON file, a `SUPPORTED_LOCALES` entry, a `CATALOG_FILES`\n * entry. Never derive a filename from a locale tag by concatenation or truncation — the filename\n * Crowdin writes is decided by the Crowdin project's language mapping, not by anything here, and a\n * computed path that misses falls through to the default locale with HTTP 200. The table plus\n * `locales.test.ts` is what makes a disagreement loud.\n */\nimport type enUS from './messages/en-US.json';\n\n/** The resolved record a render formats against: what crosses the RSC boundary and what `IntlProvider` takes. */\nexport type Messages = Readonly<Record<string, string>>;\n\n/** Every id in the source catalog. Exported for the `Record<string, MessageId>` escape hatch. */\nexport type MessageId = keyof typeof enUS;\n\n/** The locales this package ships a catalog for. */\nexport const SUPPORTED_LOCALES = ['en-US', 'es-ES', 'pt-BR'] as const;\n\nexport type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];\n\n/** The hand-authored source catalog and the implicit floor of every fallback chain. */\nexport const DEFAULT_LOCALE: SupportedLocale = 'en-US';\n\n/** Locale tag → catalog loader. An explicit table, never string formatting. */\nexport const CATALOG_FILES: Readonly<Record<SupportedLocale, () => Promise<Messages>>> = Object.freeze({\n  'en-US': () => import('./messages/en-US.json').then((module) => module.default),\n  'es-ES': () => import('./messages/es-ES.json').then((module) => module.default),\n  'pt-BR': () => import('./messages/pt-BR.json').then((module) => module.default),\n});\n\n/**\n * The supported locale a tag names, matched against the table's keys case-insensitively.\n * `undefined` for anything else — no truncation, no language-only fallback.\n */\nexport function normalizeLocale(tag: string): SupportedLocale | undefined {\n  const wanted = tag.toLowerCase();\n  return SUPPORTED_LOCALES.find((locale) => locale.toLowerCase() === wanted);\n}\n\n/**\n * The merged record as `react-intl` types it.\n *\n * The id augmentation in `intl.d.ts` makes `messages` require *every* id in the union, which a\n * record merged from up to four catalogs cannot prove structurally — and typing `Messages` by the\n * union instead would push the same gap out to every caller that serializes it. What actually holds\n * is Invariant 4: `loadMessages` merges the source catalog underneath every chain, and\n * `locales.test.ts` asserts the result is a superset of its keys for every supported locale. This is\n * the one place that gap is crossed.\n *\n * An assertion and never a copy: `IntlProvider` compares `messages` by reference to decide whether\n * to rebuild `intl`, so handing it a fresh object would invalidate every `useIntl()` in the tree on\n * each render of the provider above it.\n */\nexport function asIntlMessages(messages: Messages): Record<MessageId, string> {\n  return messages as Record<MessageId, string>;\n}\n\n/**\n * How both entries answer a formatting error.\n *\n * A missing id is impossible — the id union rejects one at `pnpm typecheck` — and a missing\n * translation is the build warning's business, not a shopper's console. What is left is a malformed\n * ICU string from a translator, which the parity test already fails CI over. Logging it in\n * development keeps it findable while a catalog is being edited; staying silent in production keeps\n * a shopper's console clean.\n */\nexport function onIntlError(error: Error): void {\n  if (process.env.NODE_ENV === 'production') return;\n  console.error(error);\n}\n"],"mappings":";;AAoCA,MAAa,oBAAoB;CAAC;CAAS;CAAS;AAAO;;AAK3D,MAAa,iBAAkC;;AAG/C,MAAa,gBAA4E,OAAO,OAAO;CACrG,eAAe,OAAO,sBAAwB,CAAC,MAAM,WAAW,OAAO,OAAO;CAC9E,eAAe,OAAO,sBAAwB,CAAC,MAAM,WAAW,OAAO,OAAO;CAC9E,eAAe,OAAO,sBAAwB,CAAC,MAAM,WAAW,OAAO,OAAO;AAChF,CAAC;;;;;AAMD,SAAgB,gBAAgB,KAA0C;CACxE,MAAM,SAAS,IAAI,YAAY;CAC/B,OAAO,kBAAkB,MAAM,WAAW,OAAO,YAAY,MAAM,MAAM;AAC3E;;;;;;;;;;;;;;;AAgBA,SAAgB,eAAe,UAA+C;CAC5E,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,YAAY,OAAoB;CAC9C,IAAI,QAAQ,IAAI,aAAa,cAAc;CAC3C,QAAQ,MAAM,KAAK;AACrB"}