@redeemid/emdash 0.0.7 → 0.0.9

package/src/routes/cart-edit.ts

@@ -0,0 +1,97 @@
+/**
+ * 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),
+ *   `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.
+ */
+
+import type { APIRoute } from "astro";
+
+import { safeReturn } from "../access.js";
+import { readCart, saveCart } from "../cart.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 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");
+		}
+
+		return fail(redirect, returnTo, "cart_updated");
+	} catch {
+		return fail(redirect, returnTo, "checkout_failed");
+	}
+};

package/src/routes/webhook.ts

@@ -8,7 +8,8 @@
 
 import type { APIRoute } from "astro";
 
-import { env, ENV } from "../config.js";
+import { env, ENV, readConfig } from "../config.js";
+import { levelChange } from "../events.js";
 import { stores } from "../storage.js";
 import { apply, kindOf, verifyHmac } from "../webhooks.js";
 
@@ -17,7 +18,7 @@ export const prerender = false;
 const MAX_BYTES = 1024 * 1024;
 
 export const POST: APIRoute = async ({ request, locals }) => {
-	const emdash = (locals as { emdash?: { db?: unknown } }).emdash;
+	const emdash = (locals as { emdash?: { db?: unknown; config?: unknown } }).emdash;
 	const secret = env(ENV.webhookSecret);
 	if (!emdash?.db || !secret) return new Response("Not configured", { status: 503 });
 
@@ -48,7 +49,8 @@ export const POST: APIRoute = async ({ request, locals }) => {
 	}
 
 	try {
-		const outcome = await apply(s, topic, payload);
+		const config = readConfig(emdash.config);
+		const outcome = await apply(s, topic, payload, (before, after) => levelChange(config, before, after, topic));
 		return new Response(outcome, { status: 200 });
 	} catch (e) {
 		console.error("[redeemid] webhook failed:", topic, (e as Error).message);

package/src/staff.ts

@@ -0,0 +1,220 @@
+/**
+ * Staff tools in the admin (Block Kit): member detail with Resync and tag
+ * edits written to Shopify, a paced manual bulk resync, webhook
+ * registration and health, recent deliveries and the access test.
+ */
+
+import { adminConfigured, adminScopes, editTags, registerWebhooks, resync, webhookSubscriptions, WEBHOOK_TOPICS } from "./admin-api.js";
+import { describe, levelsFor, membership, passes, requirement, termTree, type Terms } from "./access.js";
+import type { RedeemIDConfig } from "./config.js";
+import { levelChange } from "./events.js";
+import { featuresFor } from "./features.js";
+import { cleanTags, numericId, type MemberRecord, type Stores } from "./storage.js";
+
+/** Members resynced per click; well inside Shopify's query cost limits. */
+export const BULK_BATCH = 50;
+
+type Blocks = { blocks: unknown[]; toast?: { message: string; type: "success" | "error" | "info" } };
+
+const date = (iso: string | null | undefined) => (iso ? iso.slice(0, 10) : "—");
+
+export function memberDetail(config: RedeemIDConfig, m: MemberRecord, toast?: Blocks["toast"]): Blocks {
+	const levels = config.levels ?? [];
+	const { current, past } = membership(m, levels);
+	const features = featuresFor(m, config.features, levels);
+	const featureNames = (config.features ?? []).filter((f) => features.includes(f.slug)).map((f) => f.name);
+	const name = [m.firstName, m.lastName].filter(Boolean).join(" ") || m.email || `Customer ${m.customerId}`;
+	return {
+		toast,
+		blocks: [
+			{ type: "actions", elements: [{ type: "button", action_id: "members_back", label: "← All members", style: "secondary" }] },
+			{ type: "header", text: name },
+			{
+				type: "fields",
+				fields: [
+					{ label: "Email", value: m.email ?? "—" },
+					{ label: "Shopify customer", value: m.customerId },
+					{ label: "Account", value: m.status === "enabled" ? "On" : "Turned off in Shopify" },
+					{ label: "Signed in here", value: m.userId ? `Yes, first on ${date(m.linkedAt)}` : "Not yet" },
+					{ label: "Levels", value: current.map((l) => `${l.name} (since ${date(l.since)})`).join(", ") || "—" },
+					{ label: "Levels before", value: past.map((l) => `${l.name} (${date(l.from)} to ${date(l.to)})`).join(", ") || "—" },
+					{ label: "Features", value: featureNames.join(", ") || "—" },
+					{ label: "Last synced", value: `${m.syncedAt} (${m.source || "unknown"})` },
+				],
+			},
+			{ type: "header", text: "Shopify tags" },
+			m.tags.length
+				? {
+						type: "table",
+						page_action_id: "member_tags",
+						columns: [
+							{ key: "tag", label: "Tag" },
+							{ key: "since", label: "Since" },
+							{ key: "remove", label: "", format: "element" },
+						],
+						rows: m.tags.map((t) => ({
+							tag: t,
+							since: date(m.tagsSince?.[t.toLowerCase()]),
+							remove: adminConfigured()
+								? {
+										type: "button",
+										action_id: "member_tag_remove",
+										label: "Remove in Shopify",
+										style: "danger",
+										value: { customerId: m.customerId, tag: t },
+										confirm: { title: "Remove this tag in Shopify?", text: `Removes "${t}" from the customer in Shopify. Access follows.`, confirm: "Remove", deny: "Cancel", style: "danger" },
+									}
+								: null,
+						})),
+					}
+				: { type: "context", text: "No tags." },
+			adminConfigured()
+				? {
+						type: "form",
+						block_id: `tags:${m.customerId}`,
+						fields: [{ type: "text_input", action_id: "tags", label: "Add tags in Shopify (comma separated)", placeholder: "gold-member" }],
+						submit: { label: "Add in Shopify", action_id: "member_tag_add" },
+					}
+				: { type: "context", text: "Set the Admin API app's client ID to edit tags and resync from here." },
+			adminConfigured()
+				? { type: "actions", elements: [{ type: "button", action_id: "member_resync", label: "Resync from Shopify", style: "primary", value: m.customerId }] }
+				: { type: "divider" },
+			{ type: "context", text: "Tags are written to Shopify, then read back. Shopify stays the only source of access." },
+		],
+	};
+}
+
+/** Resync the members synced longest ago, one batch per click. */
+export async function bulkResync(config: RedeemIDConfig, s: Stores): Promise<{ done: number; missing: number; changed: number }> {
+	const page = await s.members.query({ orderBy: { syncedAt: "asc" }, limit: BULK_BATCH });
+	const ids = page.items.map((r) => r.data.customerId);
+	const before = new Map(page.items.map((r) => [r.data.customerId, [...r.data.tags]]));
+	const { updated, missing } = await resync(config, s, ids, "bulk resync");
+	let changed = 0;
+	for (const m of updated) {
+		const was = before.get(m.customerId) ?? [];
+		if (was.join("\n") !== m.tags.join("\n")) changed++;
+		await levelChange(config, was, m, "bulk resync");
+	}
+	return { done: updated.length, missing: missing.length, changed };
+}
+
+export async function resyncOne(config: RedeemIDConfig, s: Stores, customerId: string, source: string): Promise<MemberRecord | null> {
+	const before = await s.members.get(customerId);
+	const { updated } = await resync(config, s, [customerId], source);
+	const m = updated[0] ?? null;
+	if (m) await levelChange(config, before?.tags ?? null, m, source);
+	return m;
+}
+
+export async function tagEdit(config: RedeemIDConfig, s: Stores, customerId: string, change: "add" | "remove", raw: unknown): Promise<MemberRecord | null> {
+	const id = numericId(customerId);
+	if (!id) return null;
+	await editTags(config, id, change, cleanTags(raw));
+	return resyncOne(config, s, id, change === "add" ? "staff added tags" : "staff removed tags");
+}
+
+/** Webhooks: what Shopify sends to this site, and what's missing. */
+export async function webhooksSection(config: RedeemIDConfig, uri: string): Promise<unknown[]> {
+	if (!adminConfigured()) {
+		return [{ type: "context", text: "Set the Admin API app's client ID to check and register webhooks from here. Until then, add them in the app's settings." }];
+	}
+	try {
+		const [subs, scope] = await Promise.all([webhookSubscriptions(config), adminScopes(config)]);
+		const rows = WEBHOOK_TOPICS.map((t) => {
+			const here = subs.find((s) => s.topic === t && s.uri === uri);
+			const elsewhere = subs.find((s) => s.topic === t && s.uri !== uri);
+			return { topic: t.toLowerCase().replace("_", "/").replace("customer/tags", "customer.tags"), state: here ? "Registered" : elsewhere ? `Goes to ${elsewhere.uri}` : "Missing" };
+		});
+		const missing = rows.filter((r) => r.state !== "Registered").length;
+		return [
+			{ type: "fields", fields: [{ label: "Admin API", value: `Connected (${scope || "no scopes reported"})` }, { label: "Webhook address", value: uri }] },
+			{ type: "table", page_action_id: "webhooks", columns: [{ key: "topic", label: "Topic" }, { key: "state", label: "Sends here", format: "badge" }], rows },
+			missing
+				? { type: "actions", elements: [{ type: "button", action_id: "webhooks_register", label: `Register ${missing} missing`, style: "primary", value: uri }] }
+				: { type: "context", text: "Every topic RedeemID needs is sent here. customers/redact is set in the app's compliance settings." },
+		];
+	} catch (e) {
+		return [{ type: "banner", variant: "alert", title: "Couldn't read webhooks from Shopify", description: (e as Error).message }];
+	}
+}
+
+export async function deliveriesSection(s: Stores): Promise<unknown[]> {
+	const { items } = await s.deliveries.query({ orderBy: { receivedAt: "desc" }, limit: 20 });
+	return items.length
+		? [
+				{
+					type: "table",
+					page_action_id: "deliveries",
+					columns: [
+						{ key: "topic", label: "Topic", format: "code" },
+						{ key: "at", label: "Received", format: "relative_time" },
+						{ key: "id", label: "Delivery" },
+					],
+					rows: items.map((r) => ({ topic: r.data.topic, at: r.data.receivedAt, id: r.id })),
+				},
+			]
+		: [{ type: "context", text: "No webhooks received yet." }];
+}
+
+export { registerWebhooks };
+
+/** "category:pro, tag:weekend" → { category: ["pro"], tag: ["weekend"] } */
+export function parseTerms(raw: string): Terms {
+	const terms: Record<string, string[]> = {};
+	for (const part of raw.split(",")) {
+		const [tax, term] = part.split(":").map((x) => x.trim());
+		if (tax && term) (terms[tax] ??= []).push(term);
+	}
+	return terms;
+}
+
+/** The access test: what an entry needs, and whether a reader with these tags passes. */
+export async function accessTest(config: RedeemIDConfig, values: Record<string, unknown> = {}): Promise<Blocks> {
+	const collection = String(values.collection ?? "").trim();
+	const termsRaw = String(values.terms ?? "").trim();
+	const tags = cleanTags(String(values.tags ?? ""));
+	const signedIn = values.signed_in !== false;
+	const levels = config.levels ?? [];
+	const form = {
+		type: "form",
+		block_id: "access_test",
+		fields: [
+			{ type: "text_input", action_id: "collection", label: "Collection", placeholder: "posts", initial_value: collection },
+			{ type: "text_input", action_id: "terms", label: "Terms (taxonomy:slug, comma separated)", placeholder: "category:investigations, tag:free-to-read", initial_value: termsRaw },
+			{ type: "text_input", action_id: "tags", label: "Reader's Shopify tags (comma separated)", placeholder: "gold-member", initial_value: tags.join(", ") },
+			{ type: "toggle", action_id: "signed_in", label: "Signed in", initial_value: signedIn },
+		],
+		submit: { label: "Test", action_id: "access_test" },
+	};
+	const out: unknown[] = [
+		{ type: "header", text: "Access test" },
+		{ type: "context", text: "Check what an entry needs under the rules, and whether a reader with some Shopify tags may read it. Nothing is saved." },
+		form,
+	];
+	if (collection) {
+		const terms = parseTerms(termsRaw);
+		const tree = await termTree(config.rules, collection, terms);
+		const required = requirement(config.rules, collection, terms, { combine: config.combine, tree });
+		const held = levelsFor(tags, levels);
+		const ok = required === null || (signedIn && passes(held, required));
+		out.push(
+			{ type: "divider" },
+			{
+				type: "fields",
+				fields: [
+					{ label: "Needs", value: describe(required, levels) },
+					{ label: "Reader's levels", value: levels.filter((l) => held.includes(l.slug)).map((l) => l.name).join(", ") || "None" },
+					{ label: "Result", value: ok ? "Can read" : signedIn ? "Locked: asked to upgrade" : "Locked: asked to sign in" },
+				],
+			},
+			{
+				type: "banner",
+				variant: ok ? "default" : "alert",
+				title: ok ? "This reader can read it" : "This reader is kept out",
+				description: "A Paywall break with levels picked, a Members only part, drip and the meter can still change what a page shows.",
+			},
+		);
+	}
+	return { blocks: out };
+}

package/src/storage.ts

@@ -78,7 +78,7 @@ export interface DeliveryRecord {
 }
 
 export const STORAGE_CONFIG = {
-	members: { indexes: ["email", "userId"] },
+	members: { indexes: ["email", "userId", "syncedAt"] },
 	deliveries: { indexes: ["receivedAt"] },
 	meter: { indexes: ["userId"] },
 };

package/src/storefront.ts

@@ -27,6 +27,7 @@ const planCache = new Map<string, { at: number; value: Plan | null }>();
 
 export function resetStorefrontCache(): void {
 	planCache.clear();
+	shopCache.clear();
 }
 
 export async function storefront<T>(
@@ -169,18 +170,304 @@ export async function getCart(
 export async function addToCart(
 	config: RedeemIDConfig,
 	cartId: string | null,
-	line: { variantId: string; sellingPlanId?: string | null },
-	opts: { email?: string | null; buyerIp?: string | null; fetcher?: typeof fetch } = {},
+	line: { variantId: string; sellingPlanId?: string | null; quantity?: number },
+	opts: {
+		email?: string | null;
+		/** Cart attributes for a new cart, e.g. where the buyer came from. Keys starting "_" are hidden at checkout. */
+		attributes?: Record<string, string>;
+		buyerIp?: string | null;
+		fetcher?: typeof fetch;
+	} = {},
 ): Promise<Cart> {
-	const lines = [{ merchandiseId: line.variantId, quantity: 1, ...(line.sellingPlanId ? { sellingPlanId: line.sellingPlanId } : {}) }];
+	const quantity = Math.max(1, Math.floor(line.quantity ?? 1));
+	const lines = [{ merchandiseId: line.variantId, quantity, ...(line.sellingPlanId ? { sellingPlanId: line.sellingPlanId } : {}) }];
 	if (cartId) {
 		const data = await storefront<{ cartLinesAdd: CartResult }>(config, CART_ADD, { id: cartId, lines }, opts).catch(() => null);
 		if (data?.cartLinesAdd.cart) return data.cartLinesAdd.cart;
 	}
 	const input: Record<string, unknown> = { lines };
 	if (opts.email) input.buyerIdentity = { email: opts.email };
+	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);
 	const cart = data.cartCreate.cart;
 	if (!cart) throw new Error(data.cartCreate.userErrors[0]?.message ?? "Shopify returned no cart.");
 	return cart;
 }
+
+// ---------------------------------------------------------------- shop
+
+export interface Money {
+	amount: string;
+	currencyCode: string;
+}
+
+export interface Image {
+	url: string;
+	altText: string | null;
+}
+
+export interface Variant {
+	id: string;
+	title: string;
+	availableForSale: boolean;
+	price: Money;
+}
+
+export interface Product {
+	handle: string;
+	title: string;
+	description: string;
+	availableForSale: boolean;
+	image: Image | null;
+	variants: Variant[];
+	/** The first selling plan, for subscription-only products. */
+	sellingPlanId: string | null;
+}
+
+export interface ProductCard {
+	handle: string;
+	title: string;
+	availableForSale: boolean;
+	image: Image | null;
+	/** The lowest variant price. */
+	price: Money | null;
+}
+
+export interface Collection {
+	handle: string;
+	title: string;
+	description: string;
+	products: ProductCard[];
+}
+
+const PRODUCT_QUERY = `query Product($handle: String!) {
+  product(handle: $handle) {
+    handle title description availableForSale requiresSellingPlan
+    featuredImage { url altText }
+    variants(first: 50) { nodes { id title availableForSale price { amount currencyCode } } }
+    sellingPlanGroups(first: 1) { nodes { sellingPlans(first: 1) { nodes { id } } } }
+  }
+}`;
+
+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 } } }
+    }
+  }
+}`;
+
+const shopCache = new Map<string, { at: number; value: unknown }>();
+
+async function cached<T>(key: string, load: () => Promise<T>): Promise<T> {
+	const hit = shopCache.get(key);
+	if (hit && Date.now() - hit.at < PLAN_TTL_MS) return hit.value as T;
+	const value = await load();
+	shopCache.set(key, { at: Date.now(), value });
+	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,
+		};
+	});
+}
+
+/** 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> {
+	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 });
+		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,
+			})),
+		};
+	});
+}
+
+/** Format Shopify money for display. */
+export function money(m: Money | null | undefined, locale = "en-US"): string | null {
+	if (!m) return null;
+	const n = Number(m.amount);
+	if (!Number.isFinite(n)) return null;
+	return new Intl.NumberFormat(locale, { style: "currency", currency: m.currencyCode }).format(n);
+}
+
+// ---------------------------------------------------------------- cart details
+
+export interface CartLine {
+	id: string;
+	quantity: number;
+	variantId: string;
+	variantTitle: string;
+	productTitle: string;
+	productHandle: string;
+	image: Image | null;
+	price: Money | null;
+	total: Money | null;
+}
+
+export interface CartDetails extends Cart {
+	lines: CartLine[];
+	subtotal: Money | null;
+	total: Money | null;
+	discountCodes: Array<{ code: string; applicable: boolean }>;
+}
+
+const CART_DETAIL_FIELDS = `${CART_FIELDS}
+  cost { subtotalAmount { amount currencyCode } totalAmount { amount currencyCode } }
+  discountCodes { code applicable }
+  lines(first: 100) { nodes {
+    id quantity
+    cost { totalAmount { amount currencyCode } }
+    merchandise { ... on ProductVariant { id title price { amount currencyCode } image { url altText } product { title handle featuredImage { url altText } } } }
+  } }`;
+
+type RawCart = Cart & {
+	cost?: { subtotalAmount?: Money | null; totalAmount?: Money | null } | null;
+	discountCodes?: Array<{ code: string; applicable: boolean }>;
+	lines?: {
+		nodes: Array<{
+			id: string;
+			quantity: number;
+			cost?: { totalAmount?: Money | null } | null;
+			merchandise: {
+				id: string;
+				title: string;
+				price?: Money | null;
+				image?: Image | null;
+				product: { title: string; handle: string; featuredImage?: Image | null };
+			};
+		}>;
+	};
+};
+
+function details(c: RawCart): CartDetails {
+	return {
+		id: c.id,
+		checkoutUrl: c.checkoutUrl,
+		totalQuantity: c.totalQuantity,
+		subtotal: c.cost?.subtotalAmount ?? null,
+		total: c.cost?.totalAmount ?? null,
+		discountCodes: c.discountCodes ?? [],
+		lines: (c.lines?.nodes ?? []).map((l) => ({
+			id: l.id,
+			quantity: l.quantity,
+			variantId: l.merchandise.id,
+			variantTitle: l.merchandise.title,
+			productTitle: l.merchandise.product.title,
+			productHandle: l.merchandise.product.handle,
+			image: l.merchandise.image ?? l.merchandise.product.featuredImage ?? null,
+			price: l.merchandise.price ?? null,
+			total: l.cost?.totalAmount ?? null,
+		})),
+	};
+}
+
+type DetailResult = { cart: RawCart | null; userErrors: Array<{ message: string }> };
+
+/** The cart with its lines, costs and discount codes. Null once Shopify no longer has it. */
+export async function cartDetails(
+	config: RedeemIDConfig,
+	id: string,
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<CartDetails | null> {
+	const data = await storefront<{ cart: RawCart | null }>(config, `query Cart($id: ID!) { cart(id: $id) { ${CART_DETAIL_FIELDS} } }`, { id }, opts);
+	return data.cart ? details(data.cart) : null;
+}
+
+function result(r: DetailResult): CartDetails {
+	if (!r.cart) throw new Error(r.userErrors[0]?.message ?? "Shopify returned no cart.");
+	return details(r.cart);
+}
+
+/** Set line quantities; a quantity of 0 removes the line. */
+export async function updateLines(
+	config: RedeemIDConfig,
+	cartId: string,
+	lines: Array<{ id: string; quantity: number }>,
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<CartDetails> {
+	const data = await storefront<{ cartLinesUpdate: DetailResult }>(
+		config,
+		`mutation CartUpdate($id: ID!, $lines: [CartLineUpdateInput!]!) { cartLinesUpdate(cartId: $id, lines: $lines) { cart { ${CART_DETAIL_FIELDS} } userErrors { message } } }`,
+		{ id: cartId, lines },
+		opts,
+	);
+	return result(data.cartLinesUpdate);
+}
+
+export async function removeLines(
+	config: RedeemIDConfig,
+	cartId: string,
+	lineIds: string[],
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<CartDetails> {
+	const data = await storefront<{ cartLinesRemove: DetailResult }>(
+		config,
+		`mutation CartRemove($id: ID!, $lineIds: [ID!]!) { cartLinesRemove(cartId: $id, lineIds: $lineIds) { cart { ${CART_DETAIL_FIELDS} } userErrors { message } } }`,
+		{ id: cartId, lineIds },
+		opts,
+	);
+	return result(data.cartLinesRemove);
+}
+
+/** Replace the cart's discount codes (an empty list clears them). */
+export async function setDiscountCodes(
+	config: RedeemIDConfig,
+	cartId: string,
+	codes: string[],
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<CartDetails> {
+	const data = await storefront<{ cartDiscountCodesUpdate: DetailResult }>(
+		config,
+		`mutation CartDiscount($id: ID!, $codes: [String!]) { cartDiscountCodesUpdate(cartId: $id, discountCodes: $codes) { cart { ${CART_DETAIL_FIELDS} } userErrors { message } } }`,
+		{ id: cartId, codes },
+		opts,
+	);
+	return result(data.cartDiscountCodesUpdate);
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.0.7";
+export const VERSION = "0.0.9";