@redeemid/emdash 0.0.9 → 0.0.11

package/README.md

@@ -2,7 +2,7 @@
 
 Shopify customer accounts, member levels and paywalls for [EmDash](https://github.com/emdash-cms/emdash) sites. Shopify runs the store and the customer account; EmDash runs the content.
 
-**Status: 0.0.9, early.** Runs on Node and Cloudflare Workers. Sign-in, the member mirror, webhooks, levels, rules, the meter and drip, teasers, badges, the page gate, the Shopify cart and checkout, the staff tools and outbound events are covered by an end-to-end test against a fake store.
+**Status: 0.0.11, early.** Runs on Node and Cloudflare Workers. Sign-in, the member mirror, webhooks, levels, rules, the meter and drip, teasers, badges, the page gate, the Shopify cart and checkout, the staff tools, preferences, protected files, privacy requests, AI agent tools, the command line, replacement text and outbound events are covered by an end-to-end test against a fake store.
 
 ## What it does
 
@@ -17,11 +17,17 @@ Shopify customer accounts, member levels and paywalls for [EmDash](https://githu
 - **Account.** Members get an Account link to their Shopify customer account (orders, profile, addresses) and Sign out, which also ends the Shopify session.
 - **Paywall break block.** Editors write one body and drop a "Paywall break" block where members-only content starts, picking which levels may read on, or leaving it to the entry's rule. `<Content>` renders the body and leaves the rest off the page for everyone else.
 - **Members only block.** For a members part in the middle of a body: "Members only" (pick the levels) and "Members only: end". Everyone else sees the wall in its place and reads on after it.
+- **Sold on its own block.** Sell one entry by itself: buyers get a Shopify tag that opens the whole entry whatever its levels say, and locked readers see "Buy just this" with the price.
 - **The wall.** Readers kept out see why and what to do next: sign in, or join, with each level's own wall text. `<Notices>` shows the messages sign-in, Buy, Cart and Account send readers back with.
 - **Plan block.** Editors add a Shopify product to any page with the "Plan" block: title, price and a buy button.
 - **Shop.** `<Product>`, `<Collection>` and `<CartView>` (with the Product and Collection blocks) give the site product pages, collection grids and a cart page with quantities and discount codes. `<Contribution>` (and its block) takes pay-what-you-want amounts. Carts note the page each sale started on.
 - **Features.** Name perks members hold through levels or tags (ad-free, a supporter thank-you) and show them with `<Feature>` or `hasFeature()`.
 - **In the admin.** RedeemID shows under Plugins with a Members page (Shopify customers, tags, levels; open a member to resync them or add and remove tags, which are written to Shopify), a bulk resync you start yourself, a Status page (secrets, store discovery, webhook subscriptions with a Register button, recent deliveries, levels and rules), an Access test and a dashboard widget.
+- **Member preferences.** Members see and change customer fields you define in Shopify, such as topics or a newsletter choice, with `<Preferences>` or its block. Answers are saved on the Shopify customer, ready for Flow, segments and email; the site keeps no copy.
+- **Protected files.** Put uploads in a media folder named in `files`, and every download checks the reader's levels, features or the entries that use the file. Copied links are no use to anyone else.
+- **Privacy requests.** Members download or delete what the site keeps about them with `<YourData>`. Staff export or erase any member, and can ask Shopify to erase the customer too. Shopify's compliance webhooks are handled and logged on a Privacy page.
+- **AI agents and a command line.** Staff questions (can this reader read this entry, who is this member, what changed) as MCP tools for EmDash's MCP server, and as the `redeemid-emdash` command.
+- **Replacement text.** Put any string members and visitors see in your own words, one string at a time, with `text`.
 - **Outbound events.** Signed JSON POSTs to a URL of yours when a member signs in, their levels change, or they use the meter, for a CRM, an email tool or your own code.
 - **Keeps members out of EmDash's own APIs**, so the gate is the only way to read locked content.
 
@@ -109,6 +115,16 @@ Each rule names a collection and the levels, any of which may read. An empty `le
 
 Term rules beat the collection's rule, which beats the site default. When several term rules cover one entry (a story in Investigations, Gold, and Culture, Silver), readers must pass every one of them, so only Gold + Silver members read it. Set `combine: "any"` to let one of them be enough.
 
+### Selling one entry on its own
+
+Add the **Sold on its own** block anywhere in an entry's body. Give it the Shopify customer tag buyers get, such as `item-big-story`, and the Shopify product that sells it (its handle, or a link to it). Then:
+
+- A reader whose customer holds that tag reads the whole entry: its rule, Paywall break, Members only parts and drip don't apply, and the meter isn't used.
+- Locked readers see **Buy just this** on the wall, with the product's price from Shopify, beside the level's offer. It starts checkout for that product.
+- `<AccessBadge>` drops the lock for buyers, and protected files in an `entries: true` folder that the entry uses reach them too.
+
+Shopify adds the tag when the order is paid, usually with a Flow workflow (Order paid → the line item is that product → add the customer tag). The site never grants it, so a refund workflow that removes the tag takes the entry away again. A tag on an entry that's open to everyone changes nothing.
+
 ### Meter and drip
 
 The meter lets a signed-in reader who can't read an entry open it anyway, `limit` entries per `period` (`"month"`, the default, or `"week"`, in UTC). Each entry counts once per period, when its own page renders through `<Content>` with an `id`; lists, feeds, search and the content API never count. Visitors get the wall and a nudge to sign in. While it runs, `<Content>` says how many free reads are left; when it runs out, the wall says so. Rules with `meter: false` are never metered, and the meter never opens an entry a member is waiting on by drip.
@@ -135,6 +151,124 @@ import { hasFeature } from "@redeemid/emdash/features";
 {!(await hasFeature(Astro, "ad-free")) && <aside class="ad">…</aside>}
 ```
 
+### Preferences
+
+```ts
+preferences: [
+	{ key: "preferences.topics" },                  // members can change it
+	{ key: "preferences.level", access: "view" },   // members only see it
+],
+```
+
+Define each field in Shopify (**Settings → Custom data → Customers**). The definition sets its name, type and limits, such as allowed choices or a minimum and maximum. List the ones members get in `preferences`, in the order to show them. Reading and saving use the Admin API app (`REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID`, with `read_customers` and `write_customers`), always on the signed-in member's own customer. Fields in the `membership` namespace are never offered. Preferences never open content.
+
+`<Preferences>` (or the Preferences block) is a form with a control for each field. It works without JavaScript and comes back with the `preferences_saved`, `preferences_refused` or `preferences_unavailable` notice. Visitors see its `signed-out` slot.
+
+| Shopify type | Value |
+| --- | --- |
+| Single line text | A string; with choices, one of them |
+| Multi-line text | A string |
+| List of single line text | A list of strings; with choices, each one of them |
+| True or false | `true` or `false` |
+| Integer | A whole number |
+| Decimal | A number, as a string |
+| Date | `YYYY-MM-DD` |
+
+Every value is checked against the definition before it goes to Shopify; one refusal saves nothing, and an empty value clears the field. Scripts can use `/_emdash/api/auth/redeemid/preferences` too: `GET` returns `{ fields }` with values, `POST` with JSON `{ values: { "namespace.key": value } }` saves. A refused save answers `400` with `fields` mapping each key to `unknown_field`, `read_only`, `invalid_type`, `invalid_choice`, `invalid_length` or `invalid_range`. Saves are limited to 10 a minute per member (`429`). From your own code, `readPreferences()` and `savePreferences()` in `@redeemid/emdash/preferences` do the same.
+
+A save sends the `preferences.saved` event with the field names changed, never the answers.
+
+### Protected files
+
+```ts
+files: [
+	{ folder: "Gold downloads", levels: ["gold"] },
+	{ folder: "Member downloads", levels: [] },             // any signed-in member
+	{ folder: "Supporter extras", features: ["supporter"] },
+	{ folder: "Story files", entries: true },               // whoever can read an entry that uses it
+],
+```
+
+Upload files into a folder in the EmDash media library. Folder names match without regard to case. Every request for a file in a protected folder at `/_emdash/api/media/file/…` is checked before EmDash serves it:
+
+- **Allowed:** the file, sent with `Cache-Control: private, no-store`.
+- **Signed out:** a 401 page with a sign-in link that comes back to the file.
+- **Signed in without access:** a 403 page.
+
+A rule lets in members who hold any of its `levels` (an empty list means any signed-in member) or `features`. With `entries: true`, it also lets in whoever can read a published entry that uses the file: its rule, its drip, and the levels picked on its Paywall break or Members only parts. Staff can always download. Disabled members can't. If a file can't be checked, it isn't served.
+
+Limits:
+
+- Only EmDash's file route is checked. Don't give the storage bucket a public URL of its own.
+- Image services that fetch the file without the reader's cookies, such as a CDN image resizer, get refused, so keep protected images out of resized `<Image>` output.
+- Moving a file out of the folder makes it public again.
+
+### Privacy requests
+
+What RedeemID keeps about a member: the synced record (Shopify customer ID, email, name, tags and when each started, account status, when they first signed in and were last synced) and their meter. Preference answers stay on the Shopify customer. Webhook deliveries keep only a topic and a time. Shopify stays the record of the customer, so erasing on the site never erases Shopify data. It can only ask Shopify to.
+
+| Started | What happens |
+| --- | --- |
+| A member, with `<YourData>` on an account page | **Download my data** returns their record and meter as JSON. **Delete my data** needs a ticked box, erases both, and signs them out. |
+| Staff, on a member's page in the admin | **Export data** shows the same JSON. **Erase site data** erases it. **Also request erasure in Shopify** asks Shopify to erase the customer across the store, orders included. Shopify waits before it does, and **Cancel the Shopify erasure** withdraws it. That needs the `write_customer_data_erasure` scope on the Admin API app. |
+| Shopify `customers/data_request` | An open request on the **Privacy** page. Press **Export and mark done**, then send the export to the store owner. |
+| Shopify `customers/redact` | The member's record and meter are erased. |
+| Shopify `shop/redact` | Every member record and meter is erased. |
+
+The Privacy page lists every request with where it came from and the Shopify customer ID. It never shows an email or a name. An erase sends the `member.erased` event with `customerId` and `source`, so a CRM that took earlier events can delete its copy too.
+
+Erasing leaves the site's own user account (EmDash's users table) in place; delete it in the admin's Users if the person asks. If they sign in again, they're linked again and get back whatever Shopify still grants.
+
+The JSON route is `/_emdash/api/auth/redeemid/privacy`: `GET` downloads, and `POST` with `confirm=yes` erases. It only acts for the signed-in member and refuses a POST from another origin.
+
+### AI agents and the command line
+
+RedeemID answers the questions staff ask in the admin as data, for AI agents and for scripts. All of them need an administrator. They read what the site has synced. None of them grants access, edits a level or a rule, or returns a secret.
+
+| MCP tool | Command | What it answers |
+| --- | --- | --- |
+| `explain_access` | `access <collection>` | Can this reader read this entry, and why. Give the entry by `id` (its terms and body are read from the site) or by `terms`. Give the reader by Shopify `tags`, a member's `customerId`, or `signedIn: false`. The answer covers what the entry needs, the reader's levels, the result and reason, the level a locked reader is offered, drip days, and each members-only part. |
+| `list_levels` | `levels` | Every level, the tags that grant it, its wall text and join link. |
+| `get_rules` | `rules` | How rules combine, every rule, the meter, teasers, features and protected-file rules. |
+| `get_member` | `member <id or email>` | One synced member: status, tags, levels with start dates, past levels, features, last sync. |
+| `site_health` | `health` | Whether each setting is in place (yes or no, never a value), the last webhook, open privacy requests and ignored text replacements. |
+| `level_changes` | `changes --since <date>` | Who joined or left a level since a date. |
+
+With `agents: { actions: true }` in the config, three actions are offered too:
+
+| MCP tool | Command | What it does |
+| --- | --- | --- |
+| `resync_member` | `resync <customer id>` | Reads one member from Shopify and updates the site. Changes nothing in Shopify. |
+| `resync_batch` | `resync-batch` | Reads the 50 members synced longest ago. |
+| `edit_member_tags` | `tags <customer id> --add a,b --remove c` | Adds or removes tags on the Shopify customer, then reads back what Shopify holds. It's marked destructive for agents. |
+
+**Agents.** EmDash's MCP server is at `/_emdash/api/mcp`, on EmDash versions with plugin MCP tools. RedeemID's tools stay off until an administrator turns them on for RedeemID under **Plugins**. Turning them on approves the list as it stands, and a release that changes the list needs approving again. The agent uses an EmDash API token with the `mcp:tools` or `mcp:tools:redeemid` scope, made by an administrator. Tool names carry the plugin's prefix, for example `redeemid__explain_access`.
+
+**Command line.**
+
+```sh
+npx -p @redeemid/emdash redeemid-emdash access posts --id my-story --tags gold-member --url https://example.com
+npx -p @redeemid/emdash redeemid-emdash member jane@example.com
+```
+
+It signs in the way EmDash's own CLI does: `--token`, or `EMDASH_TOKEN`, or the token `emdash login` saved for the site. The site comes from `--url` or `EMDASH_URL`. Output is JSON. Each command calls a staff-only route at `/_emdash/api/plugins/redeemid/<name>`, so scripts can call the same routes directly with a POST and a JSON body.
+
+### Replacement text
+
+```ts
+text: {
+	"Sign in": "Log in",
+	"This is for members. {signIn} to read on.": "Members only. {signIn} to keep reading.",
+	"This is for {level} members.": "{level} members only.",
+},
+```
+
+Each key is a string's original English; its value is the new text. Only the strings you name change. There is no find-and-replace across strings, so replacing "Sign in" leaves "Sign in to download this file." alone: to change a word everywhere, replace each string that uses it. `STRINGS` in `@redeemid/emdash/text` lists every string, grouped by where it shows (account, badge, cart, wall, meter, member card, notices, plan, preferences, product, files).
+
+Some strings have placeholders such as `{level}` or `{signIn}` (a link), filled in when the text shows. A replacement may use its original's placeholders, in any order or not at all, but no others. Text is plain: HTML in a replacement shows as typed. A replacement that uses another placeholder, or names a string RedeemID doesn't show, is ignored, so the original shows, and the Status page lists it with the reason.
+
+Props win over `text`: a `label` or `title` you pass, or Notices `messages`, is used as given. Staff screens in the admin aren't covered.
+
 ### Events
 
 ```ts
@@ -149,12 +283,14 @@ With `REDEEMID_EVENTS_SECRET` set, RedeemID POSTs `{ id, event, at, data }` to t
 | `member.levels_changed` | `customerId`, `levels`, `added`, `removed`, `source` (`sign-in`, the webhook topic, or a staff resync or tag edit) |
 | `meter.used` | `userId` (EmDash), `entry` (`collection:id`), `used`, `limit`, `period` (`2026-11`, or `2026-W45` by week) |
 | `meter.exhausted` | the same, sent with the last free read |
+| `preferences.saved` | `customerId`, `fields` (the `namespace.key` names changed) |
+| `member.erased` | `customerId`, `source` (`member`, `staff` or `shopify`) |
 
 No event carries an email address or a name: match people by the Shopify `customerId`. `only` limits which events are sent; leave it out for all of them.
 
 ### Staff tools
 
-With `REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID` set, RedeemID gets an Admin API token for the webhook app with the client credentials grant (the app must belong to the same Shopify organization as the store, as Dev Dashboard apps do) and needs the `read_customers` and `write_customers` scopes. Then, in the admin:
+With `REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID` set (it also runs member preferences), RedeemID gets an Admin API token for the webhook app with the client credentials grant (the app must belong to the same Shopify organization as the store, as Dev Dashboard apps do) and needs the `read_customers` and `write_customers` scopes. Then, in the admin:
 
 - **Member detail.** Open a member from the Members page to see their levels, tags and features, resync them from Shopify, or add and remove tags. Tag edits are made in Shopify, then read back; nothing is granted on the EmDash side.
 - **Bulk resync.** Reads the 50 members synced longest ago from Shopify in one request. Run it again for the next 50. It never runs on its own.

package/bin/redeemid-emdash.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * redeemid-emdash: ask a RedeemID site the questions staff ask in the admin.
+ *
+ *   npx redeemid-emdash access posts --id my-story --tags gold-member
+ *   npx redeemid-emdash member jane@example.com
+ *
+ * Signs in like EmDash's own CLI: --token or EMDASH_TOKEN, else the token
+ * `emdash login` saved for the site. The site comes from --url or EMDASH_URL.
+ * The token's user must be an administrator.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+
+const HELP = `Usage: redeemid-emdash <command> [options]
+
+Commands:
+  access <collection>     Can a reader read an entry, and why
+      --id <id or slug>   the entry (or --terms taxonomy:slug,…)
+      --tags a,b          the reader's Shopify tags (or --customer <id>)
+      --signed-out        a signed-out visitor
+  levels                  Every level and the tags that grant it
+  rules                   The paywall rules, meter, features and file rules
+  member <id or email>    One synced member
+  health                  What's set up (never the values)
+  changes --since <date>  Who joined or left a level [--level <slug>]
+  resync <customer id>    Read one member from Shopify again *
+  resync-batch            Read the 50 members synced longest ago *
+  tags <customer id>      Edit tags in Shopify: --add a,b --remove c *
+
+  * only when the site sets agents: { actions: true }
+
+Options:
+  --url <site>      the site (or EMDASH_URL)
+  --token <token>   an EmDash API token (or EMDASH_TOKEN, or emdash login)
+  -h, --help`;
+
+const { values: o, positionals } = parseArgs({
+	allowPositionals: true,
+	options: {
+		url: { type: "string" },
+		token: { type: "string" },
+		id: { type: "string" },
+		terms: { type: "string" },
+		tags: { type: "string" },
+		customer: { type: "string" },
+		"signed-out": { type: "boolean" },
+		since: { type: "string" },
+		level: { type: "string" },
+		add: { type: "string" },
+		remove: { type: "string" },
+		help: { type: "boolean", short: "h" },
+	},
+});
+
+const list = (s) => (s ? s.split(",").map((x) => x.trim()).filter(Boolean) : undefined);
+const [command, arg] = positionals;
+
+function request() {
+	switch (command) {
+		case "access": {
+			if (!arg) throw new Error("access needs a collection");
+			const terms = {};
+			for (const pair of list(o.terms) ?? []) {
+				const [tax, slug] = pair.split(":");
+				if (tax && slug) (terms[tax] ??= []).push(slug);
+			}
+			return ["explain-access", { collection: arg, id: o.id, terms: o.terms ? terms : undefined, tags: list(o.tags), customerId: o.customer, signedIn: o["signed-out"] ? false : undefined }];
+		}
+		case "levels":
+			return ["list-levels", {}];
+		case "rules":
+			return ["get-rules", {}];
+		case "member":
+			if (!arg) throw new Error("member needs a customer id or an email");
+			return ["get-member", arg.includes("@") ? { email: arg } : { customerId: arg }];
+		case "health":
+			return ["site-health", {}];
+		case "changes":
+			if (!o.since) throw new Error("changes needs --since <date>");
+			return ["level-changes", { since: o.since, level: o.level }];
+		case "resync":
+			if (!arg) throw new Error("resync needs a customer id");
+			return ["resync-member", { customerId: arg }];
+		case "resync-batch":
+			return ["resync-batch", {}];
+		case "tags":
+			if (!arg || (!o.add && !o.remove)) throw new Error("tags needs a customer id and --add or --remove");
+			return ["edit-member-tags", { customerId: arg, add: list(o.add), remove: list(o.remove) }];
+		default:
+			return null;
+	}
+}
+
+/** The token: --token, EMDASH_TOKEN, or what `emdash login` saved for this site. */
+function token(site) {
+	if (o.token) return o.token;
+	if (process.env.EMDASH_TOKEN) return process.env.EMDASH_TOKEN;
+	try {
+		const dir = process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, "emdash") : join(homedir(), ".config", "emdash");
+		const saved = JSON.parse(readFileSync(join(dir, "auth.json"), "utf8"))[new URL(site).origin];
+		if (saved?.accessToken && new Date(saved.expiresAt) > new Date()) return saved.accessToken;
+		if (saved?.accessToken) throw new Error("The saved sign-in has expired. Run `npx emdash whoami` (or `emdash login`) for this site, then try again.");
+	} catch (e) {
+		if (e instanceof Error && e.message.startsWith("The saved")) throw e;
+	}
+	throw new Error("No token. Pass --token, set EMDASH_TOKEN, or run `npx emdash login --url <site>`.");
+}
+
+async function main() {
+	const req = o.help || !command ? null : request();
+	if (!req) {
+		console.log(HELP);
+		process.exit(command && !o.help ? 2 : 0);
+	}
+	const site = (o.url ?? process.env.EMDASH_URL ?? "").replace(/\/+$/, "");
+	if (!site) throw new Error("No site. Pass --url or set EMDASH_URL.");
+	const [route, body] = req;
+	const res = await fetch(`${site}/_emdash/api/plugins/redeemid/${route}`, {
+		method: "POST",
+		headers: { authorization: `Bearer ${token(site)}`, "content-type": "application/json", "x-emdash-request": "1" },
+		body: JSON.stringify(body),
+	});
+	const text = await res.text();
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch {
+		throw new Error(`${res.status} from the site: ${text.slice(0, 200)}`);
+	}
+	if (res.status === 404) throw new Error(`The site has no "${route}" route. Actions need agents: { actions: true }, and every command needs @redeemid/emdash 0.0.11 or later.`);
+	if (!res.ok) throw new Error(json?.error?.message ?? `${res.status} from the site`);
+	const out = json?.data ?? json;
+	if (out && out.ok === false) throw new Error(out.error);
+	console.log(JSON.stringify(out?.result ?? out, null, 2));
+}
+
+main().catch((e) => {
+	console.error(`redeemid-emdash: ${e.message}`);
+	process.exit(1);
+});

package/docs/shopify-setup.md

@@ -29,7 +29,9 @@ RedeemID keeps tags and status current from webhooks. Point these topics at `htt
 
 Subscribe them from a Shopify app on the store (for example a Dev Dashboard app). If the app already sends webhooks to another site, add this URL as extra subscriptions. `customers/merge` needs the `read_customer_merge` scope. Shopify signs every webhook with that app's **client secret**, which is the site's webhook secret.
 
-For the staff tools (member resync, tag edits written to Shopify, the Register webhooks button), give the same app the `read_customers` and `write_customers` Admin API scopes and set its **client ID** as well. RedeemID uses the client credentials grant, which works when the app and the store are in the same Shopify organization.
+For the staff tools (member resync, tag edits written to Shopify, the Register webhooks button) and member preferences, give the same app the `read_customers` and `write_customers` Admin API scopes and set its **client ID** as well. RedeemID uses the client credentials grant, which works when the app and the store are in the same Shopify organization. For the **Also request erasure in Shopify** button on a member's page, add the optional `write_customer_data_erasure` scope.
+
+Shopify's compliance topics (`customers/data_request`, `customers/redact`, `shop/redact`) reach only apps that declare them in the app's configuration, under `[webhooks.privacy_compliance]`. Point all three at the same webhook URL. RedeemID logs each one on the Privacy page.
 
 ## 3. The site
 
@@ -57,4 +59,4 @@ The Workers free plan is enough: RedeemID is a native plugin and doesn't need sa
 3. Click **Sign in**, sign in with that customer's email, and you come back to the post, unlocked.
 4. Add or remove the tag in Shopify; the post opens or locks again once the webhook arrives.
 
-If sign-in sends you back with `?redeemid_notice=…`, the code says why: `not_configured` (secrets or `shop` missing), `sign_in_unavailable` (store discovery failed), `sign_in_expired`, `staff_account`, `site_not_ready`, `email_required`, `token_failed`, `bad_id_token`, `identity_failed`. A Buy button can return `plan_unavailable` (no such product, or sold out) or `checkout_failed`. The Cart link returns `cart_empty` when there's nothing in the cart, and Account returns `account_unavailable` when store discovery fails. Cart changes return `cart_added`, `cart_updated`, `discount_applied` or `discount_not_applicable`. Refresh membership returns `refreshed` once it has read the member's tags again.
+If sign-in sends you back with `?redeemid_notice=…`, the code says why: `not_configured` (secrets or `shop` missing), `sign_in_unavailable` (store discovery failed), `sign_in_expired`, `staff_account`, `site_not_ready`, `email_required`, `token_failed`, `bad_id_token`, `identity_failed`. A Buy button can return `plan_unavailable` (no such product, or sold out) or `checkout_failed`. The Cart link returns `cart_empty` when there's nothing in the cart, and Account returns `account_unavailable` when store discovery fails. Cart changes return `cart_added`, `cart_updated`, `discount_applied` or `discount_not_applicable`. Refresh membership returns `refreshed` once it has read the member's tags again. Preferences return `preferences_saved`, `preferences_refused` or `preferences_unavailable`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@redeemid/emdash",
-	"version": "0.0.9",
+	"version": "0.0.11",
 	"description": "Shopify customer accounts, member levels and paywalls for EmDash sites. Shopify runs commerce; EmDash runs content.",
 	"type": "module",
 	"license": "MIT",
@@ -17,6 +17,8 @@
 		"./storefront": "./src/storefront.ts",
 		"./features": "./src/features.ts",
 		"./events": "./src/events.ts",
+		"./preferences": "./src/preferences.ts",
+		"./text": "./src/text.ts",
 		"./plugin": "./src/plugin.ts",
 		"./blocks": "./src/blocks/index.ts",
 		"./components/*": "./src/components/*",
@@ -26,7 +28,8 @@
 		"src",
 		"README.md",
 		"LICENSE",
-		"docs"
+		"docs",
+		"bin"
 	],
 	"keywords": [
 		"emdash",
@@ -62,5 +65,8 @@
 	},
 	"bugs": {
 		"url": "https://github.com/webmultipliers/redeemid-emdash/issues"
+	},
+	"bin": {
+		"redeemid-emdash": "./bin/redeemid-emdash.mjs"
 	}
 }

package/src/access.ts

@@ -277,11 +277,11 @@ export function passes(held: string[], required: string[][]): boolean {
  * The requirement in words, for badges and admin pages: "Gold + Silver",
  * "Silver or Gold", "Signed in". `null` gives `open`.
  */
-export function describe(required: Requirement, levels: LevelConfig[] = [], open = "Free"): string {
+export function describe(required: Requirement, levels: LevelConfig[] = [], open = "Free", signedIn = "Signed in"): string {
 	if (required === null) return open;
 	const name = (slug: string) => levels.find((l) => l.slug === slug)?.name ?? slug;
 	const parts = reduce(required).filter((c) => c.length > 0).map((c) => c.map(name).join(" or "));
-	return parts.length ? parts.join(" + ") : "Signed in";
+	return parts.length ? parts.join(" + ") : signedIn;
 }
 
 /**

package/src/agents.ts

@@ -0,0 +1,179 @@
+/**
+ * Answers for AI agents (EmDash's MCP server) and the command line: the same
+ * questions the admin answers, as plain data. Staff only. Read-only by
+ * default; the three actions (resync one member, resync a batch, edit a
+ * member's tags in Shopify) are offered only with config `agents.actions`.
+ *
+ * Nothing here grants access on the site, edits a level or rule, or returns a
+ * secret: Shopify still decides who is entitled, and settings show only
+ * whether each value is set.
+ */
+
+import { adminConfigured } from "./admin-api.js";
+import { describe as describeRequirement, dripDays, levelsFor, membership, passes, requirement, termTree, type Requirement, type Terms } from "./access.js";
+import { ENV, env, storeDomain, type RedeemIDConfig } from "./config.js";
+import { featuresFor } from "./features.js";
+import { bodyClauses } from "./files.js";
+import { holdsItem, soldItem, type SoldItem } from "./blocks-names.js";
+import { cleanTags, numericId, type MemberRecord, type Stores } from "./storage.js";
+import { textProblems } from "./text.js";
+
+export class AgentError extends Error {}
+
+export interface ExplainInput {
+	collection: string;
+	/** An entry's id or slug: its terms and body are read from the site. */
+	id?: string;
+	/** Terms by taxonomy, when no `id` is given: { category: ["investigations"] }. */
+	terms?: Record<string, string[]>;
+	/** A reader by their Shopify tags… */
+	tags?: string[];
+	/** …or a real member, by Shopify customer id. */
+	customerId?: string;
+	/** A signed-out visitor when false. Defaults to true. */
+	signedIn?: boolean;
+}
+
+/** Can this reader read this entry, and why. */
+export async function explainAccess(config: RedeemIDConfig, s: Stores, input: ExplainInput): Promise<Record<string, unknown>> {
+	const levels = config.levels ?? [];
+	const collection = input.collection.trim();
+	if (!collection) throw new AgentError("collection is required");
+	let terms: Terms = input.terms ?? {};
+	let parts: string[][] = [];
+	let entry: { id: string; title: string | null } | null = null;
+	let item: SoldItem | null = null;
+	if (input.id) {
+		const { getEmDashEntry } = await import("emdash");
+		const result = (await getEmDashEntry(collection, input.id)) as { entry?: { id?: string; data?: Record<string, unknown> } | null } | null;
+		const data = result?.entry?.data;
+		if (!data) throw new AgentError(`No published ${collection} entry "${input.id}"`);
+		terms = (data.terms as Terms | undefined) ?? {};
+		const body = Object.values(data).find((v) => Array.isArray(v) && v.some((b) => typeof (b as { _type?: unknown })?._type === "string" && String((b as { _type: string })._type).startsWith("redeemid-")));
+		parts = bodyClauses(body);
+		item = soldItem(body);
+		entry = { id: String(result?.entry?.id ?? input.id), title: typeof data.title === "string" ? data.title : null };
+	}
+
+	let tags = cleanTags(input.tags ?? []);
+	let member: MemberRecord | null = null;
+	if (input.customerId) {
+		const id = numericId(input.customerId);
+		member = id ? await s.members.get(id) : null;
+		if (!member) throw new AgentError(`No synced member with customer id ${input.customerId}`);
+		tags = member.tags;
+	}
+	const signedIn = input.signedIn !== false || Boolean(member);
+	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 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;
+	const partResults = parts.map((clause) => ({
+		needs: clause.map(name),
+		canRead: owned || (signedIn && !disabled && (clause.includes("signed-in") || clause.some((l) => held.includes(l)))),
+	}));
+	const missing = required?.find((clause) => clause.length > 0 && !passes(held, [clause]));
+	return {
+		entry,
+		collection,
+		terms,
+		reader: {
+			signedIn,
+			...(member ? { customerId: member.customerId, status: member.status } : {}),
+			tags,
+			levels: held.map(name),
+		},
+		needs: describeRequirement(required, levels),
+		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),
+		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.",
+	};
+}
+
+export function listLevels(config: RedeemIDConfig): Array<Record<string, unknown>> {
+	return (config.levels ?? []).map((l) => ({ slug: l.slug, name: l.name, tags: l.tags, match: l.match ?? "any", wall: l.wall ?? null, joinUrl: l.joinUrl ?? null }));
+}
+
+export function getRules(config: RedeemIDConfig): Record<string, unknown> {
+	return {
+		combine: config.combine ?? "all",
+		rules: config.rules ?? [],
+		meter: config.meter ?? null,
+		teaser: config.teaser ?? {},
+		features: config.features ?? [],
+		files: config.files ?? [],
+	};
+}
+
+/** One synced member, by customer id or email. */
+export async function getMember(config: RedeemIDConfig, s: Stores, input: { customerId?: string; email?: string }): Promise<Record<string, unknown>> {
+	let m: MemberRecord | null = null;
+	const id = input.customerId ? numericId(input.customerId) : null;
+	if (id) m = await s.members.get(id);
+	else if (input.email) {
+		const { items } = await s.members.query({ where: { email: input.email.trim().toLowerCase() }, limit: 1 });
+		m = items[0]?.data ?? null;
+	} else throw new AgentError("Give customerId or email");
+	if (!m) throw new AgentError("No synced member matches");
+	const levels = config.levels ?? [];
+	const { current, past } = membership(m, levels);
+	const held = featuresFor(m, config.features, levels);
+	return {
+		customerId: m.customerId,
+		email: m.email,
+		name: [m.firstName, m.lastName].filter(Boolean).join(" ") || null,
+		status: m.status,
+		signedInHere: Boolean(m.userId),
+		linkedAt: m.linkedAt ?? null,
+		tags: m.tags,
+		levels: current.map((l) => ({ slug: l.slug, name: l.name, since: l.since })),
+		pastLevels: past.map((l) => ({ slug: l.slug, name: l.name, from: l.from, to: l.to })),
+		features: (config.features ?? []).filter((f) => held.includes(f.slug)).map((f) => f.slug),
+		syncedAt: m.syncedAt,
+		source: m.source,
+	};
+}
+
+/** What's set up, as yes or no: never a value. */
+export async function siteHealth(config: RedeemIDConfig, s: Stores): Promise<Record<string, unknown>> {
+	const { items } = await s.deliveries.query({ orderBy: { receivedAt: "desc" }, limit: 1 });
+	const open = await s.requests.query({ where: { status: "open" }, limit: 50 });
+	return {
+		storeDomain: Boolean(storeDomain(config)),
+		customerAccountClientId: Boolean(env(ENV.clientId)),
+		webhookSecret: Boolean(env(ENV.webhookSecret)),
+		adminApi: adminConfigured(),
+		events: Boolean(config.events?.url) && Boolean(env(ENV.eventsSecret)),
+		storefront: env(ENV.storefrontPrivateToken) ? "private token" : env(ENV.storefrontPublicToken) ? "public token" : "tokenless",
+		lastWebhook: items[0]?.data ?? null,
+		openPrivacyRequests: open.items.length,
+		ignoredTextReplacements: textProblems(config).length,
+	};
+}
+
+/** Who started or ended a level since a date, from each member's tag dates. */
+export async function levelChanges(config: RedeemIDConfig, s: Stores, input: { since: string; level?: string }): Promise<Array<Record<string, unknown>>> {
+	const since = Date.parse(input.since);
+	if (Number.isNaN(since)) throw new AgentError("since must be a date, e.g. 2026-11-01");
+	const levels = (config.levels ?? []).filter((l) => !input.level || l.slug === input.level);
+	if (input.level && levels.length === 0) throw new AgentError(`No level "${input.level}"`);
+	const out: Array<Record<string, unknown>> = [];
+	let cursor: string | undefined;
+	do {
+		const page = await s.members.query({ limit: 100, cursor });
+		for (const { data: m } of page.items) {
+			const { current, past } = membership(m, config.levels ?? []);
+			for (const l of current) if (levels.some((x) => x.slug === l.slug) && l.since && Date.parse(l.since) >= since) out.push({ customerId: m.customerId, email: m.email, level: l.slug, change: "joined", at: l.since });
+			for (const l of past) if (levels.some((x) => x.slug === l.slug) && Date.parse(l.to) >= since) out.push({ customerId: m.customerId, email: m.email, level: l.slug, change: "left", at: l.to });
+		}
+		cursor = page.cursor;
+	} while (cursor);
+	return out.sort((a, b) => String(a.at).localeCompare(String(b.at)));
+}

package/src/blocks/ContributionBlock.astro

@@ -18,7 +18,7 @@ const amounts = (node.amounts ?? "")
 	<Contribution
 		handle={handle}
 		title={node.title?.trim() || undefined}
-		label={node.label?.trim() || "Give"}
+		label={node.label?.trim() || undefined}
 		amounts={amounts.length ? amounts : undefined}
 	/>
 )}

package/src/blocks/PlanBlock.astro

@@ -10,4 +10,4 @@ const { node } = Astro.props;
 const handle = (node.handle ?? "").trim();
 ---
 
-{handle && <Plan handle={handle} title={node.title?.trim() || undefined} label={node.label?.trim() || "Join"} levels={Array.isArray(node.levels) ? node.levels : []} />}
+{handle && <Plan handle={handle} title={node.title?.trim() || undefined} label={node.label?.trim() || undefined} levels={Array.isArray(node.levels) ? node.levels : []} />}

package/src/blocks/PreferencesBlock.astro

@@ -0,0 +1,12 @@
+---
+/** The "Preferences" block: the signed-in member's preferences form. */
+import Preferences from "../components/Preferences.astro";
+
+interface Props {
+	node: { title?: string; label?: string };
+}
+
+const { node } = Astro.props;
+---
+
+<Preferences title={node.title?.trim() || undefined} label={node.label?.trim() || undefined} />

package/src/blocks/index.ts

@@ -6,14 +6,17 @@ import Marker from "./PaywallBreak.astro";
 import CollectionBlock from "./CollectionBlock.astro";
 import ContributionBlock from "./ContributionBlock.astro";
 import PlanBlock from "./PlanBlock.astro";
+import PreferencesBlock from "./PreferencesBlock.astro";
 import ProductBlock from "./ProductBlock.astro";
 
 export const blockComponents = {
 	"redeemid-paywall": Marker,
 	"redeemid-members": Marker,
 	"redeemid-members-end": Marker,
+	"redeemid-item": Marker,
 	"redeemid-plan": PlanBlock,
 	"redeemid-product": ProductBlock,
 	"redeemid-collection": CollectionBlock,
 	"redeemid-contribution": ContributionBlock,
+	"redeemid-preferences": PreferencesBlock,
 };