@vtex/faststore 0.0.8 → 0.0.11

package/dist/sdk/saved-cards/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","names":[],"sources":["../../../src/sdk/saved-cards/operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Saved-card GraphQL operations: the account's writes against the shopper's saved cards.\n *\n * Authored with the serializable `gql` tag and excluded from the codegen `documents` glob (see\n * `codegen.ts`), like the identity operations: the pluck would otherwise duplicate these\n * hand-written types in `sdk/generated/`.\n */\n\n/** A single domain error returned by a saved-card write. */\nexport type SavedCardUserError = Readonly<{ code: string; message: string }>;\n\n/** The account's list of saved cards, as `customerSavedCards` reads it. */\nexport type CustomerSavedCardsEntity = Readonly<{\n  __typename?: 'CustomerSavedCards';\n  id: string;\n  cards: ReadonlyArray<{\n    __typename?: 'CustomerSavedCard';\n    id: string;\n    network: { __typename?: 'CardNetwork'; id: string; name: string };\n    lastDigits: string;\n    expiry: { __typename?: 'CardExpiry'; month: number; year: number } | null;\n    status: 'USABLE' | 'EXPIRED' | 'UNUSABLE';\n  }>;\n}>;\n\nexport type CustomerSavedCardRemoveMutation = {\n  customerSavedCardRemove: {\n    __typename?: 'CustomerSavedCardRemovePayload';\n    customerSavedCards: CustomerSavedCardsEntity | null;\n    userErrors: SavedCardUserError[];\n  };\n};\n\nexport type CustomerSavedCardRemoveMutationVariables = {\n  id: string;\n};\n\n/**\n * Selects every field the read exposes: the payload replaces the cached list, so a partial\n * selection would leave the remaining cards holding stale fields.\n */\nexport const CUSTOMER_SAVED_CARD_REMOVE: TypedDocumentNode<\n  CustomerSavedCardRemoveMutation,\n  CustomerSavedCardRemoveMutationVariables\n> = gql`\n  mutation CustomerSavedCardRemove($id: ID!) {\n    customerSavedCardRemove(id: $id) {\n      __typename\n      customerSavedCards {\n        __typename\n        id\n        cards {\n          __typename\n          id\n          network {\n            __typename\n            id\n            name\n          }\n          lastDigits\n          expiry {\n            __typename\n            month\n            year\n          }\n          status\n        }\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`;\n"],"mappings":";;;;;;AA4CA,MAAa,6BAGT,GAAG"}

package/dist/sdk/saved-cards/use-saved-card-actions.d.ts

@@ -0,0 +1,26 @@
+import "../../core/dist/index.js";
+import { SavedCardUserError } from "./operations.js";
+//#region src/sdk/saved-cards/use-saved-card-actions.d.ts
+/**
+ * The `savedCard` action namespace — the account's writes against the shopper's saved cards
+ * (docs/storefront-core/adr-0010-actions-own-the-write-side.md).
+ *
+ * Every write is pessimistic: the caller awaits the server, and the returned `CustomerSavedCards`
+ * replaces the cached list, so the removed row leaves every subscriber with no refetch. A failure
+ * leaves the cache as it was.
+ *
+ * The removal prompt cannot close while a removal is pending, and the browser client has no request
+ * timeout, so `remove` bounds its own request. Past the bound it aborts through the `AbortSignal` in
+ * `context.fetchOptions` (honored by `HttpLink`) and resolves `NETWORK_ERROR`. The mutation skips
+ * the cache, and `remove` writes only an answer that arrived inside the bound, so a late answer from a
+ * link that ignores the abort cannot change the list after the shopper was told it failed.
+ */
+export type SavedCardRemovePayload = Readonly<{
+  id: string;
+}>;
+export type SavedCardActions = Readonly<{
+  /** Removes one saved card. Resolves to the payload's `userErrors` (empty on success). */
+  remove: (payload: SavedCardRemovePayload) => Promise<readonly SavedCardUserError[]>;
+}>;
+//#endregion
+//# sourceMappingURL=use-saved-card-actions.d.ts.map

package/dist/sdk/saved-cards/use-saved-card-actions.js

@@ -0,0 +1,86 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { CUSTOMER_SAVED_CARD_REMOVE } from "./operations.js";
+import { useApolloClient, useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+import { CombinedGraphQLErrors } from "@apollo/client/errors";
+//#region src/sdk/saved-cards/use-saved-card-actions.ts
+const SAVED_CARD_REMOVE_TIMEOUT_MS = 45e3;
+var SavedCardRemoveTimeoutError = class extends Error {
+	constructor() {
+		super("Saved card removal timed out.");
+		this.name = "SavedCardRemoveTimeoutError";
+	}
+};
+const NETWORK_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to remove the card. Please try again."
+};
+const UNAUTHORIZED_ERROR = {
+	code: "UNAUTHORIZED",
+	message: "Your session has expired. Please sign in again."
+};
+/** An expired session needs sign-in, not a retry, so it keeps its own code. */
+function toSavedCardError(error) {
+	if (CombinedGraphQLErrors.is(error)) {
+		if (error.errors.some(({ extensions }) => extensions?.code === "UNAUTHORIZED")) return UNAUTHORIZED_ERROR;
+	}
+	return NETWORK_ERROR;
+}
+function useSavedCardActions() {
+	const client = useApolloClient();
+	const [removeMutation] = useMutation(CUSTOMER_SAVED_CARD_REMOVE);
+	const remove = useCallback(async ({ id }) => {
+		const controller = new AbortController();
+		let timer;
+		const timeout = new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				controller.abort();
+				reject(new SavedCardRemoveTimeoutError());
+			}, SAVED_CARD_REMOVE_TIMEOUT_MS);
+		});
+		try {
+			const result = await Promise.race([removeMutation({
+				variables: { id },
+				context: { fetchOptions: { signal: controller.signal } },
+				fetchPolicy: "no-cache"
+			}), timeout]);
+			if (result.data) client.cache.writeQuery({
+				id: "ROOT_MUTATION",
+				query: CUSTOMER_SAVED_CARD_REMOVE,
+				variables: { id },
+				data: result.data
+			});
+			const payload = result.data?.customerSavedCardRemove;
+			return payload ? payload.userErrors : [NETWORK_ERROR];
+		} catch (error) {
+			console.error("[savedCard.remove] customerSavedCardRemove failed", loggableErrorName(error));
+			return [toSavedCardError(error)];
+		} finally {
+			clearTimeout(timer);
+		}
+	}, [client, removeMutation]);
+	return useMemo(() => ({ remove }), [remove]);
+}
+defineActions({
+	namespace: "savedCard",
+	description: "Mutation-backed writes against the signed-in shopper's saved cards.",
+	provider: {
+		name: "SavedCardActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: { remove: {
+		description: "Remove one saved card (async strategy). The row stays until the server answers.",
+		payload: [{
+			name: "id",
+			type: "string"
+		}]
+	} },
+	use: useSavedCardActions
+});
+//#endregion
+export { SAVED_CARD_REMOVE_TIMEOUT_MS, useSavedCardActions };
+
+//# sourceMappingURL=use-saved-card-actions.js.map

package/dist/sdk/saved-cards/use-saved-card-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-saved-card-actions.js","names":[],"sources":["../../../src/sdk/saved-cards/use-saved-card-actions.ts"],"sourcesContent":["'use client';\n\nimport { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport { useApolloClient, 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 { CUSTOMER_SAVED_CARD_REMOVE, type SavedCardUserError } from './operations.js';\n\n/**\n * The `savedCard` action namespace — the account's writes against the shopper's saved cards\n * (docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * Every write is pessimistic: the caller awaits the server, and the returned `CustomerSavedCards`\n * replaces the cached list, so the removed row leaves every subscriber with no refetch. A failure\n * leaves the cache as it was.\n *\n * The removal prompt cannot close while a removal is pending, and the browser client has no request\n * timeout, so `remove` bounds its own request. Past the bound it aborts through the `AbortSignal` in\n * `context.fetchOptions` (honored by `HttpLink`) and resolves `NETWORK_ERROR`. The mutation skips\n * the cache, and `remove` writes only an answer that arrived inside the bound, so a late answer from a\n * link that ignores the abort cannot change the list after the shopper was told it failed.\n */\n\nexport type SavedCardRemovePayload = Readonly<{ id: string }>;\n\nexport type SavedCardActions = Readonly<{\n  /** Removes one saved card. Resolves to the payload's `userErrors` (empty on success). */\n  remove: (payload: SavedCardRemovePayload) => Promise<readonly SavedCardUserError[]>;\n}>;\n\n// Above the resolver's own upstream budget (10 s per call, up to four in series), so the bound fires\n// only on a genuine hang.\nexport const SAVED_CARD_REMOVE_TIMEOUT_MS = 45_000;\n\nclass SavedCardRemoveTimeoutError extends Error {\n  constructor() {\n    super('Saved card removal timed out.');\n    this.name = 'SavedCardRemoveTimeoutError';\n  }\n}\n\nconst NETWORK_ERROR: SavedCardUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to remove the card. Please try again.',\n};\n\nconst UNAUTHORIZED_ERROR: SavedCardUserError = {\n  code: 'UNAUTHORIZED',\n  message: 'Your session has expired. Please sign in again.',\n};\n\n/** An expired session needs sign-in, not a retry, so it keeps its own code. */\nfunction toSavedCardError(error: unknown): SavedCardUserError {\n  if (CombinedGraphQLErrors.is(error)) {\n    const unauthorized = error.errors.some(({ extensions }) => extensions?.code === 'UNAUTHORIZED');\n    if (unauthorized) return UNAUTHORIZED_ERROR;\n  }\n  return NETWORK_ERROR;\n}\n\nexport function useSavedCardActions(): SavedCardActions {\n  const client = useApolloClient();\n  const [removeMutation] = useMutation(CUSTOMER_SAVED_CARD_REMOVE);\n\n  const remove = useCallback<SavedCardActions['remove']>(\n    async ({ id }) => {\n      const controller = new AbortController();\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      const timeout = new Promise<never>((_, reject) => {\n        timer = setTimeout(() => {\n          controller.abort();\n          reject(new SavedCardRemoveTimeoutError());\n        }, SAVED_CARD_REMOVE_TIMEOUT_MS);\n      });\n\n      try {\n        const result = await Promise.race([\n          removeMutation({\n            variables: { id },\n            context: { fetchOptions: { signal: controller.signal } },\n            fetchPolicy: 'no-cache',\n          }),\n          timeout,\n        ]);\n        if (result.data) {\n          client.cache.writeQuery({\n            id: 'ROOT_MUTATION',\n            query: CUSTOMER_SAVED_CARD_REMOVE,\n            variables: { id },\n            data: result.data,\n          });\n        }\n        // A missing payload removed nothing, so it must never read as success.\n        const payload = result.data?.customerSavedCardRemove;\n        return payload ? payload.userErrors : [NETWORK_ERROR];\n      } catch (error) {\n        console.error('[savedCard.remove] customerSavedCardRemove failed', loggableErrorName(error));\n        return [toSavedCardError(error)];\n      } finally {\n        clearTimeout(timer);\n      }\n    },\n    [client, removeMutation],\n  );\n\n  return useMemo(() => ({ remove }), [remove]);\n}\n\n/**\n * Declares the `savedCard` action namespace. The catalog builder reads this call to emit\n * `actions.json`; at runtime `SavedCardActionProvider` calls `useSavedCardActions` directly.\n */\nexport const savedCardActions = defineActions({\n  namespace: 'savedCard',\n  description: \"Mutation-backed writes against the signed-in shopper's saved cards.\",\n  provider: { name: 'SavedCardActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    remove: {\n      description: 'Remove one saved card (async strategy). The row stays until the server answers.',\n      payload: [{ name: 'id', type: 'string' }],\n    },\n  },\n  use: useSavedCardActions,\n});\n"],"mappings":";;;;;;;;;AAiCA,MAAa,+BAA+B;AAE5C,IAAM,8BAAN,cAA0C,MAAM;CAC9C,cAAc;EACZ,MAAM,+BAA+B;EACrC,KAAK,OAAO;CACd;AACF;AAEA,MAAM,gBAAoC;CACxC,MAAM;CACN,SAAS;AACX;AAEA,MAAM,qBAAyC;CAC7C,MAAM;CACN,SAAS;AACX;;AAGA,SAAS,iBAAiB,OAAoC;CAC5D,IAAI,sBAAsB,GAAG,KAAK,GACX;MAAA,MAAM,OAAO,MAAM,EAAE,iBAAiB,YAAY,SAAS,cACjE,GAAG,OAAO;CAAA;CAE3B,OAAO;AACT;AAEA,SAAgB,sBAAwC;CACtD,MAAM,SAAS,gBAAgB;CAC/B,MAAM,CAAC,kBAAkB,YAAY,0BAA0B;CAE/D,MAAM,SAAS,YACb,OAAO,EAAE,SAAS;EAChB,MAAM,aAAa,IAAI,gBAAgB;EACvC,IAAI;EACJ,MAAM,UAAU,IAAI,SAAgB,GAAG,WAAW;GAChD,QAAQ,iBAAiB;IACvB,WAAW,MAAM;IACjB,OAAO,IAAI,4BAA4B,CAAC;GAC1C,GAAG,4BAA4B;EACjC,CAAC;EAED,IAAI;GACF,MAAM,SAAS,MAAM,QAAQ,KAAK,CAChC,eAAe;IACb,WAAW,EAAE,GAAG;IAChB,SAAS,EAAE,cAAc,EAAE,QAAQ,WAAW,OAAO,EAAE;IACvD,aAAa;GACf,CAAC,GACD,OACF,CAAC;GACD,IAAI,OAAO,MACT,OAAO,MAAM,WAAW;IACtB,IAAI;IACJ,OAAO;IACP,WAAW,EAAE,GAAG;IAChB,MAAM,OAAO;GACf,CAAC;GAGH,MAAM,UAAU,OAAO,MAAM;GAC7B,OAAO,UAAU,QAAQ,aAAa,CAAC,aAAa;EACtD,SAAS,OAAO;GACd,QAAQ,MAAM,qDAAqD,kBAAkB,KAAK,CAAC;GAC3F,OAAO,CAAC,iBAAiB,KAAK,CAAC;EACjC,UAAU;GACR,aAAa,KAAK;EACpB;CACF,GACA,CAAC,QAAQ,cAAc,CACzB;CAEA,OAAO,eAAe,EAAE,OAAO,IAAI,CAAC,MAAM,CAAC;AAC7C;AAMgC,cAAc;CAC5C,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAA2B,YAAY;CAAkC;CAC3F,SAAS,EACP,QAAQ;EACN,aAAa;EACb,SAAS,CAAC;GAAE,MAAM;GAAM,MAAM;EAAS,CAAC;CAC1C,EACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/seo/entity-landing.d.ts

@@ -0,0 +1,24 @@
+import { RouteMap } from "../navigation/types.js";
+//#region src/sdk/seo/entity-landing.d.ts
+export type EntityLandingLookupOptions = {
+  routeMap: RouteMap;
+};
+export type EntityLandingQuery = {
+  bindingId: string;
+  /** The listing's `CATALOG_ROUTE_ALTERNATES_QUERY` read, shared with its cluster lookup. */
+  load: () => Promise<{
+    data: unknown;
+    error?: unknown;
+  }>;
+};
+/** Resolves the logical path of the Entity Landing Page that claims a listing, or `null` when none does. */
+export type EntityLandingLookup = (query: EntityLandingQuery) => Promise<string | null>;
+/**
+ * The standard listings' claim lookup (#958). Claims come from the route map, keyed by the claimed entity's
+ * node ID, and match the `id` `catalogRoute` returns for the listing's path. A claimant the rendered binding
+ * does not serve leaves the listing its own canonical. A failed read never fails the page: the listing
+ * keeps its own canonical, and the cluster lookup that shares the read reports the failure.
+ */
+export declare function createEntityLandingLookup({ routeMap }: EntityLandingLookupOptions): EntityLandingLookup;
+//#endregion
+//# sourceMappingURL=entity-landing.d.ts.map

package/dist/sdk/seo/entity-landing.js

@@ -0,0 +1,30 @@
+import { servedPath } from "./search-landing.js";
+//#region src/sdk/seo/entity-landing.ts
+function routeNodeId(data) {
+	return data?.catalogRoute?.id;
+}
+/**
+* The standard listings' claim lookup (#958). Claims come from the route map, keyed by the claimed entity's
+* node ID, and match the `id` `catalogRoute` returns for the listing's path. A claimant the rendered binding
+* does not serve leaves the listing its own canonical. A failed read never fails the page: the listing
+* keeps its own canonical, and the cluster lookup that shares the read reports the failure.
+*/
+function createEntityLandingLookup({ routeMap }) {
+	const claimants = /* @__PURE__ */ new Map();
+	for (const entry of Object.values(routeMap)) if (entry.canonicalFor && !claimants.has(entry.canonicalFor)) claimants.set(entry.canonicalFor, entry);
+	return async function entityLandingPath({ bindingId, load }) {
+		if (claimants.size === 0) return null;
+		let id;
+		try {
+			id = routeNodeId((await load()).data);
+		} catch {
+			return null;
+		}
+		const claimant = typeof id === "string" ? claimants.get(id) : void 0;
+		return claimant ? servedPath(claimant, bindingId) : null;
+	};
+}
+//#endregion
+export { createEntityLandingLookup };
+
+//# sourceMappingURL=entity-landing.js.map

package/dist/sdk/seo/entity-landing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-landing.js","names":[],"sources":["../../../src/sdk/seo/entity-landing.ts"],"sourcesContent":["import type { RouteMap, RouteMapEntry } from '../navigation/types.js';\nimport { servedPath } from './search-landing.js';\n\nexport type EntityLandingLookupOptions = { routeMap: RouteMap };\n\nexport type EntityLandingQuery = {\n  bindingId: string;\n  /** The listing's `CATALOG_ROUTE_ALTERNATES_QUERY` read, shared with its cluster lookup. */\n  load: () => Promise<{ data: unknown; error?: unknown }>;\n};\n\n/** Resolves the logical path of the Entity Landing Page that claims a listing, or `null` when none does. */\nexport type EntityLandingLookup = (query: EntityLandingQuery) => Promise<string | null>;\n\nfunction routeNodeId(data: unknown): unknown {\n  return (data as { catalogRoute?: { id?: unknown } | null } | null)?.catalogRoute?.id;\n}\n\n/**\n * The standard listings' claim lookup (#958). Claims come from the route map, keyed by the claimed entity's\n * node ID, and match the `id` `catalogRoute` returns for the listing's path. A claimant the rendered binding\n * does not serve leaves the listing its own canonical. A failed read never fails the page: the listing\n * keeps its own canonical, and the cluster lookup that shares the read reports the failure.\n */\nexport function createEntityLandingLookup({ routeMap }: EntityLandingLookupOptions): EntityLandingLookup {\n  const claimants = new Map<string, RouteMapEntry>();\n  for (const entry of Object.values(routeMap)) {\n    if (entry.canonicalFor && !claimants.has(entry.canonicalFor)) claimants.set(entry.canonicalFor, entry);\n  }\n\n  return async function entityLandingPath({ bindingId, load }) {\n    if (claimants.size === 0) return null;\n    let id: unknown;\n    try {\n      id = routeNodeId((await load()).data);\n    } catch {\n      return null;\n    }\n    const claimant = typeof id === 'string' ? claimants.get(id) : undefined;\n    return claimant ? servedPath(claimant, bindingId) : null;\n  };\n}\n"],"mappings":";;AAcA,SAAS,YAAY,MAAwB;CAC3C,OAAQ,MAA4D,cAAc;AACpF;;;;;;;AAQA,SAAgB,0BAA0B,EAAE,YAA6D;CACvG,MAAM,4BAAY,IAAI,IAA2B;CACjD,KAAK,MAAM,SAAS,OAAO,OAAO,QAAQ,GACxC,IAAI,MAAM,gBAAgB,CAAC,UAAU,IAAI,MAAM,YAAY,GAAG,UAAU,IAAI,MAAM,cAAc,KAAK;CAGvG,OAAO,eAAe,kBAAkB,EAAE,WAAW,QAAQ;EAC3D,IAAI,UAAU,SAAS,GAAG,OAAO;EACjC,IAAI;EACJ,IAAI;GACF,KAAK,aAAa,MAAM,KAAK,EAAA,CAAG,IAAI;EACtC,QAAQ;GACN,OAAO;EACT;EACA,MAAM,WAAW,OAAO,OAAO,WAAW,UAAU,IAAI,EAAE,IAAI,KAAA;EAC9D,OAAO,WAAW,WAAW,UAAU,SAAS,IAAI;CACtD;AACF"}

package/dist/sdk/seo/page-alternates.d.ts

@@ -24,8 +24,9 @@ export type BuildPageAlternatesOptions = {
   buildUrl: (bindingId: string, logicalPath: string) => string;
 };
 /**
- * The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its result, and the
- * package tests validate it against the Storefront API schema.
+ * The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its variants, the
+ * entity landing lookup reads its `id`, and the package tests validate it against the Storefront API
+ * schema.
  */
 export declare const CATALOG_ROUTE_ALTERNATES_QUERY: import("@graphql-typed-document-node/core").TypedDocumentNode<CatalogRouteAlternatesQuery, {
   path: string;
@@ -36,9 +37,11 @@ export declare const CATALOG_ROUTE_ALTERNATES_QUERY: import("@graphql-typed-docu
  */
 export declare function buildPageAlternates({ bindingId, defaultBindingId, bindings, selfPath, clusterPaths, buildUrl }: BuildPageAlternatesOptions): PageAlternates;
 /**
- * The decoded logical path a route pattern names under these params:
- * `('/[slug]/p', { slug: 'caf%C3%A9' })` -> `'/café/p'`. Catch-alls join with `/`; empty -> `'/'`.
- * Empty, `.` and `..` values are dropped.
+ * The logical path a route pattern names under these params, which arrive decoded
+ * (`decodeRouteParams`): `('/[slug]/p', { slug: 'café' })` -> `'/café/p'`. Catch-alls join with `/`;
+ * empty -> `'/'`.
+ * Empty, `.` and `..` values are dropped. It never decodes: a caller must decode first, or an
+ * encoded dot segment (`%2E%2E`) stays an inert literal segment.
  */
 export declare function routeLogicalPath(route: string, params: RouteParams): string;
 /**

package/dist/sdk/seo/page-alternates.js

@@ -3,12 +3,14 @@ import { loggableErrorName } from "../../utils/loggable-error-name.js";
 import { CombinedGraphQLErrors } from "@apollo/client/errors";
 //#region src/sdk/seo/page-alternates.ts
 /**
-* The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its result, and the
-* package tests validate it against the Storefront API schema.
+* The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its variants, the
+* entity landing lookup reads its `id`, and the package tests validate it against the Storefront API
+* schema.
 */
 const CATALOG_ROUTE_ALTERNATES_QUERY = graphql(`
   query CatalogRouteAlternates($path: String!) {
     catalogRoute(input: { path: $path }) {
+      id
       variants {
         locale
         path
@@ -57,27 +59,22 @@ function buildPageAlternates({ bindingId, defaultBindingId, bindings, selfPath,
 		languages
 	};
 }
-function decodeSegment(segment) {
-	try {
-		return decodeURIComponent(segment);
-	} catch {
-		return segment;
-	}
-}
 /** `.` and `..` would make the URL a crawler resolves differ from the page that states it. */
 function isPathSegment(segment) {
 	return segment !== "" && segment !== "." && segment !== "..";
 }
 /**
-* The decoded logical path a route pattern names under these params:
-* `('/[slug]/p', { slug: 'caf%C3%A9' })` -> `'/café/p'`. Catch-alls join with `/`; empty -> `'/'`.
-* Empty, `.` and `..` values are dropped.
+* The logical path a route pattern names under these params, which arrive decoded
+* (`decodeRouteParams`): `('/[slug]/p', { slug: 'café' })` -> `'/café/p'`. Catch-alls join with `/`;
+* empty -> `'/'`.
+* Empty, `.` and `..` values are dropped. It never decodes: a caller must decode first, or an
+* encoded dot segment (`%2E%2E`) stays an inert literal segment.
 */
 function routeLogicalPath(route, params) {
 	return `/${route.split("/").filter(Boolean).flatMap((segment) => {
 		const dynamic = /^\[{1,2}(?:\.\.\.)?([^\]]+)\]{1,2}$/.exec(segment);
 		if (!dynamic) return [segment];
-		return [params[dynamic[1]] ?? []].flat().map(decodeSegment);
+		return [params[dynamic[1]] ?? []].flat();
 	}).filter(isPathSegment).join("/")}`;
 }
 function readVariants(data) {
@@ -127,6 +124,6 @@ async function catalogClusterPaths(bindings, load) {
 	}
 }
 //#endregion
-export { CATALOG_ROUTE_ALTERNATES_QUERY, buildPageAlternates, catalogClusterPaths, routeLogicalPath };
+export { CATALOG_ROUTE_ALTERNATES_QUERY, buildPageAlternates, catalogClusterPaths, encodePath, routeLogicalPath };
 
 //# sourceMappingURL=page-alternates.js.map

package/dist/sdk/seo/page-alternates.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-alternates.js","names":[],"sources":["../../../src/sdk/seo/page-alternates.ts"],"sourcesContent":["import { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { graphql } from '../generated/gql.js';\nimport type { CatalogRouteAlternatesQuery } from '../generated/graphql.js';\n\nexport type AlternateBinding = { bindingId: string; locale: string };\n\nexport type RouteVariant = NonNullable<CatalogRouteAlternatesQuery['catalogRoute']>['variants'][number];\n\n/** Structurally assignable to Next.js `Metadata['alternates']`. */\nexport type PageAlternates = {\n  canonical: string;\n  /** BCP 47 tag or `x-default` -> absolute URL. */\n  languages?: Record<string, string>;\n};\n\nexport type RouteParams = Readonly<Record<string, string | string[] | undefined>>;\n\nexport type BuildPageAlternatesOptions = {\n  bindingId: string;\n  defaultBindingId: string;\n  /** Every declared binding, in authoring order. */\n  bindings: readonly AlternateBinding[];\n  /** Decoded logical path of the request. */\n  selfPath: string;\n  /** Binding id -> decoded logical path, for the cluster members only. `null` means no cluster source. */\n  clusterPaths: Readonly<Record<string, string>> | null;\n  buildUrl: (bindingId: string, logicalPath: string) => string;\n};\n\n/**\n * The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its result, and the\n * package tests validate it against the Storefront API schema.\n */\nexport const CATALOG_ROUTE_ALTERNATES_QUERY = graphql(`\n  query CatalogRouteAlternates($path: String!) {\n    catalogRoute(input: { path: $path }) {\n      variants {\n        locale\n        path\n      }\n    }\n  }\n`);\n\n/** Encodes each segment and keeps `/` literal, so a decoded path is encoded exactly once. */\nfunction encodePath(path: string): string {\n  return path.split('/').map(encodeURIComponent).join('/');\n}\n\n/**\n * One binding per locale: `hreflang` maps a tag to a single URL. The default binding represents a\n * locale it declares; otherwise the first binding declaring it does.\n */\nfunction representatives(bindings: readonly AlternateBinding[], defaultBindingId: string): AlternateBinding[] {\n  const byLocale = new Map<string, AlternateBinding>();\n  for (const binding of bindings) {\n    const key = binding.locale.toLowerCase();\n    const current = byLocale.get(key);\n    if (!current || binding.bindingId === defaultBindingId) byLocale.set(key, binding);\n  }\n  return bindings.filter((binding) => byLocale.get(binding.locale.toLowerCase()) === binding);\n}\n\n/**\n * The canonical URL plus, when a reciprocal cluster exists, `languages`. A cluster needs two members\n * and must include the rendered binding: search engines ignore a set that does not reference itself.\n */\nexport function buildPageAlternates({\n  bindingId,\n  defaultBindingId,\n  bindings,\n  selfPath,\n  clusterPaths,\n  buildUrl,\n}: BuildPageAlternatesOptions): PageAlternates {\n  const url = (id: string, path: string) => buildUrl(id, encodePath(path));\n  const pathOf = (id: string) => (clusterPaths && Object.hasOwn(clusterPaths, id) ? clusterPaths[id] : undefined);\n  const canonical = url(bindingId, pathOf(bindingId) ?? selfPath);\n\n  const members = representatives(bindings, defaultBindingId).flatMap((binding) => {\n    const path = pathOf(binding.bindingId);\n    return path === undefined ? [] : [{ ...binding, href: url(binding.bindingId, path) }];\n  });\n  if (members.length < 2 || !members.some((member) => member.bindingId === bindingId)) return { canonical };\n\n  const languages: Record<string, string> = {};\n  for (const member of members) languages[member.locale] = member.href;\n  const defaultMember = members.find((member) => member.bindingId === defaultBindingId);\n  if (defaultMember) languages['x-default'] = defaultMember.href;\n  return { canonical, languages };\n}\n\nfunction decodeSegment(segment: string): string {\n  try {\n    return decodeURIComponent(segment);\n  } catch {\n    return segment;\n  }\n}\n\n/** `.` and `..` would make the URL a crawler resolves differ from the page that states it. */\nfunction isPathSegment(segment: string): boolean {\n  return segment !== '' && segment !== '.' && segment !== '..';\n}\n\n/**\n * The decoded logical path a route pattern names under these params:\n * `('/[slug]/p', { slug: 'caf%C3%A9' })` -> `'/café/p'`. Catch-alls join with `/`; empty -> `'/'`.\n * Empty, `.` and `..` values are dropped.\n */\nexport function routeLogicalPath(route: string, params: RouteParams): string {\n  const segments = route\n    .split('/')\n    .filter(Boolean)\n    .flatMap((segment) => {\n      const dynamic = /^\\[{1,2}(?:\\.\\.\\.)?([^\\]]+)\\]{1,2}$/.exec(segment);\n      if (!dynamic) return [segment];\n      return [params[dynamic[1] as string] ?? []].flat().map(decodeSegment);\n    })\n    .filter(isPathSegment);\n  return `/${segments.join('/')}`;\n}\n\nfunction readVariants(data: unknown): RouteVariant[] {\n  const variants = (data as { catalogRoute?: { variants?: unknown } | null } | null)?.catalogRoute?.variants;\n  if (!Array.isArray(variants)) return [];\n  return variants.filter(\n    (variant): variant is RouteVariant => typeof variant?.locale === 'string' && typeof variant?.path === 'string',\n  );\n}\n\n/** Binding id -> confirmed variant path, matching BCP 47 tags case-insensitively and nothing looser. */\nfunction variantPathsByBinding(\n  bindings: readonly AlternateBinding[],\n  variants: readonly RouteVariant[],\n): Record<string, string> {\n  const paths: Record<string, string> = {};\n  for (const binding of bindings) {\n    const locale = binding.locale.toLowerCase();\n    const variant = variants.find((candidate) => candidate.locale.toLowerCase() === locale);\n    if (variant) paths[binding.bindingId] = variant.path;\n  }\n  return paths;\n}\n\n/**\n * Why a lookup degraded, safe to log: the GraphQL error code, else the allow-listed error name. `null`\n * for `BAD_USER_INPUT`, which a path `catalogRoute` cannot parse (a slug with a dot) always answers.\n */\nfunction degradedReason(error: unknown): string | null {\n  if (!CombinedGraphQLErrors.is(error)) return loggableErrorName(error);\n  const codes = error.errors.map(({ extensions }) => extensions?.code);\n  if (codes.length > 0 && codes.every((candidate) => candidate === 'BAD_USER_INPUT')) return null;\n  const code = codes.find(\n    (candidate): candidate is string => typeof candidate === 'string' && candidate !== 'BAD_USER_INPUT',\n  );\n  return code ?? 'GRAPHQL_ERROR';\n}\n\nfunction warnDegraded(error: unknown): null {\n  const reason = degradedReason(error);\n  if (reason) console.warn('[seo.catalogClusterPaths] catalogRoute lookup degraded to no cluster', reason);\n  return null;\n}\n\n/**\n * Binding id -> variant path for the bindings whose locale a confirmed variant matches. Never\n * rejects: a thrown loader, an `error`, a missing or `null` `catalogRoute`, or no matching variant\n * all resolve to `null`, so a catalog lookup can never fail the page it describes. A thrown loader\n * or an `error` is logged by code or error name only, never with the path or the upstream message.\n */\nexport async function catalogClusterPaths(\n  bindings: readonly AlternateBinding[],\n  load: () => Promise<{ data: unknown; error?: unknown }>,\n): Promise<Record<string, string> | null> {\n  try {\n    const { data, error } = await load();\n    if (error) return warnDegraded(error);\n    const paths = variantPathsByBinding(bindings, readVariants(data));\n    return Object.keys(paths).length > 0 ? paths : null;\n  } catch (error) {\n    return warnDegraded(error);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"page-alternates.js","names":[],"sources":["../../../src/sdk/seo/page-alternates.ts"],"sourcesContent":["import { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { graphql } from '../generated/gql.js';\nimport type { CatalogRouteAlternatesQuery } from '../generated/graphql.js';\n\nexport type AlternateBinding = { bindingId: string; locale: string };\n\nexport type RouteVariant = NonNullable<CatalogRouteAlternatesQuery['catalogRoute']>['variants'][number];\n\n/** Structurally assignable to Next.js `Metadata['alternates']`. */\nexport type PageAlternates = {\n  canonical: string;\n  /** BCP 47 tag or `x-default` -> absolute URL. */\n  languages?: Record<string, string>;\n};\n\nexport type RouteParams = Readonly<Record<string, string | string[] | undefined>>;\n\nexport type BuildPageAlternatesOptions = {\n  bindingId: string;\n  defaultBindingId: string;\n  /** Every declared binding, in authoring order. */\n  bindings: readonly AlternateBinding[];\n  /** Decoded logical path of the request. */\n  selfPath: string;\n  /** Binding id -> decoded logical path, for the cluster members only. `null` means no cluster source. */\n  clusterPaths: Readonly<Record<string, string>> | null;\n  buildUrl: (bindingId: string, logicalPath: string) => string;\n};\n\n/**\n * The only GraphQL text the alternates feature owns. `catalogClusterPaths` reads its variants, the\n * entity landing lookup reads its `id`, and the package tests validate it against the Storefront API\n * schema.\n */\nexport const CATALOG_ROUTE_ALTERNATES_QUERY = graphql(`\n  query CatalogRouteAlternates($path: String!) {\n    catalogRoute(input: { path: $path }) {\n      id\n      variants {\n        locale\n        path\n      }\n    }\n  }\n`);\n\n/** Encodes each segment and keeps `/` literal, so a decoded path is encoded exactly once. */\nexport function encodePath(path: string): string {\n  return path.split('/').map(encodeURIComponent).join('/');\n}\n\n/**\n * One binding per locale: `hreflang` maps a tag to a single URL. The default binding represents a\n * locale it declares; otherwise the first binding declaring it does.\n */\nfunction representatives(bindings: readonly AlternateBinding[], defaultBindingId: string): AlternateBinding[] {\n  const byLocale = new Map<string, AlternateBinding>();\n  for (const binding of bindings) {\n    const key = binding.locale.toLowerCase();\n    const current = byLocale.get(key);\n    if (!current || binding.bindingId === defaultBindingId) byLocale.set(key, binding);\n  }\n  return bindings.filter((binding) => byLocale.get(binding.locale.toLowerCase()) === binding);\n}\n\n/**\n * The canonical URL plus, when a reciprocal cluster exists, `languages`. A cluster needs two members\n * and must include the rendered binding: search engines ignore a set that does not reference itself.\n */\nexport function buildPageAlternates({\n  bindingId,\n  defaultBindingId,\n  bindings,\n  selfPath,\n  clusterPaths,\n  buildUrl,\n}: BuildPageAlternatesOptions): PageAlternates {\n  const url = (id: string, path: string) => buildUrl(id, encodePath(path));\n  const pathOf = (id: string) => (clusterPaths && Object.hasOwn(clusterPaths, id) ? clusterPaths[id] : undefined);\n  const canonical = url(bindingId, pathOf(bindingId) ?? selfPath);\n\n  const members = representatives(bindings, defaultBindingId).flatMap((binding) => {\n    const path = pathOf(binding.bindingId);\n    return path === undefined ? [] : [{ ...binding, href: url(binding.bindingId, path) }];\n  });\n  if (members.length < 2 || !members.some((member) => member.bindingId === bindingId)) return { canonical };\n\n  const languages: Record<string, string> = {};\n  for (const member of members) languages[member.locale] = member.href;\n  const defaultMember = members.find((member) => member.bindingId === defaultBindingId);\n  if (defaultMember) languages['x-default'] = defaultMember.href;\n  return { canonical, languages };\n}\n\n/** `.` and `..` would make the URL a crawler resolves differ from the page that states it. */\nfunction isPathSegment(segment: string): boolean {\n  return segment !== '' && segment !== '.' && segment !== '..';\n}\n\n/**\n * The logical path a route pattern names under these params, which arrive decoded\n * (`decodeRouteParams`): `('/[slug]/p', { slug: 'café' })` -> `'/café/p'`. Catch-alls join with `/`;\n * empty -> `'/'`.\n * Empty, `.` and `..` values are dropped. It never decodes: a caller must decode first, or an\n * encoded dot segment (`%2E%2E`) stays an inert literal segment.\n */\nexport function routeLogicalPath(route: string, params: RouteParams): string {\n  const segments = route\n    .split('/')\n    .filter(Boolean)\n    .flatMap((segment) => {\n      const dynamic = /^\\[{1,2}(?:\\.\\.\\.)?([^\\]]+)\\]{1,2}$/.exec(segment);\n      if (!dynamic) return [segment];\n      return [params[dynamic[1] as string] ?? []].flat();\n    })\n    .filter(isPathSegment);\n  return `/${segments.join('/')}`;\n}\n\nfunction readVariants(data: unknown): RouteVariant[] {\n  const variants = (data as { catalogRoute?: { variants?: unknown } | null } | null)?.catalogRoute?.variants;\n  if (!Array.isArray(variants)) return [];\n  return variants.filter(\n    (variant): variant is RouteVariant => typeof variant?.locale === 'string' && typeof variant?.path === 'string',\n  );\n}\n\n/** Binding id -> confirmed variant path, matching BCP 47 tags case-insensitively and nothing looser. */\nfunction variantPathsByBinding(\n  bindings: readonly AlternateBinding[],\n  variants: readonly RouteVariant[],\n): Record<string, string> {\n  const paths: Record<string, string> = {};\n  for (const binding of bindings) {\n    const locale = binding.locale.toLowerCase();\n    const variant = variants.find((candidate) => candidate.locale.toLowerCase() === locale);\n    if (variant) paths[binding.bindingId] = variant.path;\n  }\n  return paths;\n}\n\n/**\n * Why a lookup degraded, safe to log: the GraphQL error code, else the allow-listed error name. `null`\n * for `BAD_USER_INPUT`, which a path `catalogRoute` cannot parse (a slug with a dot) always answers.\n */\nfunction degradedReason(error: unknown): string | null {\n  if (!CombinedGraphQLErrors.is(error)) return loggableErrorName(error);\n  const codes = error.errors.map(({ extensions }) => extensions?.code);\n  if (codes.length > 0 && codes.every((candidate) => candidate === 'BAD_USER_INPUT')) return null;\n  const code = codes.find(\n    (candidate): candidate is string => typeof candidate === 'string' && candidate !== 'BAD_USER_INPUT',\n  );\n  return code ?? 'GRAPHQL_ERROR';\n}\n\nfunction warnDegraded(error: unknown): null {\n  const reason = degradedReason(error);\n  if (reason) console.warn('[seo.catalogClusterPaths] catalogRoute lookup degraded to no cluster', reason);\n  return null;\n}\n\n/**\n * Binding id -> variant path for the bindings whose locale a confirmed variant matches. Never\n * rejects: a thrown loader, an `error`, a missing or `null` `catalogRoute`, or no matching variant\n * all resolve to `null`, so a catalog lookup can never fail the page it describes. A thrown loader\n * or an `error` is logged by code or error name only, never with the path or the upstream message.\n */\nexport async function catalogClusterPaths(\n  bindings: readonly AlternateBinding[],\n  load: () => Promise<{ data: unknown; error?: unknown }>,\n): Promise<Record<string, string> | null> {\n  try {\n    const { data, error } = await load();\n    if (error) return warnDegraded(error);\n    const paths = variantPathsByBinding(bindings, readVariants(data));\n    return Object.keys(paths).length > 0 ? paths : null;\n  } catch (error) {\n    return warnDegraded(error);\n  }\n}\n"],"mappings":"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"}

package/dist/sdk/seo/search-landing.d.ts

@@ -0,0 +1,42 @@
+import { RouteMap } from "../navigation/types.js";
+//#region src/sdk/seo/search-landing.d.ts
+/**
+ * The one search-term normalization (#957): NFD, combining diacritics stripped, trimmed, lower-cased,
+ * every whitespace run collapsed to one hyphen. No stop words. A CMS term entry's slug has this shape,
+ * so the singleton term map and the read by slug share this function.
+ */
+export declare function normalizeSearchTerm(term: string): string;
+/**
+ * One content item read by slug. Structurally the content runtime's `readContentItem`, which this module
+ * does not import: the server entry must not pull the content runtime into every page's graph.
+ */
+export type SearchLandingItemRead = (args: {
+  contentTypeId: string;
+  slug: string;
+  locale: string;
+}) => Promise<{
+  status: 'found' | 'not-found' | 'unavailable';
+}>;
+export type SearchLandingLookupOptions = {
+  routeMap: RouteMap;
+  /** Present when the store has page-level content types; without it, CMS term entries are never read. */
+  readContentItem?: SearchLandingItemRead;
+  now?: () => number;
+};
+export type SearchLandingQuery = {
+  bindingId: string;
+  locale: string;
+  /** The search page's `q` as Next.js hands it over. A repeated key reads its first value. */
+  query: string | string[] | undefined;
+};
+/** Resolves the logical path of the Search Landing Page for a query, or `null` when it has none. */
+export type SearchLandingLookup = (query: SearchLandingQuery) => Promise<string | null>;
+/**
+ * The search page's landing lookup. Singleton terms come from the route map, normalized once here, and a
+ * singleton wins its term. Any other term costs one content read by its normalized slug, unless the same
+ * term answered `not-found` less than a minute ago. `unavailable` is never cached and never fails the page:
+ * the search page keeps its own canonical.
+ */
+export declare function createSearchLandingLookup({ routeMap, readContentItem, now }: SearchLandingLookupOptions): SearchLandingLookup;
+//#endregion
+//# sourceMappingURL=search-landing.d.ts.map

package/dist/sdk/seo/search-landing.js

@@ -0,0 +1,85 @@
+import { routeLogicalPath } from "./page-alternates.js";
+//#region src/sdk/seo/search-landing.ts
+/** How long a `not-found` term answer is reused, matching the Data Plane's own 404 `max-age`. */
+const SEARCH_LANDING_MISS_TTL_MS = 6e4;
+/** The most `not-found` answers kept at once. The key comes from the shopper, so the cache is bounded. */
+const SEARCH_LANDING_MISS_LIMIT = 1e4;
+const COMBINING_DIACRITICS = /[̀-ͯ]/g;
+const WHITESPACE_RUN = /\s+/g;
+/**
+* The one search-term normalization (#957): NFD, combining diacritics stripped, trimmed, lower-cased,
+* every whitespace run collapsed to one hyphen. No stop words. A CMS term entry's slug has this shape,
+* so the singleton term map and the read by slug share this function.
+*/
+function normalizeSearchTerm(term) {
+	return term.normalize("NFD").replaceAll(COMBINING_DIACRITICS, "").trim().toLowerCase().replaceAll(WHITESPACE_RUN, "-");
+}
+/** The path `entry` is served at in a binding: its alias there, else its pattern. `null` when unserved. */
+function servedPath(entry, bindingId) {
+	if (entry.bindings && !entry.bindings.includes(bindingId)) return null;
+	return entry.aliases?.[bindingId] ?? entry.pattern;
+}
+/**
+* The search page's landing lookup. Singleton terms come from the route map, normalized once here, and a
+* singleton wins its term. Any other term costs one content read by its normalized slug, unless the same
+* term answered `not-found` less than a minute ago. `unavailable` is never cached and never fails the page:
+* the search page keeps its own canonical.
+*/
+function createSearchLandingLookup({ routeMap, readContentItem, now = Date.now }) {
+	const singletons = /* @__PURE__ */ new Map();
+	let content;
+	for (const entry of Object.values(routeMap)) {
+		const { searchTerm } = entry;
+		if (typeof searchTerm === "string") {
+			const term = normalizeSearchTerm(searchTerm);
+			if (term !== "" && !singletons.has(term)) singletons.set(term, entry);
+		} else if (searchTerm && !content) content = {
+			entry,
+			...searchTerm
+		};
+	}
+	const misses = /* @__PURE__ */ new Map();
+	function missed(key) {
+		const expiresAt = misses.get(key);
+		if (expiresAt === void 0) return false;
+		if (expiresAt > now()) return true;
+		misses.delete(key);
+		return false;
+	}
+	function remember(key) {
+		if (misses.size >= 1e4) {
+			const at = now();
+			for (const [stale, expiresAt] of misses) if (expiresAt <= at) misses.delete(stale);
+			if (misses.size >= 1e4) misses.delete(misses.keys().next().value);
+		}
+		misses.set(key, now() + SEARCH_LANDING_MISS_TTL_MS);
+	}
+	return async function searchLandingPath({ bindingId, locale, query }) {
+		const raw = Array.isArray(query) ? query[0] : query;
+		const term = raw === void 0 ? "" : normalizeSearchTerm(raw);
+		if (term === "") return null;
+		const singleton = singletons.get(term);
+		const singletonPath = singleton && servedPath(singleton, bindingId);
+		if (singletonPath) return singletonPath;
+		const pattern = content && readContentItem ? servedPath(content.entry, bindingId) : null;
+		if (!content || !readContentItem || pattern === null) return null;
+		if (!isSingleSegment(term)) return null;
+		const key = `${content.contentType}\u0000${locale}\u0000${term}`;
+		if (missed(key)) return null;
+		const { status } = await readContentItem({
+			contentTypeId: content.contentType,
+			slug: term,
+			locale
+		});
+		if (status === "not-found") remember(key);
+		return status === "found" ? routeLogicalPath(pattern, { [content.param]: term }) : null;
+	};
+}
+/** Whether a normalized term fills one route segment: no `/`, and not a dot segment. */
+function isSingleSegment(term) {
+	return !term.includes("/") && term !== "." && term !== "..";
+}
+//#endregion
+export { SEARCH_LANDING_MISS_LIMIT, SEARCH_LANDING_MISS_TTL_MS, createSearchLandingLookup, normalizeSearchTerm, servedPath };
+
+//# sourceMappingURL=search-landing.js.map

package/dist/sdk/seo/search-landing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-landing.js","names":[],"sources":["../../../src/sdk/seo/search-landing.ts"],"sourcesContent":["import type { RouteMap, RouteMapEntry } from '../navigation/types.js';\nimport { routeLogicalPath } from './page-alternates.js';\n\n/** How long a `not-found` term answer is reused, matching the Data Plane's own 404 `max-age`. */\nexport const SEARCH_LANDING_MISS_TTL_MS = 60_000;\n\n/** The most `not-found` answers kept at once. The key comes from the shopper, so the cache is bounded. */\nexport const SEARCH_LANDING_MISS_LIMIT = 10_000;\n\nconst COMBINING_DIACRITICS = /[̀-ͯ]/g;\nconst WHITESPACE_RUN = /\\s+/g;\n\n/**\n * The one search-term normalization (#957): NFD, combining diacritics stripped, trimmed, lower-cased,\n * every whitespace run collapsed to one hyphen. No stop words. A CMS term entry's slug has this shape,\n * so the singleton term map and the read by slug share this function.\n */\nexport function normalizeSearchTerm(term: string): string {\n  return term\n    .normalize('NFD')\n    .replaceAll(COMBINING_DIACRITICS, '')\n    .trim()\n    .toLowerCase()\n    .replaceAll(WHITESPACE_RUN, '-');\n}\n\n/**\n * One content item read by slug. Structurally the content runtime's `readContentItem`, which this module\n * does not import: the server entry must not pull the content runtime into every page's graph.\n */\nexport type SearchLandingItemRead = (args: {\n  contentTypeId: string;\n  slug: string;\n  locale: string;\n}) => Promise<{ status: 'found' | 'not-found' | 'unavailable' }>;\n\nexport type SearchLandingLookupOptions = {\n  routeMap: RouteMap;\n  /** Present when the store has page-level content types; without it, CMS term entries are never read. */\n  readContentItem?: SearchLandingItemRead;\n  now?: () => number;\n};\n\nexport type SearchLandingQuery = {\n  bindingId: string;\n  locale: string;\n  /** The search page's `q` as Next.js hands it over. A repeated key reads its first value. */\n  query: string | string[] | undefined;\n};\n\n/** Resolves the logical path of the Search Landing Page for a query, or `null` when it has none. */\nexport type SearchLandingLookup = (query: SearchLandingQuery) => Promise<string | null>;\n\ntype ContentLanding = { entry: RouteMapEntry; contentType: string; param: string };\n\n/** The path `entry` is served at in a binding: its alias there, else its pattern. `null` when unserved. */\nexport function servedPath(entry: RouteMapEntry, bindingId: string): string | null {\n  if (entry.bindings && !entry.bindings.includes(bindingId)) return null;\n  return entry.aliases?.[bindingId] ?? entry.pattern;\n}\n\n/**\n * The search page's landing lookup. Singleton terms come from the route map, normalized once here, and a\n * singleton wins its term. Any other term costs one content read by its normalized slug, unless the same\n * term answered `not-found` less than a minute ago. `unavailable` is never cached and never fails the page:\n * the search page keeps its own canonical.\n */\nexport function createSearchLandingLookup({\n  routeMap,\n  readContentItem,\n  now = Date.now,\n}: SearchLandingLookupOptions): SearchLandingLookup {\n  const singletons = new Map<string, RouteMapEntry>();\n  let content: ContentLanding | undefined;\n  for (const entry of Object.values(routeMap)) {\n    const { searchTerm } = entry;\n    if (typeof searchTerm === 'string') {\n      const term = normalizeSearchTerm(searchTerm);\n      if (term !== '' && !singletons.has(term)) singletons.set(term, entry);\n    } else if (searchTerm && !content) {\n      content = { entry, ...searchTerm };\n    }\n  }\n  const misses = new Map<string, number>();\n\n  function missed(key: string): boolean {\n    const expiresAt = misses.get(key);\n    if (expiresAt === undefined) return false;\n    if (expiresAt > now()) return true;\n    misses.delete(key);\n    return false;\n  }\n\n  function remember(key: string): void {\n    if (misses.size >= SEARCH_LANDING_MISS_LIMIT) {\n      const at = now();\n      for (const [stale, expiresAt] of misses) if (expiresAt <= at) misses.delete(stale);\n      // Insertion order is expiry order, so the first key is the one closest to expiring.\n      if (misses.size >= SEARCH_LANDING_MISS_LIMIT) misses.delete(misses.keys().next().value as string);\n    }\n    misses.set(key, now() + SEARCH_LANDING_MISS_TTL_MS);\n  }\n\n  return async function searchLandingPath({ bindingId, locale, query }) {\n    const raw = Array.isArray(query) ? query[0] : query;\n    const term = raw === undefined ? '' : normalizeSearchTerm(raw);\n    if (term === '') return null;\n\n    const singleton = singletons.get(term);\n    const singletonPath = singleton && servedPath(singleton, bindingId);\n    if (singletonPath) return singletonPath;\n\n    const pattern = content && readContentItem ? servedPath(content.entry, bindingId) : null;\n    if (!content || !readContentItem || pattern === null) return null;\n    // The CMS page has one `[param]` segment, so a term that cannot fill one has no entry to read.\n    if (!isSingleSegment(term)) return null;\n    const key = `${content.contentType}\\u0000${locale}\\u0000${term}`;\n    if (missed(key)) return null;\n    const { status } = await readContentItem({ contentTypeId: content.contentType, slug: term, locale });\n    if (status === 'not-found') remember(key);\n    // The path stays decoded, like every logical path: `routeLogicalPath` never decodes, and the\n    // canonical's `url()` encodes the path once on the way out.\n    return status === 'found' ? routeLogicalPath(pattern, { [content.param]: term }) : null;\n  };\n}\n\n/** Whether a normalized term fills one route segment: no `/`, and not a dot segment. */\nfunction isSingleSegment(term: string): boolean {\n  return !term.includes('/') && term !== '.' && term !== '..';\n}\n"],"mappings":";;;AAIA,MAAa,6BAA6B;;AAG1C,MAAa,4BAA4B;AAEzC,MAAM,uBAAuB;AAC7B,MAAM,iBAAiB;;;;;;AAOvB,SAAgB,oBAAoB,MAAsB;CACxD,OAAO,KACJ,UAAU,KAAK,CAAC,CAChB,WAAW,sBAAsB,EAAE,CAAC,CACpC,KAAK,CAAC,CACN,YAAY,CAAC,CACb,WAAW,gBAAgB,GAAG;AACnC;;AAgCA,SAAgB,WAAW,OAAsB,WAAkC;CACjF,IAAI,MAAM,YAAY,CAAC,MAAM,SAAS,SAAS,SAAS,GAAG,OAAO;CAClE,OAAO,MAAM,UAAU,cAAc,MAAM;AAC7C;;;;;;;AAQA,SAAgB,0BAA0B,EACxC,UACA,iBACA,MAAM,KAAK,OACuC;CAClD,MAAM,6BAAa,IAAI,IAA2B;CAClD,IAAI;CACJ,KAAK,MAAM,SAAS,OAAO,OAAO,QAAQ,GAAG;EAC3C,MAAM,EAAE,eAAe;EACvB,IAAI,OAAO,eAAe,UAAU;GAClC,MAAM,OAAO,oBAAoB,UAAU;GAC3C,IAAI,SAAS,MAAM,CAAC,WAAW,IAAI,IAAI,GAAG,WAAW,IAAI,MAAM,KAAK;EACtE,OAAO,IAAI,cAAc,CAAC,SACxB,UAAU;GAAE;GAAO,GAAG;EAAW;CAErC;CACA,MAAM,yBAAS,IAAI,IAAoB;CAEvC,SAAS,OAAO,KAAsB;EACpC,MAAM,YAAY,OAAO,IAAI,GAAG;EAChC,IAAI,cAAc,KAAA,GAAW,OAAO;EACpC,IAAI,YAAY,IAAI,GAAG,OAAO;EAC9B,OAAO,OAAO,GAAG;EACjB,OAAO;CACT;CAEA,SAAS,SAAS,KAAmB;EACnC,IAAI,OAAO,QAAA,KAAmC;GAC5C,MAAM,KAAK,IAAI;GACf,KAAK,MAAM,CAAC,OAAO,cAAc,QAAQ,IAAI,aAAa,IAAI,OAAO,OAAO,KAAK;GAEjF,IAAI,OAAO,QAAA,KAAmC,OAAO,OAAO,OAAO,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,KAAe;EAClG;EACA,OAAO,IAAI,KAAK,IAAI,IAAI,0BAA0B;CACpD;CAEA,OAAO,eAAe,kBAAkB,EAAE,WAAW,QAAQ,SAAS;EACpE,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;EAC9C,MAAM,OAAO,QAAQ,KAAA,IAAY,KAAK,oBAAoB,GAAG;EAC7D,IAAI,SAAS,IAAI,OAAO;EAExB,MAAM,YAAY,WAAW,IAAI,IAAI;EACrC,MAAM,gBAAgB,aAAa,WAAW,WAAW,SAAS;EAClE,IAAI,eAAe,OAAO;EAE1B,MAAM,UAAU,WAAW,kBAAkB,WAAW,QAAQ,OAAO,SAAS,IAAI;EACpF,IAAI,CAAC,WAAW,CAAC,mBAAmB,YAAY,MAAM,OAAO;EAE7D,IAAI,CAAC,gBAAgB,IAAI,GAAG,OAAO;EACnC,MAAM,MAAM,GAAG,QAAQ,YAAY,QAAQ,OAAO,QAAQ;EAC1D,IAAI,OAAO,GAAG,GAAG,OAAO;EACxB,MAAM,EAAE,WAAW,MAAM,gBAAgB;GAAE,eAAe,QAAQ;GAAa,MAAM;GAAM;EAAO,CAAC;EACnG,IAAI,WAAW,aAAa,SAAS,GAAG;EAGxC,OAAO,WAAW,UAAU,iBAAiB,SAAS,GAAG,QAAQ,QAAQ,KAAK,CAAC,IAAI;CACrF;AACF;;AAGA,SAAS,gBAAgB,MAAuB;CAC9C,OAAO,CAAC,KAAK,SAAS,GAAG,KAAK,SAAS,OAAO,SAAS;AACzD"}

package/dist/sdk/session/mock-session.d.ts

@@ -0,0 +1,9 @@
+//#region src/sdk/session/mock-session.d.ts
+/**
+ * The development-only mock session. A process that sets `FS_MOCK_SESSION` to a token treats a
+ * request carrying the cookie `fs-mock-session` with that same token as signed in, so the session gate can
+ * be exercised without a real shopper. Production deployments never set the variable.
+ */
+export declare const MOCK_SESSION_COOKIE = "fs-mock-session";
+//#endregion
+//# sourceMappingURL=mock-session.d.ts.map

package/dist/sdk/session/mock-session.js

@@ -0,0 +1,31 @@
+import { cookies } from "next/headers";
+//#region src/sdk/session/mock-session.ts
+/**
+* The development-only mock session. A process that sets `FS_MOCK_SESSION` to a token treats a
+* request carrying the cookie `fs-mock-session` with that same token as signed in, so the session gate can
+* be exercised without a real shopper. Production deployments never set the variable.
+*/
+const MOCK_SESSION_COOKIE = "fs-mock-session";
+/** The template route handler that sets the mock cookie and sends the shopper back. */
+const MOCK_SESSION_ROUTE = "/api/mock-session";
+/** The token `FS_MOCK_SESSION` carries, or `null` when the variable is unset or empty. */
+function mockSessionToken() {
+	return process.env.FS_MOCK_SESSION || null;
+}
+/**
+* Whether the request carries the mock cookie with the configured token. Fakes `loggedIn` only: no
+* customer data comes with it. Outside a request scope `cookies()` throws, and there is no mock session.
+*/
+async function hasMockSession() {
+	const token = mockSessionToken();
+	if (token === null) return false;
+	try {
+		return (await cookies()).get(MOCK_SESSION_COOKIE)?.value === token;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { MOCK_SESSION_COOKIE, MOCK_SESSION_ROUTE, hasMockSession, mockSessionToken };
+
+//# sourceMappingURL=mock-session.js.map

package/dist/sdk/session/mock-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-session.js","names":[],"sources":["../../../src/sdk/session/mock-session.ts"],"sourcesContent":["import { cookies } from 'next/headers';\n\n/**\n * The development-only mock session. A process that sets `FS_MOCK_SESSION` to a token treats a\n * request carrying the cookie `fs-mock-session` with that same token as signed in, so the session gate can\n * be exercised without a real shopper. Production deployments never set the variable.\n */\nexport const MOCK_SESSION_COOKIE = 'fs-mock-session';\n\n/** The template route handler that sets the mock cookie and sends the shopper back. */\nexport const MOCK_SESSION_ROUTE = '/api/mock-session';\n\n/** The token `FS_MOCK_SESSION` carries, or `null` when the variable is unset or empty. */\nexport function mockSessionToken(): string | null {\n  const token = process.env.FS_MOCK_SESSION;\n  return token || null;\n}\n\n/**\n * Whether the request carries the mock cookie with the configured token. Fakes `loggedIn` only: no\n * customer data comes with it. Outside a request scope `cookies()` throws, and there is no mock session.\n */\nexport async function hasMockSession(): Promise<boolean> {\n  const token = mockSessionToken();\n  if (token === null) return false;\n  try {\n    return (await cookies()).get(MOCK_SESSION_COOKIE)?.value === token;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;;;;;AAOA,MAAa,sBAAsB;;AAGnC,MAAa,qBAAqB;;AAGlC,SAAgB,mBAAkC;CAEhD,OADc,QAAQ,IAAI,mBACV;AAClB;;;;;AAMA,eAAsB,iBAAmC;CACvD,MAAM,QAAQ,iBAAiB;CAC/B,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI;EACF,QAAQ,MAAM,QAAQ,EAAA,CAAG,IAAI,mBAAmB,CAAC,EAAE,UAAU;CAC/D,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/sdk/session/read-server-session.d.ts

@@ -7,6 +7,9 @@ import { CreateClientOptions } from "../client/create-client.js";
  * throw, a GraphQL error, a missing `session`, or a timeout is `failed`, including a partial
  * payload that says `loggedIn: true`. The result carries no session payload. No `Cookie` header
  * is set here, so `createClient` keeps forwarding `cookies()`.
+ *
+ * A mock session (`FS_MOCK_SESSION` plus a matching `fs-mock-session` cookie) resolves `signed-in`
+ * without querying the API, and logs `[session-gate] mock session` on every such read.
  */
 export type ServerSessionRead = {
   status: 'signed-in';

package/dist/sdk/session/read-server-session.js

@@ -1,5 +1,6 @@
 import { ServerSessionReadDocument } from "../generated/graphql.js";
 import { createClient } from "../client/create-client.js";
+import { hasMockSession } from "./mock-session.js";
 import { CombinedGraphQLErrors } from "@apollo/client/errors";
 //#region src/sdk/session/read-server-session.ts
 /**
@@ -8,6 +9,10 @@ import { CombinedGraphQLErrors } from "@apollo/client/errors";
 */
 const SERVER_SESSION_READ_TIMEOUT_MS = 5e3;
 async function readServerSession(options) {
+	if (await hasMockSession()) {
+		console.warn("[session-gate] mock session");
+		return { status: "signed-in" };
+	}
 	try {
 		const result = await createClient(options).query({
 			query: ServerSessionReadDocument,

package/dist/sdk/session/read-server-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-server-session.js","names":[],"sources":["../../../src/sdk/session/read-server-session.ts"],"sourcesContent":["import { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport type { CreateClientOptions } from '../client/create-client.js';\nimport { createClient } from '../client/create-client.js';\nimport { ServerSessionReadDocument } from '../generated/graphql.js';\n\n/**\n * Local bound for the session read. Not the content runtime's request timeout: that module must\n * stay off the server barrel.\n */\nconst SERVER_SESSION_READ_TIMEOUT_MS = 5_000;\n\n/**\n * Classifies `Query.session` for a server caller.\n *\n * Always resolves. `signed-in` is `loggedIn === true`. An identified guest is `anonymous`. A\n * throw, a GraphQL error, a missing `session`, or a timeout is `failed`, including a partial\n * payload that says `loggedIn: true`. The result carries no session payload. No `Cookie` header\n * is set here, so `createClient` keeps forwarding `cookies()`.\n */\nexport type ServerSessionRead =\n  | { status: 'signed-in' }\n  | { status: 'anonymous' }\n  | { status: 'failed'; reason: string };\n\nexport async function readServerSession(options?: CreateClientOptions): Promise<ServerSessionRead> {\n  try {\n    const client = createClient(options);\n    const result = await client.query({\n      query: ServerSessionReadDocument,\n      errorPolicy: 'all',\n      fetchPolicy: 'no-cache',\n      context: { fetchOptions: { signal: AbortSignal.timeout(SERVER_SESSION_READ_TIMEOUT_MS) } },\n    });\n\n    // A timeout lands on `result.error` under `errorPolicy: 'all'` rather than rejecting.\n    if (isTimeoutError(result.error)) {\n      return { status: 'failed', reason: 'timeout' };\n    }\n\n    if (result.error || result.data?.session == null) {\n      return { status: 'failed', reason: graphqlFailureReason(result.error) };\n    }\n\n    if (result.data.session.loggedIn === true) {\n      return { status: 'signed-in' };\n    }\n\n    return { status: 'anonymous' };\n  } catch (error) {\n    if (isTimeoutError(error)) {\n      return { status: 'failed', reason: 'timeout' };\n    }\n    if (error instanceof Error && error.message.length > 0) {\n      return { status: 'failed', reason: error.message };\n    }\n    return { status: 'failed', reason: 'network error' };\n  }\n}\n\nfunction graphqlFailureReason(error: unknown): string {\n  if (CombinedGraphQLErrors.is(error)) {\n    const message = error.errors[0]?.message;\n    if (typeof message === 'string' && message.length > 0) return message;\n  }\n  return 'graphql error';\n}\n\nfunction isTimeoutError(error: unknown): boolean {\n  if (hasAbortName(error)) return true;\n  if (typeof error === 'object' && error !== null && 'cause' in error) {\n    return hasAbortName(error.cause);\n  }\n  return false;\n}\n\nfunction hasAbortName(error: unknown): boolean {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    'name' in error &&\n    (error.name === 'TimeoutError' || error.name === 'AbortError')\n  );\n}\n"],"mappings":";;;;;;;;AASA,MAAM,iCAAiC;AAevC,eAAsB,kBAAkB,SAA2D;CACjG,IAAI;EAEF,MAAM,SAAS,MADA,aAAa,OACF,CAAC,CAAC,MAAM;GAChC,OAAO;GACP,aAAa;GACb,aAAa;GACb,SAAS,EAAE,cAAc,EAAE,QAAQ,YAAY,QAAQ,8BAA8B,EAAE,EAAE;EAC3F,CAAC;EAGD,IAAI,eAAe,OAAO,KAAK,GAC7B,OAAO;GAAE,QAAQ;GAAU,QAAQ;EAAU;EAG/C,IAAI,OAAO,SAAS,OAAO,MAAM,WAAW,MAC1C,OAAO;GAAE,QAAQ;GAAU,QAAQ,qBAAqB,OAAO,KAAK;EAAE;EAGxE,IAAI,OAAO,KAAK,QAAQ,aAAa,MACnC,OAAO,EAAE,QAAQ,YAAY;EAG/B,OAAO,EAAE,QAAQ,YAAY;CAC/B,SAAS,OAAO;EACd,IAAI,eAAe,KAAK,GACtB,OAAO;GAAE,QAAQ;GAAU,QAAQ;EAAU;EAE/C,IAAI,iBAAiB,SAAS,MAAM,QAAQ,SAAS,GACnD,OAAO;GAAE,QAAQ;GAAU,QAAQ,MAAM;EAAQ;EAEnD,OAAO;GAAE,QAAQ;GAAU,QAAQ;EAAgB;CACrD;AACF;AAEA,SAAS,qBAAqB,OAAwB;CACpD,IAAI,sBAAsB,GAAG,KAAK,GAAG;EACnC,MAAM,UAAU,MAAM,OAAO,EAAE,EAAE;EACjC,IAAI,OAAO,YAAY,YAAY,QAAQ,SAAS,GAAG,OAAO;CAChE;CACA,OAAO;AACT;AAEA,SAAS,eAAe,OAAyB;CAC/C,IAAI,aAAa,KAAK,GAAG,OAAO;CAChC,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,WAAW,OAC5D,OAAO,aAAa,MAAM,KAAK;CAEjC,OAAO;AACT;AAEA,SAAS,aAAa,OAAyB;CAC7C,OACE,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,UACT,MAAM,SAAS,kBAAkB,MAAM,SAAS;AAErD"}
+{"version":3,"file":"read-server-session.js","names":[],"sources":["../../../src/sdk/session/read-server-session.ts"],"sourcesContent":["import { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport type { CreateClientOptions } from '../client/create-client.js';\nimport { createClient } from '../client/create-client.js';\nimport { ServerSessionReadDocument } from '../generated/graphql.js';\nimport { hasMockSession } from './mock-session.js';\n\n/**\n * Local bound for the session read. Not the content runtime's request timeout: that module must\n * stay off the server barrel.\n */\nconst SERVER_SESSION_READ_TIMEOUT_MS = 5_000;\n\n/**\n * Classifies `Query.session` for a server caller.\n *\n * Always resolves. `signed-in` is `loggedIn === true`. An identified guest is `anonymous`. A\n * throw, a GraphQL error, a missing `session`, or a timeout is `failed`, including a partial\n * payload that says `loggedIn: true`. The result carries no session payload. No `Cookie` header\n * is set here, so `createClient` keeps forwarding `cookies()`.\n *\n * A mock session (`FS_MOCK_SESSION` plus a matching `fs-mock-session` cookie) resolves `signed-in`\n * without querying the API, and logs `[session-gate] mock session` on every such read.\n */\nexport type ServerSessionRead =\n  | { status: 'signed-in' }\n  | { status: 'anonymous' }\n  | { status: 'failed'; reason: string };\n\nexport async function readServerSession(options?: CreateClientOptions): Promise<ServerSessionRead> {\n  if (await hasMockSession()) {\n    console.warn('[session-gate] mock session');\n    return { status: 'signed-in' };\n  }\n\n  try {\n    const client = createClient(options);\n    const result = await client.query({\n      query: ServerSessionReadDocument,\n      errorPolicy: 'all',\n      fetchPolicy: 'no-cache',\n      context: { fetchOptions: { signal: AbortSignal.timeout(SERVER_SESSION_READ_TIMEOUT_MS) } },\n    });\n\n    // A timeout lands on `result.error` under `errorPolicy: 'all'` rather than rejecting.\n    if (isTimeoutError(result.error)) {\n      return { status: 'failed', reason: 'timeout' };\n    }\n\n    if (result.error || result.data?.session == null) {\n      return { status: 'failed', reason: graphqlFailureReason(result.error) };\n    }\n\n    if (result.data.session.loggedIn === true) {\n      return { status: 'signed-in' };\n    }\n\n    return { status: 'anonymous' };\n  } catch (error) {\n    if (isTimeoutError(error)) {\n      return { status: 'failed', reason: 'timeout' };\n    }\n    if (error instanceof Error && error.message.length > 0) {\n      return { status: 'failed', reason: error.message };\n    }\n    return { status: 'failed', reason: 'network error' };\n  }\n}\n\nfunction graphqlFailureReason(error: unknown): string {\n  if (CombinedGraphQLErrors.is(error)) {\n    const message = error.errors[0]?.message;\n    if (typeof message === 'string' && message.length > 0) return message;\n  }\n  return 'graphql error';\n}\n\nfunction isTimeoutError(error: unknown): boolean {\n  if (hasAbortName(error)) return true;\n  if (typeof error === 'object' && error !== null && 'cause' in error) {\n    return hasAbortName(error.cause);\n  }\n  return false;\n}\n\nfunction hasAbortName(error: unknown): boolean {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    'name' in error &&\n    (error.name === 'TimeoutError' || error.name === 'AbortError')\n  );\n}\n"],"mappings":";;;;;;;;;AAUA,MAAM,iCAAiC;AAkBvC,eAAsB,kBAAkB,SAA2D;CACjG,IAAI,MAAM,eAAe,GAAG;EAC1B,QAAQ,KAAK,6BAA6B;EAC1C,OAAO,EAAE,QAAQ,YAAY;CAC/B;CAEA,IAAI;EAEF,MAAM,SAAS,MADA,aAAa,OACF,CAAC,CAAC,MAAM;GAChC,OAAO;GACP,aAAa;GACb,aAAa;GACb,SAAS,EAAE,cAAc,EAAE,QAAQ,YAAY,QAAQ,8BAA8B,EAAE,EAAE;EAC3F,CAAC;EAGD,IAAI,eAAe,OAAO,KAAK,GAC7B,OAAO;GAAE,QAAQ;GAAU,QAAQ;EAAU;EAG/C,IAAI,OAAO,SAAS,OAAO,MAAM,WAAW,MAC1C,OAAO;GAAE,QAAQ;GAAU,QAAQ,qBAAqB,OAAO,KAAK;EAAE;EAGxE,IAAI,OAAO,KAAK,QAAQ,aAAa,MACnC,OAAO,EAAE,QAAQ,YAAY;EAG/B,OAAO,EAAE,QAAQ,YAAY;CAC/B,SAAS,OAAO;EACd,IAAI,eAAe,KAAK,GACtB,OAAO;GAAE,QAAQ;GAAU,QAAQ;EAAU;EAE/C,IAAI,iBAAiB,SAAS,MAAM,QAAQ,SAAS,GACnD,OAAO;GAAE,QAAQ;GAAU,QAAQ,MAAM;EAAQ;EAEnD,OAAO;GAAE,QAAQ;GAAU,QAAQ;EAAgB;CACrD;AACF;AAEA,SAAS,qBAAqB,OAAwB;CACpD,IAAI,sBAAsB,GAAG,KAAK,GAAG;EACnC,MAAM,UAAU,MAAM,OAAO,EAAE,EAAE;EACjC,IAAI,OAAO,YAAY,YAAY,QAAQ,SAAS,GAAG,OAAO;CAChE;CACA,OAAO;AACT;AAEA,SAAS,eAAe,OAAyB;CAC/C,IAAI,aAAa,KAAK,GAAG,OAAO;CAChC,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,WAAW,OAC5D,OAAO,aAAa,MAAM,KAAK;CAEjC,OAAO;AACT;AAEA,SAAS,aAAa,OAAyB;CAC7C,OACE,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,UACT,MAAM,SAAS,kBAAkB,MAAM,SAAS;AAErD"}

package/dist/sdk/session/return-path-segment.d.ts

@@ -0,0 +1,10 @@
+//#region src/sdk/session/return-path-segment.d.ts
+/**
+ * One dynamic route segment of the session gate's return path, with its leading `/`, filled from the
+ * awaited params: a `[name]` value is encoded, a `[...name]` value is encoded part by part with a `/`
+ * before each, and the absent value of an optional catch-all (`[[...name]]`) is empty, so the path
+ * ends at the literal before it with no trailing `/`.
+ */
+export declare function returnPathSegment(value: string | readonly string[] | undefined): string;
+//#endregion
+//# sourceMappingURL=return-path-segment.d.ts.map

package/dist/sdk/session/return-path-segment.js

@@ -0,0 +1,15 @@
+//#region src/sdk/session/return-path-segment.ts
+/**
+* One dynamic route segment of the session gate's return path, with its leading `/`, filled from the
+* awaited params: a `[name]` value is encoded, a `[...name]` value is encoded part by part with a `/`
+* before each, and the absent value of an optional catch-all (`[[...name]]`) is empty, so the path
+* ends at the literal before it with no trailing `/`.
+*/
+function returnPathSegment(value) {
+	if (value === void 0) return "";
+	return (typeof value === "string" ? [value] : value).map((part) => `/${encodeURIComponent(part)}`).join("");
+}
+//#endregion
+export { returnPathSegment };
+
+//# sourceMappingURL=return-path-segment.js.map

package/dist/sdk/session/return-path-segment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-path-segment.js","names":[],"sources":["../../../src/sdk/session/return-path-segment.ts"],"sourcesContent":["/**\n * One dynamic route segment of the session gate's return path, with its leading `/`, filled from the\n * awaited params: a `[name]` value is encoded, a `[...name]` value is encoded part by part with a `/`\n * before each, and the absent value of an optional catch-all (`[[...name]]`) is empty, so the path\n * ends at the literal before it with no trailing `/`.\n */\nexport function returnPathSegment(value: string | readonly string[] | undefined): string {\n  if (value === undefined) return '';\n  const parts = typeof value === 'string' ? [value] : value;\n  return parts.map((part) => `/${encodeURIComponent(part)}`).join('');\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,kBAAkB,OAAuD;CACvF,IAAI,UAAU,KAAA,GAAW,OAAO;CAEhC,QADc,OAAO,UAAU,WAAW,CAAC,KAAK,IAAI,MAAA,CACvC,KAAK,SAAS,IAAI,mBAAmB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE;AACpE"}