@shop-on/theme-server 0.1.0 → 0.3.0

package/dist/account-state.js

@@ -0,0 +1,55 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
+import { createServerOnlyFn } from "@tanstack/react-start";
+import { createShopBoundCookieConfig } from "@shop-on/customer-runtime/session-cookie";
+import { ACCOUNT_STATE_FORMAT } from "@shop-on/customer-runtime/handoff-state";
+//#region src/account-state.ts
+const TTL_SECONDS = 1800;
+const DOMAIN_LABEL = "account-state";
+const sessionConfig = createServerOnlyFn(async () => {
+	return createShopBoundCookieConfig({
+		name: "account_state",
+		password: await derivedCookieSecret(DOMAIN_LABEL),
+		maxAge: TTL_SECONDS
+	});
+});
+const loadSession = createServerOnlyFn(async () => {
+	const { openSession } = await import("@shop-on/customer-runtime/sealed-session");
+	return openSession(await sessionConfig());
+});
+/** The state this browser holds, or a fresh one once it is past its 30
+*  minutes. Reused so a second tab bouncing to account doesn't void the state
+*  an in-flight sign-in will come back with, and rewritten on reuse: the
+*  cookie's expiry counts from its first write, so only clearing first lets
+*  it outlast the OTP round trip that reuse starts. */
+const issueAccountState = createServerOnlyFn(async () => {
+	const session = await loadSession();
+	const { state: kept, issuedAt } = session.data;
+	if (kept && issuedAt && Date.now() - issuedAt < TTL_SECONDS * 1e3) {
+		await session.clear();
+		await session.update({
+			state: kept,
+			issuedAt
+		});
+		return kept;
+	}
+	const { randomBytes } = await import("node:crypto");
+	const state = randomBytes(32).toString("base64url");
+	await session.clear();
+	await session.update({
+		state,
+		issuedAt: Date.now()
+	});
+	return state;
+});
+/** Whether `state` is the one this browser was issued. Constant-time. */
+const matchesAccountState = createServerOnlyFn(async (state) => {
+	if (!state || !ACCOUNT_STATE_FORMAT.test(state)) return false;
+	const issued = (await loadSession()).data.state;
+	if (!issued) return false;
+	const { timingSafeEqual } = await import("node:crypto");
+	const a = Buffer.from(issued);
+	const b = Buffer.from(state);
+	return a.length === b.length && timingSafeEqual(a, b);
+});
+//#endregion
+export { issueAccountState, matchesAccountState };

package/dist/account.js

@@ -22,7 +22,12 @@ async function getAccountRedirectUrl(data) {
 			xForwardedHost: true,
 			xForwardedProto: true
 		}).origin;
-		target.searchParams.set("return_to", `${origin}${safePath}`);
+		const returnTo = new URL(`${origin}${safePath}`);
+		const { issueAccountState } = await import("./account-state.js");
+		returnTo.searchParams.set("state", await issueAccountState());
+		const { markResponsePrivate } = await import("@shop-on/customer-runtime/handoff-state");
+		await markResponsePrivate();
+		target.searchParams.set("return_to", returnTo.toString());
 	}
 	return { url: target.toString() };
 }

package/dist/analytics-proxy.js

@@ -1,3 +1,4 @@
+import { requestTraceHeaders } from "./trace.js";
 import { getStorefrontToken, storefrontApiUrl } from "./graphql.js";
 import { isIP } from "node:net";
 //#region src/analytics-proxy.ts
@@ -8,7 +9,8 @@ const PATHS = {
 async function proxyAnalytics({ endpoint, body, visitToken, visitorToken, userAgent, clientIp, fbp, fbc, eventSourceUrl }) {
 	const headers = {
 		Authorization: `Bearer ${await getStorefrontToken()}`,
-		"Content-Type": "application/json"
+		"Content-Type": "application/json",
+		...requestTraceHeaders()
 	};
 	if (visitToken) headers["Ahoy-Visit"] = visitToken;
 	if (visitorToken) headers["Ahoy-Visitor"] = visitorToken;

package/dist/cart-session.d.ts

@@ -1,10 +1,8 @@
-import { useSession } from "@tanstack/react-start/server";
+import { SealedSession } from "@shop-on/customer-runtime/sealed-session";
 //#region src/cart-session.d.ts
 export interface CartSessionData {
   token?: string;
   expiresAtMs?: number;
 }
-type CartSession = ReturnType<typeof useSession<CartSessionData>>;
-export declare const useCartSession: () => CartSession;
-//#endregion
-export {};
+export declare const useCartSession: () => Promise<SealedSession<CartSessionData>>;
+//#endregion

package/dist/cart-session.js

@@ -1,29 +1,19 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
+import { createShopBoundCookieConfig } from "@shop-on/customer-runtime/session-cookie";
 //#region src/cart-session.ts
 const TTL_SECONDS = 2592e3;
 const DOMAIN_LABEL = "cart";
-const readSecret = createServerOnlyFn(async () => {
-	const customer = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
-	if (!customer) throw new Error("cart-session: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it");
-	const { createHmac } = await import("node:crypto");
-	return createHmac("sha256", customer).update(DOMAIN_LABEL).digest("hex");
-});
 const sessionConfig = createServerOnlyFn(async () => {
-	return {
-		password: await readSecret(),
+	return createShopBoundCookieConfig({
 		name: "cart_session",
-		maxAge: TTL_SECONDS,
-		cookie: {
-			secure: process.env.NODE_ENV === "production",
-			sameSite: "lax",
-			httpOnly: true,
-			path: "/"
-		}
-	};
+		password: await derivedCookieSecret(DOMAIN_LABEL),
+		maxAge: TTL_SECONDS
+	});
 });
 const useCartSession = createServerOnlyFn(async () => {
-	const { useSession } = await import("@tanstack/react-start/server");
-	return useSession(await sessionConfig());
+	const { openSession } = await import("@shop-on/customer-runtime/sealed-session");
+	return openSession(await sessionConfig());
 });
 //#endregion
 export { useCartSession };

package/dist/checkout.d.ts

@@ -4,21 +4,22 @@ export type CheckoutHandoffResult = {
   redirectTo: string;
 } | {
   ok: false;
-  reason: "no_cart";
+  reason: "no_cart" | "bad_state";
 };
 /**
- * Read this shop's `cart_session` cookie, call Rails `cartCheckout` (forwarding
- * the customer-session token as `X-Customer-Session` when provided so Rails
- * folds the customer into the handoff payload in one trip), and return the URL
- * on the checkout app that consumes it.
+ * The theme's `/checkout`, both passes. `state` is the URL's `checkout_state`,
+ * a REQUIRED key even when `undefined`: a caller that never passed it would
+ * bounce theme ↔ `/begin` forever, and this way that is a compile error.
  *
- * `no_cart` covers both "no cart cookie" and Rails' `NOT_FOUND` (cart digest
- * miss / cross-shop) / `CART_EMPTY` — the central app's "no cart" StatusPage is
- * the recovery surface for either. Any other userError code is unexpected and
- * throws; the calling route's error boundary handles it (matching `request`'s
- * retry-once-then-throw contract for top-level GraphQL errors).
+ * - No state: the URL of checkout's `/begin`, which binds this browser and
+ *   returns the buyer here with one. Mints nothing.
+ * - A state: mint the cart handoff with it (`mintCheckoutHandoff`).
+ *
+ * The customer-session token is injected: forwarded as `X-Customer-Session` on
+ * the mint so Rails folds the buyer into the handoff payload in one trip.
  */
-export declare function startCheckoutHandoff(opts?: {
+export declare function startCheckoutHandoff(opts: {
+  state: string | undefined;
   customerToken?: string;
 }): Promise<CheckoutHandoffResult>;
 //#endregion

package/dist/checkout.js

@@ -1,7 +1,9 @@
 import { graphql, request } from "./graphql.js";
+import { fetchShopInfo } from "./shop.js";
 import { useCartSession } from "./cart-session.js";
 import { parseMarketingCookies } from "./marketing-cookies.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
+import { CHECKOUT_STATE_FORMAT, isLoopback, markResponsePrivate } from "@shop-on/customer-runtime/handoff-state";
 //#region src/checkout.ts
 const CartCheckoutMutation = graphql(`
   mutation CartCheckout($input: CartCheckoutInput!) {
@@ -25,24 +27,73 @@ const readMarketingAttribution = createServerOnlyFn(async () => {
 		return null;
 	}
 });
+function publicCheckoutUrl(origin) {
+	const url = new URL("/checkout", origin);
+	if (!isLoopback(url.hostname)) url.protocol = "https:";
+	return url.toString();
+}
+/**
+* The theme's `/checkout`, both passes. `state` is the URL's `checkout_state`,
+* a REQUIRED key even when `undefined`: a caller that never passed it would
+* bounce theme ↔ `/begin` forever, and this way that is a compile error.
+*
+* - No state: the URL of checkout's `/begin`, which binds this browser and
+*   returns the buyer here with one. Mints nothing.
+* - A state: mint the cart handoff with it (`mintCheckoutHandoff`).
+*
+* The customer-session token is injected: forwarded as `X-Customer-Session` on
+* the mint so Rails folds the buyer into the handoff payload in one trip.
+*/
+function startCheckoutHandoff(opts) {
+	return opts.state === void 0 ? beginCheckoutUrl() : mintCheckoutHandoff({
+		state: opts.state,
+		customerToken: opts.customerToken
+	});
+}
+async function beginCheckoutUrl() {
+	if (!(await useCartSession()).data.token) return {
+		ok: false,
+		reason: "no_cart"
+	};
+	await markResponsePrivate();
+	const shop = await fetchShopInfo();
+	if (!shop) throw new Error("[checkout] shop info unavailable from Rails");
+	const { getPublicOrigin } = await import("./seo-context.js");
+	const url = new URL(`${shop.checkoutUrl}/begin`);
+	url.searchParams.set("return_to", publicCheckoutUrl(getPublicOrigin()));
+	return {
+		ok: true,
+		redirectTo: url.toString()
+	};
+}
 /**
-* Read this shop's `cart_session` cookie, call Rails `cartCheckout` (forwarding
-* the customer-session token as `X-Customer-Session` when provided so Rails
-* folds the customer into the handoff payload in one trip), and return the URL
-* on the checkout app that consumes it.
+* Read this shop's `cart_session` cookie, call Rails `cartCheckout`, and return
+* the URL on the checkout app that consumes it, `checkout_state` appended.
 *
-* `no_cart` covers both "no cart cookie" and Rails' `NOT_FOUND` (cart digest
-* miss / cross-shop) / `CART_EMPTY` — the central app's "no cart" StatusPage is
-* the recovery surface for either. Any other userError code is unexpected and
-* throws; the calling route's error boundary handles it (matching `request`'s
-* retry-once-then-throw contract for top-level GraphQL errors).
+* `no_cart` covers "no cart cookie" and Rails' `NOT_FOUND` (cart digest miss /
+* cross-shop) / `CART_EMPTY`; `bad_state` a state of the wrong shape (never
+* bounced to `/begin` again, so it can't loop). Any other userError code is
+* unexpected and throws (matching `request`'s retry-once-then-throw contract
+* for top-level GraphQL errors); the calling route sends the buyer home rather
+* than render on a URL holding a state.
 */
-async function startCheckoutHandoff(opts = {}) {
+async function mintCheckoutHandoff(opts) {
 	const cartToken = (await useCartSession()).data.token;
 	if (!cartToken) return {
 		ok: false,
 		reason: "no_cart"
 	};
+	await markResponsePrivate();
+	if (!CHECKOUT_STATE_FORMAT.test(opts.state)) {
+		console.warn(JSON.stringify({
+			event: "theme_checkout_bad_state",
+			ts: Date.now()
+		}));
+		return {
+			ok: false,
+			reason: "bad_state"
+		};
+	}
 	const attribution = await readMarketingAttribution();
 	const result = await request(CartCheckoutMutation, { input: attribution ? {
 		cartToken,
@@ -57,9 +108,11 @@ async function startCheckoutHandoff(opts = {}) {
 		};
 		throw new Error(`[checkout] cartCheckout returned no URL (code=${code ?? "UNKNOWN"})`);
 	}
+	const bound = new URL(checkoutUrl);
+	bound.searchParams.set("checkout_state", opts.state);
 	return {
 		ok: true,
-		redirectTo: checkoutUrl
+		redirectTo: bound.toString()
 	};
 }
 //#endregion

package/dist/cookie-secret.js

@@ -0,0 +1,10 @@
+import { createServerOnlyFn } from "@tanstack/react-start";
+//#region src/cookie-secret.ts
+const derivedCookieSecret = createServerOnlyFn(async (label) => {
+	const secret = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
+	if (!secret) throw new Error(`${label} cookie: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it`);
+	const { createHmac } = await import("node:crypto");
+	return createHmac("sha256", secret).update(label).digest("hex");
+});
+//#endregion
+export { derivedCookieSecret };

package/dist/customer-handoff.d.ts

@@ -9,5 +9,5 @@ export type ConsumeCustomerHandoffResult = {
  * Plain server-only helper. Tested directly; each theme wraps it in a thin
  * `createServerFn` for its root route's `beforeLoad`.
  */
-export declare const consumeCustomerHandoff: (nonce: string) => Promise<ConsumeCustomerHandoffResult>;
+export declare const consumeCustomerHandoff: (nonce: string, state: string | undefined) => Promise<ConsumeCustomerHandoffResult>;
 //#endregion

package/dist/customer-handoff.js

@@ -1,13 +1,14 @@
 import { writeCustomerSession } from "./customer-session.js";
+import { matchesAccountState } from "./account-state.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
 //#region src/customer-handoff.ts
 /**
 * Plain server-only helper. Tested directly; each theme wraps it in a thin
 * `createServerFn` for its root route's `beforeLoad`.
 */
-const consumeCustomerHandoff = createServerOnlyFn(async (nonce) => {
+const consumeCustomerHandoff = createServerOnlyFn(async (nonce, state) => {
 	try {
-		return await consumeAndStore(nonce);
+		return await consumeAndStore(nonce, state);
 	} catch (err) {
 		console.warn(JSON.stringify({
 			event: "theme_customer_handoff_consume_error",
@@ -20,7 +21,18 @@ const consumeCustomerHandoff = createServerOnlyFn(async (nonce) => {
 		};
 	}
 });
-const consumeAndStore = createServerOnlyFn(async (nonce) => {
+const consumeAndStore = createServerOnlyFn(async (nonce, state) => {
+	if (!await matchesAccountState(state)) {
+		console.warn(JSON.stringify({
+			event: "theme_customer_handoff_unbound",
+			hasState: Boolean(state),
+			ts: Date.now()
+		}));
+		return {
+			ok: false,
+			reason: "unbound"
+		};
+	}
 	const { consumeCustomerSessionHandoff } = await import("@shop-on/customer-runtime/customer-session-handoff");
 	const result = await consumeCustomerSessionHandoff(nonce);
 	if (!result.ok) {

package/dist/customer-session.js

@@ -1,29 +1,19 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
+import { createShopBoundCookieConfig } from "@shop-on/customer-runtime/session-cookie";
 //#region src/customer-session.ts
 const TTL_SECONDS = 2592e3;
 const DOMAIN_LABEL = "customer";
-const readSecret = createServerOnlyFn(async () => {
-	const secret = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
-	if (!secret) throw new Error("customer-session: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it");
-	const { createHmac } = await import("node:crypto");
-	return createHmac("sha256", secret).update(DOMAIN_LABEL).digest("hex");
-});
 const sessionConfig = createServerOnlyFn(async () => {
-	return {
-		password: await readSecret(),
+	return createShopBoundCookieConfig({
 		name: "customer_session",
-		maxAge: TTL_SECONDS,
-		cookie: {
-			secure: process.env.NODE_ENV === "production",
-			sameSite: "lax",
-			httpOnly: true,
-			path: "/"
-		}
-	};
+		password: await derivedCookieSecret(DOMAIN_LABEL),
+		maxAge: TTL_SECONDS
+	});
 });
 const loadSession = createServerOnlyFn(async () => {
-	const { useSession } = await import("@tanstack/react-start/server");
-	return useSession(await sessionConfig());
+	const { openSession } = await import("@shop-on/customer-runtime/sealed-session");
+	return openSession(await sessionConfig());
 });
 const readCustomerSession = createServerOnlyFn(async () => {
 	try {

package/dist/graphql-env.d.ts

@@ -2158,6 +2158,22 @@ export type introspection_types = {
         ofType: null;
       };
       defaultValue: null;
+    }, {
+      name: 'latitude';
+      type: {
+        kind: 'SCALAR';
+        name: 'Float';
+        ofType: null;
+      };
+      defaultValue: null;
+    }, {
+      name: 'longitude';
+      type: {
+        kind: 'SCALAR';
+        name: 'Float';
+        ofType: null;
+      };
+      defaultValue: null;
     }, {
       name: 'phone';
       type: {
@@ -2794,6 +2810,14 @@ export type introspection_types = {
         };
       };
       defaultValue: null;
+    }, {
+      name: 'retryKey';
+      type: {
+        kind: 'SCALAR';
+        name: 'String';
+        ofType: null;
+      };
+      defaultValue: null;
     }];
   };
   'CheckoutRecoverPayload': {
@@ -2838,6 +2862,10 @@ export type introspection_types = {
       };
     };
   };
+  'CheckoutRecoveryStatusEnum': {
+    name: 'CheckoutRecoveryStatusEnum';
+    enumValues: 'EXPIRED' | 'INVALID' | 'VALID';
+  };
   'CheckoutShippingAddress': {
     kind: 'OBJECT';
     name: 'CheckoutShippingAddress';
@@ -2942,6 +2970,22 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'latitude': {
+        name: 'latitude';
+        type: {
+          kind: 'SCALAR';
+          name: 'Float';
+          ofType: null;
+        };
+      };
+      'longitude': {
+        name: 'longitude';
+        type: {
+          kind: 'SCALAR';
+          name: 'Float';
+          ofType: null;
+        };
+      };
       'phone': {
         name: 'phone';
         type: {
@@ -3654,6 +3698,10 @@ export type introspection_types = {
       };
     };
   };
+  'CourierPromptEnum': {
+    name: 'CourierPromptEnum';
+    enumValues: 'PHONE' | 'PIN' | 'UNAVAILABLE';
+  };
   'CropRegionEnum': {
     name: 'CropRegionEnum';
     enumValues: 'BOTTOM' | 'CENTER' | 'LEFT' | 'RIGHT' | 'TOP';
@@ -6583,6 +6631,22 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'latitude': {
+        name: 'latitude';
+        type: {
+          kind: 'SCALAR';
+          name: 'Float';
+          ofType: null;
+        };
+      };
+      'longitude': {
+        name: 'longitude';
+        type: {
+          kind: 'SCALAR';
+          name: 'Float';
+          ofType: null;
+        };
+      };
       'phone': {
         name: 'phone';
         type: {
@@ -7133,6 +7197,18 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'checkoutRecoveryStatus': {
+        name: 'checkoutRecoveryStatus';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'ENUM';
+            name: 'CheckoutRecoveryStatusEnum';
+            ofType: null;
+          };
+        };
+      };
       'collection': {
         name: 'collection';
         type: {
@@ -8693,6 +8769,18 @@ export type introspection_types = {
           };
         };
       };
+      'checkoutUrl': {
+        name: 'checkoutUrl';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'SCALAR';
+            name: 'String';
+            ofType: null;
+          };
+        };
+      };
       'city': {
         name: 'city';
         type: {
@@ -10473,6 +10561,14 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'deliveryCourierPrompt': {
+        name: 'deliveryCourierPrompt';
+        type: {
+          kind: 'ENUM';
+          name: 'CourierPromptEnum';
+          ofType: null;
+        };
+      };
       'deliveryOptionHandle': {
         name: 'deliveryOptionHandle';
         type: {
@@ -11877,6 +11973,18 @@ export type introspection_types = {
           };
         };
       };
+      'cashOnDeliveryAllowed': {
+        name: 'cashOnDeliveryAllowed';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'SCALAR';
+            name: 'Boolean';
+            ofType: null;
+          };
+        };
+      };
       'handle': {
         name: 'handle';
         type: {
@@ -12196,6 +12304,14 @@ export type introspection_types = {
           ofType: null;
         };
       };
+      'totalAmount': {
+        name: 'totalAmount';
+        type: {
+          kind: 'SCALAR';
+          name: 'Decimal';
+          ofType: null;
+        };
+      };
       'updatedAt': {
         name: 'updatedAt';
         type: {
@@ -15726,6 +15842,18 @@ export type introspection_types = {
           };
         };
       };
+      'cashOnDeliveryAllowed': {
+        name: 'cashOnDeliveryAllowed';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'SCALAR';
+            name: 'Boolean';
+            ofType: null;
+          };
+        };
+      };
       'handle': {
         name: 'handle';
         type: {
@@ -17848,6 +17976,18 @@ export type introspection_types = {
           };
         };
       };
+      'cashOnDeliveryAllowed': {
+        name: 'cashOnDeliveryAllowed';
+        type: {
+          kind: 'NON_NULL';
+          name: never;
+          ofType: {
+            kind: 'SCALAR';
+            name: 'Boolean';
+            ofType: null;
+          };
+        };
+      };
       'deliveryDetails': {
         name: 'deliveryDetails';
         type: {
@@ -20026,6 +20166,14 @@ export type introspection_types = {
     name: 'ThemeFilter';
     isOneOf: false;
     inputFields: [{
+      name: 'createdAt';
+      type: {
+        kind: 'INPUT_OBJECT';
+        name: 'DateFilter';
+        ofType: null;
+      };
+      defaultValue: null;
+    }, {
       name: 'handleCont';
       type: {
         kind: 'SCALAR';
@@ -20057,6 +20205,30 @@ export type introspection_types = {
         ofType: null;
       };
       defaultValue: null;
+    }, {
+      name: 'query';
+      type: {
+        kind: 'INPUT_OBJECT';
+        name: 'StringFilter';
+        ofType: null;
+      };
+      defaultValue: null;
+    }, {
+      name: 'status';
+      type: {
+        kind: 'INPUT_OBJECT';
+        name: 'EnumStringFilter';
+        ofType: null;
+      };
+      defaultValue: null;
+    }, {
+      name: 'updatedAt';
+      type: {
+        kind: 'INPUT_OBJECT';
+        name: 'DateFilter';
+        ofType: null;
+      };
+      defaultValue: null;
     }];
   };
   'ThemePreset': {

package/dist/graphql.js

@@ -1,5 +1,6 @@
 import { createLease } from "./lease.js";
 import { requestSlot } from "./request-scope.js";
+import { requestTraceHeaders } from "./trace.js";
 import { initGraphQLTada } from "gql.tada";
 import { Kind, print } from "graphql";
 import { ClientError, GraphQLClient } from "graphql-request";
@@ -145,17 +146,18 @@ function extraHeaders(options) {
 	if (options?.acceptLanguage) extra["Accept-Language"] = options.acceptLanguage;
 	return extra;
 }
-function bearerHeaders(token, options) {
+function bearerHeaders(token, options, trace) {
 	return {
 		Authorization: `Bearer ${token}`,
-		...extraHeaders(options)
+		...extraHeaders(options),
+		...trace
 	};
 }
 function invalidateToken(used) {
 	if (cached?.accessToken === used) cached = null;
 }
-async function executeSingle(document, variables, options) {
-	const send = async (token) => await buildClient(bearerHeaders(token, options)).request(document, variables);
+async function executeSingle(document, variables, options, trace) {
+	const send = async (token) => await buildClient(bearerHeaders(token, options, trace)).request(document, variables);
 	const token = await getToken();
 	try {
 		return await send(token);
@@ -179,11 +181,12 @@ function enqueueBatched(queues, query, variables, options) {
 		let queue = queues.get(key);
 		if (!queue) {
 			const scheduled = [];
+			const trace = requestTraceHeaders();
 			queue = scheduled;
 			queues.set(key, scheduled);
 			setTimeout(() => {
 				queues.delete(key);
-				flushBatch(scheduled, options);
+				flushBatch(scheduled, options, trace);
 			}, 0);
 		}
 		queue.push({
@@ -194,15 +197,15 @@ function enqueueBatched(queues, query, variables, options) {
 		});
 	});
 }
-async function flushBatch(entries, options) {
+async function flushBatch(entries, options, trace) {
 	const chunks = [];
 	for (let i = 0; i < entries.length; i += BATCH_MAX_QUERIES) chunks.push(entries.slice(i, i + BATCH_MAX_QUERIES));
 	await Promise.all(chunks.map(async (chunk) => {
 		try {
 			if (chunk.length === 1) {
 				const only = chunk[0];
-				only.resolve(await executeSingle(only.query, only.variables, options));
-			} else await executeBatchChunk(chunk, options);
+				only.resolve(await executeSingle(only.query, only.variables, options, trace));
+			} else await executeBatchChunk(chunk, options, trace);
 		} catch (err) {
 			for (const entry of chunk) entry.reject(err);
 		}
@@ -223,7 +226,7 @@ async function postWithAuthRetry(buildInit) {
 	invalidateToken(token);
 	return await post(await getToken());
 }
-async function executeBatchChunk(chunk, options) {
+async function executeBatchChunk(chunk, options, trace) {
 	const body = JSON.stringify(chunk.map(({ query, variables }) => ({
 		query,
 		variables
@@ -231,7 +234,7 @@ async function executeBatchChunk(chunk, options) {
 	const res = await postWithAuthRetry((token) => ({
 		headers: {
 			"Content-Type": "application/json",
-			...bearerHeaders(token, options)
+			...bearerHeaders(token, options, trace)
 		},
 		body
 	}));
@@ -266,7 +269,7 @@ async function executeBatchChunk(chunk, options) {
 async function request(document, variables, options) {
 	assertServerOnly();
 	const queues = isBatchableQuery(document) ? requestSlot(BATCH_QUEUES, () => /* @__PURE__ */ new Map()) : void 0;
-	if (!queues) return await executeSingle(document, variables, options);
+	if (!queues) return await executeSingle(document, variables, options, requestTraceHeaders());
 	return await enqueueBatched(queues, print(document), variables, options);
 }
 /**
@@ -285,6 +288,7 @@ async function request(document, variables, options) {
 */
 async function requestUpload(document, variables, files, filesPath, options) {
 	assertServerOnly();
+	const trace = requestTraceHeaders();
 	const query = print(document);
 	const map = {};
 	files.forEach((_, i) => {
@@ -305,7 +309,7 @@ async function requestUpload(document, variables, files, filesPath, options) {
 		return form;
 	};
 	const res = await postWithAuthRetry((token) => ({
-		headers: bearerHeaders(token, options),
+		headers: bearerHeaders(token, options, trace),
 		body: buildBody()
 	}));
 	if (!res.ok) throw batchClientError({

package/dist/password-session.js

@@ -1,16 +1,11 @@
+import { derivedCookieSecret } from "./cookie-secret.js";
 import { createServerOnlyFn } from "@tanstack/react-start";
 //#region src/password-session.ts
 const TTL_SECONDS = 2592e3;
 const DOMAIN_LABEL = "password";
-const readSecret = createServerOnlyFn(async () => {
-	const secret = process.env.STOREFRONT_CUSTOMER_SESSION_SECRET;
-	if (!secret) throw new Error("password-session: STOREFRONT_CUSTOMER_SESSION_SECRET missing — orchestrator did not inject it");
-	const { createHmac } = await import("node:crypto");
-	return createHmac("sha256", secret).update(DOMAIN_LABEL).digest("hex");
-});
 const sessionConfig = createServerOnlyFn(async () => {
 	return {
-		password: await readSecret(),
+		password: await derivedCookieSecret(DOMAIN_LABEL),
 		name: "storefront_unlock",
 		maxAge: TTL_SECONDS,
 		cookie: {
@@ -22,8 +17,8 @@ const sessionConfig = createServerOnlyFn(async () => {
 	};
 });
 const loadSession = createServerOnlyFn(async () => {
-	const { useSession } = await import("@tanstack/react-start/server");
-	return useSession(await sessionConfig());
+	const { openSession } = await import("@shop-on/customer-runtime/sealed-session");
+	return openSession(await sessionConfig());
 });
 const readPasswordSession = createServerOnlyFn(async () => {
 	try {

package/dist/schema.storefront.graphql

@@ -408,6 +408,10 @@ input CartCheckoutInput {
 Autogenerated return type of CartCheckout.
 """
 type CartCheckoutPayload {
+  """
+  Where to send the buyer. Append `checkout_state` from the
+  `shop.checkoutUrl/begin` bounce before redirecting; checkout rejects a handoff without it.
+  """
   checkoutUrl: String
 
   """
@@ -714,6 +718,16 @@ input CheckoutAddressInput {
   firstName: String
   khorooId: ID
   lastName: String
+
+  """
+  Delivery pin. Send both or neither.
+  """
+  latitude: Float
+
+  """
+  Delivery pin. Send both or neither.
+  """
+  longitude: Float
   phone: String
   provinceId: ID
   zip: String
@@ -929,6 +943,12 @@ input CheckoutRecoverInput {
   """
   clientMutationId: String
   recoveryToken: String!
+
+  """
+  A random key the caller keeps for this link. If the reply to the first use is
+  lost, the same key may resume the checkout again for a few minutes.
+  """
+  retryKey: String
 }
 
 """
@@ -944,6 +964,26 @@ type CheckoutRecoverPayload {
   userErrors: [UserError!]!
 }
 
+"""
+Whether a checkout recovery link can still resume its checkout.
+"""
+enum CheckoutRecoveryStatusEnum {
+  """
+  The checkout was completed or has expired.
+  """
+  EXPIRED
+
+  """
+  The link is unknown, already used, or replaced by a newer one.
+  """
+  INVALID
+
+  """
+  The link resumes the checkout.
+  """
+  VALID
+}
+
 """
 Buyer-facing snapshot of the shipping address on a checkout.
 """
@@ -963,6 +1003,8 @@ type CheckoutShippingAddress {
   formatted(locale: String): [String!]!
   khoroo: AddressKhoroo
   lastName: String
+  latitude: Float
+  longitude: Float
   phone: String
   province: AddressProvince
   provinceCode: String
@@ -1346,6 +1388,26 @@ type CourierDriverLoginPayload {
   userErrors: [UserError!]!
 }
 
+"""
+What the buyer must do, or wait for, to see a delivery a courier prices.
+"""
+enum CourierPromptEnum {
+  """
+  Add a phone number the courier can call.
+  """
+  PHONE
+
+  """
+  Drop a pin on the map: the courier prices from it.
+  """
+  PIN
+
+  """
+  The courier cannot be reached right now; choose another delivery.
+  """
+  UNAVAILABLE
+}
+
 """
 Crop region for image transforms
 """
@@ -2404,6 +2466,9 @@ type Mutation {
 
   """
   Mint a checkout handoff for the given cart and return the URL to redirect to.
+  Checkout consumes the handoff only in the browser that started it: bounce the
+  buyer through `shop.checkoutUrl` + `/begin` first, and append the
+  `checkout_state` it sends back to `checkoutUrl`, or checkout rejects it.
   """
   cartCheckout(
     """
@@ -2869,6 +2934,8 @@ type OrderShippingAddress {
   formatted(locale: String): [String!]!
   khoroo: AddressKhoroo
   lastName: String
+  latitude: Float
+  longitude: Float
   phone: String
   province: AddressProvince
   provinceCode: String
@@ -3238,6 +3305,18 @@ type Query {
   """
   checkout(checkoutToken: String!): ShopCheckout
 
+  """
+  Whether a recovery link can still resume its checkout. Read-only: it never spends the link.
+  """
+  checkoutRecoveryStatus(
+    recoveryToken: String!
+
+    """
+    The key sent with an earlier use of this link.
+    """
+    retryKey: String
+  ): CheckoutRecoveryStatusEnum!
+
   """
   Find a collection by ID or handle
   """
@@ -4392,6 +4471,14 @@ type Shop implements Node {
   due (PAYMENT_REQUIRED).
   """
   cashOnDeliveryEnabled: Boolean!
+
+  """
+  URL of this shop's section on the central checkout app
+  (`{checkoutHost}/shops/{handle}/checkout`). Theme sends the buyer to
+  `{checkoutUrl}/begin` before minting a cart handoff, so the handoff is bound
+  to the browser that started it.
+  """
+  checkoutUrl: String!
   city: String
 
   """
@@ -4432,8 +4519,8 @@ type Shop implements Node {
 
   """
   Whether this shop issues eBarimt fiscal receipts (a fiscal engine is enabled).
-  Buyer surfaces read this to decide whether to ask the Иргэн / Байгууллага
-  receipt question at checkout.
+  Buyer surfaces and the register read this to decide whether to ask the Иргэн /
+  Байгууллага receipt question at checkout.
   """
   issuesFiscalReceipts: Boolean!
   khoroo: AddressKhoroo
@@ -5061,7 +5148,18 @@ type ShopCheckout implements Node {
   availableDeliveryOptions: [ShopDeliveryOption!]!
   completedAt: ISO8601DateTime
   createdAt: ISO8601DateTime!
+
+  """
+  The checkout's customer. Storefront callers get null without that customer's session.
+  """
   customer: ShopCustomer
+
+  """
+  What stands between the buyer and a delivery a courier prices (drop a pin, add
+  a phone, or the courier is unavailable). Null when nothing does, or no
+  shipping address is set yet.
+  """
+  deliveryCourierPrompt: CourierPromptEnum
   deliveryOptionHandle: String
 
   """
@@ -5597,6 +5695,11 @@ A storefront delivery option.
 interface ShopDeliveryOption {
   amount: Money!
 
+  """
+  False for a delivery a courier prices: the courier carries paid orders only, so the buyer pays online.
+  """
+  cashOnDeliveryAllowed: Boolean!
+
   """
   Stable identifier passed back via deliveryOptionHandle to select this option.
   """
@@ -5861,6 +5964,13 @@ type ShopFiscalReceipt {
   which is the only one `ShopOrder.fiscalReceipt` ever returns.
   """
   supersededAt: ISO8601DateTime
+
+  """
+  What the receipt declared to the tax authority — less than the order total
+  when gift cards paid part of it. With the lottery number, it is what the buyer
+  registers the receipt by hand with when the QR cannot be scanned. Null until issued.
+  """
+  totalAmount: Decimal
   updatedAt: ISO8601DateTime!
 }
 
@@ -6827,9 +6937,10 @@ type ShopOrder implements Node {
 
   """
   How the buyer is paying the balance — the oldest non-credit payment row’s
-  tender (`manual`, `cash_on_delivery`, `cody_pay`). Null when store credit /
-  gift cards covered the whole order and no such row exists. Buyer surfaces read
-  it to tell a cash-on-delivery order from a gateway one on the thanks page.
+  tender (`manual`, `cash_on_delivery`, `cash`, `bank_card`, `bank_transfer`,
+  `cody_pay`). Null when store credit / gift cards covered the whole order and
+  no such row exists. Buyer surfaces read it to tell a cash-on-delivery order
+  from a gateway one on the thanks page.
   """
   paymentMethod: String
   phone: String
@@ -7299,6 +7410,7 @@ type ShopPickupDeliveryOption implements ShopDeliveryOption {
   """
   addressLines: [String!]!
   amount: Money!
+  cashOnDeliveryAllowed: Boolean!
   handle: String!
   instructions: String!
   kind: ShopDeliveryKindEnum!
@@ -8303,6 +8415,7 @@ A storefront ship delivery option (quote result).
 """
 type ShopShipDeliveryOption implements ShopDeliveryOption {
   amount: Money!
+  cashOnDeliveryAllowed: Boolean!
   deliveryDetails: String
   handle: String!
   kind: ShopDeliveryKindEnum!
@@ -9099,10 +9212,29 @@ type ThemeEdge {
 }
 
 input ThemeFilter {
+  """
+  Bounds on the creation time.
+  """
+  createdAt: DateFilter
   handleCont: String
   priceEq: Float
   priceGteq: Float
   priceLteq: Float
+
+  """
+  Match against the theme's name or its handle.
+  """
+  query: StringFilter
+
+  """
+  Predicates on the status, keyed by its lowercase label ("draft", "published", "archived").
+  """
+  status: EnumStringFilter
+
+  """
+  Bounds on the last-update time.
+  """
+  updatedAt: DateFilter
 }
 
 """

package/dist/shop.d.ts

@@ -3,6 +3,7 @@ import { ResultOf } from "./graphql.js";
 declare const ShopQuery: import("gql.tada").TadaDocumentNode<{
   shop: {
     accountUrl: string;
+    checkoutUrl: string;
     currency: string;
     handle: string;
     id: string;

package/dist/shop.js

@@ -18,6 +18,7 @@ const ShopQuery = graphql(`
       }
       turnstileSitekey
       accountUrl
+      checkoutUrl
       primaryDomain {
         fqdn
         turnstileSitekey

package/dist/trace.js

@@ -0,0 +1,5 @@
+import { traceHeaders } from "@shop-on/customer-runtime/trace";
+//#region src/trace.ts
+const requestTraceHeaders = () => traceHeaders({ continueIncoming: true });
+//#endregion
+export { requestTraceHeaders };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-server",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -54,24 +54,24 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "gql.tada": "1.11.3",
+    "gql.tada": "1.11.4",
     "graphql": "17.0.2",
     "graphql-request": "7.4.0",
-    "liquidjs": "10.29.0",
-    "@shop-on/customer-runtime": "0.1.0",
-    "@shop-on/theme-runtime": "0.1.0"
+    "liquidjs": "10.30.0",
+    "@shop-on/customer-runtime": "0.3.0",
+    "@shop-on/theme-runtime": "0.3.0"
   },
   "devDependencies": {
-    "@tanstack/react-start": "1.168.60",
-    "@types/node": "26.6.3",
+    "@tanstack/react-start": "1.169.3",
+    "@types/node": "26.6.5",
     "typescript": "7.0.2",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "@tanstack/react-start": "~1.168.60"
+    "@tanstack/react-start": "~1.169.3"
   },
   "scripts": {
     "check-types": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --maxWorkers=2"
   }
 }