@shop-on/customer-runtime 0.0.0-stage → 0.2.0

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/customer-session-handoff.d.ts

@@ -0,0 +1,15 @@
+import { ConsumeResult } from "./handoff.js";
+//#region src/customer-session-handoff.d.ts
+export interface CustomerSessionHandoffPayload {
+  shopHandle: string;
+  customerSessionToken: string;
+  customerSessionExpiresAt: string;
+  /** Customer's email if Rails has one. Some accounts auth by phone, so
+   *  this can be absent; consumers fall back to the form input. */
+  customerEmail?: string;
+  createdAt: number;
+}
+export declare function createCustomerSessionHandoff(payload: CustomerSessionHandoffPayload): Promise<string>;
+export declare function consumeCustomerSessionHandoff(nonce: string): Promise<ConsumeResult<CustomerSessionHandoffPayload>>;
+//#endregion
+export type { ConsumeResult };

package/dist/customer-session-handoff.js

@@ -0,0 +1,12 @@
+import { internalDelete, internalPost } from "./internal-api.js";
+//#region src/customer-session-handoff.ts
+const KIND = "customer_session_handoff";
+async function createCustomerSessionHandoff(payload) {
+	const { nonce } = await internalPost(`handoff/${KIND}`, { payload });
+	return nonce;
+}
+async function consumeCustomerSessionHandoff(nonce) {
+	return internalDelete(`handoff/${KIND}/${encodeURIComponent(nonce)}`);
+}
+//#endregion
+export { consumeCustomerSessionHandoff, createCustomerSessionHandoff };

package/dist/graphql.d.ts

@@ -0,0 +1,21 @@
+import { TadaDocumentNode } from "gql.tada";
+//#region src/graphql.d.ts
+export interface StorefrontRequestOptions {
+  /** Pass through as `X-Customer-Session` so the Rails resolver can attach
+   *  customer context to the call. Required for customer-scoped operations
+   *  (e.g. `customerLogout`); omit for unauthenticated cart/checkout flows. */
+  customerSessionToken?: string;
+}
+/**
+ * Typed GraphQL request against the Rails storefront endpoint, authenticated
+ * via the per-shop OAuth client_credentials token from `oauth.ts`. On a 401
+ * the token it sent is evicted and the request retried once — handles clock
+ * skew and silent revocation without bubbling a transient error up.
+ *
+ * GraphQL-level errors surface as `ClientError` from `graphql-request`.
+ * `customer-runtime` doesn't own the schema (each consuming app brings its
+ * own gql.tada setup) so `TResult` / `TVariables` come from the caller's
+ * document type.
+ */
+export declare function storefrontRequest<TResult, TVariables extends Record<string, unknown> = Record<string, unknown>>(shopHandle: string, document: TadaDocumentNode<TResult, TVariables>, variables?: TVariables, options?: StorefrontRequestOptions): Promise<TResult>;
+//#endregion

package/dist/graphql.js

@@ -0,0 +1,43 @@
+import { relayHeaders } from "./relay.js";
+import { traceHeaders } from "./trace.js";
+import { evictStorefrontToken, getStorefrontToken } from "./oauth.js";
+import { ClientError, GraphQLClient } from "graphql-request";
+//#region src/graphql.ts
+const API_URL = process.env.SPN_CUSTOMER_API_URL ?? "http://localhost:3003";
+function buildClient(token, extra) {
+	return new GraphQLClient(`${API_URL}/graphql`, { headers: {
+		Authorization: `Bearer ${token}`,
+		...extra
+	} });
+}
+/**
+* Typed GraphQL request against the Rails storefront endpoint, authenticated
+* via the per-shop OAuth client_credentials token from `oauth.ts`. On a 401
+* the token it sent is evicted and the request retried once — handles clock
+* skew and silent revocation without bubbling a transient error up.
+*
+* GraphQL-level errors surface as `ClientError` from `graphql-request`.
+* `customer-runtime` doesn't own the schema (each consuming app brings its
+* own gql.tada setup) so `TResult` / `TVariables` come from the caller's
+* document type.
+*/
+async function storefrontRequest(shopHandle, document, variables, options) {
+	const extra = {
+		...options?.customerSessionToken ? { "X-Customer-Session": options.customerSessionToken } : {},
+		...traceHeaders(),
+		...relayHeaders()
+	};
+	let token = await getStorefrontToken(shopHandle);
+	try {
+		return await buildClient(token, extra).request(document, variables);
+	} catch (err) {
+		if (err instanceof ClientError && err.response.status === 401) {
+			evictStorefrontToken(shopHandle, token);
+			token = await getStorefrontToken(shopHandle);
+			return await buildClient(token, extra).request(document, variables);
+		}
+		throw err;
+	}
+}
+//#endregion
+export { storefrontRequest };

package/dist/handoff.d.ts

@@ -0,0 +1,19 @@
+//#region src/handoff.d.ts
+export interface HandoffPayload {
+  shopHandle: string;
+  cartToken: string;
+  customerSessionToken?: string;
+  customerSessionExpiresAt?: string;
+  customerEmail?: string;
+  createdAt: number;
+}
+export type ConsumeResult<P> = {
+  ok: true;
+  payload: P;
+} | {
+  ok: false;
+  reason: "missing_or_consumed" | "malformed";
+};
+export declare function createHandoff(payload: HandoffPayload): Promise<string>;
+export declare function consumeHandoff(nonce: string): Promise<ConsumeResult<HandoffPayload>>;
+//#endregion

package/dist/handoff.js

@@ -0,0 +1,12 @@
+import { internalDelete, internalPost } from "./internal-api.js";
+//#region src/handoff.ts
+const KIND = "checkout_handoff";
+async function createHandoff(payload) {
+	const { nonce } = await internalPost(`handoff/${KIND}`, { payload });
+	return nonce;
+}
+async function consumeHandoff(nonce) {
+	return internalDelete(`handoff/${KIND}/${encodeURIComponent(nonce)}`);
+}
+//#endregion
+export { consumeHandoff, createHandoff };

package/dist/internal-api.js

@@ -0,0 +1,72 @@
+import { relayHeaders } from "./relay.js";
+import { traceHeaders } from "./trace.js";
+//#region src/internal-api.ts
+function apiUrl() {
+	return process.env.SPN_CUSTOMER_API_URL ?? "http://localhost:3003";
+}
+function internalSecret() {
+	return process.env.SPN_INTERNAL_API_SECRET ?? "";
+}
+var InternalApiError = class extends Error {
+	status;
+	bodySnippet;
+	constructor(path, status, bodySnippet) {
+		super(`[customer-runtime/internal-api] ${path} returned ${status}: ${bodySnippet}`);
+		this.name = "InternalApiError";
+		this.status = status;
+		this.bodySnippet = bodySnippet;
+	}
+};
+function requireSecret(path) {
+	const secret = internalSecret();
+	if (!secret) throw new Error(`[customer-runtime/internal-api] SPN_INTERNAL_API_SECRET is unset; refusing to call ${path} without auth`);
+	return secret;
+}
+async function readBodySnippet(res) {
+	try {
+		return (await res.text()).slice(0, 200);
+	} catch {
+		return "";
+	}
+}
+/**
+* POST a JSON body to `/api/internal/customer/<path>`. Throws
+* `InternalApiError` on non-2xx so callers can decide how to map status →
+* domain outcome (e.g. token mint maps 404 → CredentialsUnavailableError).
+*/
+async function internalPost(path, body, { signal } = {}) {
+	const secret = requireSecret(path);
+	const res = await fetch(`${apiUrl()}/api/internal/customer/${path}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-Internal-Auth": secret,
+			...traceHeaders(),
+			...relayHeaders()
+		},
+		body: JSON.stringify(body),
+		signal
+	});
+	if (!res.ok) throw new InternalApiError(path, res.status, await readBodySnippet(res));
+	return await res.json();
+}
+/**
+* DELETE `/api/internal/customer/<path>`. Used by the handoff consume path —
+* the endpoint always returns 200 (with `{ ok: false, reason }` on miss), so
+* a non-2xx here is a real error, not a domain miss.
+*/
+async function internalDelete(path) {
+	const secret = requireSecret(path);
+	const res = await fetch(`${apiUrl()}/api/internal/customer/${path}`, {
+		method: "DELETE",
+		headers: {
+			"X-Internal-Auth": secret,
+			...traceHeaders(),
+			...relayHeaders()
+		}
+	});
+	if (!res.ok) throw new InternalApiError(path, res.status, await readBodySnippet(res));
+	return await res.json();
+}
+//#endregion
+export { InternalApiError, internalDelete, internalPost };

package/dist/lease.d.ts

@@ -0,0 +1,26 @@
+//#region src/lease.d.ts
+export interface Lease<T> {
+  run(key: string, work: () => Promise<T>): Promise<T>;
+  /** A live lease exists and this request isn't the one running it. */
+  heldByOther(key: string): boolean;
+  /** Test-only: outcome records not yet swept. */
+  outcomeCount(): number;
+  /** Test-only: lease records not yet released or swept. */
+  leaseCount(): number;
+}
+/**
+ * One `work` per key across concurrent requests. The first caller takes the
+ * lease and runs `work`; others poll on their own timer and take the outcome
+ * it settles with (value or error). If the holder never settles, the next
+ * waiter takes over once the lease expires. Calls within one request share
+ * that request's promise directly.
+ *
+ * `work` must not re-enter its own key — within one request it would await
+ * itself. It should settle within `leaseMs`; after that a waiter takes over
+ * and the two run concurrently.
+ */
+export declare function createLease<T>({ leaseMs, pollMs }?: {
+  leaseMs?: number;
+  pollMs?: number;
+}): Lease<T>;
+//#endregion

package/dist/lease.js

@@ -0,0 +1,86 @@
+import { requestSlot } from "./request-scope.js";
+//#region src/lease.ts
+const isLive = (lease) => lease !== void 0 && lease.until > Date.now();
+/**
+* One `work` per key across concurrent requests. The first caller takes the
+* lease and runs `work`; others poll on their own timer and take the outcome
+* it settles with (value or error). If the holder never settles, the next
+* waiter takes over once the lease expires. Calls within one request share
+* that request's promise directly.
+*
+* `work` must not re-enter its own key — within one request it would await
+* itself. It should settle within `leaseMs`; after that a waiter takes over
+* and the two run concurrently.
+*/
+function createLease({ leaseMs = 3e3, pollMs = 10 } = {}) {
+	const leases = /* @__PURE__ */ new Map();
+	const outcomes = /* @__PURE__ */ new Map();
+	const SLOT = Symbol("lease");
+	const ownSlot = () => requestSlot(SLOT, () => /* @__PURE__ */ new Map());
+	const sweep = (now) => {
+		for (const [k, outcome] of outcomes) if (now - outcome.settledAt > leaseMs) outcomes.delete(k);
+		for (const [k, lease] of leases) if (lease.until <= now) leases.delete(k);
+	};
+	const take = (key, work, slot) => {
+		const takenAt = Date.now();
+		sweep(takenAt);
+		const owner = {};
+		leases.set(key, {
+			until: takenAt + leaseMs,
+			owner
+		});
+		let promise;
+		try {
+			promise = work();
+		} catch (error) {
+			promise = Promise.reject(error);
+		}
+		slot?.set(key, promise);
+		const settle = (result) => {
+			const now = Date.now();
+			const latest = outcomes.get(key);
+			if (!latest || latest.takenAt <= takenAt) outcomes.set(key, {
+				takenAt,
+				settledAt: now,
+				...result
+			});
+			if (leases.get(key)?.owner === owner) leases.delete(key);
+			if (slot?.get(key) === promise) slot.delete(key);
+			sweep(now);
+		};
+		promise.then((value) => settle({
+			ok: true,
+			value
+		}), (error) => settle({
+			ok: false,
+			error
+		}));
+		return promise;
+	};
+	const run = async (key, work) => {
+		const slot = ownSlot();
+		const own = slot?.get(key);
+		if (own) return await own;
+		let waitStart;
+		while (isLive(leases.get(key))) {
+			waitStart ??= Date.now();
+			await new Promise((resolve) => setTimeout(resolve, pollMs));
+			const mine = slot?.get(key);
+			if (mine) return await mine;
+			const outcome = outcomes.get(key);
+			if (outcome && outcome.settledAt >= waitStart) {
+				if (outcome.ok) return outcome.value;
+				throw outcome.error;
+			}
+		}
+		return await take(key, work, slot);
+	};
+	return {
+		run,
+		heldByOther: (key) => isLive(leases.get(key)) && !ownSlot()?.has(key),
+		outcomeCount: () => outcomes.size,
+		leaseCount: () => leases.size
+	};
+}
+//#endregion
+export { createLease };

package/dist/oauth.d.ts

@@ -0,0 +1,38 @@
+//#region src/oauth.d.ts
+export declare const MINT_LEASE_MS = 3000;
+export declare const MINT_FAILURE_HOLD_MS = 2000;
+export declare class OAuthMintError extends Error {
+  readonly shopHandle: string;
+  /** True when Rails returned 404 — the shop doesn't exist. (A shop with no
+   *  storefront application is a 422, treated as transient.) Distinguishes
+   *  "this shop is gone" from "the network is flaky". Routes use this to
+   *  decide between rendering the shop-not-found page and the transient-error
+   *  page. */
+  readonly notFound: boolean;
+  /** True when Rails returned 429 naming the `relay/ip` throttle — the
+   *  buyer's own bucket, not one other buyers share. */
+  readonly buyerThrottled: boolean;
+  constructor(shopHandle: string, detail: string, opts?: {
+    notFound?: boolean;
+    buyerThrottled?: boolean;
+  });
+}
+/**
+ * Get (or mint) the storefront access token for `shopHandle`. Cached
+ * in-process; concurrent requests for one shop share one mint's outcome
+ * through the mint lease, so a cold cache costs exactly one Rails round-trip.
+ * Throws `ShopHandleInvalidError` on a malformed handle, which can arrive here
+ * unchecked from a server route or an RPC call.
+ */
+export declare function getStorefrontToken(shopHandle: string): Promise<string>;
+/**
+ * Drop the cached token for `shopHandle` if it is still `token`. Call when a
+ * Rails response signals `token` is no longer valid (typically a 401 from a
+ * downstream GraphQL request) so the next call re-mints. Compare-and-clear: a
+ * concurrent caller may already have re-minted, and a late 401 on the old
+ * token must not throw the new one away.
+ */
+export declare function evictStorefrontToken(shopHandle: string, token: string): void;
+export declare function __resetForTesting(): void;
+export declare function __mintHoldCountForTesting(): number;
+//#endregion

package/dist/oauth.js

@@ -0,0 +1,137 @@
+import { InternalApiError, internalPost } from "./internal-api.js";
+import { createLease } from "./lease.js";
+import { resolveShopHandleFromParams } from "./shop-context.js";
+//#region src/oauth.ts
+const REFRESH_SKEW_MS = 3e5;
+const STALE_TOKEN_MARGIN_MS = 3e4;
+const CACHE_MAX_ENTRIES = 1e3;
+const cache = /* @__PURE__ */ new Map();
+const MINT_LEASE_MS = 3e3;
+let mintLease = createLease({ leaseMs: MINT_LEASE_MS });
+const MINT_TIMEOUT_MS = 2750;
+const MINT_FAILURE_HOLD_MS = 2e3;
+const mintHolds = /* @__PURE__ */ new Map();
+function touch(shopHandle, token) {
+	cache.delete(shopHandle);
+	cache.set(shopHandle, token);
+	if (cache.size > CACHE_MAX_ENTRIES) {
+		const oldest = cache.keys().next().value;
+		if (oldest !== void 0) cache.delete(oldest);
+	}
+}
+var OAuthMintError = class extends Error {
+	shopHandle;
+	/** True when Rails returned 404 — the shop doesn't exist. (A shop with no
+	*  storefront application is a 422, treated as transient.) Distinguishes
+	*  "this shop is gone" from "the network is flaky". Routes use this to
+	*  decide between rendering the shop-not-found page and the transient-error
+	*  page. */
+	notFound;
+	/** True when Rails returned 429 naming the `relay/ip` throttle — the
+	*  buyer's own bucket, not one other buyers share. */
+	buyerThrottled;
+	constructor(shopHandle, detail, opts) {
+		super(`[customer-runtime/oauth] token mint failed for shop ${shopHandle}: ${detail}`);
+		this.name = "OAuthMintError";
+		this.shopHandle = shopHandle;
+		this.notFound = opts?.notFound ?? false;
+		this.buyerThrottled = opts?.buyerThrottled ?? false;
+	}
+};
+function throttleName(bodySnippet) {
+	try {
+		return JSON.parse(bodySnippet).throttle;
+	} catch {
+		return;
+	}
+}
+async function mintToken(shopHandle) {
+	let response;
+	try {
+		response = await internalPost("storefront-token", { shop_handle: shopHandle }, { signal: AbortSignal.timeout(MINT_TIMEOUT_MS) });
+	} catch (err) {
+		if (err instanceof InternalApiError) throw new OAuthMintError(shopHandle, `${err.status}: ${err.bodySnippet}`, {
+			notFound: err.status === 404,
+			buyerThrottled: err.status === 429 && throttleName(err.bodySnippet) === "relay/ip"
+		});
+		throw new OAuthMintError(shopHandle, err instanceof Error ? err.message : String(err));
+	}
+	if (typeof response.access_token !== "string" || response.access_token.length === 0) throw new OAuthMintError(shopHandle, "missing or invalid access_token in response");
+	const expiresAtMs = Date.parse(response.expires_at);
+	if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now()) throw new OAuthMintError(shopHandle, `invalid expires_at: ${String(response.expires_at)}`);
+	return {
+		accessToken: response.access_token,
+		expiresAtMs
+	};
+}
+function activeMintHold(shopHandle) {
+	const hold = mintHolds.get(shopHandle);
+	return hold && hold.until > Date.now() ? hold : null;
+}
+function holdMint(shopHandle, error) {
+	const now = Date.now();
+	for (const [k, hold] of mintHolds) if (hold.until <= now) mintHolds.delete(k);
+	mintHolds.set(shopHandle, {
+		until: now + MINT_FAILURE_HOLD_MS,
+		error
+	});
+}
+async function mintUnderLease(shopHandle) {
+	let fresh;
+	try {
+		fresh = await mintToken(shopHandle);
+	} catch (err) {
+		if (err instanceof OAuthMintError && err.notFound) cache.delete(shopHandle);
+		if (!(err instanceof OAuthMintError && err.buyerThrottled)) holdMint(shopHandle, err);
+		throw err;
+	}
+	mintHolds.delete(shopHandle);
+	touch(shopHandle, fresh);
+	return fresh;
+}
+/**
+* Get (or mint) the storefront access token for `shopHandle`. Cached
+* in-process; concurrent requests for one shop share one mint's outcome
+* through the mint lease, so a cold cache costs exactly one Rails round-trip.
+* Throws `ShopHandleInvalidError` on a malformed handle, which can arrive here
+* unchecked from a server route or an RPC call.
+*/
+async function getStorefrontToken(shopHandle) {
+	resolveShopHandleFromParams({ shopHandle });
+	const now = Date.now();
+	const hit = cache.get(shopHandle);
+	if (hit && hit.expiresAtMs - REFRESH_SKEW_MS > now) {
+		touch(shopHandle, hit);
+		return hit.accessToken;
+	}
+	const prev = hit && hit.expiresAtMs - STALE_TOKEN_MARGIN_MS > now ? hit.accessToken : null;
+	const held = activeMintHold(shopHandle);
+	if (prev && (held || mintLease.heldByOther(shopHandle))) return prev;
+	if (held) throw held.error;
+	try {
+		return (await mintLease.run(shopHandle, () => mintUnderLease(shopHandle))).accessToken;
+	} catch (err) {
+		if (prev && cache.get(shopHandle)?.accessToken === prev) return prev;
+		throw err;
+	}
+}
+/**
+* Drop the cached token for `shopHandle` if it is still `token`. Call when a
+* Rails response signals `token` is no longer valid (typically a 401 from a
+* downstream GraphQL request) so the next call re-mints. Compare-and-clear: a
+* concurrent caller may already have re-minted, and a late 401 on the old
+* token must not throw the new one away.
+*/
+function evictStorefrontToken(shopHandle, token) {
+	if (cache.get(shopHandle)?.accessToken === token) cache.delete(shopHandle);
+}
+function __resetForTesting() {
+	cache.clear();
+	mintHolds.clear();
+	mintLease = createLease({ leaseMs: MINT_LEASE_MS });
+}
+function __mintHoldCountForTesting() {
+	return mintHolds.size;
+}
+//#endregion
+export { MINT_FAILURE_HOLD_MS, MINT_LEASE_MS, OAuthMintError, __mintHoldCountForTesting, __resetForTesting, evictStorefrontToken, getStorefrontToken };

package/dist/relay.d.ts

@@ -0,0 +1,8 @@
+//#region src/relay.d.ts
+/**
+ * `X-Buyer-IP` from Cloudflare's `CF-Connecting-IP` on the request this call
+ * runs under, plus `X-Relay-Auth` when SPN_RELAY_SECRET is set. Empty outside
+ * a request or without a valid IP. Spread these last into outgoing headers.
+ */
+export declare function relayHeaders(): Record<string, string>;
+//#endregion

package/dist/relay.js

@@ -0,0 +1,24 @@
+import { currentRequest } from "./request-scope.js";
+//#region src/relay.ts
+const IPV4_OCTET = "(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
+const IPV4 = new RegExp(`^${IPV4_OCTET}(\\.${IPV4_OCTET}){3}$`);
+function isIP(value) {
+	if (IPV4.test(value)) return true;
+	return /^[\da-f:.]+$/i.test(value) && value.includes(":") && URL.canParse(`http://[${value}]`);
+}
+/**
+* `X-Buyer-IP` from Cloudflare's `CF-Connecting-IP` on the request this call
+* runs under, plus `X-Relay-Auth` when SPN_RELAY_SECRET is set. Empty outside
+* a request or without a valid IP. Spread these last into outgoing headers.
+*/
+function relayHeaders() {
+	const ip = currentRequest()?.headers.get("cf-connecting-ip");
+	if (!ip || !isIP(ip)) return {};
+	const secret = process.env.SPN_RELAY_SECRET;
+	return secret ? {
+		"X-Buyer-IP": ip,
+		"X-Relay-Auth": secret
+	} : { "X-Buyer-IP": ip };
+}
+//#endregion
+export { relayHeaders };

package/dist/request-scope.d.ts

@@ -0,0 +1,9 @@
+//#region src/request-scope.d.ts
+/** The request this call runs under; undefined outside one (browser, tests, pre-handler). */
+export declare function currentRequest(): Request | undefined;
+/**
+ * Per-request state under `key`, created by `init` on first use. Undefined
+ * outside a request — callers fall back to not sharing at all.
+ */
+export declare function requestSlot<T>(key: symbol, init: () => T): T | undefined;
+//#endregion

package/dist/request-scope.js

@@ -0,0 +1,24 @@
+//#region src/request-scope.ts
+const EVENT_STORAGE_KEY = Symbol.for("tanstack-start:event-storage");
+/** The request this call runs under; undefined outside one (browser, tests, pre-handler). */
+function currentRequest() {
+	return globalThis[EVENT_STORAGE_KEY]?.getStore()?.request;
+}
+const slots = /* @__PURE__ */ new WeakMap();
+/**
+* Per-request state under `key`, created by `init` on first use. Undefined
+* outside a request — callers fall back to not sharing at all.
+*/
+function requestSlot(key, init) {
+	const req = currentRequest();
+	if (!req) return void 0;
+	let bag = slots.get(req);
+	if (!bag) {
+		bag = /* @__PURE__ */ new Map();
+		slots.set(req, bag);
+	}
+	if (!bag.has(key)) bag.set(key, init());
+	return bag.get(key);
+}
+//#endregion
+export { currentRequest, requestSlot };

package/dist/sealed-session.d.ts

@@ -0,0 +1,27 @@
+//#region src/sealed-session.d.ts
+export interface SealedSessionConfig {
+  name: string;
+  /** At least 32 chars. */
+  password: string;
+  /** Seconds. Seal TTL plus an absolute cap counted from the first write. */
+  maxAge?: number;
+  cookie: {
+    secure: boolean;
+    httpOnly: true;
+    sameSite: "lax";
+    path: "/";
+    /** Seconds. Sent as Max-Age, refreshed on every write. */
+    maxAge?: number;
+  };
+}
+export interface SealedSession<T> {
+  /** Live: reflects every write committed so far in this request. */
+  readonly data: Partial<T>;
+  update(patch: Partial<T>): Promise<void>;
+  clear(): Promise<void>;
+}
+export declare class SessionTooLargeError extends Error {
+  constructor(name: string, length: number);
+}
+export declare function openSession<T>(config: SealedSessionConfig): Promise<SealedSession<T>>;
+//#endregion

package/dist/sealed-session.js

@@ -0,0 +1,154 @@
+import { requestSlot } from "./request-scope.js";
+import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server";
+import { defaults, seal, unseal } from "iron-webcrypto";
+//#region src/sealed-session.ts
+/**
+* Encrypted cookie sessions, wire-compatible with the `useSession` TanStack
+* Start 1.168 shipped (h3 2.0.1-rc.20) and 1.169 removed. Both seal
+* `{ id, createdAt, data }` with iron (Fe26.2, iron's defaults), so a cookie
+* either one wrote opens in the other — no sign-out on deploy, and a rollback
+* stays safe. `test/fixtures/h3-sessions.json` holds cookies Start 1.168
+* minted; `test/sealed-session.test.ts` keeps them opening.
+*
+* Where it deliberately differs from h3:
+* - A read never writes. h3 minted and set an empty session on every
+*   cookieless read.
+* - `clear()` sticks for the rest of the request. h3 re-read the stale
+*   request cookie afterwards.
+* - Writes are one cookie, never chunked. A seal over 3,800 chars throws
+*   `SessionTooLargeError` instead. h3's chunked cookies still open, and
+*   the next write or clear deletes their chunks.
+* - No `x-<name>-session` request header.
+*
+* Each request shares one state per cookie name (`requestSlot`), so parallel
+* opens unseal once, and writes queue: each merges onto the state the one
+* before it committed, in call order.
+*/
+var SessionTooLargeError = class extends Error {
+	constructor(name, length) {
+		super(`Session "${name}" seals to ${length} chars, over the ${MAX_SEALED_LENGTH} limit`);
+		this.name = "SessionTooLargeError";
+	}
+};
+const MAX_SEALED_LENGTH = 3800;
+const CHUNKED = "__chunked__";
+const MAX_CHUNKS = 100;
+const DEFAULT_COOKIE = {
+	path: "/",
+	secure: true,
+	httpOnly: true
+};
+const empty = () => ({
+	id: "",
+	createdAt: 0,
+	data: {}
+});
+async function openSession(config) {
+	if (typeof config.password !== "string" || config.password.length < 32) throw new Error(`Session "${config.name}" needs a password of at least 32 characters`);
+	const init = () => {
+		const slot = {
+			chain: Promise.resolve(),
+			state: empty()
+		};
+		slot.chain = read(config).then((state) => {
+			slot.state = state;
+		});
+		return slot;
+	};
+	const slot = requestSlot(Symbol.for(`shop-on:sealed-session:${config.name}`), init) ?? init();
+	await slot.chain;
+	const enqueue = (run) => {
+		const result = slot.chain.then(run);
+		slot.chain = result.catch(() => {});
+		return result;
+	};
+	return {
+		get data() {
+			return slot.state.data;
+		},
+		update: (patch) => enqueue(() => write(config, slot, patch)),
+		clear: () => enqueue(() => {
+			slot.state = empty();
+			deleteCookie(config.name, {
+				...DEFAULT_COOKIE,
+				...config.cookie
+			});
+			deleteChunks(config);
+		})
+	};
+}
+function sealOptions(config) {
+	return {
+		...defaults,
+		ttl: config.maxAge ? config.maxAge * 1e3 : 0
+	};
+}
+async function read(config) {
+	const sealed = readSealed(config.name);
+	if (!sealed) return empty();
+	try {
+		const opened = await unseal(sealed, config.password, sealOptions(config));
+		if (typeof opened?.id !== "string" || !opened.id || typeof opened.createdAt !== "number") return empty();
+		if (config.maxAge && Date.now() - opened.createdAt > config.maxAge * 1e3) return empty();
+		const data = opened.data && typeof opened.data === "object" ? { ...opened.data } : {};
+		return {
+			id: opened.id,
+			createdAt: opened.createdAt,
+			data
+		};
+	} catch {
+		return empty();
+	}
+}
+/** The request's sealed value, reassembled from h3's chunks when it split one. */
+function readSealed(name) {
+	const value = getCookie(name);
+	const count = chunkCount(value);
+	if (!count) return value?.startsWith(CHUNKED) ? void 0 : value;
+	const chunks = [];
+	for (let i = 1; i <= count; i++) {
+		const chunk = getCookie(`${name}.${i}`);
+		if (!chunk) return void 0;
+		chunks.push(chunk);
+	}
+	return chunks.join("");
+}
+function chunkCount(value) {
+	if (!value?.startsWith(CHUNKED)) return 0;
+	const count = Number.parseInt(value.slice(11), 10);
+	return Number.isInteger(count) && count >= 1 && count <= MAX_CHUNKS ? count : 0;
+}
+function deleteChunks(config) {
+	const count = chunkCount(getCookie(config.name));
+	for (let i = 1; i <= count; i++) deleteCookie(`${config.name}.${i}`, {
+		...DEFAULT_COOKIE,
+		...config.cookie
+	});
+}
+async function write(config, slot, patch) {
+	const previous = slot.state;
+	const fresh = !previous.id || Object.keys(previous.data).length === 0;
+	const data = JSON.parse(JSON.stringify({
+		...previous.data,
+		...patch
+	}));
+	const next = fresh ? {
+		id: globalThis.crypto.randomUUID(),
+		createdAt: Date.now(),
+		data
+	} : {
+		...previous,
+		data
+	};
+	const sealed = await seal(next, config.password, sealOptions(config));
+	if (sealed.length > MAX_SEALED_LENGTH) throw new SessionTooLargeError(config.name, sealed.length);
+	slot.state = next;
+	setCookie(config.name, sealed, {
+		...DEFAULT_COOKIE,
+		expires: config.maxAge ? new Date(next.createdAt + config.maxAge * 1e3) : void 0,
+		...config.cookie
+	});
+	deleteChunks(config);
+}
+//#endregion
+export { SessionTooLargeError, openSession };

package/dist/session-cookie.d.ts

@@ -0,0 +1,46 @@
+//#region src/session-cookie.d.ts
+/**
+ * Host-only encrypted session cookies for the central account and checkout
+ * apps. Both apps serve every shop from a single process, so we use one
+ * process-wide encryption secret per app and bind each cookie's payload to
+ * a specific `shopHandle`. A cookie minted for shop A is rejected at read
+ * time when the request resolves to shop B — `validateShopBinding` returns
+ * `undefined` for both "missing" and "wrong shop" so callers handle them
+ * uniformly (treat as logged-out).
+ *
+ * The returned `ShopBoundCookieConfig` is shape-compatible with
+ * `SealedSessionConfig` — pass it straight to `openSession`
+ * (`./sealed-session`). This module stays free of TanStack imports.
+ */
+export interface ShopBoundSession {
+  shopHandle: string;
+}
+export interface ShopBoundCookieConfig {
+  name: string;
+  password: string;
+  /** Seconds. Omit for a browser-session cookie. */
+  maxAge?: number;
+  cookie: {
+    secure: boolean;
+    httpOnly: true;
+    sameSite: "lax";
+    path: "/";
+  };
+}
+export declare function createShopBoundCookieConfig(opts: {
+  name: string;
+  password: string;
+  /** Override `process.env.NODE_ENV === "production"` for tests. */
+  secure?: boolean;
+  /** Seconds. Omit for a browser-session cookie. */
+  maxAge?: number;
+}): ShopBoundCookieConfig;
+/**
+ * Narrow a decoded session payload to its shop-bound form. Returns the
+ * payload only if it carries a `shopHandle` matching the expected value.
+ * Anything else (no payload, no shopHandle field, wrong shopHandle) returns
+ * `undefined`, which callers should treat as "no valid session for this
+ * shop in this request" — i.e. equivalent to logged-out.
+ */
+export declare function validateShopBinding<TData extends ShopBoundSession>(payload: Partial<TData> | undefined, expectedShopHandle: string): TData | undefined;
+//#endregion

package/dist/session-cookie.js

@@ -0,0 +1,28 @@
+//#region src/session-cookie.ts
+function createShopBoundCookieConfig(opts) {
+	return {
+		name: opts.name,
+		password: opts.password,
+		...opts.maxAge !== void 0 ? { maxAge: opts.maxAge } : {},
+		cookie: {
+			secure: opts.secure ?? process.env.NODE_ENV === "production",
+			httpOnly: true,
+			sameSite: "lax",
+			path: "/"
+		}
+	};
+}
+/**
+* Narrow a decoded session payload to its shop-bound form. Returns the
+* payload only if it carries a `shopHandle` matching the expected value.
+* Anything else (no payload, no shopHandle field, wrong shopHandle) returns
+* `undefined`, which callers should treat as "no valid session for this
+* shop in this request" — i.e. equivalent to logged-out.
+*/
+function validateShopBinding(payload, expectedShopHandle) {
+	if (!payload?.shopHandle) return void 0;
+	if (payload.shopHandle !== expectedShopHandle) return void 0;
+	return payload;
+}
+//#endregion
+export { createShopBoundCookieConfig, validateShopBinding };

package/dist/shop-context.d.ts

@@ -0,0 +1,55 @@
+//#region src/shop-context.d.ts
+/**
+ * Route-context shape returned by `resolveShopContext`. Intentionally NO
+ * token field — anything returned from a TanStack Router `beforeLoad` is
+ * dehydrated into the SSR hydration payload and shipped to the browser.
+ * Server-only consumers (oauth, graphql) re-resolve the token from cache
+ * on each call, so the bearer never needs to leave the server.
+ */
+export interface ShopContext {
+  shopHandle: string;
+}
+export declare class ShopHandleInvalidError extends Error {
+  constructor(value: unknown);
+}
+export declare class CredentialsUnavailableError extends Error {
+  readonly shopHandle: string;
+  constructor(shopHandle: string);
+}
+/**
+ * Validate a shopHandle pulled from a route param. Matches the format
+ * enforced by the Rails Shop model (lowercase alnum + hyphens, leading
+ * hyphen permitted). Throws on missing/malformed so router error
+ * boundaries can surface a clean 4xx rather than carrying garbage
+ * downstream.
+ */
+export declare function resolveShopHandleFromParams(params: {
+  shopHandle?: string | undefined;
+}): string;
+/**
+ * One-shot resolver for a shop-scoped layout route's `beforeLoad`. Pulls
+ * the handle from params, primes the storefront token via a Rails round-
+ * trip so a missing shop / shop-without-storefront-application surfaces
+ * the typed `CredentialsUnavailableError` page before any child route
+ * runs, and returns the minimal context.
+ *
+ * The token preload doubles as a cache warmer: every downstream GraphQL
+ * call in this request will reuse the cached token, so the probe is not
+ * wasted work.
+ *
+ * Returns only `{ shopHandle }` — the token is intentionally discarded
+ * from the return value. Anything returned from `beforeLoad` is
+ * serialized into the SSR hydration payload and shipped to the browser,
+ * so secrets must stay server-side.
+ *
+ * Routes render a typed error page from `CredentialsUnavailableError`;
+ * the structured log emitted below is the load-bearing observability
+ * signal. (TanStack Start's `setResponseStatus` doesn't propagate through
+ * a thrown `beforeLoad`, so the wire status is 500, not 503.) Recovery
+ * for a transient Rails outage is operational; for a missing shop the
+ * recovery is to point the URL at a real handle.
+ */
+export declare function resolveShopContext(params: {
+  shopHandle?: string | undefined;
+}): Promise<ShopContext>;
+//#endregion

package/dist/shop-context.js

@@ -0,0 +1,72 @@
+//#region src/shop-context.ts
+const SHOP_HANDLE_PATTERN = /^[a-z0-9-]{1,63}$/;
+var ShopHandleInvalidError = class extends Error {
+	constructor(value) {
+		super(`[customer-runtime/shop-context] invalid shopHandle: ${String(value)}`);
+		this.name = "ShopHandleInvalidError";
+	}
+};
+var CredentialsUnavailableError = class extends Error {
+	shopHandle;
+	constructor(shopHandle) {
+		super(`[customer-runtime/shop-context] credentials unavailable for shop: ${shopHandle}`);
+		this.name = "CredentialsUnavailableError";
+		this.shopHandle = shopHandle;
+	}
+};
+/**
+* Validate a shopHandle pulled from a route param. Matches the format
+* enforced by the Rails Shop model (lowercase alnum + hyphens, leading
+* hyphen permitted). Throws on missing/malformed so router error
+* boundaries can surface a clean 4xx rather than carrying garbage
+* downstream.
+*/
+function resolveShopHandleFromParams(params) {
+	const handle = params.shopHandle;
+	if (typeof handle !== "string" || !SHOP_HANDLE_PATTERN.test(handle)) throw new ShopHandleInvalidError(handle);
+	return handle;
+}
+/**
+* One-shot resolver for a shop-scoped layout route's `beforeLoad`. Pulls
+* the handle from params, primes the storefront token via a Rails round-
+* trip so a missing shop / shop-without-storefront-application surfaces
+* the typed `CredentialsUnavailableError` page before any child route
+* runs, and returns the minimal context.
+*
+* The token preload doubles as a cache warmer: every downstream GraphQL
+* call in this request will reuse the cached token, so the probe is not
+* wasted work.
+*
+* Returns only `{ shopHandle }` — the token is intentionally discarded
+* from the return value. Anything returned from `beforeLoad` is
+* serialized into the SSR hydration payload and shipped to the browser,
+* so secrets must stay server-side.
+*
+* Routes render a typed error page from `CredentialsUnavailableError`;
+* the structured log emitted below is the load-bearing observability
+* signal. (TanStack Start's `setResponseStatus` doesn't propagate through
+* a thrown `beforeLoad`, so the wire status is 500, not 503.) Recovery
+* for a transient Rails outage is operational; for a missing shop the
+* recovery is to point the URL at a real handle.
+*/
+async function resolveShopContext(params) {
+	const shopHandle = resolveShopHandleFromParams(params);
+	const { getStorefrontToken, OAuthMintError } = await import("./oauth.js");
+	try {
+		await getStorefrontToken(shopHandle);
+	} catch (err) {
+		if (err instanceof OAuthMintError) {
+			console.error(JSON.stringify({
+				event: "credentials_unavailable",
+				shopHandle,
+				notFound: err.notFound,
+				ts: Date.now()
+			}));
+			throw new CredentialsUnavailableError(shopHandle);
+		}
+		throw err;
+	}
+	return { shopHandle };
+}
+//#endregion
+export { CredentialsUnavailableError, ShopHandleInvalidError, resolveShopContext, resolveShopHandleFromParams };

package/dist/trace.d.ts

@@ -0,0 +1,13 @@
+//#region src/trace.d.ts
+export interface TraceOptions {
+  /** Continue a valid incoming `traceparent`. Only behind a proxy that started the trace (Traefik). */
+  continueIncoming?: boolean;
+}
+/**
+ * `traceparent` for the request this call runs under: one minted once per
+ * request, or with `continueIncoming` the incoming ids when valid; always
+ * sampled. Empty outside a request. Send it to our own api only, never to a
+ * third party.
+ */
+export declare function traceHeaders({ continueIncoming }?: TraceOptions): Record<string, string>;
+//#endregion

package/dist/trace.js

@@ -0,0 +1,25 @@
+import { currentRequest, requestSlot } from "./request-scope.js";
+//#region src/trace.ts
+const TRACEPARENT = /^00-((?!0{32})[\da-f]{32})-((?!0{16})[\da-f]{16})-[\da-f]{2}$/;
+const MINTED = Symbol("minted traceparent");
+function randomHex(bytes) {
+	const buf = crypto.getRandomValues(new Uint8Array(bytes));
+	if (buf.every((b) => b === 0)) buf[0] = 1;
+	return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* `traceparent` for the request this call runs under: one minted once per
+* request, or with `continueIncoming` the incoming ids when valid; always
+* sampled. Empty outside a request. Send it to our own api only, never to a
+* third party.
+*/
+function traceHeaders({ continueIncoming = false } = {}) {
+	if (continueIncoming) {
+		const incoming = currentRequest()?.headers.get("traceparent")?.match(TRACEPARENT);
+		if (incoming) return { traceparent: `00-${incoming[1]}-${incoming[2]}-01` };
+	}
+	const traceparent = requestSlot(MINTED, () => `00-${randomHex(16)}-${randomHex(8)}-01`);
+	return traceparent ? { traceparent } : {};
+}
+//#endregion
+export { traceHeaders };

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@shop-on/customer-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "license": "SEE LICENSE IN dist/LICENSE.md",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    "./customer-session-handoff": "./dist/customer-session-handoff.js",
+    "./graphql": "./dist/graphql.js",
+    "./handoff": "./dist/handoff.js",
+    "./lease": "./dist/lease.js",
+    "./oauth": "./dist/oauth.js",
+    "./relay": "./dist/relay.js",
+    "./request-scope": "./dist/request-scope.js",
+    "./sealed-session": "./dist/sealed-session.js",
+    "./session-cookie": "./dist/session-cookie.js",
+    "./shop-context": "./dist/shop-context.js",
+    "./trace": "./dist/trace.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "gql.tada": "1.11.4",
+    "graphql-request": "7.4.0",
+    "iron-webcrypto": "2.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-start": "1.169.3",
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@tanstack/react-start": "~1.169.3"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --maxWorkers=2",
+    "test:watch": "vitest"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.