@redeemid/emdash 0.0.17 → 0.0.19

package/src/routes/cart-edit.ts

@@ -2,95 +2,44 @@
  * POST /_emdash/api/auth/redeemid/cart-edit: change the visitor's Shopify cart.
  *
  * Fields: `action` (add | update | remove | discount), `return`, and
- * - add: `product` (handle), optional `variant` (must be one of that
- *   product's variants, read again from Shopify), `quantity` (1 to 1000),
+ * - add: `product` (handle); the variant by `variant` (an id of that
+ *   product's, read again from Shopify) or by one `option.<Name>` field per
+ *   option (e.g. option.Size=M); `selling_plan` (one of the product's
+ *   selling plans, or empty for one-time); `quantity` (1 to 1000);
  *   `then` = "checkout" to go straight to checkout;
  * - update: `line` and `quantity` (0 removes the line);
  * - remove: `line`;
  * - discount: `code` (empty clears the codes).
  *
- * Prices, discounts and availability come from Shopify; nothing posted is
- * trusted beyond the ids it names. Back to `return` with a notice:
- * cart_added, cart_updated, discount_applied, discount_not_applicable,
- * plan_unavailable, cart_empty or checkout_failed.
+ * Back to `return` with a notice: cart_added, cart_updated,
+ * discount_applied, discount_not_applicable, plan_unavailable, cart_empty or
+ * checkout_failed. The JSON twin is api/cart.
  */
 
 import type { APIRoute } from "astro";
 
 import { safeReturn } from "../access.js";
-import { readCart, saveCart } from "../cart.js";
+import { cartInputFromForm, editCart } from "../cart-ops.js";
+import { checkoutFor } from "../checkout.js";
 import { readConfig, storeDomain } from "../config.js";
-import { memberForUser, stores } from "../storage.js";
-import { addToCart, cartDetails, product, removeLines, setDiscountCodes, updateLines } from "../storefront.js";
 import { fail } from "./shared.js";
 
 export const prerender = false;
 
-const MAX_QUANTITY = 1000;
-
 export const POST: APIRoute = async ({ request, locals, session, redirect }) => {
 	const form = await request.formData().catch(() => null);
-	const field = (k: string) => String(form?.get(k) ?? "").trim();
-	const returnTo = safeReturn(field("return") || "/");
+	const returnTo = safeReturn(String(form?.get("return") ?? "").trim() || "/");
 	const emdash = (locals as { emdash?: { config?: unknown; db?: unknown } }).emdash;
 	const config = readConfig(emdash?.config);
 	if (!config || !storeDomain(config)) return fail(redirect, returnTo, "not_configured");
-	const buyerIp = request.headers.get("cf-connecting-ip");
-	const action = field("action");
 
 	try {
-		if (action === "add") {
-			const handle = field("product");
-			const quantity = Number.parseInt(field("quantity") || "1", 10);
-			if (!/^[a-z0-9][a-z0-9-]*$/i.test(handle) || !Number.isFinite(quantity) || quantity < 1 || quantity > MAX_QUANTITY) {
-				return fail(redirect, returnTo, "plan_unavailable");
-			}
-			const p = await product(config, handle);
-			const wanted = field("variant");
-			const variant = wanted ? p?.variants.find((v) => v.id === wanted) : p?.variants.find((v) => v.availableForSale);
-			if (!p || !variant?.availableForSale) return fail(redirect, returnTo, "plan_unavailable");
-			const user = (await session?.get("user")) as { id?: string } | undefined;
-			const member = user?.id && emdash?.db ? await memberForUser(stores(emdash.db), user.id) : null;
-			const current = await readCart(session);
-			const cart = await addToCart(
-				config,
-				current?.id ?? null,
-				{ variantId: variant.id, sellingPlanId: p.sellingPlanId, quantity },
-				{ email: member?.email ?? null, attributes: { _redeemid_page: returnTo }, buyerIp },
-			);
-			saveCart(session, { id: cart.id, count: cart.totalQuantity });
-			return field("then") === "checkout" ? redirect(cart.checkoutUrl, 303) : fail(redirect, returnTo, "cart_added");
-		}
-
-		const ref = await readCart(session);
-		if (!ref) return fail(redirect, returnTo, "cart_empty");
-		const cart = await cartDetails(config, ref.id, { buyerIp });
-		if (!cart) {
-			saveCart(session, null);
-			return fail(redirect, returnTo, "cart_empty");
-		}
-		const line = field("line");
-		const owns = cart.lines.some((l) => l.id === line);
-
-		if (action === "update" || action === "remove") {
-			if (!owns) return fail(redirect, returnTo, "cart_updated");
-			const quantity = action === "remove" ? 0 : Number.parseInt(field("quantity"), 10);
-			if (!Number.isFinite(quantity) || quantity < 0 || quantity > MAX_QUANTITY) return fail(redirect, returnTo, "cart_updated");
-			const next = quantity === 0 ? await removeLines(config, cart.id, [line], { buyerIp }) : await updateLines(config, cart.id, [{ id: line, quantity }], { buyerIp });
-			saveCart(session, { id: next.id, count: next.totalQuantity });
-			return fail(redirect, returnTo, "cart_updated");
-		}
-
-		if (action === "discount") {
-			const code = field("code").slice(0, 100);
-			const next = await setDiscountCodes(config, cart.id, code ? [code] : [], { buyerIp });
-			saveCart(session, { id: next.id, count: next.totalQuantity });
-			if (!code) return fail(redirect, returnTo, "cart_updated");
-			const applied = next.discountCodes.find((d) => d.code.toLowerCase() === code.toLowerCase());
-			return fail(redirect, returnTo, applied?.applicable ? "discount_applied" : "discount_not_applicable");
+		const input = { ...cartInputFromForm(form), page: returnTo };
+		const out = await editCart(input, { config, session, request, db: emdash?.db });
+		if (out.base && String(form?.get("then") ?? "") === "checkout") {
+			return redirect(await checkoutFor(config, out.base, { session, request, emdashConfig: emdash?.config }), 303);
 		}
-
-		return fail(redirect, returnTo, "cart_updated");
+		return fail(redirect, returnTo, out.notice);
 	} catch {
 		return fail(redirect, returnTo, "checkout_failed");
 	}

package/src/routes/cart.ts

@@ -1,7 +1,8 @@
 /**
  * GET /_emdash/api/auth/redeemid/cart?return=/path
  *
- * Sends the visitor to their Shopify cart's checkout. With no cart, or one
+ * Sends the visitor to their Shopify cart's checkout, signed in for members
+ * (see checkout.ts). With no cart, or one
  * Shopify has closed (its checkout completed), they go back with the
  * `cart_empty` notice and the stored cart is cleared.
  */
@@ -11,6 +12,7 @@ import type { APIRoute } from "astro";
 import { safeReturn } from "../access.js";
 import { readCart, saveCart } from "../cart.js";
 import { readConfig, storeDomain } from "../config.js";
+import { checkoutFor } from "../checkout.js";
 import { getCart } from "../storefront.js";
 import { fail } from "./shared.js";
 
@@ -30,7 +32,7 @@ export const GET: APIRoute = async ({ request, locals, session, redirect }) => {
 			return fail(redirect, returnTo, "cart_empty");
 		}
 		saveCart(session, { id: cart.id, count: cart.totalQuantity });
-		return redirect(cart.checkoutUrl, 303);
+		return redirect(await checkoutFor(config, cart, { session, request, emdashConfig: (locals as { emdash?: { config?: unknown } }).emdash?.config }), 303);
 	} catch {
 		return fail(redirect, returnTo, "checkout_failed");
 	}

package/src/routes/shared.ts

@@ -2,6 +2,17 @@ import { getPublicOrigin } from "emdash/api/route-utils";
 
 export const SESSION_FLOW = "redeemid:flow";
 export const SESSION_ID_TOKEN = "redeemid:id_token";
+/**
+ * The member's Customer Account API tokens, kept only in the server-side
+ * session, to open Shopify's checkout signed in. Never sent to the browser.
+ */
+export const SESSION_CUSTOMER_TOKEN = "redeemid:customer_token";
+
+export interface CustomerToken {
+	accessToken: string;
+	refreshToken: string | null;
+	expiresAt: number | null;
+}
 /** A sign-in started more than this long ago is refused. */
 export const FLOW_TTL_MS = 10 * 60 * 1000;
 

package/src/routes/webhook.ts

@@ -19,6 +19,11 @@ import { apply, customerOf, kindOf, verifyHmac } from "../webhooks.js";
 export const prerender = false;
 
 const MAX_BYTES = 1024 * 1024;
+/** A delivery still "pending" after this long never finished. */
+const STALE_PENDING_MS = 60 * 1000;
+/** At most one "Bad signature" entry per this long, so junk requests can't fill App events. */
+const REJECT_LOG_MS = 60 * 1000;
+let lastRejectLogged = 0;
 
 export const POST: APIRoute = async ({ request, locals }) => {
 	const emdash = (locals as { emdash?: { db?: unknown; config?: unknown } }).emdash;
@@ -31,7 +36,10 @@ export const POST: APIRoute = async ({ request, locals }) => {
 	const ok = await verifyHmac(body, request.headers.get("x-shopify-hmac-sha256") ?? "", secret);
 	const topic = (request.headers.get("x-shopify-topic") ?? "").toLowerCase();
 	if (!ok) {
-		await record({ event: "webhook.rejected", label: topic || "unknown", status: "rejected", level: "warn", origin: "webhook", note: "Bad signature" });
+		if (Date.now() - lastRejectLogged > REJECT_LOG_MS) {
+			lastRejectLogged = Date.now();
+			await record({ event: "webhook.rejected", label: topic || "unknown", status: "rejected", level: "warn", origin: "webhook", note: "Bad signature" });
+		}
 		return new Response("Bad signature", { status: 401 });
 	}
 
@@ -51,7 +59,17 @@ export const POST: APIRoute = async ({ request, locals }) => {
 	const customerId = topic === "shop/redact" ? null : customerOf(payload);
 	const receivedAt = new Date().toISOString();
 	if (delivery) {
-		const claimed = await s.deliveries.compareAndSet(delivery, null, { topic, receivedAt, outcome: "pending", customerId });
+		const claim = () => s.deliveries.compareAndSet(delivery, null, { topic, receivedAt, outcome: "pending", customerId });
+		let claimed = await claim();
+		if (!claimed.applied) {
+			// A delivery left "pending" was cut off before it finished (a
+			// timeout, a crash): let Shopify's retry run it again.
+			const earlier = await s.deliveries.get(delivery);
+			if (earlier?.outcome === "pending" && Date.now() - Date.parse(earlier.receivedAt) > STALE_PENDING_MS) {
+				await s.deliveries.delete(delivery);
+				claimed = await claim();
+			}
+		}
 		if (!claimed.applied) {
 			await record({ event: "webhook.received", label: topic, status: "duplicate", origin: "webhook", customerId });
 			return new Response("Duplicate", { status: 200 });

package/src/shopify.ts

@@ -127,6 +127,42 @@ export function authorizeUrl(
 export interface Tokens {
 	accessToken: string;
 	idToken: string;
+	/** Present when Shopify issued one; used to renew the access token for a signed-in checkout. */
+	refreshToken?: string | null;
+	/** When the access token expires (ms since epoch), when Shopify said. */
+	expiresAt?: number | null;
+}
+
+function tokenTimes(data: Record<string, unknown>): { refreshToken: string | null; expiresAt: number | null } {
+	const ttl = typeof data.expires_in === "number" ? data.expires_in : Number(data.expires_in);
+	return {
+		refreshToken: typeof data.refresh_token === "string" ? data.refresh_token : null,
+		expiresAt: Number.isFinite(ttl) && ttl > 0 ? Date.now() + ttl * 1000 : null,
+	};
+}
+
+/**
+ * Renew a Customer Account API access token with its refresh token. Throws
+ * when Shopify refuses (the member's store session ended).
+ */
+export async function refreshTokens(
+	d: Discovery,
+	args: { clientId: string; clientSecret: string; origin?: string; refreshToken: string },
+	fetcher: typeof fetch = fetch,
+): Promise<{ accessToken: string; refreshToken: string | null; expiresAt: number | null }> {
+	const body = new URLSearchParams({ grant_type: "refresh_token", client_id: args.clientId, refresh_token: args.refreshToken });
+	const headers: Record<string, string> = {
+		"Content-Type": "application/x-www-form-urlencoded",
+		Accept: "application/json",
+		"User-Agent": USER_AGENT,
+	};
+	if (args.origin) headers.Origin = args.origin;
+	if (args.clientSecret) headers.Authorization = `Basic ${btoa(`${args.clientId}:${args.clientSecret}`)}`;
+	const res = await fetcher(d.tokenEndpoint, { method: "POST", headers, body });
+	const data = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+	if (!res.ok || typeof data.access_token !== "string") throw new ShopifyError("token_failed", `Token refresh failed (${res.status}).`);
+	const t = tokenTimes(data);
+	return { accessToken: data.access_token, refreshToken: t.refreshToken ?? args.refreshToken, expiresAt: t.expiresAt };
 }
 
 export async function exchangeCode(
@@ -155,7 +191,7 @@ export async function exchangeCode(
 	if (!res.ok || typeof data.access_token !== "string" || typeof data.id_token !== "string") {
 		throw new ShopifyError("token_failed", `Token exchange failed (${res.status}).`);
 	}
-	return { accessToken: data.access_token, idToken: data.id_token };
+	return { accessToken: data.access_token, idToken: data.id_token, ...tokenTimes(data) };
 }
 
 /** Verify the ID token's signature, issuer, audience, expiry and nonce. */

package/src/storefront.ts

@@ -30,12 +30,61 @@ export function resetStorefrontCache(): void {
 	shopCache.clear();
 }
 
+/**
+ * Where the buyer is, for local prices and currency (Shopify Markets). Both
+ * are optional; Shopify uses the store's defaults without them.
+ */
+export interface StoreContext {
+	/** ISO 3166 two-letter country code, e.g. "CA". */
+	country?: string | null;
+	/** Shopify language code, e.g. "FR" or "PT_BR". */
+	language?: string | null;
+}
+
+/** A clean country code, or null. */
+export function countryCode(raw: unknown): string | null {
+	const c = typeof raw === "string" ? raw.trim().toUpperCase() : "";
+	return /^[A-Z]{2}$/.test(c) && c !== "XX" && c !== "T1" ? c : null;
+}
+
+function languageCode(raw: unknown): string | null {
+	const l = typeof raw === "string" ? raw.trim().toUpperCase().replace("-", "_") : "";
+	return /^[A-Z]{2}(_[A-Z]{2})?$/.test(l) ? l : null;
+}
+
+/**
+ * The buyer's context from config `market`: a fixed country, or "visitor"
+ * for the country Cloudflare reports for the request (CF-IPCountry).
+ */
+export function storeContext(config: RedeemIDConfig | null | undefined, request?: Request | null): StoreContext {
+	const m = config?.market;
+	if (!m) return {};
+	const country = m.country === "visitor" ? countryCode(request?.headers.get("cf-ipcountry")) : countryCode(m.country);
+	return { country, language: languageCode(m.language) };
+}
+
+function contextKey(ctx: StoreContext | undefined): string {
+	return `${ctx?.country ?? ""}|${ctx?.language ?? ""}`;
+}
+
+/** Add Shopify's @inContext directive to an operation, when there is a context. */
+export function withContext(query: string, ctx: StoreContext | undefined): string {
+	const parts: string[] = [];
+	const country = countryCode(ctx?.country);
+	const language = languageCode(ctx?.language);
+	if (country) parts.push(`country: ${country}`);
+	if (language) parts.push(`language: ${language}`);
+	if (!parts.length) return query;
+	return query.replace(/^(\s*(?:query|mutation)\s+\w+(?:\([^)]*\))?)/, `$1 @inContext(${parts.join(", ")})`);
+}
+
 export async function storefront<T>(
 	config: RedeemIDConfig,
 	query: string,
 	variables: Record<string, unknown> = {},
-	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch; context?: StoreContext } = {},
 ): Promise<T> {
+	query = withContext(query, opts.context);
 	const headers: Record<string, string> = {
 		"Content-Type": "application/json",
 		Accept: "application/json",
@@ -177,6 +226,8 @@ export async function addToCart(
 		attributes?: Record<string, string>;
 		buyerIp?: string | null;
 		fetcher?: typeof fetch;
+		/** A new cart's country, for local prices. */
+		context?: StoreContext;
 	} = {},
 ): Promise<Cart> {
 	const quantity = Math.max(1, Math.floor(line.quantity ?? 1));
@@ -186,7 +237,11 @@ export async function addToCart(
 		if (data?.cartLinesAdd.cart) return data.cartLinesAdd.cart;
 	}
 	const input: Record<string, unknown> = { lines };
-	if (opts.email) input.buyerIdentity = { email: opts.email };
+	const identity: Record<string, string> = {};
+	if (opts.email) identity.email = opts.email;
+	const country = countryCode(opts.context?.country);
+	if (country) identity.countryCode = country;
+	if (Object.keys(identity).length) input.buyerIdentity = identity;
 	const attributes = Object.entries(opts.attributes ?? {}).filter(([, v]) => v);
 	if (attributes.length) input.attributes = attributes.map(([key, value]) => ({ key, value }));
 	const data = await storefront<{ cartCreate: CartResult }>(config, CART_NEW, { input }, opts);
@@ -212,17 +267,57 @@ export interface Variant {
 	title: string;
 	availableForSale: boolean;
 	price: Money;
+	/** The price before a sale, when Shopify has one above `price`. */
+	compareAtPrice?: Money | null;
+	sku?: string | null;
+	image?: Image | null;
+	/** Option name and value pairs, e.g. [{ name: "Size", value: "M" }]. */
+	selectedOptions?: Array<{ name: string; value: string }>;
+}
+
+export interface SellingPlan {
+	id: string;
+	name: string;
+	/** The group's name, e.g. "Subscribe and save". */
+	group: string;
 }
 
 export interface Product {
+	/** Shopify's product id (gid). */
+	id?: string;
 	handle: string;
 	title: string;
 	description: string;
+	/** Shopify's HTML description, as the merchant wrote it. */
+	descriptionHtml?: string;
+	vendor?: string;
+	productType?: string;
 	availableForSale: boolean;
 	image: Image | null;
+	/** Every image, featured first (up to 20). */
+	images?: Image[];
+	/** The product's options and their values, e.g. Size: S, M, L. Absent or one "Title" option means none. */
+	options?: Array<{ name: string; values: string[] }>;
 	variants: Variant[];
 	/** The first selling plan, for subscription-only products. */
 	sellingPlanId: string | null;
+	/** True when the product can only be bought on a selling plan. */
+	requiresSellingPlan?: boolean;
+	/** Every selling plan offered (subscriptions, pre-orders), in Shopify's order. */
+	sellingPlans?: SellingPlan[];
+	seo?: { title: string | null; description: string | null };
+}
+
+/** Real options to choose from: none for a product with only Shopify's "Default Title". */
+export function realOptions(p: Product): Array<{ name: string; values: string[] }> {
+	const opts = p.options ?? [];
+	if (opts.length === 1 && opts[0]?.values.length === 1 && opts[0].values[0] === "Default Title") return [];
+	return opts.filter((o) => o.values.length > 0);
+}
+
+/** The variant matching the chosen option values, or undefined. */
+export function variantFor(p: Product, chosen: Record<string, string>): Variant | undefined {
+	return p.variants.find((v) => (v.selectedOptions ?? []).every((o) => chosen[o.name] === o.value));
 }
 
 export interface ProductCard {
@@ -232,6 +327,10 @@ export interface ProductCard {
 	image: Image | null;
 	/** The lowest variant price. */
 	price: Money | null;
+	/** The lowest compare-at price, when the product is on sale. */
+	compareAtPrice?: Money | null;
+	/** The variant to add straight from a card: set only when the product has exactly one and needs no selling plan. */
+	quickAddVariantId?: string | null;
 }
 
 export interface Collection {
@@ -243,18 +342,53 @@ export interface Collection {
 
 const PRODUCT_QUERY = `query Product($handle: String!) {
   product(handle: $handle) {
-    handle title description availableForSale requiresSellingPlan
+    id handle title description descriptionHtml vendor productType availableForSale requiresSellingPlan
     featuredImage { url altText }
-    variants(first: 50) { nodes { id title availableForSale price { amount currencyCode } } }
-    sellingPlanGroups(first: 1) { nodes { sellingPlans(first: 1) { nodes { id } } } }
+    images(first: 20) { nodes { url altText } }
+    options { name optionValues { name } }
+    variants(first: 100) { nodes { id title availableForSale sku price { amount currencyCode } compareAtPrice { amount currencyCode } image { url altText } selectedOptions { name value } } }
+    sellingPlanGroups(first: 5) { nodes { name sellingPlans(first: 10) { nodes { id name } } } }
+    seo { title description }
   }
 }`;
 
+/** The fields a product card needs. */
+export const CARD_FIELDS = `handle title availableForSale requiresSellingPlan featuredImage { url altText }
+      priceRange { minVariantPrice { amount currencyCode } }
+      compareAtPriceRange { minVariantPrice { amount currencyCode } }
+      variants(first: 2) { nodes { id availableForSale } }`;
+
+export type RawCard = {
+	handle: string;
+	title: string;
+	availableForSale: boolean;
+	requiresSellingPlan?: boolean;
+	featuredImage: Image | null;
+	priceRange?: { minVariantPrice: Money } | null;
+	compareAtPriceRange?: { minVariantPrice: Money } | null;
+	variants?: { nodes: Array<{ id: string; availableForSale: boolean }> };
+};
+
+export function toCard(p: RawCard): ProductCard {
+	const price = p.priceRange?.minVariantPrice ?? null;
+	const compare = p.compareAtPriceRange?.minVariantPrice ?? null;
+	const only = p.variants?.nodes.length === 1 ? p.variants.nodes[0] : null;
+	return {
+		handle: p.handle,
+		title: p.title,
+		availableForSale: p.availableForSale,
+		image: p.featuredImage ?? null,
+		price,
+		compareAtPrice: compare && price && Number(compare.amount) > Number(price.amount) ? compare : null,
+		quickAddVariantId: only?.availableForSale && !p.requiresSellingPlan ? only.id : null,
+	};
+}
+
 const COLLECTION_QUERY = `query Collection($handle: String!, $first: Int!) {
   collection(handle: $handle) {
     handle title description
     products(first: $first) {
-      nodes { handle title availableForSale featuredImage { url altText } priceRange { minVariantPrice { amount currencyCode } } }
+      nodes { ${CARD_FIELDS} }
     }
   }
 }`;
@@ -269,66 +403,74 @@ async function cached<T>(key: string, load: () => Promise<T>): Promise<T> {
 	return value;
 }
 
-/** A product with its variants, cached for five minutes. Null when Shopify has no such product. */
-export async function product(config: RedeemIDConfig, handle: string, fetcher?: typeof fetch): Promise<Product | null> {
-	return cached(`${shopOrigin(config)}|product|${handle}`, async () => {
-		type Data = {
-			product: {
-				handle: string;
-				title: string;
-				description: string;
-				availableForSale: boolean;
-				requiresSellingPlan: boolean;
-				featuredImage: Image | null;
-				variants: { nodes: Variant[] };
-				sellingPlanGroups: { nodes: Array<{ sellingPlans: { nodes: Array<{ id: string }> } }> };
-			} | null;
-		};
-		const { product: p } = await storefront<Data>(config, PRODUCT_QUERY, { handle }, { fetcher });
-		if (!p) return null;
-		return {
-			handle: p.handle,
-			title: p.title,
-			description: p.description,
-			availableForSale: p.availableForSale,
-			image: p.featuredImage ?? null,
-			variants: p.variants.nodes,
-			sellingPlanId: p.requiresSellingPlan ? (p.sellingPlanGroups.nodes[0]?.sellingPlans.nodes[0]?.id ?? null) : null,
-		};
+type RawProduct = {
+	id: string;
+	handle: string;
+	title: string;
+	description: string;
+	descriptionHtml?: string;
+	vendor?: string;
+	productType?: string;
+	availableForSale: boolean;
+	requiresSellingPlan: boolean;
+	featuredImage: Image | null;
+	images?: { nodes: Image[] };
+	options?: Array<{ name: string; optionValues?: Array<{ name: string }> }>;
+	variants: { nodes: Variant[] };
+	sellingPlanGroups: { nodes: Array<{ name?: string; sellingPlans: { nodes: Array<{ id: string; name?: string }> } }> };
+	seo?: { title: string | null; description: string | null } | null;
+};
+
+function toProduct(p: RawProduct): Product {
+	const plans: SellingPlan[] = p.sellingPlanGroups.nodes.flatMap((g) => g.sellingPlans.nodes.map((sp) => ({ id: sp.id, name: sp.name ?? "", group: g.name ?? "" })));
+	const images = p.images?.nodes ?? [];
+	const featured = p.featuredImage ?? null;
+	return {
+		id: p.id,
+		handle: p.handle,
+		title: p.title,
+		description: p.description,
+		descriptionHtml: p.descriptionHtml ?? "",
+		vendor: p.vendor ?? "",
+		productType: p.productType ?? "",
+		availableForSale: p.availableForSale,
+		image: featured,
+		images: featured ? [featured, ...images.filter((i) => i.url !== featured.url)] : images,
+		options: (p.options ?? []).map((o) => ({ name: o.name, values: (o.optionValues ?? []).map((v) => v.name) })),
+		variants: p.variants.nodes,
+		sellingPlanId: p.requiresSellingPlan ? (plans[0]?.id ?? null) : null,
+		requiresSellingPlan: p.requiresSellingPlan,
+		sellingPlans: plans,
+		seo: p.seo ?? { title: null, description: null },
+	};
+}
+
+/** A product with its variants, options, images and selling plans, cached for five minutes. Null when Shopify has no such product. */
+export async function product(config: RedeemIDConfig, handle: string, fetcher?: typeof fetch, context?: StoreContext): Promise<Product | null> {
+	return cached(`${shopOrigin(config)}|product|${handle}|${contextKey(context)}`, async () => {
+		const { product: p } = await storefront<{ product: RawProduct | null }>(config, PRODUCT_QUERY, { handle }, { fetcher, context });
+		return p ? toProduct(p) : null;
 	});
 }
 
 /** A collection's first `first` products, cached for five minutes. Null when Shopify has no such collection. */
-export async function collection(config: RedeemIDConfig, handle: string, first = 12, fetcher?: typeof fetch): Promise<Collection | null> {
+export async function collection(config: RedeemIDConfig, handle: string, first = 12, fetcher?: typeof fetch, context?: StoreContext): Promise<Collection | null> {
 	const n = Math.max(1, Math.min(50, Math.floor(first)));
-	return cached(`${shopOrigin(config)}|collection|${handle}|${n}`, async () => {
-		type Data = {
-			collection: {
-				handle: string;
-				title: string;
-				description: string;
-				products: {
-					nodes: Array<{ handle: string; title: string; availableForSale: boolean; featuredImage: Image | null; priceRange: { minVariantPrice: Money } }>;
-				};
-			} | null;
-		};
-		const { collection: c } = await storefront<Data>(config, COLLECTION_QUERY, { handle, first: n }, { fetcher });
+	return cached(`${shopOrigin(config)}|collection|${handle}|${n}|${contextKey(context)}`, async () => {
+		type Data = { collection: { handle: string; title: string; description: string; products: { nodes: RawCard[] } } | null };
+		const { collection: c } = await storefront<Data>(config, COLLECTION_QUERY, { handle, first: n }, { fetcher, context });
 		if (!c) return null;
-		return {
-			handle: c.handle,
-			title: c.title,
-			description: c.description,
-			products: c.products.nodes.map((p) => ({
-				handle: p.handle,
-				title: p.title,
-				availableForSale: p.availableForSale,
-				image: p.featuredImage ?? null,
-				price: p.priceRange?.minVariantPrice ?? null,
-			})),
-		};
+		return { handle: c.handle, title: c.title, description: c.description, products: c.products.nodes.map(toCard) };
 	});
 }
 
+/** Cache a Storefront read for five minutes, by key. Used by the catalog module. */
+export function cachedRead<T>(key: string, load: () => Promise<T>): Promise<T> {
+	return cached(key, load);
+}
+
+export { contextKey };
+
 /** Format Shopify money for display. */
 export function money(m: Money | null | undefined, locale = "en-US"): string | null {
 	if (!m) return null;
@@ -349,6 +491,10 @@ export interface CartLine {
 	image: Image | null;
 	price: Money | null;
 	total: Money | null;
+	/** The selling plan the line is bought on (a subscription), by name. */
+	sellingPlan?: string | null;
+	/** The line's price per item before a sale, when there is one. */
+	compareAtPrice?: Money | null;
 }
 
 export interface CartDetails extends Cart {
@@ -363,7 +509,8 @@ const CART_DETAIL_FIELDS = `${CART_FIELDS}
   discountCodes { code applicable }
   lines(first: 100) { nodes {
     id quantity
-    cost { totalAmount { amount currencyCode } }
+    cost { totalAmount { amount currencyCode } compareAtAmountPerQuantity { amount currencyCode } }
+    sellingPlanAllocation { sellingPlan { name } }
     merchandise { ... on ProductVariant { id title price { amount currencyCode } image { url altText } product { title handle featuredImage { url altText } } } }
   } }`;
 
@@ -374,7 +521,8 @@ type RawCart = Cart & {
 		nodes: Array<{
 			id: string;
 			quantity: number;
-			cost?: { totalAmount?: Money | null } | null;
+			cost?: { totalAmount?: Money | null; compareAtAmountPerQuantity?: Money | null } | null;
+			sellingPlanAllocation?: { sellingPlan?: { name?: string } | null } | null;
 			merchandise: {
 				id: string;
 				title: string;
@@ -404,6 +552,8 @@ function details(c: RawCart): CartDetails {
 			image: l.merchandise.image ?? l.merchandise.product.featuredImage ?? null,
 			price: l.merchandise.price ?? null,
 			total: l.cost?.totalAmount ?? null,
+			sellingPlan: l.sellingPlanAllocation?.sellingPlan?.name ?? null,
+			compareAtPrice: l.cost?.compareAtAmountPerQuantity ?? null,
 		})),
 	};
 }
@@ -471,3 +621,25 @@ export async function setDiscountCodes(
 	);
 	return result(data.cartDiscountCodesUpdate);
 }
+
+/**
+ * Sign the cart in as the member, with their Customer Account API access
+ * token, so Shopify's checkout opens signed in and the order lands on their
+ * customer. Returns the cart's fresh checkout URL, or null when Shopify
+ * refused (the visitor then checks out as a guest).
+ */
+export async function signInCart(
+	config: RedeemIDConfig,
+	cartId: string,
+	customerAccessToken: string,
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<string | null> {
+	const data = await storefront<{ cartBuyerIdentityUpdate: { cart: { checkoutUrl: string } | null; userErrors: Array<{ message: string }> } }>(
+		config,
+		`mutation CartIdentity($id: ID!, $identity: CartBuyerIdentityInput!) { cartBuyerIdentityUpdate(cartId: $id, buyerIdentity: $identity) { cart { checkoutUrl } userErrors { message } } }`,
+		{ id: cartId, identity: { customerAccessToken } },
+		opts,
+	).catch(() => null);
+	const cart = data?.cartBuyerIdentityUpdate.cart;
+	return cart && !data?.cartBuyerIdentityUpdate.userErrors.length ? cart.checkoutUrl : null;
+}