npm - @forgecart/cli - Versions diffs - 2.202608300703.0 → 2.202609190800.0 - Mend

@forgecart/cli 2.202608300703.0 → 2.202609190800.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/templates/storefront/src/lib/forgecart.ts CHANGED Viewed

@@ -1,11 +1,15 @@
 import 'server-only';
-import { ForgeCartShopClient } from '@forgecart/sdk/shop';
+import { ForgeCartShopClient, extractError } from '@forgecart/sdk/shop';
 import type {
   ShopProductFieldFragment as Product,
   ShopSellingPlanGroupFieldFragment as SellingPlanGroup,
 } from '@forgecart/sdk/shop';
+import type { AccountCallOutcome } from './account/account-link';
+import { UNREACHABLE_ERROR } from './action-result';
+import { getRequestLocale } from './locale/request-binding';
 /**
  * Server-side ForgeCart shop client.
  *
@@ -35,17 +39,25 @@ import type {
 const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
 const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
-let client: ForgeCartShopClient | null = null;
 /**
- * Lazily construct and memoize the channel-scoped shop client.
+ * One client per language (#1346, W1-8 / S1).
+ *
+ * The SDK's language is a per-CONNECTION header fixed at socket handshake, so
+ * a single instance structurally cannot serve two locales — and mutating a
+ * shared one with `setLanguageCode()` is worse than useless here: it DISPOSES
+ * the websocket, tearing down whatever concurrent request was mid-flight on
+ * it. Hence one client, one language, memoized for the process.
  *
- * All reads here are anonymous (channel scope only), so one client instance
- * serves the whole server process. Per-shopper session state lives in
- * `cart-actions.ts`, which constructs a per-request client around the session
- * cookie instead.
+ * The map is bounded by the channel's language count, not by traffic: it is
+ * keyed on the locale the layout RESOLVED, and the layout only resolves a
+ * language the channel offers — `/zz/`, `/qq/` … 404 before they ever reach a
+ * data read. Entries are never evicted: eviction would dispose a live socket
+ * and force a re-handshake, converting bounded memory into unbounded backend
+ * churn. Each idle socket is reaped by the SDK's own `lazyCloseTimeout`.
  */
-export function getShopClient(): ForgeCartShopClient {
+const clientsByLocale = new Map<string, ForgeCartShopClient>();
+function assertShopConfigured(): void {
   if (!SHOP_API_URL) {
     throw new Error(
       'FORGECART_SHOP_API_URL is not set. Add it to .env (forgecart init writes it for you).',
@@ -56,17 +68,43 @@ export function getShopClient(): ForgeCartShopClient {
       'FORGECART_CHANNEL_TOKEN is not set. Add it to .env (forgecart init writes it for you).',
     );
   }
-  if (!client) {
-    client = new ForgeCartShopClient({
-      endpoint: SHOP_API_URL,
-      channelToken: CHANNEL_TOKEN,
-    });
-  }
-  return client;
 }
-/** Convenience singleton for direct use in Server Components. */
-export const shopClient = (): ForgeCartShopClient => getShopClient();
+/**
+ * The client for an explicit language.
+ *
+ * `locale` must be one the channel offers — the caller has already resolved it
+ * through `getRequestLocale()`, whose decision function 404s anything else. It
+ * is not re-validated here, and it deliberately does NOT fall back to the
+ * default on a surprise: silently answering in another language than the
+ * document just declared in `<html lang>` is precisely the bug this slice
+ * exists to close, and it would look correct in every review.
+ */
+export function getShopClientForLocale(locale: string): ForgeCartShopClient {
+  assertShopConfigured();
+  const existing = clientsByLocale.get(locale);
+  if (existing) return existing;
+  const created = new ForgeCartShopClient({
+    endpoint: SHOP_API_URL,
+    channelToken: CHANNEL_TOKEN,
+    languageCode: locale,
+  });
+  clientsByLocale.set(locale, created);
+  return created;
+}
+/**
+ * The client for THIS request's language.
+ *
+ * Every read below goes through it, so a German page's product names, facets
+ * and selling plans come back in German — the half of the locale contract that
+ * `<html lang>` alone would only claim.
+ */
+export async function getShopClient(): Promise<ForgeCartShopClient> {
+  const { binding } = await getRequestLocale();
+  return getShopClientForLocale(binding.locale);
+}
 // The SDK's operation-shaped fragment types, re-exported under their domain
 // names so components import them from one place. These are exactly what the
@@ -93,10 +131,43 @@ import type {
   GetSessionTemplateQuery,
   GetSessionVariablesQuery,
   RefreshShippingRateGroupsMutation,
+  SeoEntriesQuery,
   ShopEligiblePaymentProvidersQuery,
+  ShopEntriesQuery,
   ShopOrderByCodeQuery,
+  ShopPageByRouteQuery,
+  ShopProductQuery,
 } from '@forgecart/sdk/shop';
+/**
+ * A single product AS SELECTED by the detail query — the display fields plus
+ * the per-language SEO sidecar (#1341) and `resolvedLanguageCode` (#1339).
+ *
+ * Distinct from `Product` (the list-row fragment) on purpose: only this shape
+ * carries what the slug law needs, and taking it by indexed access means the
+ * template cannot drift from what the operation actually asks for.
+ */
+export type ProductWithSeo = NonNullable<ShopProductQuery['product']>;
+/** One page of the XML sitemap's catalog feed (#1339). */
+export type SeoEntryFeedPage = SeoEntriesQuery['seoEntries'];
+/**
+ * An ACF page definition as `pageByRoute` selects it (#1934) — the merchant's
+ * own field definitions, in the order the editor arranged them.
+ *
+ * Taken by indexed access off the generated query rather than re-declared, like
+ * every other shape here: what the route renders and what the operation asks
+ * for cannot drift apart.
+ */
+export type PageGroup = NonNullable<ShopPageByRouteQuery['pageByRoute']>;
+/** One field definition of a page — the label and the identity of a value. */
+export type PageFieldDefinition = PageGroup['fieldDefinitions'][number];
+/** One record of a page, with its values and repeater rows. */
+export type PageEntry = ShopEntriesQuery['entries']['items'][number];
+/** One stored value, discriminated by `__typename` over the ACF field types. */
+export type PageFieldValue = PageEntry['fields'][number];
 export type Country = AvailableCountriesQuery['availableCountries'][number];
 export type ShippingRateGroup =
   RefreshShippingRateGroupsMutation['refreshShippingRateGroups'][number];
@@ -134,19 +205,34 @@ export async function getProducts(
   options: { take?: number; skip?: number } = {},
 ): Promise<{ items: Product[]; totalItems: number }> {
   const { take = 24, skip = 0 } = options;
-  const { products } = await getShopClient().product.shopProducts({ options: { take, skip } });
+  const { products } = await (
+    await getShopClient()
+  ).product.shopProducts({ options: { take, skip } });
   return { items: products.items, totalItems: products.totalItems };
 }
-/** Fetch a single product by its URL slug. Returns `null` if not found. */
-export async function getProductBySlug(slug: string): Promise<Product | null> {
-  const { product } = await getShopClient().product.shopProduct({ slug });
+/**
+ * Fetch a single product by its URL slug. Returns `null` if not found.
+ *
+ * Typed as {@link ProductWithSeo}, not `Product`: the single-product query
+ * selects the per-language SEO sidecar (#1341) alongside the display fields,
+ * and the slug law in `lib/seo/resolve-path.ts` reads it to decide whether this
+ * URL is the locale's own address, a derived copy, or a redirect. The list
+ * queries deliberately do NOT select it — resolving the sidecar per row would
+ * pay for it once per card.
+ *
+ * The lookup resolves across languages (#1339): a slug that belongs to another
+ * language, or to this product's PREVIOUS slug, still finds it, and the
+ * returned `slug` is this locale's current one.
+ */
+export async function getProductBySlug(slug: string): Promise<ProductWithSeo | null> {
+  const { product } = await (await getShopClient()).product.shopProduct({ slug });
   return product ?? null;
 }
 /** Fetch a single product by id. Returns `null` if not found. */
 export async function getProductById(id: string): Promise<Product | null> {
-  const { product } = await getShopClient().product.shopProduct({ id });
+  const { product } = await (await getShopClient()).product.shopProduct({ id });
   return product ?? null;
 }
@@ -162,23 +248,210 @@ export async function getFeaturedProducts(count = 4): Promise<Product[]> {
 export async function getSellingPlanGroupsForVariant(
   variantId: string,
 ): Promise<SellingPlanGroup[]> {
-  const { sellingPlanGroupsForVariant } =
-    await getShopClient().sellingPlan.sellingPlanGroupsForVariant({ variantId });
+  const { sellingPlanGroupsForVariant } = await (
+    await getShopClient()
+  ).sellingPlan.sellingPlanGroupsForVariant({ variantId });
   return sellingPlanGroupsForVariant;
 }
 /** Fetch the channel-wide subscription groups (whole-cart subscribe box). */
 export async function getChannelSellingPlanGroups(): Promise<SellingPlanGroup[]> {
-  const { channelSellingPlanGroups } = await getShopClient().sellingPlan.channelSellingPlanGroups();
+  const { channelSellingPlanGroups } = await (
+    await getShopClient()
+  ).sellingPlan.channelSellingPlanGroups();
   return channelSellingPlanGroups;
 }
+/**
+ * One page of the catalog entries the XML sitemap enumerates (#1339).
+ *
+ * The connection language is passed in rather than taken from the request,
+ * because this feed has no request locale to inherit: it returns EVERY
+ * language's path for every entry (languages without a translation row are
+ * omitted, never synthesized), so the answer is the same whichever language
+ * asks. `/sitemap.xml` is an unprefixed route by grammar — there is no locale
+ * in its URL to resolve — and the caller names the channel default so that the
+ * choice is visible instead of inherited from a header that is not there.
+ */
+export async function getProductSeoEntries(
+  languageCode: string,
+  options: { take: number; skip: number },
+): Promise<SeoEntryFeedPage> {
+  const { seoEntries } = await getShopClientForLocale(languageCode).seo.seoEntries({
+    input: { kind: 'PRODUCT', take: options.take, skip: options.skip },
+  });
+  return seoEntries;
+}
+/**
+ * The page definition mounted at a storefront route (#1934). `null` is "no page
+ * here" — an unknown route, a data definition's code, anything outside the
+ * route grammar — and the caller turns that into a real 404.
+ *
+ * METADATA only. Whether the page has content to show is the entries read
+ * below; keeping the two apart is what lets `resolvePage` state the whole 404
+ * decision in one place instead of splitting it across a query and a render.
+ */
+export async function getPageByRoute(route: string): Promise<PageGroup | null> {
+  const { pageByRoute } = await (await getShopClient()).acf.shopPageByRoute({ route });
+  return pageByRoute ?? null;
+}
+/**
+ * The record a page URL serves, as a list of at most one (#1934).
+ *
+ * `take: 1` because a route is ONE address; `createdAt ASC` because that makes
+ * it the page's ORIGINAL record. The shop API's own default is `createdAt
+ * DESC`, and inheriting it would mean that adding a second record to a live
+ * page silently REPLACES what the URL has been serving — a content change
+ * nobody asked for, made by a create. Ascending is a stable answer: the page a
+ * merchant published stays the page at that URL.
+ *
+ * The list may come back EMPTY, and that is the feature's whole 404 arm: every
+ * storefront read is fenced to published content, so a page whose only records
+ * are DRAFT or SCHEDULED-not-yet-live looks exactly like a page with no records
+ * at all. `resolvePage` decides; this function only asks.
+ */
+export async function getPageEntries(definitionCode: string): Promise<PageEntry[]> {
+  const { entries } = await (
+    await getShopClient()
+  ).acf.shopEntries({
+    definitionCode,
+    options: { take: 1, sort: [{ field: 'createdAt', direction: 'ASC' }] },
+  });
+  return entries.items;
+}
+/**
+ * Every ACF page route the shop currently SERVES (#1934) — the sitemap's page
+ * feed.
+ *
+ * A stricter question than `getPageByRoute`'s, deliberately: this list must
+ * contain no URL that would answer 404, because a sitemap entry that does costs
+ * crawl budget and lands in Search Console as an error. The API applies that
+ * gate; unpublishing a page takes it out of this list, and out of the document
+ * on the next window.
+ *
+ * The connection language is named by the caller for the same reason
+ * `getProductSeoEntries` names it: `/sitemap.xml` is an unprefixed route with
+ * no request locale to inherit, and a route exists in every language alike.
+ */
+export async function getServedPageRoutes(languageCode: string): Promise<string[]> {
+  const { pageRoutes } = await getShopClientForLocale(languageCode).acf.shopPageRoutes();
+  return pageRoutes;
+}
 /**
  * Countries the channel ships to — a PUBLIC channel read (no session), so it
  * belongs on this server singleton: the checkout page prefetches it and hands
  * the list to the client flow.
  */
 export async function getAvailableCountries(): Promise<Country[]> {
-  const { availableCountries } = await getShopClient().country.availableCountries();
+  const { availableCountries } = await (await getShopClient()).country.availableCountries();
   return availableCountries;
 }
+/**
+ * ── The four CUSTOMER-ACCOUNT operations (#1472, #1471) ─────────────────────
+ *
+ * The platform mails a shopper a verification link and a password-reset link
+ * pointing at THIS storefront's origin (`/verify` and `/reset-password`), and
+ * three of these are the calls those two pages make. The fourth asks for the
+ * verification mail to be sent AGAIN — the prompt `/register` leaves a shopper
+ * on, for the one whose first mail never arrived (#1471). They are the only
+ * WRITES in this module, and the only functions in it that do not throw.
+ *
+ * Not throwing is the point. Every read above serves a page whose failure IS a
+ * failure — an unreachable catalog is a 500, and the route error boundary is
+ * the right answer. For these four, refusal is the ORDINARY case: a
+ * one-shot token is used exactly once, so the second click on the same link is
+ * an expected outcome to RENDER, not an incident to report. A thrown error
+ * would put the shopper on an error page for doing something entirely normal.
+ *
+ * They answer with {@link AccountCallOutcome} rather than the `ActionResult`
+ * envelope the checkout operations use, because there is nothing to carry: the
+ * API's answer to a one-shot credential is whether it was accepted and, if
+ * not, which `ErrorCode` it refused with. That is a pure, serializable value —
+ * it crosses the Server Action boundary unchanged — and `lib/account/*`
+ * interprets it in ONE place for both pages. The unreachable/unparseable arm
+ * borrows `UNREACHABLE_ERROR`'s code so the whole template spells that
+ * condition one way.
+ */
+/** Verify a customer's e-mail address with the token from their mail. */
+export async function verifyCustomerAccount(token: string): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.verifyCustomerAccount({ token });
+  });
+}
+/** Set a new password from the token in a password-reset mail. */
+export async function resetPassword(input: {
+  token: string;
+  password: string;
+}): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.resetPassword({ input });
+  });
+}
+/**
+ * Ask the platform to mail a password-reset link.
+ *
+ * The API's boolean answer (whether an account matched) is deliberately
+ * DISCARDED here rather than returned: surfacing it would let a visitor learn
+ * whether an address shops here, and a value this module returns is a value a
+ * page can render by accident. The neutral answer is decided once, in
+ * `lib/account/reset-password-state.ts`.
+ */
+export async function requestPasswordReset(emailAddress: string): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.requestPasswordReset({ emailAddress });
+  });
+}
+/**
+ * Ask the platform to send the verification mail again (#1471).
+ *
+ * The API's boolean is deliberately DISCARDED, exactly as the password-reset
+ * request's is: a value this module returns is a value a page can render by
+ * accident, and rendering whether an address is registered here is an
+ * enumeration oracle. The neutral answer is decided once, in
+ * `lib/account/register-state.ts`.
+ *
+ * Unauthenticated by necessity rather than by convenience. A shopper who never
+ * confirmed their address cannot log in at all, so a resend sitting behind a
+ * login would be unreachable by precisely the people who need it.
+ */
+export async function requestCustomerVerification(
+  emailAddress: string,
+): Promise<AccountCallOutcome> {
+  return runAccountOperation(async (client) => {
+    await client.customer.requestCustomerVerification({ emailAddress });
+  });
+}
+/**
+ * Run one account operation and report its outcome.
+ *
+ * The `try` covers `getShopClient()` as well as the call, and that is
+ * deliberate: an unconfigured scaffold throws there (`assertShopConfigured`),
+ * and the prewarm contract says a storefront with no `.env` must SERVE rather
+ * than crash — so that failure has to arrive as a rendered state like any
+ * other, not as an unhandled throw inside a render.
+ *
+ * This is the template's one sanctioned use of `catch`: wrapping an external
+ * SDK's errors at the call site, exactly as `shop-session.ts#runSessionOp` and
+ * `server/runner.ts` already do. Nothing is swallowed — every failure leaves
+ * here as a code the page renders.
+ */
+async function runAccountOperation(
+  operation: (client: ForgeCartShopClient) => Promise<void>,
+): Promise<AccountCallOutcome> {
+  try {
+    await operation(await getShopClient());
+    return { kind: 'ok' };
+  } catch (error) {
+    return { kind: 'error', code: extractError(error)?.code ?? UNREACHABLE_ERROR.code };
+  }
+}

package/templates/storefront/src/lib/format.ts CHANGED Viewed

@@ -3,6 +3,8 @@ import type {
   ShopSellingPlanFieldFragment as SellingPlan,
 } from '@forgecart/sdk/shop';
+import { toMajorUnits } from './money';
 /**
  * Pure display helpers over SDK types — safe to import from ANY component.
  *
@@ -18,22 +20,18 @@ import type {
  * Format a minor-unit price as a currency string. Defaults to USD; pass a
  * different ISO currency code as needed.
  *
- * ForgeCart prices are integers in the currency's smallest denomination, so
- * the divisor depends on the currency's ISO-4217 exponent: 2500 is $25.00
- * (two-decimal cents) but ¥2,500 (zero-decimal yen) and BHD 2.500
- * (three-decimal fils). The exponent is derived from the same
- * `Intl.NumberFormat` instance that renders the price — its
- * `resolvedOptions().maximumFractionDigits` carries the CLDR fraction digits
- * for the currency — so the divisor always agrees with the digits shown,
- * with a defensive fallback of 2 should the formatter resolve none.
+ * The minor-unit divisor comes from {@link toMajorUnits}, which derives the
+ * currency's ISO-4217 exponent from CLDR — never a hardcoded hundred, which is
+ * wrong for zero-decimal yen and three-decimal fils. That derivation moved to
+ * `lib/money.ts` when the JSON-LD layer acquired the second consumer: the
+ * shopper-facing string and the machine-readable `Offer.price` disagreeing
+ * about what 2500 means would publish one price to people and another to
+ * search engines.
  */
 export function formatPrice(minorUnits: number, currency = 'USD'): string {
-  const formatter = new Intl.NumberFormat('en-US', {
-    style: 'currency',
-    currency,
-  });
-  const exponent = formatter.resolvedOptions().maximumFractionDigits ?? 2;
-  return formatter.format(minorUnits / 10 ** exponent);
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(
+    toMajorUnits(minorUnits, currency),
+  );
 }
 /** Lowest variant price for a product, in minor units, or `null` if none. */

package/templates/storefront/src/lib/identify-forward.ts ADDED Viewed

@@ -0,0 +1,152 @@
+import {
+  buildUpstreamHeaders,
+  getUpstreamConfig,
+  readMintedSessionToken,
+  type ForwardHeaders,
+} from './track-forward';
+/**
+ * Marketing-identity upstream forwarder (#1596).
+ *
+ * ONE implementation of "tell the ForgeCart shop API which ad click this
+ * shopper arrived from". The click IDs a landing URL carries (`gclid`,
+ * `fbclid`, `ttclid`) are read on the client by `lib/marketing-params.ts`,
+ * posted to the same-origin `/__fc/identify` relay, and land here as a single
+ * `setMarketingIdentifiers` mutation.
+ *
+ * Why a module of its own rather than a branch inside `track-forward.ts`: a
+ * click ID is not an event. It names the IDENTITY the events belong to, it is
+ * sent once per landing instead of once per batch, and the ad platforms read it
+ * back out of that identity months later when a conversion is reported. The two
+ * forwarders share their TRANSPORT and nothing else — `getUpstreamConfig`,
+ * `buildUpstreamHeaders` and `readMintedSessionToken` live next door and are
+ * imported rather than restated, so the session a request rides can never
+ * differ between them; the shapes stay apart because they describe different
+ * things.
+ *
+ * Same discipline as the event forwarder, for the same reasons: raw HTTP
+ * GraphQL (the generated SDK transports over one WebSocket whose connection
+ * pins ONE identity, and has no plain-HTTP query path), inert while
+ * `forgecart init` has not written `.env` yet, and EVERY failure mode —
+ * missing config, network, HTTP status, GraphQL errors — resolving to a typed
+ * negative outcome instead of a throw. Attribution must never break the page
+ * the shopper came for.
+ */
+/**
+ * The SDK's own `ShopSetMarketingIdentifiers` document, inlined verbatim.
+ *
+ * Kept character-identical to the shipped operation
+ * (`app/client-sdk-generators/src/operations/shop/marketing-identity.graphql`)
+ * so checking the two for drift is a diff rather than a reading. `identityId`
+ * belongs to that document and is deliberately not read below: the storefront
+ * has no use for the backend's internal id, and the client it answers has even
+ * less.
+ */
+const SET_MARKETING_IDENTIFIERS_MUTATION = `mutation ShopSetMarketingIdentifiers($input: SetMarketingIdentifiersInput!) {
+  setMarketingIdentifiers(input: $input) {
+    identityId
+    accepted
+    rejected
+  }
+}`;
+/**
+ * One click ID, shaped for the API's `MarketingIdentifierInput`.
+ *
+ * The client parser's `MarketingIdentifier` is the same pair by design — this
+ * declaration exists because the SERVER side of the hop mirrors the SDL (the
+ * sibling's `TrackEventInput` does the same), and the relay route rebuilds the
+ * pair from untrusted JSON rather than trusting anything the client typed.
+ */
+export interface MarketingIdentifierInput {
+  /** The registered identifier key the value is stored under. */
+  key: string;
+  /** The click ID exactly as the ad platform wrote it into the URL. */
+  value: string;
+}
+/**
+ * What the upstream made of the identifiers.
+ *
+ * `rejected` is NOT an error and must never be turned into one. The backend
+ * partitions the submitted keys against its identifier registry, stores the
+ * ones it knows, drops the ones it does not and REPORTS both — no throw, no
+ * rollback, no partial failure (`MarketingIdentityService.setIdentifiersForShop`).
+ * A key landing in `rejected` wrote no row and broke nothing; it means only
+ * that this storefront and the backend registry disagree about a spelling,
+ * which is a deployment fact worth being able to read and not a runtime
+ * condition to handle. Nothing downstream may treat a non-empty `rejected` as a
+ * reason to retry, to fail the request, or to hold up the page.
+ */
+export interface IdentifyOutcome {
+  /** Identifier keys the backend recognised and stored. */
+  accepted: readonly string[];
+  /** Keys it does not know — dropped upstream; see the note above. */
+  rejected: readonly string[];
+  /** Session token surfaced in the response extensions, if any. */
+  sessionToken: string | null;
+}
+interface GraphQLIdentifyResponse {
+  data?: {
+    setMarketingIdentifiers?: { accepted?: string[]; rejected?: string[] } | null;
+  } | null;
+  errors?: unknown[];
+  extensions?: Record<string, unknown>;
+}
+/** The outcome every failure mode answers with: nothing stored, nothing minted. */
+const NO_IDENTIFIERS_STORED: IdentifyOutcome = { accepted: [], rejected: [], sessionToken: null };
+/**
+ * Forward the captured click IDs as one raw HTTP GraphQL POST.
+ *
+ * One call for the whole list — the mutation takes an array and the backend
+ * writes them against a single identity, so there is no per-item sequencing to
+ * get wrong here (the event relay loops only because `trackEvent` takes one
+ * event at a time).
+ *
+ * Any failure — missing config, network, HTTP status, GraphQL errors —
+ * resolves to an empty outcome; the forwarder is best-effort by design and the
+ * outcome is terminal (callers never retry).
+ */
+export async function forwardMarketingIdentifiers(
+  identifiers: readonly MarketingIdentifierInput[],
+  forward: ForwardHeaders,
+): Promise<IdentifyOutcome> {
+  const upstream = getUpstreamConfig();
+  if (!upstream) return NO_IDENTIFIERS_STORED;
+  try {
+    const response = await fetch(upstream.shopApiUrl, {
+      method: 'POST',
+      headers: buildUpstreamHeaders(upstream.channelToken, forward),
+      body: JSON.stringify({
+        query: SET_MARKETING_IDENTIFIERS_MUTATION,
+        variables: { input: { identifiers } },
+      }),
+    });
+    if (!response.ok) return NO_IDENTIFIERS_STORED;
+    const payload = (await response.json()) as GraphQLIdentifyResponse;
+    // Read the mint even when the mutation itself did not answer: a cookie-less
+    // request mints the session in middleware, BEFORE the resolver runs, so the
+    // token is real regardless of what happened to the identifiers — and the
+    // relay must persist it or the next request mints a second identity.
+    const capturedToken = readMintedSessionToken(payload.extensions);
+    const result = payload.data?.setMarketingIdentifiers;
+    if (!result) return { accepted: [], rejected: [], sessionToken: capturedToken };
+    return {
+      accepted: result.accepted ?? [],
+      rejected: result.rejected ?? [],
+      sessionToken: capturedToken,
+    };
+  } catch {
+    // Best-effort by design: an unreachable or still-booting backend must never
+    // break the landing page. The click ID is lost with the page view it came
+    // with, which is the accepted cost of never letting analytics hold up a
+    // shopper — no caller retries.
+    return NO_IDENTIFIERS_STORED;
+  }
+}