@redeemid/emdash 0.0.16 → 0.0.18

package/src/access.ts

@@ -11,6 +11,7 @@
  */
 
 import type { LevelConfig, RedeemIDConfig, RuleConfig } from "./config.js";
+import type { EntryRule } from "./settings.js";
 import { siteConfig } from "./site-config.js";
 import { memberForUser, stores, type MemberRecord } from "./storage.js";
 
@@ -108,9 +109,14 @@ function combined(rules: RuleConfig[], mode: "all" | "any"): string[][] {
 	return reduce(rules.map((r) => r.levels));
 }
 
+/** Rules that can cover `collection`: its own, and term rules for every collection ("*"). */
+function rulesFor(rules: RuleConfig[], collection: string): RuleConfig[] {
+	return rules.filter((r) => r.collection === collection || (r.collection === "*" && r.taxonomy && r.term));
+}
+
 /** The rules that decide an entry: matching term rules, else the collection's, else the site default. */
 function deciding(rules: RuleConfig[], collection: string, terms: Terms, tree?: TermTree): RuleConfig[] | "open" {
-	const forCollection = rules.filter((r) => r.collection === collection);
+	const forCollection = rulesFor(rules, collection);
 	const matched: RuleConfig[] = [];
 	for (const [taxonomy, list] of Object.entries(terms)) {
 		const taxRules = forCollection.filter((r) => r.taxonomy === taxonomy && r.term);
@@ -123,7 +129,9 @@ function deciding(rules: RuleConfig[], collection: string, terms: Terms, tree?:
 				seen.add(slug);
 				const own = taxRules.filter((r) => r.term === slug);
 				if (own.length > 0) {
-					matched.push(...own);
+					// A rule for this collection beats one for every collection.
+					const specific = own.filter((r) => r.collection === collection);
+					matched.push(...(specific.length ? specific : own));
 					break;
 				}
 				slug = parents[slug] ?? null;
@@ -132,9 +140,54 @@ function deciding(rules: RuleConfig[], collection: string, terms: Terms, tree?:
 	}
 	if (matched.some((r) => r.open)) return "open";
 	if (matched.length > 0) return matched;
-	const whole = forCollection.filter((r) => !r.taxonomy && !r.term && !r.open);
+	const whole = forCollection.filter((r) => r.collection === collection && !r.taxonomy && !r.term);
+	if (whole.some((r) => r.open)) return "open";
 	if (whole.length > 0) return whole;
-	return rules.filter((r) => r.collection === "*" && !r.taxonomy && !r.term && !r.open);
+	const site = rules.filter((r) => r.collection === "*" && !r.taxonomy && !r.term);
+	if (site.some((r) => r.open)) return "open";
+	return site;
+}
+
+/** Where the site's rules for an entry come from, in words, for the editor. */
+export function ruleSource(rules: RuleConfig[] = [], collection: string, terms: Terms = {}, tree?: TermTree): string {
+	const found = deciding(rules, collection, terms, tree);
+	const termRules = (list: RuleConfig[]) => [...new Set(list.map((r) => `${r.taxonomy}: ${r.term}`))].join(", ");
+	if (found === "open") {
+		const opener = rulesFor(rules, collection).filter((r) => r.open && r.taxonomy);
+		const hit = opener.filter((r) => (terms[r.taxonomy!] ?? []).some((t) => slugOf(t) === r.term));
+		if (hit.length) return `A term that makes it free (${termRules(hit)})`;
+		return rules.some((r) => r.collection === collection && r.open && !r.taxonomy) ? `The rule for ${collection} (free)` : "The site default (free)";
+	}
+	if (found.length === 0) return "No rule covers it";
+	if (found[0]!.taxonomy) return `Terms: ${termRules(found)}`;
+	if (found[0]!.collection === collection) return `The rule for ${collection}`;
+	return "The site default";
+}
+
+/** The entry's own rule (set in the editor), by id or slug. */
+export function entryRuleFor(config: RedeemIDConfig | null, collection: string, id?: string | null): EntryRule | null {
+	if (!config?.entries || !id) return null;
+	return config.entries[`${collection}:${id}`] ?? null;
+}
+
+/**
+ * The site's requirement with the entry's own rule applied (see EntryRule).
+ * `now` decides the date windows.
+ */
+export function applyEntryRule(site: Requirement, own: EntryRule | null, now = Date.now()): Requirement {
+	if (!own) return site;
+	if (own.openUntil && now < Date.parse(own.openUntil)) return null;
+	if (own.lockedUntil && now >= Date.parse(own.lockedUntil)) return null;
+	switch (own.mode) {
+		case "open":
+			return null;
+		case "levels":
+			return [own.levels];
+		case "add":
+			return reduce([...(site ?? []), own.levels]);
+		default:
+			return site;
+	}
 }
 
 /**
@@ -156,14 +209,18 @@ export function requirement(
 }
 
 /** Days of membership the entry's deciding rules ask for (the largest drip), or 0. */
-export function dripDays(rules: RuleConfig[] = [], collection: string, terms: Terms = {}, tree?: TermTree): number {
+export function dripDays(rules: RuleConfig[] = [], collection: string, terms: Terms = {}, tree?: TermTree, own?: EntryRule | null): number {
+	if (own && typeof own.drip === "number" && own.drip > 0) return own.drip;
+	if (own?.mode === "open" || own?.mode === "levels") return 0;
 	const found = deciding(rules, collection, terms, tree);
 	if (found === "open") return 0;
 	return Math.max(0, ...found.map((r) => (typeof r.drip === "number" && r.drip > 0 ? r.drip : 0)));
 }
 
 /** May the meter open the entry? Not when a deciding rule says `meter: false`. */
-export function meterable(rules: RuleConfig[] = [], collection: string, terms: Terms = {}, tree?: TermTree): boolean {
+export function meterable(rules: RuleConfig[] = [], collection: string, terms: Terms = {}, tree?: TermTree, own?: EntryRule | null): boolean {
+	if (own?.meter === false) return false;
+	if (own?.mode === "levels") return true;
 	const found = deciding(rules, collection, terms, tree);
 	return found === "open" || !found.some((r) => r.meter === false);
 }
@@ -229,7 +286,7 @@ export function membership(member: MemberRecord, levels: LevelConfig[] = []): {
 /** How much of this period's meter the signed-in reader has used, or null when no meter runs. */
 export async function meterUsage(astro: AstroLike): Promise<{ used: number; limit: number; period: "month" | "week" } | null> {
 	const locals = astro.locals as Locals;
-	const meter = siteConfig(locals.emdash?.config)?.meter;
+	const meter = (await siteConfig(locals))?.meter;
 	const user = locals.user;
 	const db = locals.emdash?.db;
 	if (!meter || !(meter.limit > 0) || !user?.id || !db) return null;
@@ -291,7 +348,7 @@ export function describe(required: Requirement, levels: LevelConfig[] = [], open
  */
 export async function termTree(rules: RuleConfig[] = [], collection: string, terms: Terms = {}): Promise<TermTree> {
 	const tree: TermTree = {};
-	const forCollection = rules.filter((r) => r.collection === collection && r.taxonomy && r.term);
+	const forCollection = rulesFor(rules, collection).filter((r) => r.taxonomy && r.term);
 	const wanted = Object.entries(terms).filter(([taxonomy, list]) => {
 		const own = new Set(forCollection.filter((r) => r.taxonomy === taxonomy).map((r) => r.term));
 		return own.size > 0 && (list ?? []).some((t) => !own.has(slugOf(t)));
@@ -316,15 +373,21 @@ export async function termTree(rules: RuleConfig[] = [], collection: string, ter
 	return tree;
 }
 
-/** The entry's requirement with the site's config, walking term parents. */
+/**
+ * The entry's requirement with the site's config, walking term parents. With
+ * `id` (EmDash's id or the slug), the entry's own rule from the editor applies.
+ */
 export async function entryRequirement(
 	config: RedeemIDConfig | null,
 	collection: string,
 	terms: Terms = {},
+	id?: string | null,
 ): Promise<Requirement> {
 	if (!config) return null;
+	const own = entryRuleFor(config, collection, id);
+	if (own && (own.mode === "open" || own.mode === "levels") && !own.openUntil && !own.lockedUntil) return applyEntryRule(null, own);
 	const tree = await termTree(config.rules, collection, terms);
-	return requirement(config.rules, collection, terms, { combine: config.combine, tree });
+	return applyEntryRule(requirement(config.rules, collection, terms, { combine: config.combine, tree }), own);
 }
 
 const viewers = new WeakMap<object, Promise<Viewer>>();
@@ -354,7 +417,7 @@ async function readViewer(astro: AstroLike): Promise<Viewer> {
 	// Member-specific output must never be shared by a cache.
 	astro.response?.headers.set("Cache-Control", "private, no-store");
 
-	const config = siteConfig(locals.emdash?.config);
+	const config = await siteConfig(locals);
 	const db = locals.emdash?.db;
 	if (!config || !db) return { signedIn: true, member: null, levels: [] };
 
@@ -369,16 +432,16 @@ async function readViewer(astro: AstroLike): Promise<Viewer> {
  */
 export async function canRead(
 	astro: AstroLike,
-	entry: { collection: string; terms?: Terms },
+	entry: { collection: string; terms?: Terms; id?: string; ruleId?: string },
 	override?: { levels: string[] } | { required: string[][] },
 ): Promise<Verdict> {
 	const locals = astro.locals as Locals;
-	const config: RedeemIDConfig | null = siteConfig(locals.emdash?.config);
+	const config: RedeemIDConfig | null = await siteConfig(locals);
 	const required: Requirement = override
 		? "required" in override
 			? override.required
 			: [override.levels]
-		: await entryRequirement(config, entry.collection, entry.terms);
+		: await entryRequirement(config, entry.collection, entry.terms, entry.ruleId ?? entry.id);
 	const v = await viewer(astro);
 
 	if (required === null) return { allowed: true, reason: "open", required: [], viewer: v };
@@ -426,17 +489,18 @@ export function signOutUrl(returnTo = "/"): string {
  */
 export async function readEntry(
 	astro: AstroLike,
-	entry: { collection: string; terms?: Terms; id?: string },
+	entry: { collection: string; terms?: Terms; id?: string; ruleId?: string },
 	override?: { required: string[][] },
 ): Promise<Verdict> {
 	const verdict = await canRead(astro, entry, override);
 	const locals = astro.locals as Locals;
-	const config = siteConfig(locals.emdash?.config);
+	const config = await siteConfig(locals);
 	if (!config) return verdict;
 
 	if (verdict.allowed && verdict.reason === "allowed" && verdict.viewer.member) {
+		const own = entryRuleFor(config, entry.collection, entry.ruleId ?? entry.id);
 		const tree = await termTree(config.rules, entry.collection, entry.terms);
-		const days = dripDays(config.rules, entry.collection, entry.terms, tree);
+		const days = dripDays(config.rules, entry.collection, entry.terms, tree, own);
 		const opensAt = dripOpensAt(memberSince(verdict.viewer.member, config.levels), days);
 		if (days > 0 && (!opensAt || opensAt.getTime() > Date.now())) {
 			return { ...verdict, allowed: false, reason: "drip", opensAt: opensAt ?? undefined };
@@ -458,7 +522,7 @@ export async function readEntry(
 	) {
 		return verdict;
 	}
-	if (!meterable(config.rules, entry.collection, entry.terms, await termTree(config.rules, entry.collection, entry.terms))) {
+	if (!meterable(config.rules, entry.collection, entry.terms, await termTree(config.rules, entry.collection, entry.terms), entryRuleFor(config, entry.collection, entry.ruleId ?? entry.id))) {
 		return verdict;
 	}
 	const period = meter.period ?? "month";
@@ -473,6 +537,8 @@ export async function readEntry(
 			await s.meter.put(key, { ...record, items: used.items });
 			const { emit } = await import("./events.js");
 			const data = { userId: user.id, entry: `${entry.collection}:${entry.id}`, used: used.items.length, limit: meter.limit, period: record.period };
+			const { record: log } = await import("./log.js");
+			await log({ event: used.left === 0 ? "meter.exhausted" : "meter.used", label: entry.collection, status: used.left === 0 ? "used up" : `${used.left} left`, origin: "member" });
 			await emit(config, "meter.used", data);
 			if (used.left === 0) await emit(config, "meter.exhausted", data);
 		}

package/src/admin-api.ts

@@ -12,6 +12,7 @@
 import { env, ENV, shopOrigin, type RedeemIDConfig } from "./config.js";
 import { USER_AGENT } from "./shopify.js";
 import { cleanTags, emptyMember, stampTags, type MemberRecord, type Stores } from "./storage.js";
+import { timed } from "./log.js";
 
 export const ADMIN_API_VERSION = "2026-10";
 
@@ -68,7 +69,13 @@ export async function adminScopes(config: RedeemIDConfig, fetcher: typeof fetch
 	return (await token(config, fetcher)).scope;
 }
 
-export async function admin<T>(config: RedeemIDConfig, query: string, variables: Record<string, unknown> = {}, fetcher: typeof fetch = fetch, retry = true): Promise<T> {
+/** One Admin API call, recorded under App events by its operation name (never its variables or answer). */
+export async function admin<T>(config: RedeemIDConfig, query: string, variables: Record<string, unknown> = {}, fetcher: typeof fetch = fetch): Promise<T> {
+	const op = (/(?:query|mutation)\s+(\w+)/.exec(query)?.[1] ?? "query").replace(/^RedeemID/, "") || "query";
+	return timed("shopify.admin", op, () => call<T>(config, query, variables, fetcher, true));
+}
+
+async function call<T>(config: RedeemIDConfig, query: string, variables: Record<string, unknown>, fetcher: typeof fetch, retry: boolean): Promise<T> {
 	const t = await token(config, fetcher);
 	const res = await fetcher(`${shopOrigin(config)}/admin/api/${ADMIN_API_VERSION}/graphql.json`, {
 		method: "POST",
@@ -77,7 +84,7 @@ export async function admin<T>(config: RedeemIDConfig, query: string, variables:
 	});
 	if (res.status === 401 && retry) {
 		tokens.delete(shopOrigin(config));
-		return admin(config, query, variables, fetcher, false);
+		return call(config, query, variables, fetcher, false);
 	}
 	const body = (await res.json().catch(() => ({}))) as { data?: T; errors?: Array<{ message?: string }> };
 	if (!res.ok || !body.data) throw new AdminError(body.errors?.[0]?.message ?? `Admin API request failed (${res.status}).`);

package/src/agents.ts

@@ -10,7 +10,7 @@
  */
 
 import { adminConfigured } from "./admin-api.js";
-import { describe as describeRequirement, dripDays, levelsFor, membership, passes, requirement, termTree, type Requirement, type Terms } from "./access.js";
+import { applyEntryRule, entryRuleFor, describe as describeRequirement, dripDays, levelsFor, membership, passes, requirement, termTree, type Requirement, type Terms } from "./access.js";
 import { ENV, env, storeDomain, unknownEnvNames, type RedeemIDConfig } from "./config.js";
 import { featuresFor } from "./features.js";
 import { bodyClauses } from "./files.js";
@@ -42,6 +42,7 @@ export async function explainAccess(config: RedeemIDConfig, s: Stores, input: Ex
 	let terms: Terms = input.terms ?? {};
 	let parts: string[][] = [];
 	let entry: { id: string; title: string | null } | null = null;
+	let own: ReturnType<typeof entryRuleFor> = null;
 	let item: SoldItem | null = null;
 	if (input.id) {
 		const { getEmDashEntry } = await import("emdash");
@@ -53,6 +54,7 @@ export async function explainAccess(config: RedeemIDConfig, s: Stores, input: Ex
 		parts = bodyClauses(body);
 		item = soldItem(body);
 		entry = { id: String(result?.entry?.id ?? input.id), title: typeof data.title === "string" ? data.title : null };
+		own = entryRuleFor(config, collection, typeof data.id === "string" ? data.id : null) ?? entryRuleFor(config, collection, input.id);
 	}
 
 	let tags = cleanTags(input.tags ?? []);
@@ -67,7 +69,7 @@ export async function explainAccess(config: RedeemIDConfig, s: Stores, input: Ex
 	const disabled = member?.status === "disabled";
 	const held = disabled ? [] : levelsFor(tags, levels);
 	const tree = await termTree(config.rules, collection, terms);
-	const required: Requirement = requirement(config.rules, collection, terms, { combine: config.combine, tree });
+	const required: Requirement = applyEntryRule(requirement(config.rules, collection, terms, { combine: config.combine, tree }), own);
 	const owned = !disabled && holdsItem(item, tags);
 	const canReadRule = owned || required === null || (signedIn && !disabled && passes(held, required));
 	const name = (slug: string) => levels.find((l) => l.slug === slug)?.name ?? slug;
@@ -90,7 +92,8 @@ export async function explainAccess(config: RedeemIDConfig, s: Stores, input: Ex
 		canRead: canReadRule,
 		reason: canReadRule ? "allowed" : !signedIn ? "sign_in" : disabled ? "disabled" : "upgrade",
 		offered: !canReadRule && missing ? name(missing[0] as string) : null,
-		dripDays: owned ? 0 : dripDays(config.rules, collection, terms, tree),
+		dripDays: owned ? 0 : dripDays(config.rules, collection, terms, tree, own),
+		entryRule: own ? { mode: own.mode, levels: own.levels.map(name), drip: own.drip ?? 0, neverMetered: own.meter === false, lockedUntil: own.lockedUntil ?? null, openUntil: own.openUntil ?? null } : null,
 		soldOnItsOwn: item ? { tag: item.tag, product: item.product, held: owned } : null,
 		parts: partResults,
 		note: "Drip and the meter depend on the member's dates and use, so they can still change what the page shows.",
@@ -109,6 +112,7 @@ export function getRules(config: RedeemIDConfig): Record<string, unknown> {
 		teaser: config.teaser ?? {},
 		features: config.features ?? [],
 		files: config.files ?? [],
+		entries: Object.values(config.entries ?? {}).filter((e, i, all) => all.findIndex((x) => x.entryId === e.entryId) === i),
 	};
 }
 
@@ -178,3 +182,58 @@ export async function levelChanges(config: RedeemIDConfig, s: Stores, input: { s
 	} while (cursor);
 	return out.sort((a, b) => String(a.at).localeCompare(String(b.at)));
 }
+
+// ---------------------------------------------------------------- catalog
+
+/**
+ * Catalog lookups for agents and editors: product and collection handles,
+ * prices and options, read from the Storefront API (public data). Use the
+ * handles in Product, Collection and Plan blocks.
+ */
+export async function findProducts(config: RedeemIDConfig, input: { query: string; first?: number }): Promise<Record<string, unknown>> {
+	const { searchProducts } = await import("./catalog.js");
+	const q = String(input.query ?? "").trim();
+	if (!q) throw new AgentError("query is required");
+	const page = await searchProducts(config, q, { first: Math.max(1, Math.min(25, input.first ?? 10)) });
+	return {
+		total: page.total ?? page.products.length,
+		products: page.products.map((p) => ({ handle: p.handle, title: p.title, availableForSale: p.availableForSale, price: p.price, compareAtPrice: p.compareAtPrice ?? null })),
+	};
+}
+
+export async function getProduct(config: RedeemIDConfig, input: { handle: string }): Promise<Record<string, unknown>> {
+	const { product, realOptions } = await import("./storefront.js");
+	const handle = String(input.handle ?? "").trim();
+	if (!/^[a-z0-9][a-z0-9-]*$/i.test(handle)) throw new AgentError("handle must be a Shopify product handle");
+	const p = await product(config, handle);
+	if (!p) throw new AgentError(`Shopify has no product "${handle}" on this storefront`);
+	return {
+		handle: p.handle,
+		title: p.title,
+		vendor: p.vendor ?? null,
+		productType: p.productType ?? null,
+		description: p.description,
+		availableForSale: p.availableForSale,
+		options: realOptions(p),
+		variants: p.variants.map((v) => ({ id: v.id, title: v.title, availableForSale: v.availableForSale, price: v.price, compareAtPrice: v.compareAtPrice ?? null, sku: v.sku ?? null, options: v.selectedOptions ?? [] })),
+		requiresSellingPlan: Boolean(p.requiresSellingPlan),
+		sellingPlans: p.sellingPlans ?? [],
+		images: (p.images ?? []).length,
+	};
+}
+
+export async function getCollection(config: RedeemIDConfig, input: { handle: string; first?: number }): Promise<Record<string, unknown>> {
+	const { collectionPage } = await import("./catalog.js");
+	const handle = String(input.handle ?? "").trim();
+	if (!/^[a-z0-9][a-z0-9-]*$/i.test(handle)) throw new AgentError("handle must be a Shopify collection handle");
+	const c = await collectionPage(config, handle, { first: Math.max(1, Math.min(50, input.first ?? 25)) });
+	if (!c) throw new AgentError(`Shopify has no collection "${handle}" on this storefront`);
+	return {
+		handle: c.handle,
+		title: c.title,
+		description: c.description,
+		filters: c.filters.map((f) => ({ label: f.label, type: f.type, values: f.values.map((v) => v.label) })),
+		products: c.products.map((p) => ({ handle: p.handle, title: p.title, availableForSale: p.availableForSale, price: p.price })),
+		more: c.pageInfo.hasNextPage,
+	};
+}

package/src/api-version.ts

@@ -0,0 +1,6 @@
+/**
+ * The developer API's version (docs/developer-api.md): the minor part bumps
+ * when something is added, the major part when something stable changes or
+ * goes. Separate from the package version.
+ */
+export const API_VERSION = "1.0.0";

package/src/blocks/CollectionBlock.astro

@@ -3,13 +3,14 @@
 import Collection from "../components/Collection.astro";
 
 interface Props {
-	node: { handle?: string; limit?: string; link?: string };
+	node: { handle?: string; limit?: string; link?: string; extras?: string[] };
 }
 
 const { node } = Astro.props;
 const handle = (node.handle ?? "").trim();
 const limit = Number.parseInt(node.limit ?? "", 10);
 const link = (node.link ?? "").trim();
+const extras = Array.isArray(node.extras) ? node.extras : [];
 ---
 
 {handle && (
@@ -18,5 +19,7 @@ const link = (node.link ?? "").trim();
 		limit={Number.isFinite(limit) ? limit : 12}
 		productHref={link.startsWith("/") && link.includes("{handle}") ? link : undefined}
 		showTitle
+		browse={extras.includes("browse")}
+		quickAdd={extras.includes("quick-add")}
 	/>
 )}

package/src/blocks/SearchBlock.astro

@@ -0,0 +1,14 @@
+---
+/** The "Product search" block: a search box with Shopify's results, filters, sorting and paging. */
+import ProductSearch from "../components/ProductSearch.astro";
+
+interface Props {
+	node: { link?: string; label?: string };
+}
+
+const { node } = Astro.props;
+const link = (node.link ?? "").trim();
+const label = (node.label ?? "").trim();
+---
+
+<ProductSearch productHref={link.startsWith("/") && link.includes("{handle}") ? link : undefined} label={label || undefined} />

package/src/blocks/index.ts

@@ -8,6 +8,7 @@ import ContributionBlock from "./ContributionBlock.astro";
 import PlanBlock from "./PlanBlock.astro";
 import PreferencesBlock from "./PreferencesBlock.astro";
 import ProductBlock from "./ProductBlock.astro";
+import SearchBlock from "./SearchBlock.astro";
 
 export const blockComponents = {
 	"redeemid-paywall": Marker,
@@ -17,6 +18,7 @@ export const blockComponents = {
 	"redeemid-plan": PlanBlock,
 	"redeemid-product": ProductBlock,
 	"redeemid-collection": CollectionBlock,
+	"redeemid-search": SearchBlock,
 	"redeemid-contribution": ContributionBlock,
 	"redeemid-preferences": PreferencesBlock,
 };

package/src/blocks-names.ts

@@ -3,6 +3,7 @@ export const PAYWALL_BLOCK = "redeemid-paywall";
 export const PLAN_BLOCK = "redeemid-plan";
 export const PRODUCT_BLOCK = "redeemid-product";
 export const COLLECTION_BLOCK = "redeemid-collection";
+export const SEARCH_BLOCK = "redeemid-search";
 export const CONTRIBUTION_BLOCK = "redeemid-contribution";
 export const PREFERENCES_BLOCK = "redeemid-preferences";
 /** Starts a members-only part of the body; it runs to the next end block. */

package/src/cart-ops.ts

@@ -0,0 +1,164 @@
+/**
+ * Cart changes, shared by the form route (cart-edit, which redirects back
+ * with a notice) and the JSON route (api/cart, for the browser client and
+ * the cart drawer).
+ *
+ * Prices, discounts and availability come from Shopify; nothing posted is
+ * trusted beyond the ids it names, and each is checked against what Shopify
+ * says the product or cart holds.
+ */
+
+import { readCart, saveCart } from "./cart.js";
+import type { RedeemIDConfig } from "./config.js";
+import { memberForUser, stores } from "./storage.js";
+import { addToCart, cartDetails, product, realOptions, removeLines, setDiscountCodes, storeContext, updateLines, variantFor, type Cart, type CartDetails, type Product, type Variant } from "./storefront.js";
+
+export const MAX_QUANTITY = 1000;
+
+export type CartNotice =
+	| "cart_added"
+	| "cart_updated"
+	| "discount_applied"
+	| "discount_not_applicable"
+	| "plan_unavailable"
+	| "cart_empty"
+	| "checkout_failed";
+
+export interface CartInput {
+	action: string;
+	/** add: product handle. */
+	product?: string;
+	/** add: a variant id of that product. */
+	variant?: string;
+	/** add: chosen option values by option name, when no variant is given. */
+	options?: Record<string, string>;
+	/** add: a selling plan id of that product, or "" for one-time. */
+	sellingPlan?: string | null;
+	quantity?: number | string;
+	/** update / remove: the cart line id. */
+	line?: string;
+	/** discount: the code ("" clears). */
+	code?: string;
+	/** add: the page the buyer was on, kept as a hidden cart attribute. */
+	page?: string;
+}
+
+export interface CartContext {
+	config: RedeemIDConfig;
+	session: { get(key: string): unknown; set(key: string, value: unknown): void; delete?(key: string): void } | undefined;
+	request: Request;
+	db?: unknown;
+}
+
+export interface CartOutcome {
+	notice: CartNotice;
+	/** The cart after the change, when it could be read. */
+	cart: CartDetails | null;
+	/** The cart's id, checkout URL and count after an add (lines aren't read back). */
+	base?: Cart;
+	/** add: the line's variant, for analytics. */
+	added?: { product: string; variant: string; quantity: number; sellingPlan: boolean };
+}
+
+const HANDLE = /^[a-z0-9][a-z0-9-]*$/i;
+
+/** Pick the variant an add names: by id, by option values, or the first one for sale. */
+export function pickVariant(p: Product, input: Pick<CartInput, "variant" | "options">): Variant | undefined {
+	if (input.variant) return p.variants.find((v) => v.id === input.variant);
+	const opts = realOptions(p);
+	if (opts.length && input.options && Object.keys(input.options).length) {
+		const chosen: Record<string, string> = {};
+		for (const o of opts) {
+			const v = input.options[o.name];
+			if (typeof v === "string" && o.values.includes(v)) chosen[o.name] = v;
+		}
+		if (Object.keys(chosen).length !== opts.length) return undefined;
+		return variantFor(p, chosen);
+	}
+	return p.variants.find((v) => v.availableForSale);
+}
+
+/** The selling plan an add uses: one the product offers, the first one when it can only be bought on a plan, or none. */
+export function pickSellingPlan(p: Product, wanted: string | null | undefined): string | null | undefined {
+	const plans = p.sellingPlans ?? [];
+	if (wanted) return plans.some((sp) => sp.id === wanted) ? wanted : undefined;
+	if (p.requiresSellingPlan) return plans[0]?.id ?? p.sellingPlanId ?? undefined;
+	return null;
+}
+
+export async function editCart(input: CartInput, ctx: CartContext): Promise<CartOutcome> {
+	const { config, session, request } = ctx;
+	const buyerIp = request.headers.get("cf-connecting-ip");
+	const context = storeContext(config, request);
+	const save = (c: { id: string; totalQuantity: number }) => saveCart(session, { id: c.id, count: c.totalQuantity });
+
+	if (input.action === "add") {
+		const handle = String(input.product ?? "").trim();
+		const quantity = Number.parseInt(String(input.quantity ?? "1"), 10);
+		if (!HANDLE.test(handle) || !Number.isFinite(quantity) || quantity < 1 || quantity > MAX_QUANTITY) return { notice: "plan_unavailable", cart: null };
+		const p = await product(config, handle, undefined, context);
+		const variant = p ? pickVariant(p, input) : undefined;
+		const plan = p ? pickSellingPlan(p, input.sellingPlan) : undefined;
+		if (!p || !variant?.availableForSale || plan === undefined) return { notice: "plan_unavailable", cart: null };
+		const user = (await session?.get("user")) as { id?: string } | undefined;
+		const member = user?.id && ctx.db ? await memberForUser(stores(ctx.db), user.id) : null;
+		const current = await readCart(session);
+		const cart = await addToCart(
+			config,
+			current?.id ?? null,
+			{ variantId: variant.id, sellingPlanId: plan, quantity },
+			{ email: member?.email ?? null, attributes: input.page ? { _redeemid_page: input.page } : {}, buyerIp, context },
+		);
+		save(cart);
+		return { notice: "cart_added", cart: null, base: cart, added: { product: p.handle, variant: variant.id, quantity, sellingPlan: Boolean(plan) } };
+	}
+
+	const ref = await readCart(session);
+	if (!ref) return { notice: "cart_empty", cart: null };
+	const cart = await cartDetails(config, ref.id, { buyerIp });
+	if (!cart) {
+		saveCart(session, null);
+		return { notice: "cart_empty", cart: null };
+	}
+	const line = String(input.line ?? "");
+	const owns = cart.lines.some((l) => l.id === line);
+
+	if (input.action === "update" || input.action === "remove") {
+		if (!owns) return { notice: "cart_updated", cart };
+		const quantity = input.action === "remove" ? 0 : Number.parseInt(String(input.quantity ?? ""), 10);
+		if (!Number.isFinite(quantity) || quantity < 0 || quantity > MAX_QUANTITY) return { notice: "cart_updated", cart };
+		const next = quantity === 0 ? await removeLines(config, cart.id, [line], { buyerIp }) : await updateLines(config, cart.id, [{ id: line, quantity }], { buyerIp });
+		save(next);
+		return { notice: "cart_updated", cart: next };
+	}
+
+	if (input.action === "discount") {
+		const code = String(input.code ?? "").trim().slice(0, 100);
+		const next = await setDiscountCodes(config, cart.id, code ? [code] : [], { buyerIp });
+		save(next);
+		if (!code) return { notice: "cart_updated", cart: next };
+		const applied = next.discountCodes.find((d) => d.code.toLowerCase() === code.toLowerCase());
+		return { notice: applied?.applicable ? "discount_applied" : "discount_not_applicable", cart: next };
+	}
+
+	return { notice: "cart_updated", cart };
+}
+
+/** Read the add fields from a posted form: option.<Name> fields become `options`. */
+export function cartInputFromForm(form: FormData | null): CartInput {
+	const field = (k: string) => String(form?.get(k) ?? "").trim();
+	const options: Record<string, string> = {};
+	form?.forEach((value, key) => {
+		if (key.startsWith("option.") && typeof value === "string") options[key.slice(7)] = value;
+	});
+	return {
+		action: field("action"),
+		product: field("product"),
+		variant: field("variant"),
+		options,
+		sellingPlan: form?.has("selling_plan") ? field("selling_plan") : null,
+		quantity: field("quantity") || "1",
+		line: field("line"),
+		code: field("code"),
+	};
+}