@redeemid/emdash 0.0.9 → 0.0.11

package/src/plugin.ts

@@ -30,23 +30,29 @@ import { definePlugin } from "emdash";
 import { describe, levelsFor, SIGNED_IN } from "./access.js";
 import { env, ENV, storeDomain, type RedeemIDConfig } from "./config.js";
 import { discover } from "./shopify.js";
-import { stores, type MemberRecord } from "./storage.js";
+import { stores, type MemberRecord, type Stores } from "./storage.js";
 import { PAGES, WIDGETS } from "./descriptor.js";
 import { VERSION } from "./version.js";
-import { adminConfigured } from "./admin-api.js";
-import { accessTest, bulkResync, BULK_BATCH, deliveriesSection, memberDetail, registerWebhooks, resyncOne, tagEdit, webhooksSection } from "./staff.js";
+import { AdminError, adminConfigured } from "./admin-api.js";
+import { cancelShopifyErasure, closeRequest, eraseMember, exportMember, exportRequest, requestShopifyErasure } from "./privacy.js";
+import { accessTest, bulkResync, BULK_BATCH, deliveriesSection, exportBlocks, memberDetail, privacyPage, registerWebhooks, resyncOne, tagEdit, webhooksSection } from "./staff.js";
+import { textProblems } from "./text.js";
+import { z } from "astro/zod";
+import { AgentError, explainAccess, getMember, getRules, levelChanges, listLevels, siteHealth, type ExplainInput } from "./agents.js";
 
 import {
 	COLLECTION_BLOCK,
 	CONTRIBUTION_BLOCK,
+	ITEM_BLOCK,
 	MEMBERS_BLOCK,
 	MEMBERS_END_BLOCK,
 	PAYWALL_BLOCK,
 	PLAN_BLOCK,
+	PREFERENCES_BLOCK,
 	PRODUCT_BLOCK,
 } from "./blocks-names.js";
 
-export { COLLECTION_BLOCK, CONTRIBUTION_BLOCK, MEMBERS_BLOCK, MEMBERS_END_BLOCK, PAYWALL_BLOCK, PLAN_BLOCK, PRODUCT_BLOCK };
+export { COLLECTION_BLOCK, CONTRIBUTION_BLOCK, ITEM_BLOCK, MEMBERS_BLOCK, MEMBERS_END_BLOCK, PAYWALL_BLOCK, PLAN_BLOCK, PREFERENCES_BLOCK, PRODUCT_BLOCK };
 
 function blocks(config: RedeemIDConfig) {
 	const levelOptions = [
@@ -89,6 +95,16 @@ function blocks(config: RedeemIDConfig) {
 			description: "Ends the members-only part; everyone reads on from here",
 			fields: [],
 		},
+		{
+			type: ITEM_BLOCK,
+			label: "Sold on its own",
+			icon: "tag",
+			description: "Buyers of this entry read all of it, whatever its levels say",
+			fields: [
+				{ type: "text_input" as const, action_id: "tag", label: "Shopify customer tag buyers get", placeholder: "item-big-story" },
+				{ type: "text_input" as const, action_id: "product", label: "Shopify product that sells it (handle or link)", placeholder: "the-big-story" },
+			],
+		},
 		{
 			type: PLAN_BLOCK,
 			label: "Plan",
@@ -140,6 +156,17 @@ function blocks(config: RedeemIDConfig) {
 				{ type: "text_input" as const, action_id: "label", label: "Button label", placeholder: "Give" },
 			],
 		},
+		{
+			type: PREFERENCES_BLOCK,
+			label: "Preferences",
+			icon: "users",
+			description: "The signed-in member's preferences, saved on their Shopify customer",
+			placeholder: "Member preferences",
+			fields: [
+				{ type: "text_input" as const, action_id: "title", label: "Title", placeholder: "Your preferences" },
+				{ type: "text_input" as const, action_id: "label", label: "Button label", placeholder: "Save preferences" },
+			],
+		},
 	];
 }
 
@@ -153,7 +180,9 @@ export function createPlugin(config: RedeemIDConfig = {}): ResolvedPlugin {
 			widgets: WIDGETS,
 			portableTextBlocks: blocks(config),
 		},
+		mcp: agentTools(config),
 		routes: {
+			...agentRoutes(config),
 			admin: {
 				handler: async (ctx: RouteContext) => {
 					const i = (ctx.input ?? {}) as { type?: string; page?: string; action_id?: string; value?: unknown; values?: Record<string, unknown>; block_id?: string };
@@ -163,6 +192,7 @@ export function createPlugin(config: RedeemIDConfig = {}): ResolvedPlugin {
 						if (i.page === "/") return await membersPage(config);
 						if (i.page === "/status") return await statusPage(config, ctx.request);
 						if (i.page === "/test") return await accessTest(config);
+						if (i.page === "/privacy") return await privacyPage(await memberStores());
 						if (i.page === "widget:status") return await statusWidget(config);
 					} catch (e) {
 						return { blocks: [{ type: "banner", variant: "error", title: "RedeemID couldn't load this page", description: (e as Error).message }] };
@@ -176,6 +206,85 @@ export function createPlugin(config: RedeemIDConfig = {}): ResolvedPlugin {
 
 export default createPlugin;
 
+// ---------------------------------------------------------------- agents and CLI
+
+const STAFF = "users:read" as const;
+
+/** Staff-only JSON routes, also offered as MCP tools. */
+function agentRoutes(config: RedeemIDConfig) {
+	const run = (fn: (s: Stores, input: Record<string, unknown>) => Promise<unknown> | unknown) => async (ctx: RouteContext) => {
+		try {
+			return { ok: true, result: await fn(await memberStores(), (ctx.input ?? {}) as Record<string, unknown>) };
+		} catch (e) {
+			if (e instanceof AgentError || e instanceof AdminError) return { ok: false, error: e.message };
+			throw e;
+		}
+	};
+	const route = (input: z.ZodType, fn: Parameters<typeof run>[0]) => ({ permission: STAFF, input, request: { body: "json" as const }, handler: run(fn) });
+	const read = {
+		"explain-access": route(EXPLAIN, (s, i) => explainAccess(config, s, i as unknown as ExplainInput)),
+		"list-levels": route(EMPTY, () => listLevels(config)),
+		"get-rules": route(EMPTY, () => getRules(config)),
+		"get-member": route(MEMBER, (s, i) => getMember(config, s, i as { customerId?: string; email?: string })),
+		"site-health": route(EMPTY, (s) => siteHealth(config, s)),
+		"level-changes": route(CHANGES, (s, i) => levelChanges(config, s, i as { since: string; level?: string })),
+	};
+	if (!config.agents?.actions) return read;
+	return {
+		...read,
+		"resync-member": route(CUSTOMER, async (s, i) => {
+			const m = await resyncOne(config, s, String(i.customerId), "agent resync");
+			if (!m) throw new AgentError("Shopify no longer has this customer");
+			return getMember(config, s, { customerId: m.customerId });
+		}),
+		"resync-batch": route(EMPTY, (s) => bulkResync(config, s)),
+		"edit-member-tags": route(TAGS, async (s, i) => {
+			const id = String(i.customerId);
+			const add = (i.add as string[] | undefined) ?? [];
+			const remove = (i.remove as string[] | undefined) ?? [];
+			if (add.length) await tagEdit(config, s, id, "add", add);
+			if (remove.length) await tagEdit(config, s, id, "remove", remove);
+			return getMember(config, s, { customerId: id });
+		}),
+	};
+}
+
+const EMPTY = z.object({});
+const EXPLAIN = z.object({
+	collection: z.string().min(1).describe("Collection slug, e.g. posts"),
+	id: z.string().optional().describe("An entry's id or slug; its terms and body are read from the site"),
+	terms: z.record(z.string(), z.array(z.string())).optional().describe('Terms by taxonomy when no id is given, e.g. {"category":["investigations"]}'),
+	tags: z.array(z.string()).optional().describe("The reader's Shopify customer tags"),
+	customerId: z.string().optional().describe("A real member's Shopify customer id, in place of tags"),
+	signedIn: z.boolean().optional().describe("false for a signed-out visitor (default true)"),
+});
+const MEMBER = z.object({ customerId: z.string().optional(), email: z.string().optional() });
+const CUSTOMER = z.object({ customerId: z.string().min(1).describe("Shopify customer id") });
+const CHANGES = z.object({ since: z.string().describe("A date, e.g. 2026-11-01"), level: z.string().optional().describe("Only this level slug") });
+const TAGS = z.object({
+	customerId: z.string().min(1).describe("Shopify customer id"),
+	add: z.array(z.string()).optional().describe("Tags to add in Shopify"),
+	remove: z.array(z.string()).optional().describe("Tags to remove in Shopify"),
+});
+
+/** MCP tools for the routes above. Staff turn them on for RedeemID under Plugins. */
+function agentTools(config: RedeemIDConfig) {
+	const tools: Record<string, { description: string; route: string; input: z.ZodType; destructive?: boolean }> = {
+		explain_access: { route: "explain-access", input: EXPLAIN, description: "Can this reader read this entry, and why? Give the entry by collection and id (or terms), and the reader by Shopify tags, a member's customer id, or signedIn:false. Answers what the entry needs, the reader's levels, the result, the level a locked reader is offered, and each members-only part." },
+		list_levels: { route: "list-levels", input: EMPTY, description: "Every membership level: slug, name, the Shopify tags that grant it (any or all), wall text and join link." },
+		get_rules: { route: "get-rules", input: EMPTY, description: "The paywall rules: how they combine, each rule (collection, term, levels, drip, open), the meter, teasers, features and protected-file rules." },
+		get_member: { route: "get-member", input: MEMBER, description: "One synced member by Shopify customer id or email: status, tags, current levels with start dates, past levels, features and last sync." },
+		site_health: { route: "site-health", input: EMPTY, description: "Whether each setting is in place (never the values), the last webhook, open privacy requests and ignored text replacements." },
+		level_changes: { route: "level-changes", input: CHANGES, description: "Who joined or left a level since a date, from each member's tag dates." },
+	};
+	if (config.agents?.actions) {
+		tools.resync_member = { route: "resync-member", input: CUSTOMER, description: "Read one member from Shopify now and update the site. Changes nothing in Shopify." };
+		tools.resync_batch = { route: "resync-batch", input: EMPTY, description: "Read the 50 members synced longest ago from Shopify. Run again for the next 50." };
+		tools.edit_member_tags = { route: "edit-member-tags", input: TAGS, destructive: true, description: "Add or remove tags on a member's Shopify customer, then read back what Shopify holds. Access follows from Shopify." };
+	}
+	return { tools };
+}
+
 // ---------------------------------------------------------------- actions
 
 const webhookUri = (request: Request) => `${new URL(request.url).origin}/_emdash/api/auth/redeemid/webhook`;
@@ -241,6 +350,41 @@ async function action(
 		}
 		case "access_test":
 			return accessTest(config, i.values);
+		case "member_export": {
+			const id = String(i.value ?? "");
+			const m = await s.members.get(id);
+			if (!m) return membersPage(config);
+			return exportBlocks(memberDetail(config, m, { type: "success", message: "Export below." }), await exportRequest(s, id, "staff"));
+		}
+		case "member_erase": {
+			const id = String(i.value ?? "");
+			await eraseMember(config, s, id, "staff");
+			return { ...(await membersPage(config)), toast: { type: "success", message: "Erased from the site." } };
+		}
+		case "member_shopify_erase":
+		case "member_shopify_cancel": {
+			const id = String(i.value ?? "");
+			const m = await s.members.get(id);
+			try {
+				if (i.action_id === "member_shopify_erase") await requestShopifyErasure(config, s, id);
+				else await cancelShopifyErasure(config, s, id);
+				const message = i.action_id === "member_shopify_erase" ? "Shopify will erase the customer after its waiting period." : "The Shopify erasure is cancelled.";
+				return m ? memberDetail(config, m, { type: "success", message }) : privacyPage(s, { type: "success", message });
+			} catch (e) {
+				return m ? memberDetail(config, m, fail(e)) : privacyPage(s, fail(e));
+			}
+		}
+		case "privacy_done": {
+			const r = await closeRequest(s, String(i.value ?? ""));
+			if (r?.kind === "export" && r.customerId) {
+				const data = await exportMember(s, r.customerId);
+				return privacyPage(s, { type: "success", message: "Marked done. Send the export below to the store owner." }, [
+					{ type: "header", text: `Export for customer ${r.customerId}` },
+					{ type: "code", language: "jsonc", code: JSON.stringify(data, null, 2) },
+				]);
+			}
+			return privacyPage(s, { type: "success", message: "Marked done." });
+		}
 	}
 	return { blocks: [] };
 }
@@ -364,6 +508,13 @@ async function lastDelivery(): Promise<string | null> {
 	return d ? `${d.topic} at ${d.receivedAt}` : null;
 }
 
+function textSummary(config: RedeemIDConfig): string {
+	const all = Object.keys(config.text ?? {}).length;
+	const ignored = textProblems(config).length;
+	if (!all) return "None";
+	return ignored ? `${all - ignored} in use, ${ignored} ignored` : `${all} in use`;
+}
+
 async function statusPage(config: RedeemIDConfig, request: Request) {
 	const c = await checks(config);
 	const origin = new URL(request.url).origin;
@@ -392,8 +543,22 @@ async function statusPage(config: RedeemIDConfig, request: Request) {
 					{ label: "Events", value: config.events?.url ? `${config.events.url}${env(ENV.eventsSecret) ? "" : " (REDEEMID_EVENTS_SECRET missing)"}` : "Off" },
 					{ label: "Storefront API access", value: c.storefront },
 					{ label: "Last webhook", value: delivery ?? "None received yet" },
+					{ label: "Replacement text", value: textSummary(config) },
 				],
 			},
+			...(textProblems(config).length
+				? [
+						{
+							type: "table",
+							page_action_id: "text_problems",
+							columns: [
+								{ key: "original", label: "Ignored replacement for" },
+								{ key: "problem", label: "Why" },
+							],
+							rows: textProblems(config),
+						},
+					]
+				: []),
 			{ type: "divider" },
 			{ type: "header", text: "Webhooks" },
 			...webhooks,

package/src/preferences.ts

@@ -0,0 +1,298 @@
+/**
+ * Member preferences: customer metafields members may see or change, such as
+ * the topics they follow. Shopify defines each field (Settings → Custom data
+ * → Customers); `preferences` in the config picks which ones members get, and
+ * whether they may change them. Answers live on the Shopify customer, where
+ * Flow, segments and email can use them. The site keeps no copy.
+ *
+ * Reading and saving use the Admin API app (the staff tools' client ID), and
+ * always on the signed-in member's own customer. Preferences never open
+ * content: access still comes only from tags.
+ */
+
+import { admin, adminConfigured, AdminError } from "./admin-api.js";
+import type { PreferenceConfig, RedeemIDConfig } from "./config.js";
+import type { MemberRecord } from "./storage.js";
+
+/** Metafield types members can use, and the value each takes. */
+export const PREFERENCE_TYPES = [
+	"single_line_text_field",
+	"multi_line_text_field",
+	"list.single_line_text_field",
+	"boolean",
+	"number_integer",
+	"number_decimal",
+	"date",
+] as const;
+export type PreferenceType = (typeof PREFERENCE_TYPES)[number];
+export type PreferenceValue = string | string[] | boolean | number | null;
+
+export interface PreferenceField {
+	/** "namespace.key" */
+	key: string;
+	name: string;
+	description: string | null;
+	type: PreferenceType;
+	choices: string[] | null;
+	/** Length for text, value for numbers and dates. */
+	min: string | null;
+	max: string | null;
+	editable: boolean;
+	value: PreferenceValue;
+}
+
+export type Refusal = "unknown_field" | "read_only" | "invalid_type" | "invalid_choice" | "invalid_length" | "invalid_range";
+
+export class PreferenceError extends Error {
+	constructor(
+		message: string,
+		readonly fields: Record<string, Refusal> = {},
+	) {
+		super(message);
+	}
+}
+
+/** Saves allowed per member per minute. */
+export const SAVES_PER_MINUTE = 10;
+const DEFINITIONS_TTL_MS = 5 * 60 * 1000;
+/** RedeemID reads membership dates from this namespace, so members never get it. */
+const RESERVED_NAMESPACE = "membership";
+
+type Definition = Omit<PreferenceField, "editable" | "value">;
+let cache: { at: number; shop: string; defs: Definition[] } | null = null;
+
+export function resetPreferenceCache(): void {
+	cache = null;
+}
+
+/** Can preferences run at all? */
+export function preferencesConfigured(config: RedeemIDConfig | null): boolean {
+	return Boolean(config?.preferences?.length && adminConfigured());
+}
+
+function wanted(config: RedeemIDConfig): PreferenceConfig[] {
+	return (config.preferences ?? []).filter((p) => /^[\w-]+\.[\w-]+$/.test(p.key) && !p.key.startsWith(`${RESERVED_NAMESPACE}.`));
+}
+
+/** The customer metafield definitions Shopify has for the configured keys, cached for five minutes. */
+export async function definitions(config: RedeemIDConfig, fetcher: typeof fetch = fetch): Promise<Definition[]> {
+	const shop = config.shop ?? "";
+	if (cache && cache.shop === shop && Date.now() - cache.at < DEFINITIONS_TTL_MS) return cache.defs;
+	type Node = { namespace: string; key: string; name: string; description: string | null; type: { name: string }; validations: Array<{ name: string; value: string | null }> };
+	const data = await admin<{ metafieldDefinitions: { nodes: Node[] } }>(
+		config,
+		`query RedeemIDPreferenceDefinitions { metafieldDefinitions(ownerType: CUSTOMER, first: 250) { nodes { namespace key name description type { name } validations { name value } } } }`,
+		{},
+		fetcher,
+	);
+	const defs = data.metafieldDefinitions.nodes
+		.filter((n) => (PREFERENCE_TYPES as readonly string[]).includes(n.type.name))
+		.map((n) => {
+			const v = (name: string) => n.validations.find((x) => x.name === name)?.value ?? null;
+			let choices: string[] | null = null;
+			try {
+				const raw = v("choices");
+				const parsed = raw ? (JSON.parse(raw) as unknown) : null;
+				if (Array.isArray(parsed)) choices = parsed.map(String);
+			} catch {
+				choices = null;
+			}
+			return {
+				key: `${n.namespace}.${n.key}`,
+				name: n.name,
+				description: n.description || null,
+				type: n.type.name as PreferenceType,
+				choices,
+				// Length for text types, value for numbers and dates.
+				min: v("min") || null,
+				max: v("max") || null,
+			};
+		});
+	cache = { at: Date.now(), shop, defs };
+	return defs;
+}
+
+/** Turn a stored metafield value into what members see. */
+export function decode(type: PreferenceType, raw: string | null | undefined): PreferenceValue {
+	if (raw == null || raw === "") return type.startsWith("list.") ? [] : null;
+	switch (type) {
+		case "list.single_line_text_field":
+			try {
+				const v = JSON.parse(raw) as unknown;
+				return Array.isArray(v) ? v.map(String) : [];
+			} catch {
+				return [];
+			}
+		case "boolean":
+			return raw === "true";
+		case "number_integer":
+			return Number.parseInt(raw, 10);
+		default:
+			return raw;
+	}
+}
+
+const isEmpty = (v: unknown) => v === null || v === undefined || v === "" || (Array.isArray(v) && v.length === 0);
+
+/**
+ * Check one value against its definition. Returns the metafield value to
+ * save, null to clear the field, or a refusal.
+ */
+export function encode(def: Definition, input: unknown): { value: string | null } | { refused: Refusal } {
+	if (isEmpty(input)) return { value: null };
+	const len = (s: string) => {
+		if (def.min !== null && s.length < Number(def.min)) return false;
+		if (def.max !== null && s.length > Number(def.max)) return false;
+		return true;
+	};
+	const choice = (s: string) => !def.choices || def.choices.includes(s);
+	switch (def.type) {
+		case "single_line_text_field":
+		case "multi_line_text_field": {
+			if (typeof input !== "string") return { refused: "invalid_type" };
+			const s = def.type === "single_line_text_field" ? input.trim() : input;
+			if (def.type === "single_line_text_field" && /[\r\n]/.test(s)) return { refused: "invalid_type" };
+			if (!choice(s)) return { refused: "invalid_choice" };
+			if (!len(s)) return { refused: "invalid_length" };
+			return { value: s };
+		}
+		case "list.single_line_text_field": {
+			const list = typeof input === "string" ? [input] : input;
+			if (!Array.isArray(list) || list.some((x) => typeof x !== "string")) return { refused: "invalid_type" };
+			const items = [...new Set((list as string[]).map((x) => x.trim()).filter(Boolean))];
+			if (items.some((x) => /[\r\n]/.test(x))) return { refused: "invalid_type" };
+			if (!items.every(choice)) return { refused: "invalid_choice" };
+			if (!items.every(len)) return { refused: "invalid_length" };
+			return { value: items.length ? JSON.stringify(items) : null };
+		}
+		case "boolean": {
+			const b = input === true || input === "true" || input === "on" ? true : input === false || input === "false" ? false : null;
+			if (b === null) return { refused: "invalid_type" };
+			return { value: String(b) };
+		}
+		case "number_integer":
+		case "number_decimal": {
+			const s = typeof input === "number" ? String(input) : typeof input === "string" ? input.trim() : "";
+			const ok = def.type === "number_integer" ? /^-?\d+$/.test(s) : /^-?\d+(\.\d+)?$/.test(s);
+			if (!ok) return { refused: "invalid_type" };
+			const n = Number(s);
+			if ((def.min !== null && n < Number(def.min)) || (def.max !== null && n > Number(def.max))) return { refused: "invalid_range" };
+			return { value: s };
+		}
+		case "date": {
+			const s = typeof input === "string" ? input.trim() : "";
+			if (!/^\d{4}-\d{2}-\d{2}$/.test(s) || Number.isNaN(Date.parse(`${s}T00:00:00Z`))) return { refused: "invalid_type" };
+			if ((def.min !== null && s < def.min.slice(0, 10)) || (def.max !== null && s > def.max.slice(0, 10))) return { refused: "invalid_range" };
+			return { value: s };
+		}
+	}
+}
+
+/** The fields members can use, in config order, with their access. Without values. */
+export async function preferenceFields(config: RedeemIDConfig, fetcher: typeof fetch = fetch): Promise<Array<Omit<PreferenceField, "value">>> {
+	const defs = await definitions(config, fetcher);
+	return wanted(config).flatMap((p) => {
+		const def = defs.find((d) => d.key === p.key);
+		return def ? [{ ...def, editable: p.access !== "view" }] : [];
+	});
+}
+
+const gid = (id: string) => `gid://shopify/Customer/${id}`;
+
+/** The member's fields with their current values, read from Shopify. */
+export async function readPreferences(config: RedeemIDConfig, customerId: string, fetcher: typeof fetch = fetch): Promise<PreferenceField[]> {
+	const fields = await preferenceFields(config, fetcher);
+	if (fields.length === 0) return [];
+	type Node = { namespace: string; key: string; value: string };
+	const data = await admin<{ customer: { metafields: { nodes: Node[] } } | null }>(
+		config,
+		`query RedeemIDPreferences($id: ID!, $keys: [String!]) { customer(id: $id) { metafields(first: 100, keys: $keys) { nodes { namespace key value } } } }`,
+		{ id: gid(customerId), keys: fields.map((f) => f.key) },
+		fetcher,
+	);
+	if (!data.customer) throw new AdminError("Shopify has no such customer.");
+	const values = new Map(data.customer.metafields.nodes.map((n) => [`${n.namespace}.${n.key}`, n.value]));
+	return fields.map((f) => ({ ...f, value: decode(f.type, values.get(f.key)) }));
+}
+
+/** Room for one more save this minute? Records it when there is. */
+export function allowSave(member: Pick<MemberRecord, "prefSaves">, now = Date.now()): number[] | null {
+	const recent = (member.prefSaves ?? []).filter((t) => now - t < 60_000);
+	if (recent.length >= SAVES_PER_MINUTE) return null;
+	return [...recent, now];
+}
+
+/**
+ * Save some of the member's fields to their Shopify customer, then read them
+ * back. Every value is checked first; one refusal saves nothing. Keys left
+ * out are left alone; an empty value clears the field.
+ */
+export async function savePreferences(
+	config: RedeemIDConfig,
+	customerId: string,
+	values: Record<string, unknown>,
+	fetcher: typeof fetch = fetch,
+): Promise<{ fields: PreferenceField[]; changed: string[] }> {
+	const fields = await preferenceFields(config, fetcher);
+	const refused: Record<string, Refusal> = {};
+	const set: Array<{ namespace: string; key: string; type: string; value: string }> = [];
+	const clear: Array<{ namespace: string; key: string }> = [];
+	for (const [key, input] of Object.entries(values)) {
+		const f = fields.find((x) => x.key === key);
+		if (!f) {
+			refused[key] = "unknown_field";
+			continue;
+		}
+		if (!f.editable) {
+			refused[key] = "read_only";
+			continue;
+		}
+		const out = encode(f, input);
+		if ("refused" in out) {
+			refused[key] = out.refused;
+			continue;
+		}
+		const [namespace = "", k = ""] = key.split(".");
+		if (out.value === null) clear.push({ namespace, key: k });
+		else set.push({ namespace, key: k, type: f.type, value: out.value });
+	}
+	if (Object.keys(refused).length) throw new PreferenceError("Some answers weren't saved.", refused);
+
+	const ownerId = gid(customerId);
+	if (set.length) {
+		const data = await admin<{ metafieldsSet: { userErrors: Array<{ field?: string[] | null; message: string }> } }>(
+			config,
+			`mutation RedeemIDSavePreferences($metafields: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $metafields) { userErrors { field message } } }`,
+			{ metafields: set.map((m) => ({ ownerId, ...m })) },
+			fetcher,
+		);
+		const err = data.metafieldsSet.userErrors[0];
+		if (err) throw new AdminError(err.message);
+	}
+	if (clear.length) {
+		const data = await admin<{ metafieldsDelete: { userErrors: Array<{ message: string }> } }>(
+			config,
+			`mutation RedeemIDClearPreferences($metafields: [MetafieldIdentifierInput!]!) { metafieldsDelete(metafields: $metafields) { userErrors { field message } } }`,
+			{ metafields: clear.map((m) => ({ ownerId, ...m })) },
+			fetcher,
+		);
+		const err = data.metafieldsDelete.userErrors[0];
+		if (err) throw new AdminError(err.message);
+	}
+	const changed = [...set, ...clear].map((m) => `${m.namespace}.${m.key}`);
+	return { fields: await readPreferences(config, customerId, fetcher), changed };
+}
+
+/** Read a posted form into values: `pref:<key>` fields, with `present:<key>` marking checkboxes and lists that may be empty. */
+export function formValues(form: FormData, fields: Array<Pick<PreferenceField, "key" | "type" | "editable">>): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const f of fields) {
+		if (!f.editable || !form.has(`present:${f.key}`)) continue;
+		const all = form.getAll(`pref:${f.key}`).map(String);
+		// A list without choices comes from a textarea: one answer per line.
+		if (f.type === "list.single_line_text_field") out[f.key] = all.flatMap((v) => v.split(/\r?\n/));
+		else if (f.type === "boolean") out[f.key] = all.includes("true");
+		else out[f.key] = all[0] ?? "";
+	}
+	return out;
+}