@shopify/hydrogen 2026.10.0-preview.2 → 2026.10.0-preview.4

package/dist/customer-account/errors.mjs

@@ -1,7 +1,23 @@
 //#region src/customer-account/errors.ts
+/**
+* Base error for Customer Account API failures. Thrown by
+* `CustomerAccountClient.graphql()` when the API responds with a non-OK
+* HTTP status, when the response body cannot be parsed as JSON, or when the
+* parsed response is missing `data`. Also thrown (without subclassing) for
+* OAuth token-request timeouts and network failures.
+*
+* Not all fields are populated on every instance. `status` is present
+* whenever an HTTP response was received. `requestId` is set when the
+* `x-request-id` response header exists. Both are absent on network
+* failures where no response arrived. `retryAfter` is populated only on
+* non-OK responses.
+*/
 var CustomerAccountApiError = class extends Error {
+	/** HTTP status code from the API response. Present whenever an HTTP response was received (including parse failures), absent on network failures where no response arrived. */
 	status;
+	/** Value of the `x-request-id` response header, when the API returned one. Useful for Shopify support requests. */
 	requestId;
+	/** Value of the `retry-after` response header, when present. Indicates when the client should retry a rate-limited request. */
 	retryAfter;
 	constructor(message, options) {
 		super(message, options?.cause ? { cause: options.cause } : void 0);
@@ -11,13 +27,27 @@ var CustomerAccountApiError = class extends Error {
 		this.retryAfter = options?.retryAfter;
 	}
 };
+/**
+* Client-side pre-flight check. Thrown when the access token is missing,
+* empty, has leading or trailing whitespace, or contains ASCII control
+* characters (including DEL). Also thrown when the options object is
+* missing. A token the server rejects (e.g. expired or revoked) produces
+* the base {@link CustomerAccountApiError} with `status: 401` instead.
+*/
 var CustomerAccountAuthenticationError = class extends CustomerAccountApiError {
 	constructor(message = "Customer Account API access token is required") {
 		super(message);
 		this.name = "CustomerAccountAuthenticationError";
 	}
 };
+/**
+* Thrown when a `CustomerAccountClient.graphql()` request exceeds
+* `defaultTimeoutInMs`. (OAuth token-request timeouts throw the base
+* {@link CustomerAccountApiError} instead.) Extends
+* {@link CustomerAccountApiError}.
+*/
 var CustomerAccountTimeoutError = class extends CustomerAccountApiError {
+	/** The timeout threshold (in milliseconds) that was exceeded. */
 	timeoutInMs;
 	constructor(timeoutInMs) {
 		super(`Customer Account API request timed out after ${timeoutInMs}ms`);
@@ -25,7 +55,23 @@ var CustomerAccountTimeoutError = class extends CustomerAccountApiError {
 		this.timeoutInMs = timeoutInMs;
 	}
 };
+/**
+* Thrown during the Customer Account OAuth authorization code exchange
+* or id_token validation in `handleOAuthCallback`. Refresh failures never
+* surface this error (they are caught internally and returned as
+* `undefined`). Extends `Error` directly, **not**
+* {@link CustomerAccountApiError}. A `catch` block for
+* `CustomerAccountApiError` will not catch this error.
+*
+* Use the `code` field for programmatic handling. Known codes:
+* `"missing_callback_params"`, `"state_mismatch"`,
+* `"token_exchange_rejected"`, `"token_exchange_failed"`,
+* `"invalid_token_response"`, `"nonce_mismatch"`, `"issuer_mismatch"`,
+* `"audience_mismatch"`, `"expired_id_token"`, `"invalid_id_token"`,
+* `"missing_pending_login"`.
+*/
 var CustomerAccountOAuthError = class extends Error {
+	/** Machine-readable error identifier for programmatic handling. */
 	code;
 	constructor(code, message, options) {
 		super(message, options?.cause ? { cause: options.cause } : void 0);

package/dist/customer-account/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/customer-account/errors.ts"],"sourcesContent":["export class CustomerAccountApiError extends Error {\n  readonly status?: number;\n  readonly requestId?: string;\n  readonly retryAfter?: string;\n\n  constructor(\n    message: string,\n    options?: { status?: number; requestId?: string; retryAfter?: string; cause?: unknown },\n  ) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"CustomerAccountApiError\";\n    this.status = options?.status;\n    this.requestId = options?.requestId;\n    this.retryAfter = options?.retryAfter;\n  }\n}\n\nexport class CustomerAccountAuthenticationError extends CustomerAccountApiError {\n  constructor(message = \"Customer Account API access token is required\") {\n    super(message);\n    this.name = \"CustomerAccountAuthenticationError\";\n  }\n}\n\nexport class CustomerAccountTimeoutError extends CustomerAccountApiError {\n  readonly timeoutInMs: number;\n\n  constructor(timeoutInMs: number) {\n    super(`Customer Account API request timed out after ${timeoutInMs}ms`);\n    this.name = \"CustomerAccountTimeoutError\";\n    this.timeoutInMs = timeoutInMs;\n  }\n}\n\nexport class CustomerAccountOAuthError extends Error {\n  readonly code: string;\n\n  constructor(code: string, message: string, options?: { cause?: unknown }) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"CustomerAccountOAuthError\";\n    this.code = code;\n  }\n}\n"],"mappings":";AAAA,IAAa,0BAAb,cAA6C,MAAM;CACjD,AAAS;CACT,AAAS;CACT,AAAS;CAET,YACE,SACA,SACA;AACA,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,SAAS,SAAS;AACvB,OAAK,YAAY,SAAS;AAC1B,OAAK,aAAa,SAAS;;;AAI/B,IAAa,qCAAb,cAAwD,wBAAwB;CAC9E,YAAY,UAAU,iDAAiD;AACrE,QAAM,QAAQ;AACd,OAAK,OAAO;;;AAIhB,IAAa,8BAAb,cAAiD,wBAAwB;CACvE,AAAS;CAET,YAAY,aAAqB;AAC/B,QAAM,gDAAgD,YAAY,IAAI;AACtE,OAAK,OAAO;AACZ,OAAK,cAAc;;;AAIvB,IAAa,4BAAb,cAA+C,MAAM;CACnD,AAAS;CAET,YAAY,MAAc,SAAiB,SAA+B;AACxE,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,OAAO"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/customer-account/errors.ts"],"sourcesContent":["/**\n * Base error for Customer Account API failures. Thrown by\n * `CustomerAccountClient.graphql()` when the API responds with a non-OK\n * HTTP status, when the response body cannot be parsed as JSON, or when the\n * parsed response is missing `data`. Also thrown (without subclassing) for\n * OAuth token-request timeouts and network failures.\n *\n * Not all fields are populated on every instance. `status` is present\n * whenever an HTTP response was received. `requestId` is set when the\n * `x-request-id` response header exists. Both are absent on network\n * failures where no response arrived. `retryAfter` is populated only on\n * non-OK responses.\n */\nexport class CustomerAccountApiError extends Error {\n  /** HTTP status code from the API response. Present whenever an HTTP response was received (including parse failures), absent on network failures where no response arrived. */\n  readonly status?: number;\n  /** Value of the `x-request-id` response header, when the API returned one. Useful for Shopify support requests. */\n  readonly requestId?: string;\n  /** Value of the `retry-after` response header, when present. Indicates when the client should retry a rate-limited request. */\n  readonly retryAfter?: string;\n\n  constructor(\n    message: string,\n    options?: { status?: number; requestId?: string; retryAfter?: string; cause?: unknown },\n  ) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"CustomerAccountApiError\";\n    this.status = options?.status;\n    this.requestId = options?.requestId;\n    this.retryAfter = options?.retryAfter;\n  }\n}\n\n/**\n * Client-side pre-flight check. Thrown when the access token is missing,\n * empty, has leading or trailing whitespace, or contains ASCII control\n * characters (including DEL). Also thrown when the options object is\n * missing. A token the server rejects (e.g. expired or revoked) produces\n * the base {@link CustomerAccountApiError} with `status: 401` instead.\n */\nexport class CustomerAccountAuthenticationError extends CustomerAccountApiError {\n  constructor(message = \"Customer Account API access token is required\") {\n    super(message);\n    this.name = \"CustomerAccountAuthenticationError\";\n  }\n}\n\n/**\n * Thrown when a `CustomerAccountClient.graphql()` request exceeds\n * `defaultTimeoutInMs`. (OAuth token-request timeouts throw the base\n * {@link CustomerAccountApiError} instead.) Extends\n * {@link CustomerAccountApiError}.\n */\nexport class CustomerAccountTimeoutError extends CustomerAccountApiError {\n  /** The timeout threshold (in milliseconds) that was exceeded. */\n  readonly timeoutInMs: number;\n\n  constructor(timeoutInMs: number) {\n    super(`Customer Account API request timed out after ${timeoutInMs}ms`);\n    this.name = \"CustomerAccountTimeoutError\";\n    this.timeoutInMs = timeoutInMs;\n  }\n}\n\n/**\n * Thrown during the Customer Account OAuth authorization code exchange\n * or id_token validation in `handleOAuthCallback`. Refresh failures never\n * surface this error (they are caught internally and returned as\n * `undefined`). Extends `Error` directly, **not**\n * {@link CustomerAccountApiError}. A `catch` block for\n * `CustomerAccountApiError` will not catch this error.\n *\n * Use the `code` field for programmatic handling. Known codes:\n * `\"missing_callback_params\"`, `\"state_mismatch\"`,\n * `\"token_exchange_rejected\"`, `\"token_exchange_failed\"`,\n * `\"invalid_token_response\"`, `\"nonce_mismatch\"`, `\"issuer_mismatch\"`,\n * `\"audience_mismatch\"`, `\"expired_id_token\"`, `\"invalid_id_token\"`,\n * `\"missing_pending_login\"`.\n */\nexport class CustomerAccountOAuthError extends Error {\n  /** Machine-readable error identifier for programmatic handling. */\n  readonly code: string;\n\n  constructor(code: string, message: string, options?: { cause?: unknown }) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"CustomerAccountOAuthError\";\n    this.code = code;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,IAAa,0BAAb,cAA6C,MAAM;;CAEjD,AAAS;;CAET,AAAS;;CAET,AAAS;CAET,YACE,SACA,SACA;AACA,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,SAAS,SAAS;AACvB,OAAK,YAAY,SAAS;AAC1B,OAAK,aAAa,SAAS;;;;;;;;;;AAW/B,IAAa,qCAAb,cAAwD,wBAAwB;CAC9E,YAAY,UAAU,iDAAiD;AACrE,QAAM,QAAQ;AACd,OAAK,OAAO;;;;;;;;;AAUhB,IAAa,8BAAb,cAAiD,wBAAwB;;CAEvE,AAAS;CAET,YAAY,aAAqB;AAC/B,QAAM,gDAAgD,YAAY,IAAI;AACtE,OAAK,OAAO;AACZ,OAAK,cAAc;;;;;;;;;;;;;;;;;;AAmBvB,IAAa,4BAAb,cAA+C,MAAM;;CAEnD,AAAS;CAET,YAAY,MAAc,SAAiB,SAA+B;AACxE,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,OAAO"}

package/dist/customer-account/graphql.d.mts

@@ -9,20 +9,88 @@ type CustomerAccountTadaGql = initGraphQLTada<{
   scalars: CustomerAccountScalars;
 }>;
 declare const CUSTOMER_ACCOUNT_DOCUMENT: unique symbol;
+/**
+ * Branded document type returned by {@link gql}.
+ *
+ * Carries the GraphQL source as a type-level string literal so that
+ * `InferResult` and `InferVariables` can derive typed responses. The
+ * `[CUSTOMER_ACCOUNT_DOCUMENT]` brand is private and cannot be constructed
+ * externally — only `gql()` produces valid instances. Passing a plain object
+ * with a `source` property to `CustomerAccountClient.graphql()` will throw
+ * a `TypeError` at runtime.
+ */
 type CustomerAccountDocument<Result = unknown, Variables = never, Source extends string = string> = DocumentDecoration<Result, Variables> & {
   readonly [CUSTOMER_ACCOUNT_DOCUMENT]: true;
   readonly source: Source;
 };
+/** Widened alias for {@link CustomerAccountDocument}. Use as a constraint when accepting any Customer Account document. */
 type AnyCustomerAccountDocument = CustomerAccountDocument<unknown, never, string>;
+/** Extracts the source string literal type from a {@link CustomerAccountDocument}. */
 type SourceOf<Doc> = Doc extends {
   readonly source: infer Source extends string;
 } ? Source : never;
+/**
+ * Recursively concatenates the source strings of an array of fragment
+ * documents at the type level, joining each with a newline. An empty
+ * tuple produces `""`.
+ */
 type FragmentSources<Fragments extends readonly AnyCustomerAccountDocument[]> = Fragments extends readonly [] ? "" : Fragments extends readonly [infer Only extends AnyCustomerAccountDocument] ? SourceOf<Only> : Fragments extends readonly [infer First extends AnyCustomerAccountDocument, ...infer Rest extends readonly AnyCustomerAccountDocument[]] ? `${SourceOf<First>}\n${FragmentSources<Rest>}` : string;
+/**
+ * Combines an operation source with its {@link FragmentSources} at the type
+ * level. When `Fragments` is empty the result is just `Source`.
+ */
 type ComposedSource<Source extends string, Fragments extends readonly AnyCustomerAccountDocument[]> = FragmentSources<Fragments> extends "" ? Source : `${Source}\n${FragmentSources<Fragments>}`;
 type CustomerAccountGql = {
   <const Source extends string>(source: Source): CustomerAccountDocument<InferResult<Source>, InferVariables<Source>, Source>;
   <const Source extends string, const Fragments extends readonly AnyCustomerAccountDocument[], const DocumentSource extends string = ComposedSource<Source, Fragments>>(source: Source, fragments: Fragments): CustomerAccountDocument<InferResult<DocumentSource>, InferVariables<DocumentSource>, DocumentSource>;
 } & CustomerAccountTadaGql;
+/**
+ * Creates a branded {@link CustomerAccountDocument} from a GraphQL source
+ * string. This is a regular function call, not a tagged template literal.
+ *
+ * The returned document is branded with a private Symbol that
+ * `CustomerAccountClient.graphql()` validates at runtime — passing a plain
+ * object with a `source` property will throw a `TypeError`.
+ *
+ * An optional second argument accepts an array of fragment documents. Fragments
+ * are deduplicated by source string identity (`Set` check, not by fragment
+ * name) and appended to the operation source.
+ *
+ * @example
+ * ```ts
+ * import { gql } from "@shopify/hydrogen/customer-account";
+ *
+ * const CUSTOMER_QUERY = gql(`
+ *   query CustomerDetails {
+ *     customer {
+ *       firstName
+ *       lastName
+ *       emailAddress { emailAddress }
+ *     }
+ *   }
+ * `);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const ORDER_FIELDS = gql(`
+ *   fragment OrderFields on Order {
+ *     id
+ *     totalPrice { amount currencyCode }
+ *   }
+ * `);
+ *
+ * const ORDERS_QUERY = gql(`
+ *   query CustomerOrders {
+ *     customer {
+ *       orders(first: 10) {
+ *         nodes { ...OrderFields }
+ *       }
+ *     }
+ *   }
+ * `, [ORDER_FIELDS]);
+ * ```
+ */
 declare const gql: CustomerAccountGql;
 //#endregion
 export { AnyCustomerAccountDocument, ComposedSource, CustomerAccountDocument, FragmentSources, SourceOf, gql };

package/dist/customer-account/graphql.mjs

@@ -3,6 +3,53 @@ import { isObjectRecord } from "../core/utils/record.mjs";
 //#region src/customer-account/graphql.ts
 const CUSTOMER_ACCOUNT_DOCUMENT = Symbol("CustomerAccountDocument");
 const VARIABLE_DEFINITION_RE = /\$([_A-Za-z][_0-9A-Za-z]*)\s*:/g;
+/**
+* Creates a branded {@link CustomerAccountDocument} from a GraphQL source
+* string. This is a regular function call, not a tagged template literal.
+*
+* The returned document is branded with a private Symbol that
+* `CustomerAccountClient.graphql()` validates at runtime — passing a plain
+* object with a `source` property will throw a `TypeError`.
+*
+* An optional second argument accepts an array of fragment documents. Fragments
+* are deduplicated by source string identity (`Set` check, not by fragment
+* name) and appended to the operation source.
+*
+* @example
+* ```ts
+* import { gql } from "@shopify/hydrogen/customer-account";
+*
+* const CUSTOMER_QUERY = gql(`
+*   query CustomerDetails {
+*     customer {
+*       firstName
+*       lastName
+*       emailAddress { emailAddress }
+*     }
+*   }
+* `);
+* ```
+*
+* @example
+* ```ts
+* const ORDER_FIELDS = gql(`
+*   fragment OrderFields on Order {
+*     id
+*     totalPrice { amount currencyCode }
+*   }
+* `);
+*
+* const ORDERS_QUERY = gql(`
+*   query CustomerOrders {
+*     customer {
+*       orders(first: 10) {
+*         nodes { ...OrderFields }
+*       }
+*     }
+*   }
+* `, [ORDER_FIELDS]);
+* ```
+*/
 const gql = ((source, fragments) => {
 	let query = source;
 	if (fragments) {

package/dist/customer-account/graphql.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"graphql.mjs","names":[],"sources":["../../src/customer-account/graphql.ts"],"sourcesContent":["import type { DocumentDecoration, initGraphQLTada as InitGraphQLTada } from \"gql.tada\";\n\nimport { isObjectRecord } from \"../core/utils/record\";\nimport type { introspection } from \"../graphql/generated/customer-account-graphql-env\";\nimport type { CustomerAccountScalars } from \"../graphql/scalars\";\nimport type { InferResult, InferVariables } from \"./type-resolver\";\n\ntype CustomerAccountTadaGql = InitGraphQLTada<{\n  introspection: introspection;\n  scalars: CustomerAccountScalars;\n}>;\n\nconst CUSTOMER_ACCOUNT_DOCUMENT = Symbol(\"CustomerAccountDocument\");\nconst VARIABLE_DEFINITION_RE = /\\$([_A-Za-z][_0-9A-Za-z]*)\\s*:/g;\n\nexport type CustomerAccountDocument<\n  Result = unknown,\n  Variables = never,\n  Source extends string = string,\n> = DocumentDecoration<Result, Variables> & {\n  readonly [CUSTOMER_ACCOUNT_DOCUMENT]: true;\n  readonly source: Source;\n};\n\nexport type AnyCustomerAccountDocument = CustomerAccountDocument<unknown, never, string>;\n\nexport type SourceOf<Doc> = Doc extends { readonly source: infer Source extends string }\n  ? Source\n  : never;\n\nexport type FragmentSources<Fragments extends readonly AnyCustomerAccountDocument[]> =\n  Fragments extends readonly []\n    ? \"\"\n    : Fragments extends readonly [infer Only extends AnyCustomerAccountDocument]\n      ? SourceOf<Only>\n      : Fragments extends readonly [\n            infer First extends AnyCustomerAccountDocument,\n            ...infer Rest extends readonly AnyCustomerAccountDocument[],\n          ]\n        ? `${SourceOf<First>}\\n${FragmentSources<Rest>}`\n        : string;\n\nexport type ComposedSource<\n  Source extends string,\n  Fragments extends readonly AnyCustomerAccountDocument[],\n> = FragmentSources<Fragments> extends \"\" ? Source : `${Source}\\n${FragmentSources<Fragments>}`;\n\ntype CustomerAccountDocumentValue = AnyCustomerAccountDocument & {\n  readonly variableNames: ReadonlySet<string>;\n};\n\ntype CustomerAccountGql = {\n  <const Source extends string>(\n    source: Source,\n  ): CustomerAccountDocument<InferResult<Source>, InferVariables<Source>, Source>;\n  <\n    const Source extends string,\n    const Fragments extends readonly AnyCustomerAccountDocument[],\n    const DocumentSource extends string = ComposedSource<Source, Fragments>,\n  >(\n    source: Source,\n    fragments: Fragments,\n  ): CustomerAccountDocument<\n    InferResult<DocumentSource>,\n    InferVariables<DocumentSource>,\n    DocumentSource\n  >;\n} & CustomerAccountTadaGql;\n\n// oxlint-disable-next-line typescript-eslint/consistent-type-assertions -- gql.tada adds phantom helper properties to the function type that are not used at runtime.\nexport const gql = ((source: string, fragments?: readonly CustomerAccountDocument[]) => {\n  let query = source;\n\n  if (fragments) {\n    const seen = new Set<string>();\n    for (const fragment of fragments) {\n      assertCustomerAccountDocument(fragment);\n      if (!seen.has(fragment.source)) {\n        seen.add(fragment.source);\n        query += \"\\n\" + fragment.source;\n      }\n    }\n  }\n\n  const document = {\n    [CUSTOMER_ACCOUNT_DOCUMENT]: true,\n    source: query,\n    variableNames: getVariableNames(query),\n  } satisfies CustomerAccountDocumentValue;\n  return document;\n}) as unknown as CustomerAccountGql;\n\nexport function isCustomerAccountDocument(value: unknown): value is CustomerAccountDocumentValue {\n  if (!isObjectRecord(value)) return false;\n  return value[CUSTOMER_ACCOUNT_DOCUMENT] === true && typeof value.source === \"string\";\n}\n\nexport function assertCustomerAccountDocument(\n  value: unknown,\n): asserts value is CustomerAccountDocumentValue {\n  if (!isCustomerAccountDocument(value)) {\n    throw new TypeError(\"Expected a Customer Account API document returned by CAAPI.gql().\");\n  }\n}\n\nfunction getVariableNames(source: string): ReadonlySet<string> {\n  const names = new Set<string>();\n  for (const match of source.matchAll(VARIABLE_DEFINITION_RE)) {\n    names.add(match[1]);\n  }\n  return names;\n}\n"],"mappings":";;;AAYA,MAAM,4BAA4B,OAAO,0BAA0B;AACnE,MAAM,yBAAyB;AAyD/B,MAAa,QAAQ,QAAgB,cAAmD;CACtF,IAAI,QAAQ;AAEZ,KAAI,WAAW;EACb,MAAM,uBAAO,IAAI,KAAa;AAC9B,OAAK,MAAM,YAAY,WAAW;AAChC,iCAA8B,SAAS;AACvC,OAAI,CAAC,KAAK,IAAI,SAAS,OAAO,EAAE;AAC9B,SAAK,IAAI,SAAS,OAAO;AACzB,aAAS,OAAO,SAAS;;;;AAU/B,QAAO;GAJJ,4BAA4B;EAC7B,QAAQ;EACR,eAAe,iBAAiB,MAAM;EAEzB;;AAGjB,SAAgB,0BAA0B,OAAuD;AAC/F,KAAI,CAAC,eAAe,MAAM,CAAE,QAAO;AACnC,QAAO,MAAM,+BAA+B,QAAQ,OAAO,MAAM,WAAW;;AAG9E,SAAgB,8BACd,OAC+C;AAC/C,KAAI,CAAC,0BAA0B,MAAM,CACnC,OAAM,IAAI,UAAU,oEAAoE;;AAI5F,SAAS,iBAAiB,QAAqC;CAC7D,MAAM,wBAAQ,IAAI,KAAa;AAC/B,MAAK,MAAM,SAAS,OAAO,SAAS,uBAAuB,CACzD,OAAM,IAAI,MAAM,GAAG;AAErB,QAAO"}
+{"version":3,"file":"graphql.mjs","names":[],"sources":["../../src/customer-account/graphql.ts"],"sourcesContent":["import type { DocumentDecoration, initGraphQLTada as InitGraphQLTada } from \"gql.tada\";\n\nimport { isObjectRecord } from \"../core/utils/record\";\nimport type { introspection } from \"../graphql/generated/customer-account-graphql-env\";\nimport type { CustomerAccountScalars } from \"../graphql/scalars\";\nimport type { InferResult, InferVariables } from \"./type-resolver\";\n\ntype CustomerAccountTadaGql = InitGraphQLTada<{\n  introspection: introspection;\n  scalars: CustomerAccountScalars;\n}>;\n\nconst CUSTOMER_ACCOUNT_DOCUMENT = Symbol(\"CustomerAccountDocument\");\nconst VARIABLE_DEFINITION_RE = /\\$([_A-Za-z][_0-9A-Za-z]*)\\s*:/g;\n\n/**\n * Branded document type returned by {@link gql}.\n *\n * Carries the GraphQL source as a type-level string literal so that\n * `InferResult` and `InferVariables` can derive typed responses. The\n * `[CUSTOMER_ACCOUNT_DOCUMENT]` brand is private and cannot be constructed\n * externally — only `gql()` produces valid instances. Passing a plain object\n * with a `source` property to `CustomerAccountClient.graphql()` will throw\n * a `TypeError` at runtime.\n */\nexport type CustomerAccountDocument<\n  Result = unknown,\n  Variables = never,\n  Source extends string = string,\n> = DocumentDecoration<Result, Variables> & {\n  readonly [CUSTOMER_ACCOUNT_DOCUMENT]: true;\n  readonly source: Source;\n};\n\n/** Widened alias for {@link CustomerAccountDocument}. Use as a constraint when accepting any Customer Account document. */\nexport type AnyCustomerAccountDocument = CustomerAccountDocument<unknown, never, string>;\n\n/** Extracts the source string literal type from a {@link CustomerAccountDocument}. */\nexport type SourceOf<Doc> = Doc extends { readonly source: infer Source extends string }\n  ? Source\n  : never;\n\n/**\n * Recursively concatenates the source strings of an array of fragment\n * documents at the type level, joining each with a newline. An empty\n * tuple produces `\"\"`.\n */\nexport type FragmentSources<Fragments extends readonly AnyCustomerAccountDocument[]> =\n  Fragments extends readonly []\n    ? \"\"\n    : Fragments extends readonly [infer Only extends AnyCustomerAccountDocument]\n      ? SourceOf<Only>\n      : Fragments extends readonly [\n            infer First extends AnyCustomerAccountDocument,\n            ...infer Rest extends readonly AnyCustomerAccountDocument[],\n          ]\n        ? `${SourceOf<First>}\\n${FragmentSources<Rest>}`\n        : string;\n\n/**\n * Combines an operation source with its {@link FragmentSources} at the type\n * level. When `Fragments` is empty the result is just `Source`.\n */\nexport type ComposedSource<\n  Source extends string,\n  Fragments extends readonly AnyCustomerAccountDocument[],\n> = FragmentSources<Fragments> extends \"\" ? Source : `${Source}\\n${FragmentSources<Fragments>}`;\n\ntype CustomerAccountDocumentValue = AnyCustomerAccountDocument & {\n  readonly variableNames: ReadonlySet<string>;\n};\n\ntype CustomerAccountGql = {\n  <const Source extends string>(\n    source: Source,\n  ): CustomerAccountDocument<InferResult<Source>, InferVariables<Source>, Source>;\n  <\n    const Source extends string,\n    const Fragments extends readonly AnyCustomerAccountDocument[],\n    const DocumentSource extends string = ComposedSource<Source, Fragments>,\n  >(\n    source: Source,\n    fragments: Fragments,\n  ): CustomerAccountDocument<\n    InferResult<DocumentSource>,\n    InferVariables<DocumentSource>,\n    DocumentSource\n  >;\n} & CustomerAccountTadaGql;\n\n/**\n * Creates a branded {@link CustomerAccountDocument} from a GraphQL source\n * string. This is a regular function call, not a tagged template literal.\n *\n * The returned document is branded with a private Symbol that\n * `CustomerAccountClient.graphql()` validates at runtime — passing a plain\n * object with a `source` property will throw a `TypeError`.\n *\n * An optional second argument accepts an array of fragment documents. Fragments\n * are deduplicated by source string identity (`Set` check, not by fragment\n * name) and appended to the operation source.\n *\n * @example\n * ```ts\n * import { gql } from \"@shopify/hydrogen/customer-account\";\n *\n * const CUSTOMER_QUERY = gql(`\n *   query CustomerDetails {\n *     customer {\n *       firstName\n *       lastName\n *       emailAddress { emailAddress }\n *     }\n *   }\n * `);\n * ```\n *\n * @example\n * ```ts\n * const ORDER_FIELDS = gql(`\n *   fragment OrderFields on Order {\n *     id\n *     totalPrice { amount currencyCode }\n *   }\n * `);\n *\n * const ORDERS_QUERY = gql(`\n *   query CustomerOrders {\n *     customer {\n *       orders(first: 10) {\n *         nodes { ...OrderFields }\n *       }\n *     }\n *   }\n * `, [ORDER_FIELDS]);\n * ```\n */\n// oxlint-disable-next-line typescript-eslint/consistent-type-assertions -- gql.tada adds phantom helper properties to the function type that are not used at runtime.\nexport const gql = ((source: string, fragments?: readonly CustomerAccountDocument[]) => {\n  let query = source;\n\n  if (fragments) {\n    const seen = new Set<string>();\n    for (const fragment of fragments) {\n      assertCustomerAccountDocument(fragment);\n      if (!seen.has(fragment.source)) {\n        seen.add(fragment.source);\n        query += \"\\n\" + fragment.source;\n      }\n    }\n  }\n\n  const document = {\n    [CUSTOMER_ACCOUNT_DOCUMENT]: true,\n    source: query,\n    variableNames: getVariableNames(query),\n  } satisfies CustomerAccountDocumentValue;\n  return document;\n}) as unknown as CustomerAccountGql;\n\nexport function isCustomerAccountDocument(value: unknown): value is CustomerAccountDocumentValue {\n  if (!isObjectRecord(value)) return false;\n  return value[CUSTOMER_ACCOUNT_DOCUMENT] === true && typeof value.source === \"string\";\n}\n\nexport function assertCustomerAccountDocument(\n  value: unknown,\n): asserts value is CustomerAccountDocumentValue {\n  if (!isCustomerAccountDocument(value)) {\n    throw new TypeError(\"Expected a Customer Account API document returned by CAAPI.gql().\");\n  }\n}\n\nfunction getVariableNames(source: string): ReadonlySet<string> {\n  const names = new Set<string>();\n  for (const match of source.matchAll(VARIABLE_DEFINITION_RE)) {\n    names.add(match[1]);\n  }\n  return names;\n}\n"],"mappings":";;;AAYA,MAAM,4BAA4B,OAAO,0BAA0B;AACnE,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6H/B,MAAa,QAAQ,QAAgB,cAAmD;CACtF,IAAI,QAAQ;AAEZ,KAAI,WAAW;EACb,MAAM,uBAAO,IAAI,KAAa;AAC9B,OAAK,MAAM,YAAY,WAAW;AAChC,iCAA8B,SAAS;AACvC,OAAI,CAAC,KAAK,IAAI,SAAS,OAAO,EAAE;AAC9B,SAAK,IAAI,SAAS,OAAO;AACzB,aAAS,OAAO,SAAS;;;;AAU/B,QAAO;GAJJ,4BAA4B;EAC7B,QAAQ;EACR,eAAe,iBAAiB,MAAM;EAEzB;;AAGjB,SAAgB,0BAA0B,OAAuD;AAC/F,KAAI,CAAC,eAAe,MAAM,CAAE,QAAO;AACnC,QAAO,MAAM,+BAA+B,QAAQ,OAAO,MAAM,WAAW;;AAG9E,SAAgB,8BACd,OAC+C;AAC/C,KAAI,CAAC,0BAA0B,MAAM,CACnC,OAAM,IAAI,UAAU,oEAAoE;;AAI5F,SAAS,iBAAiB,QAAqC;CAC7D,MAAM,wBAAQ,IAAI,KAAa;AAC/B,MAAK,MAAM,SAAS,OAAO,SAAS,uBAAuB,CACzD,OAAM,IAAI,MAAM,GAAG;AAErB,QAAO"}

package/dist/customer-account/session.d.mts

@@ -3,11 +3,16 @@ import { CallableRouteHandler, ShopifyRouteErrorResult, ShopifyRouteHandlerConte
 import { CartBuyerIdentitySyncSource } from "../core/cart/buyer-identity-sync.mjs";
 
 //#region src/customer-account/session.d.ts
+/** OAuth callback route path: `"/account/authorize"`. */
 declare const CUSTOMER_ACCOUNT_AUTHORIZE_PATH: "/account/authorize";
+/** Login route path: `"/account/login"`. */
 declare const CUSTOMER_ACCOUNT_LOGIN_PATH: "/account/login";
+/** Logout route path: `"/account/logout"`. */
 declare const CUSTOMER_ACCOUNT_LOGOUT_PATH: "/account/logout";
+/** Token refresh route path: `"/account/refresh"`. */
 declare const CUSTOMER_ACCOUNT_REFRESH_PATH: "/account/refresh";
 declare const CUSTOMER_SESSION_INTERNAL_BRAND: unique symbol;
+/** A value that is either `T` or a `Promise<T>`, used as the return type of session manager methods. */
 type Awaitable<T> = T | Promise<T>;
 /** Read-only Customer Account session storage for UI state and strict access-token reads. */
 type ReadonlyCustomerSessionManager = {
@@ -15,50 +20,117 @@ type ReadonlyCustomerSessionManager = {
 };
 /** Writable Customer Account session storage for OAuth, refresh, and logout response boundaries. */
 type WritableCustomerSessionManager = ShopifyRouteSessionManager;
+/** Options for {@link createCustomerSession}. */
 type CreateCustomerSessionOptions = {
-  shopId: string;
+  /** Numeric Shopify shop ID as a string (digits only, e.g. `"12345"`). Validated against `/^\d+$/`. */shopId: string; /** Customer Account API OAuth client ID. Must be a non-empty string. */
   customerAccountApiClientId: string;
-  customerAccountApiUrl?: string;
-  fetch?: typeof globalThis.fetch;
+  /**
+   * Overrides the default `https://shopify.com/authentication/{shopId}` base URL
+   * for OAuth endpoints (authorize, token, logout). Also used as the expected
+   * `iss` claim when validating id_tokens — pointing this at a proxy causes
+   * `issuer_mismatch` unless the proxy preserves the original issuer. Must use
+   * HTTPS; validated at construction.
+   */
+  customerAccountApiUrl?: string; /** Custom fetch implementation. Falls back to `globalThis.fetch` when omitted. */
+  fetch?: typeof globalThis.fetch; /** Timeout for OAuth token requests in milliseconds. Defaults to 30 000 ms. */
   defaultTimeoutInMs?: number;
 };
+/** Options for {@link CustomerSession.prepareLoginUrl}. */
 type PrepareLoginUrlOptions = {
+  /**
+   * Overrides the origin used for the OAuth redirect URI. Must be HTTPS —
+   * unlike `createCustomerAccountClient`, `http://localhost` is not accepted.
+   * Falls back to the session manager's `getSessionOrigin()`.
+   */
   origin?: string;
-  returnTo?: string;
-  locale?: string;
-  countryCode?: string;
-  loginHint?: string;
-  loginHintMode?: string;
+  /**
+   * Same-origin path or URL to redirect back to after login, such as `"/account/orders"`.
+   * Cross-origin values and values over 2 048 bytes fall back to the default, `"/account"`.
+   */
+  returnTo?: string; /** Passed as the `locale` search param on the Shopify OAuth authorize URL. */
+  locale?: string; /** Passed as the `region_country` search param on the Shopify OAuth authorize URL. */
+  countryCode?: string; /** Email address to pre-fill on the login screen. Passed as `login_hint`. */
+  loginHint?: string; /** When set to `"submit"` (and `loginHint` is provided), skips the login form and sends the one-time code immediately. Passed as `login_hint_mode`. */
+  loginHintMode?: string; /** Passed as the `acr_values` search param for authentication context class. */
   acrValues?: string;
 };
+/**
+ * Origin override accepted by {@link CustomerSession.getOrRefreshAccessToken}
+ * and {@link CustomerSession.logout}. Falls back to the session manager's
+ * `getSessionOrigin()`.
+ */
 type RequestOriginOptions = {
-  origin?: string;
+  /** HTTPS origin string. */origin?: string;
 };
+/** Options for {@link CustomerSession.logout}. */
 type LogoutOptions = RequestOriginOptions & {
+  /**
+   * URL to redirect to after Shopify's IdP logout completes.
+   * Resolved as an absolute same-origin URL. Defaults to `"/"`.
+   */
   postLogoutRedirectUri?: string;
 };
+/**
+ * Core session interface returned by {@link createCustomerSession}. Server-only.
+ * All methods require a session manager and request context.
+ */
 type CustomerSession = {
   /**
-   * Read-only signed-in check for UI state. Returns true for a usable access token
-   * or a refresh token that can attempt to restore one later. Not an authorization
-   * check for private Customer Account data.
+   * Read-only signed-in check for UI state. Returns `true` when a usable access
+   * token OR a refresh token exists. Does not attempt a refresh. Use for
+   * conditional UI rendering, not for authorizing access to Customer Account data.
+   */
+  isLoggedIn(sessionManager: ReadonlyCustomerSessionManager, requestContext: ShopifyRequestContext): Promise<boolean>;
+  /**
+   * Returns only a currently usable access token, or `undefined` when the token
+   * is missing or expired. Never refreshes and never writes session state.
    */
-  isLoggedIn(sessionManager: ReadonlyCustomerSessionManager, requestContext: ShopifyRequestContext): Promise<boolean>; /** Returns only a currently usable access token. Does not refresh or mutate session state. */
   getAccessToken(sessionManager: ReadonlyCustomerSessionManager, requestContext: ShopifyRequestContext): Promise<string | undefined>;
   /**
-   * Returns a usable access token, writing updated session state through the
-   * supplied writable session manager when no usable access token is stored. Use
-   * only where the eventual response commits the session manager.
+   * Returns a usable access token, refreshing from Shopify's token endpoint and
+   * writing updated tokens through the writable session manager when needed.
+   * Returns `undefined` when no refresh token exists (unauthenticated) or when
+   * the refresh fails transiently (the session is preserved for retry). A
+   * 400/401 from the token endpoint clears stored tokens. Never throws for
+   * refresh failures. Concurrent refresh requests for the same origin+token
+   * combination are deduplicated per `createCustomerSession` instance. Use only
+   * where the eventual response commits the session manager.
    */
   getOrRefreshAccessToken(sessionManager: WritableCustomerSessionManager, requestContext: ShopifyRequestContext, options?: RequestOriginOptions): Promise<string | undefined>;
+  /**
+   * Builds a Shopify OAuth authorize URL with PKCE (S256). Stores pending login
+   * state (state, nonce, code verifier, returnTo, origin) in the session. Pending
+   * login state expires after 10 minutes. Returns the full authorize URL string.
+   */
   prepareLoginUrl(sessionManager: WritableCustomerSessionManager, requestContext: ShopifyRequestContext, options: PrepareLoginUrlOptions): Promise<string>;
+  /**
+   * Completes the OAuth authorization code exchange. Validates `state`, exchanges
+   * the code for tokens, validates the `id_token` claims (nonce, issuer, audience,
+   * expiry), and stores tokens in the session. Returns the `returnTo` path. Clears
+   * pending login state on failure.
+   *
+   * @throws {CustomerAccountOAuthError} On validation failures (`missing_callback_params`,
+   *   `state_mismatch`, `missing_pending_login`, `token_exchange_rejected`,
+   *   `token_exchange_failed`, `invalid_token_response`, or id_token claim mismatches).
+   * @throws {CustomerAccountApiError} On token-request timeout.
+   */
   handleOAuthCallback(sessionManager: WritableCustomerSessionManager, requestContext: ShopifyRequestContext, request: Request): Promise<string>;
+  /**
+   * Clears session tokens. When an `id_token` exists, returns the Shopify IdP
+   * logout URL (with `id_token_hint` and `post_logout_redirect_uri`). When no
+   * `id_token` is stored, returns the `postLogoutRedirectUri` directly (local-only
+   * logout, no IdP round-trip).
+   */
   logout(sessionManager: WritableCustomerSessionManager, requestContext: ShopifyRequestContext, options?: LogoutOptions): Promise<string>;
 };
+/**
+ * Route handler objects returned by {@link createCustomerAccountServerHandlers}.
+ * Register these with `handleShopifyRoutes` to serve the Customer Account OAuth flow.
+ */
 type CustomerAccountServerHandlers<TContext extends CustomerAccountRouteHandlerContext = CustomerAccountRouteHandlerContext> = {
-  authorize: CallableRouteHandler<TContext, CustomerAccountRouteResult, typeof CUSTOMER_ACCOUNT_AUTHORIZE_PATH, "GET">;
-  login: CallableRouteHandler<TContext, CustomerAccountRouteResult, typeof CUSTOMER_ACCOUNT_LOGIN_PATH, "GET">;
-  logout: CallableRouteHandler<TContext, CustomerAccountRouteResult, typeof CUSTOMER_ACCOUNT_LOGOUT_PATH, "POST">;
+  /** GET handler for the OAuth callback path (`/account/authorize`). */authorize: CallableRouteHandler<TContext, CustomerAccountRouteResult, typeof CUSTOMER_ACCOUNT_AUTHORIZE_PATH, "GET">; /** GET handler that redirects to Shopify OAuth (`/account/login`). */
+  login: CallableRouteHandler<TContext, CustomerAccountRouteResult, typeof CUSTOMER_ACCOUNT_LOGIN_PATH, "GET">; /** POST handler for logout (`/account/logout`). Requires a same-origin POST for CSRF protection. */
+  logout: CallableRouteHandler<TContext, CustomerAccountRouteResult, typeof CUSTOMER_ACCOUNT_LOGOUT_PATH, "POST">; /** GET handler that refreshes the access token (`/account/refresh`). */
   refresh: CallableRouteHandler<TContext, CustomerAccountRouteResult, typeof CUSTOMER_ACCOUNT_REFRESH_PATH, "GET">;
 };
 /** Customer Account handlers that also synchronize cart buyer identity, so their context requires `storefrontClient`. */
@@ -67,12 +139,13 @@ type CustomerSessionWithInternals = CustomerSession & {
   readonly [CUSTOMER_SESSION_INTERNAL_BRAND]: true;
 };
 type CreateCustomerAccountServerHandlersBaseOptions<TCustomerSession extends CustomerSession = CustomerSession> = {
-  customerSession: TCustomerSession;
-  defaultPostLoginRedirectPathname?: string;
-  loginFailedRedirectPath?: string;
-  origin?: string | ((request: Request) => string);
+  /** The session object returned by {@link createCustomerSession}. */customerSession: TCustomerSession; /** Path to redirect to after a successful login when `return_to` is missing or cross-origin. Defaults to `"/"`. */
+  defaultPostLoginRedirectPathname?: string; /** Same-origin path to redirect to when the OAuth callback throws a `CustomerAccountOAuthError` (other errors propagate). Defaults to `"/account?login=failed"`. Cross-origin values fall back to `"/account"`. */
+  loginFailedRedirectPath?: string; /** Static origin string, or a function that resolves the origin per request for dynamic multi-origin setups. */
+  origin?: string | ((request: Request) => string); /** URL to redirect to after logout. Defaults to `"/"`. */
   postLogoutRedirectUri?: string;
 };
+/** Options for {@link createCustomerAccountServerHandlers}. */
 type CreateCustomerAccountServerHandlersOptions = (CreateCustomerAccountServerHandlersBaseOptions & {
   cartServerHandlers?: undefined;
 }) | (CreateCustomerAccountServerHandlersBaseOptions<CustomerSessionWithInternals> & {
@@ -95,6 +168,24 @@ type CustomerAccountRouteHandlerContext = {
 type CustomerAccountServerHandlersForOptions<TOptions> = TOptions extends {
   cartServerHandlers: CartBuyerIdentitySyncSource;
 } ? CustomerAccountServerHandlersWithCartSync : CustomerAccountServerHandlers;
+/**
+ * Creates a {@link CustomerSession} that manages the Shopify Customer Account
+ * OAuth flow (PKCE, token exchange, refresh, logout). Server-only: throws in a
+ * browser context. Validates `shopId`, `customerAccountApiClientId`,
+ * `customerAccountApiUrl` (HTTPS), and timeout at construction.
+ *
+ * @example
+ * ```ts
+ * import { createCustomerSession } from '@shopify/hydrogen/customer-account';
+ *
+ * const customerSession = createCustomerSession({
+ *   shopId: env.SHOP_ID,
+ *   customerAccountApiClientId: env.CUSTOMER_ACCOUNT_API_CLIENT_ID,
+ * });
+ * ```
+ *
+ * @throws {Error} When called in a browser context, when an option fails validation, or when no `fetch` is available.
+ */
 declare function createCustomerSession({
   shopId,
   customerAccountApiClientId,

package/dist/customer-account/session.mjs

@@ -1,15 +1,19 @@
 import { getLogger } from "../core/logging/logging.mjs";
+import { CUSTOMER_ACCOUNT_PATHS, getSameOriginPath } from "../core/url.mjs";
 import { DEFAULT_TIMEOUT_IN_MS } from "../core/constants.mjs";
-import { CUSTOMER_ACCOUNT_PATHS } from "../core/url.mjs";
 import { createCallableRouteHandler } from "../core/request-routing/registered-routes.mjs";
 import { getCartBuyerIdentitySync } from "../core/cart/buyer-identity-sync.mjs";
 import { CustomerAccountApiError, CustomerAccountOAuthError } from "./errors.mjs";
 
 //#region src/customer-account/session.ts
 const log = getLogger("customer-account");
+/** OAuth callback route path: `"/account/authorize"`. */
 const CUSTOMER_ACCOUNT_AUTHORIZE_PATH = CUSTOMER_ACCOUNT_PATHS.authorize;
+/** Login route path: `"/account/login"`. */
 const CUSTOMER_ACCOUNT_LOGIN_PATH = CUSTOMER_ACCOUNT_PATHS.login;
+/** Logout route path: `"/account/logout"`. */
 const CUSTOMER_ACCOUNT_LOGOUT_PATH = CUSTOMER_ACCOUNT_PATHS.logout;
+/** Token refresh route path: `"/account/refresh"`. */
 const CUSTOMER_ACCOUNT_REFRESH_PATH = CUSTOMER_ACCOUNT_PATHS.refresh;
 const CUSTOMER_ACCOUNT_SESSION_KEY = "customerAccount";
 const DEFAULT_LOGIN_RETURN_TO_PATH = "/account";
@@ -24,7 +28,7 @@ const AUTHORIZATION_CODE_GRANT_TYPE = "authorization_code";
 const REFRESH_TOKEN_GRANT_TYPE = "refresh_token";
 const CUSTOMER_ACCOUNT_SCOPE = "openid email customer-account-api:full";
 const CODE_CHALLENGE_METHOD = "S256";
-const USER_AGENT = `Hydrogen 2026.10.0-preview.2`;
+const USER_AGENT = `Hydrogen 2026.10.0-preview.4`;
 const EXPIRY_BUFFER_IN_SECONDS = 120;
 const PENDING_LOGIN_TTL_IN_MINUTES = 10;
 const SECONDS_PER_MINUTE = 60;
@@ -38,6 +42,24 @@ const CUSTOMER_SESSION_ACCESS_TOKEN_PERSONALIZATION_REASON = "customer-session-a
 const CUSTOMER_SESSION_MUTATION_PERSONALIZATION_REASON = "customer-session-mutation";
 const CUSTOMER_SESSION_INTERNAL_BRAND = Symbol("hydrogen.customerSessionInternal");
 const customerSessionInternals = /* @__PURE__ */ new WeakMap();
+/**
+* Creates a {@link CustomerSession} that manages the Shopify Customer Account
+* OAuth flow (PKCE, token exchange, refresh, logout). Server-only: throws in a
+* browser context. Validates `shopId`, `customerAccountApiClientId`,
+* `customerAccountApiUrl` (HTTPS), and timeout at construction.
+*
+* @example
+* ```ts
+* import { createCustomerSession } from '@shopify/hydrogen/customer-account';
+*
+* const customerSession = createCustomerSession({
+*   shopId: env.SHOP_ID,
+*   customerAccountApiClientId: env.CUSTOMER_ACCOUNT_API_CLIENT_ID,
+* });
+* ```
+*
+* @throws {Error} When called in a browser context, when an option fails validation, or when no `fetch` is available.
+*/
 function createCustomerSession({ shopId, customerAccountApiClientId, customerAccountApiUrl, fetch: customFetch, defaultTimeoutInMs = DEFAULT_TIMEOUT_IN_MS }) {
 	if (typeof document !== "undefined") throw new Error("Customer Account OAuth sessions cannot be used in a browser context. Use this helper from server or edge routes only.");
 	validateShopId(shopId);
@@ -655,16 +677,9 @@ function setOptionalLoginParams(loginUrl, options) {
 	if (options.loginHintMode) loginUrl.searchParams.set("login_hint_mode", options.loginHintMode);
 }
 function sanitizeReturnTo(returnTo, origin, fallbackReturnTo = DEFAULT_LOGIN_RETURN_TO_PATH) {
-	if (!returnTo) return fallbackReturnTo;
-	try {
-		const url = new URL(returnTo, origin);
-		if (url.origin !== origin) return fallbackReturnTo;
-		const sanitizedReturnTo = `${url.pathname}${url.search}${url.hash}`;
-		if (new TextEncoder().encode(sanitizedReturnTo).byteLength > MAX_RETURN_TO_LENGTH_IN_BYTES) return fallbackReturnTo;
-		return sanitizedReturnTo;
-	} catch {
-		return fallbackReturnTo;
-	}
+	const path = getSameOriginPath(returnTo, origin);
+	if (!path || new TextEncoder().encode(path).byteLength > MAX_RETURN_TO_LENGTH_IN_BYTES) return fallbackReturnTo;
+	return path;
 }
 function absoluteSameOriginUrl(url, origin) {
 	const parsedUrl = new URL(url, origin);