@redeemid/emdash 0.0.24 → 0.0.26

package/docs/access.md

@@ -0,0 +1,131 @@
+# Access: levels, rules and the meter
+
+Who reads what. Shopify decides who holds which tags; everything here only says what each tag opens.
+
+## Rules
+
+Each rule names a collection and the levels, any of which may read. An empty `levels` list, or the built-in `signed-in` level, means any signed-in member.
+
+| Rule | Covers |
+| --- | --- |
+| `{ collection: "reports", levels: ["gold"] }` | Every entry in the collection |
+| `{ collection: "posts", taxonomy: "category", term: "investigations", levels: ["gold"] }` | Entries with that term, or a child of it in a hierarchical taxonomy. A child's own rule wins over its parent's. |
+| `{ collection: "posts", taxonomy: "tag", term: "free-to-read", levels: [], open: true }` | Opens entries with that term to everyone, whatever else covers them |
+| `{ collection: "pages", levels: [], open: true }` | Opens a whole collection to everyone, unless a term rule locks an entry |
+| `{ collection: "*", taxonomy: "category", term: "members", levels: ["member"] }` | That term in every collection, new ones included. A rule for the same term and a named collection wins there. |
+| `{ collection: "*", levels: [] }` | The site default, for collections with no rule of their own |
+| `{ collection: "posts", taxonomy: "category", term: "archive", levels: ["member"], drip: 30 }` | Drip: members read these entries 30 days after their level started |
+| `{ collection: "posts", taxonomy: "category", term: "exclusive", levels: ["pro"], meter: false }` | The meter never opens these entries |
+
+Term rules beat the collection's rule, which beats the site default. When several term rules cover one entry (a story in Investigations, which needs Gold, and Culture, which needs Silver), readers must pass every one of them, so only members with both read it. Set `combine: "any"` to let one be enough.
+
+## Levels
+
+A level is a name for customers who hold some Shopify tags. `tags` is one group: any one of them grants the level, or every one with `match: "all"`. `groups` adds more groups, and any one group is enough:
+
+```js
+levels: [
+	{ slug: "silver", name: "Silver", tags: ["silver"] },
+	// "gold", or "silver" with "annual".
+	{ slug: "gold", name: "Gold", tags: ["gold"], groups: [{ tags: ["silver", "annual"], match: "all" }], includes: ["silver"] },
+],
+```
+
+`includes` lists levels this one also opens: Gold members read everything for Silver, and inclusion carries on (Gold includes Silver includes Members). So a rule names only the lowest level that may read, and an entry that needs Silver and Gold needs Gold once. Members hold the levels their tags grant and every level those include; the account box and member card show only the top one ("Gold", not "Gold, Silver"), and `member.levels_changed` lists them all.
+
+The rest of a level is how it looks and where it leads:
+
+| Key | What it does |
+| --- | --- |
+| `wall` | What the wall says to readers this level would let in |
+| `joinUrl` | Where the wall's join link goes for this level (else `join.href`) |
+| `products` | Handles of the Shopify products whose purchase leads to the level. Display only: plan cards use it (see [`<Plan>`](content.md)). It grants nothing. |
+| `home` | Members' home: the same-site path a member lands on after signing in from the home page or a plain sign-in link (their top level's, in level order). Signing in from an entry returns them to it. |
+| `badge` | A hex colour, set as `--redeemid-level-color` on badges, the account box and the member card. Badges always show the name too. |
+
+## Access settings in the admin
+
+Everything about who reads what can be set in the EmDash admin, so a new content type, taxonomy or level never needs a code change. Under **Plugins → RedeemID → Access**:
+
+- **Levels.** Add, rename and remove levels and the Shopify tags that grant them: one group per line, commas between tags, and `all:` before a line that needs every tag on it. Tick the levels each one includes, and set its plan products, members' home and badge colour. Name them anything; the slug is made from the name. A level that rules, features or folders still use can't be removed; removing one drops it from other levels' includes.
+- **Site rules.** The site default, how term rules combine, the meter and the wall's join link.
+- **Content types.** Who can read each collection, with drip, the meter and the teaser. Every collection on the site is listed, including ones made after RedeemID was set up.
+- **Taxonomies.** Rules for terms in every taxonomy, for one collection or every collection the taxonomy is on.
+- **Features** and **Protected files.**
+
+The first save of a setting copies its value from your code config, so nothing is lost, and from then on the admin's value is used. **Use the code's setting** removes the admin's copy. Saved settings are kept in the site's database. Each server keeps the last ones it read and checks one small record per request to see whether anyone saved since, so the whole set is read again only after a save. If the database can't be read, the settings last read stand; a server that has read none yet locks every entry (and refuses files in any media folder) until it can, rather than falling back to the code's settings and opening what the admin locked.
+
+Each saved entry also gets an **Access** panel in the editor. It shows who can read the entry right now and which rule says so, and sets the entry's own rule:
+
+| Choice | Readers need |
+| --- | --- |
+| Follow the site rules | What the rules say (the default) |
+| Free to everyone | Nothing |
+| Only some levels | One of the levels ticked (none ticked: any signed-in member) |
+| Site rules plus a level | What the rules say and one of the levels ticked |
+
+The panel can also hold the entry back for some days of membership, keep the meter off it, lock it until a date and then open it, or keep it free until a date and then lock it. Pass the entry's `id` (or slug) to `<Content>`, `<AccessBadge>` and `<Gate>` so its own rule applies there.
+
+Moving an entry to the trash keeps its rule for a restore but frees its slug, so a new entry that takes the slug doesn't inherit the rule.
+
+## Meter and drip
+
+```ts
+meter: { limit: 3, period: "month", collections: ["posts"] },
+teaser: { posts: 40 },
+```
+
+The meter lets a signed-in reader open a locked entry 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, and 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.
+
+Drip holds a rule's entries back from members who pass it until they've held their level for `drip` days. A level starts when the customer first had a tag of its group (for a `match: "all"` group, the last of its tags); a level held through another's `includes` starts with that one. With several levels the earliest counts, and with none known, the first sign-in. RedeemID notes when each tag first arrives and forgets it when Shopify removes it. The wall shows the date the entry opens.
+
+## 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 product that sells it (its handle, or a link to it). Then:
+
+- A reader holding 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, beside the level's offer.
+- `<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). A refund workflow that removes the tag takes the entry away again.
+
+## Features
+
+```ts
+features: [
+	{ slug: "ad-free", name: "Ad-free", levels: ["gold", "premium"] },
+	{ slug: "supporter", name: "Supporter", tags: ["supporter"] },
+],
+```
+
+A member holds a feature through any of its levels or tags. `<MemberCard>` lists them under the member's levels.
+
+```astro
+---
+import Feature from "@redeemid/emdash/components/Feature.astro";
+import { hasFeature } from "@redeemid/emdash/features";
+---
+<Feature slug="supporter"><p>Thanks for your support.</p><p slot="else">Become a supporter.</p></Feature>
+{!(await hasFeature(Astro, "ad-free")) && <aside class="ad">…</aside>}
+```
+
+## 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 (names match without regard to case). Every request for one at `/_emdash/api/media/file/…` is checked before EmDash serves it:
+
+- **Allowed:** the file, 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` or `features`. With `entries: true` it also lets in whoever can read a published entry that uses the file. Staff can always download, disabled members can't, and a file that can't be checked isn't served.
+
+Limits: only EmDash's file route is checked, so don't give the storage bucket a public URL. Image services that fetch without the reader's cookies, such as a CDN resizer, are refused. Moving a file out of the folder makes it public again.

package/docs/content.md

@@ -0,0 +1,84 @@
+# Content and templates
+
+EmDash has no content filter hook, so templates decide what to render.
+
+**`<Content>`** renders an entry body. Levels come from the entry's rule (its content type, its terms, or its own Access panel); a Paywall break only says where that rule starts. Everything before the first Paywall break block is shown to everyone, and what follows reaches the page only for readers the rule lets in. With no rule covering the entry, the break changes nothing. A body with no break follows the entry's rule as a whole, and readers it keeps out see the collection's `teaser` if one is set (whole paragraphs, never half of one).
+
+```astro
+<Content value={post.data.content} collection="posts" terms={post.data.terms} id={post.id} title={post.data.title}>
+	<a slot="locked" href="/join/">Become a member</a>
+</Content>
+```
+
+Pass `id` on the entry's own page. It lets the meter count the read, and a locked entry gets Google's paywalled-content markup: JSON-LD with `isAccessibleForFree: false` and the wall (`.redeemid-locked`) as the part that isn't free, so search engines can tell a paywall from cloaking. `title` is its headline. Set `schema: false` if an SEO plugin already adds this markup.
+
+**Members only.** A "Members only" block starts a part for the levels picked on it (none picked: the entry's rule, or any signed-in member) that runs to the next "Members only: end" block. Readers who can't read it see the wall in its place and read on after it.
+
+**The wall** is `<LockedPanel>`. It says why the reader is kept out and offers sign-in or the join link, with the wall text of the first level they're missing. `<Content>` and `<Gate>` show it, and their `locked` slot goes on top.
+
+**`<Gate>`** locks any part of a template that isn't the body:
+
+```astro
+<Gate levels={["pro"]}><a href="/reports/archive.zip">Download the archive</a></Gate>
+```
+
+**`<AccessBadge>`** shows what an entry needs, on cards and on the entry. It shows "Free" for open entries (`free=""` hides it), adds `is-locked` and a lock for readers it keeps out, and puts the level slugs in `data-redeemid-level` for colours (and the first level's `badge` colour in `--redeemid-level-color`):
+
+```astro
+<AccessBadge collection="posts" terms={post.data.terms} content={post.data.content} />
+```
+
+**`<Notices />`** goes near the top of the layout. It shows the message for a `?redeemid_notice=` code (see [notices](reference.md#notices)) and nothing otherwise.
+
+**`<MemberCard />`** is for an account page: levels with start dates, the renewal or end date and any gift membership that Shopify keeps (see [membership dates](staff.md#membership-dates)), past levels, the meter, and links to the store account, Refresh membership and Sign out. Refresh membership sends a member to the store with no sign-in form; one still signed in there comes straight back with their tags read again. Add `<Preferences />` and `<YourData />` beside it.
+
+**`<Plan>`** sells a membership: a Shopify product's title and price with a button that starts checkout (members check out with their email). Its levels are `levels`, or else the levels whose `products` list the handle. Then the card fits the member: one who holds a level through its own tags sees "You're on this plan." in place of the button; one whose bigger level includes it sees "Included in your Gold membership."; one the plan would move up (its level includes theirs) gets **Upgrade** (`upgradeLabel`); and one who held it before (Shopify has since removed its tag) gets **Renew** (`renewLabel`) instead of `label`. `data-redeemid-state` is `held`, `included`, `upgrade`, `renew` or `join`. The wall does the same: a lapsed member reads "Your Pro membership has ended." with **Renew Pro** and **Already renewed? Refresh**, not the newcomer's join link.
+
+```astro
+<Plan handle="gold-membership" label="Join Gold" levels={["gold"]}>
+	<p>Shown if the product can't be loaded.</p>
+</Plan>
+```
+
+**In your own code** (`@redeemid/emdash/access`):
+
+```ts
+import { canRead, entryRequirement, readEntry, siteConfig } from "@redeemid/emdash/access";
+
+const verdict = await canRead(Astro, { collection: "posts", terms: post.data.terms, id: post.id });
+// verdict.allowed; verdict.reason: open | allowed | sign_in | upgrade | disabled | unconfigured
+const read = await readEntry(Astro, { collection: "posts", terms: post.data.terms, id: post.id });
+// adds drip (read.opensAt) and the meter (read.meterLeft), and counts a metered read
+
+const config = await siteConfig(Astro.locals);
+const needs = await entryRequirement(config, "posts", post.data.terms, post.id);
+// e.g. [["gold", "pro"]]: readers pass every clause, each with any one of its levels; null when open
+```
+
+**Site search.** EmDash's search API (`/_emdash/api/search`, which its live search box uses) is public and answers with a snippet of the matching text. `redeemidGuard()` checks each result for visitors and members: an entry the reader can't read in full keeps its title but loses its snippet, and stays in the results only when its title holds every searched word, so a search can't show locked text or tell which locked entry contains a word. Staff get every result. A search page that calls EmDash's `search()` in its template filters the same way with `readableResults()`:
+
+```astro
+---
+import { search } from "emdash";
+import { readableResults } from "@redeemid/emdash/search";
+
+const q = Astro.url.searchParams.get("q") ?? "";
+const results = q ? await readableResults(Astro, q, (await search(q)).items) : [];
+---
+```
+
+`siteConfig(Astro.locals)` is the config for this request: your code's config with the Access page's saved settings laid over it. Pass it to the functions that take a `config`, such as `entryRequirement()`, `readPreferences()` and the storefront and catalog calls.
+
+## 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 and its value is the new text. Only the strings you name change: there is no find-and-replace, so replacing "Sign in" leaves "Sign in to download this file." alone. `STRINGS` in `@redeemid/emdash/text` lists every string, grouped by where it shows.
+
+A replacement may use its original's placeholders (such as `{level}`, or `{signIn}` for a link) in any order, or not at all, but no others. Text is plain, so HTML shows as typed. A replacement with an unknown placeholder, or for a string RedeemID doesn't show, is ignored and listed on the Status page with the reason. Props you pass (`label`, `title`, Notices `messages`) win over `text`. Staff screens in the admin aren't covered.

package/docs/developer-api.md

@@ -1,6 +1,6 @@
 # Developer API
 
-What site code, other plugins and AI agents can rely on in `@redeemid/emdash`. API version **1.3.0** (`API_VERSION` in `@redeemid/emdash/contract`, also in `api/state` and `window.redeemid.apiVersion`).
+What site code, other plugins and AI agents can rely on in `@redeemid/emdash`. API version **1.5.0** (`API_VERSION` in `@redeemid/emdash/contract`, also in `api/state` and `window.redeemid.apiVersion`).
 
 Everything on this page is stable: it changes only with a changelog entry and an API version bump (minor when something is added, major when something changes or goes). Anything not listed is internal, even when a module exports it. `src/contract.ts` is the same list as code, and a test fails when the code, that list and this page disagree.
 
@@ -21,10 +21,11 @@ Import these in Astro pages, components and endpoints.
 | `@redeemid/emdash/features` | `hasFeature`, `viewerFeatures`, `featuresFor` |
 | `@redeemid/emdash/preferences` | `readPreferences`, `savePreferences`, `preferenceFields` |
 | `@redeemid/emdash/storefront` | `plan`, `product`, `collection`, `money`, `realOptions`, `variantFor`, `storeContext`, `cartDetails`, `addToCart`, `updateLines`, `removeLines`, `setDiscountCodes` |
-| `@redeemid/emdash/catalog` | `searchProducts`, `collectionPage`, `suggest`, `recommendations`, `browseFromUrl`, `browseHref`, `parseFilters`, `priceFilter`, `SORTS` |
+| `@redeemid/emdash/catalog` | `searchProducts`, `collectionPage`, `suggest`, `recommendations`, `browseFromUrl`, `browseHref`, `parseFilters`, `priceFilter`, `SORTS`, `productSitemap` |
 | `@redeemid/emdash/events` | `signBody` |
 | `@redeemid/emdash/text` | `STRINGS`, `text`, `textParts` |
 | `@redeemid/emdash/search` | `readableResults` |
+| `@redeemid/emdash/cache` | `cacheEntry`, `cachePage`, `noRouteCache`, `CACHE_TAG` |
 
 Levels: `levelsFor(tags, levels)` answers every level the tags hold, including the ones a held level `includes` (so `levels` in `api/state`, `Viewer.levels` and `member.levels_changed` list Silver for a Gold member whose Gold includes Silver). `topLevels(held, levels)` keeps the ones no other held level includes, for showing ("Gold"). `closure(slug, levels)` is every level holding `slug` opens, itself first. `simplify(required, levels)` drops what inclusion already covers from a requirement (`[["silver"], ["gold"]]` becomes `[["gold"]]`); `entryRequirement` already does it. `membership()` marks a level held only through another with `via` (that level's slug).
 
@@ -44,6 +45,8 @@ const totes = config && (await searchProducts(config, "tote", {}, { context: sto
 ---
 ```
 
+Route cache: call `await cacheEntry(Astro, collection, entry, cacheHint)` on an entry's page and `cachePage(Astro, cacheHint)` on lists in place of `Astro.cache.set()`. See [caching](production.md#caching).
+
 Catalog reads (`product`, `collection`, `searchProducts`, `collectionPage`, `suggest`, `recommendations`) are cached for five minutes per Worker isolate. Pass `storeContext(config, Astro.request)` as `context` for local prices when config `market` is set.
 
 ## JSON routes
@@ -53,7 +56,7 @@ Under `/_emdash/api/auth/redeemid/`. Same-origin only: EmDash checks `Origin` on
 - `api/state` (GET): the visitor's own state.
 
   ```json
-  { "apiVersion": "1.3.0", "version": "0.0.24", "signedIn": true, "linked": true,
+  { "apiVersion": "1.5.0", "version": "0.0.26", "signedIn": true, "linked": true,
     "levels": ["gold"], "features": ["ad-free"], "cart": { "count": 2 },
     "meter": { "used": 1, "limit": 3, "period": "month" } }
   ```
@@ -70,7 +73,7 @@ Under `/_emdash/api/auth/redeemid/`. Same-origin only: EmDash checks `Origin` on
   - `?collection=shop`: the collection's page, `{ handle, title, description, products, filters, pageInfo }`.
 
   Both take `first` (1 to 50), `sort`, `after` or `before` (cursors from `pageInfo`), `filter` (repeatable: a filter value's `input` exactly as Shopify gave it), `price_min` and `price_max`. Sorts are `relevance`, `best-selling`, `newest`, `price-asc`, `price-desc`, `title-asc`, `title-desc` (search: relevance and price only). Over the rate limit a search answers 429, as `api/cart` does.
-- `preferences` (GET, POST) and `privacy` (GET export, POST erase): see the README.
+- `preferences` (GET, POST) and `privacy` (GET export, POST erase): see [preferences](shop.md#preferences) and [privacy requests](staff.md#privacy-requests).
 
 Form routes, which redirect back with `?redeemid_notice=<code>` when something needs saying: `login`, `callback`, `logout`, `buy`, `cart`, `cart-edit`, `account`. `webhook` is for Shopify only and answers with a status code.
 
@@ -116,7 +119,24 @@ The client also enhances RedeemID's markup: with `<CartDrawer />` on the page, A
 
 ## Server events
 
-Signed outbound webhooks to config `events.url` (see the README): `member.signed_in`, `member.levels_changed`, `meter.used`, `meter.exhausted`, `preferences.saved`, `member.erased`. Verify `X-RedeemID-Signature` with `signBody(rawBody, secret)`.
+Signed outbound webhooks for a CRM or email tool. Verify `X-RedeemID-Signature` with `signBody(rawBody, secret)` from `@redeemid/emdash/events`.
+
+```ts
+events: { url: "https://hooks.example.com/redeemid", only: ["member.signed_in", "member.levels_changed"] },
+```
+
+With `REDEEMID_EVENTS_SECRET` set, RedeemID POSTs `{ id, event, at, data }` to the URL with the headers `X-RedeemID-Event`, `X-RedeemID-Delivery` (the `id`) and `X-RedeemID-Signature: sha256=<hex HMAC-SHA256 of the raw body>`. Check the signature before you trust a body. Events go out after the response (with `waitUntil` on Workers), so sign-in, webhooks and pages never wait for your receiver. Each try waits at most 3 seconds; a send that fails is tried again after 1 second and after 5 seconds. One that fails all three tries is kept under **App events → Failed events**, where staff can **Send again** (same `id`, so drop duplicates by it) or **Clear** it; failed events are deleted after 30 days.
+
+| Event | `data` |
+| --- | --- |
+| `member.signed_in` | `customerId`, `levels`, `first` (first sign-in), `refresh` |
+| `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 names changed, never the answers) |
+| `member.erased` | `customerId`, `source` (`member`, `staff` or `shopify`) |
+
+No event carries an email address or a name; match people by `customerId`. Leave `only` out to send every event.
 
 ## MCP and the command line
 

package/docs/getting-started.md

@@ -0,0 +1,94 @@
+# Getting started
+
+From an empty EmDash site to a locked post that opens for a tagged customer.
+
+## Requirements
+
+- **EmDash 1.1 or later** with Astro 6 or later, on Node or Cloudflare Workers (the Workers free plan is enough). The MCP tools need an EmDash version with plugin MCP tools.
+- **A Shopify store with the new customer accounts** (Settings → Customer accounts). Classic accounts have no Customer Account API.
+- **The Headless sales channel**, for the sign-in client and Storefront API tokens.
+- **A Shopify app on the store**, such as a Dev Dashboard app, to send webhooks. With its client ID too, it runs the staff tools and preferences.
+- **HTTPS.** Shopify only accepts `https` callback URIs, so a local site needs a tunnel to sign in for real.
+
+## 1. Set up Shopify
+
+Follow [Connect a store](shopify-setup.md). It gives you a Customer Account API client, Storefront API tokens and a webhook app. Once the package is installed, **Plugins → RedeemID → Setup** walks through the same steps for your site, with its own callback URI filled in, and says which are done.
+
+## 2. Install
+
+```sh
+pnpm add @redeemid/emdash
+```
+
+RedeemID is a native EmDash plugin: an npm dependency, not a registry plugin, because sign-in and page gating run in the site process.
+
+## 3. Configure
+
+```js title="astro.config.mjs"
+import { redeemid, redeemidGuard, redeemidPlugin } from "@redeemid/emdash";
+import { defineConfig } from "astro/config";
+import emdash from "emdash/astro";
+
+const config = {
+	shop: "my-store.myshopify.com",
+	levels: [
+		{ slug: "member", name: "Member", tags: ["member"] },
+		{ slug: "pro", name: "Pro", tags: ["pro"], wall: "Pro members read every report." },
+	],
+	rules: [
+		{ collection: "posts", taxonomy: "category", term: "members", levels: ["member", "pro"] },
+		{ collection: "posts", taxonomy: "category", term: "pro", levels: ["pro"] },
+	],
+	join: { href: "/join/", label: "Become a member" },
+};
+
+export default defineConfig({
+	integrations: [
+		emdash({
+			// database, storage, …
+			authProviders: [redeemid(config)], // sign-in, webhooks, cart and checkout routes
+			plugins: [redeemidPlugin(config)], // admin pages and editor blocks
+		}),
+		redeemidGuard(), // gates pages and keeps members out of EmDash's own APIs
+	],
+});
+```
+
+Pass the same `config` to `redeemid()` and `redeemidPlugin()`. Every option is in the [config reference](reference.md#config).
+
+Levels, rules, the meter, features, protected folders, teasers and the join link in this config are the site's defaults. You can leave them all out and set them under **Plugins → RedeemID → Access** instead; see [access settings in the admin](access.md#access-settings-in-the-admin).
+
+## 4. Set the secrets
+
+Set them as runtime secrets of the site (`.env` locally, `wrangler secret put` on Workers), not as build-time variables:
+
+```sh
+REDEEMID_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID=…       # sign-in
+REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_SECRET=…          # verifies webhooks
+REDEEMID_SHOPIFY_STOREFRONT_PRIVATE_TOKEN=…         # only to sell on the site: plans, shop and checkout
+```
+
+The [secrets reference](reference.md#secrets) lists the rest. The Setup page prints the command for each secret its steps need.
+
+## 5. Render content through RedeemID
+
+```astro
+---
+import Account from "@redeemid/emdash/components/Account.astro";
+import Cart from "@redeemid/emdash/components/Cart.astro";
+import Content from "@redeemid/emdash/components/Content.astro";
+import Notices from "@redeemid/emdash/components/Notices.astro";
+---
+<header><Account /> <Cart /></header>
+<Notices />
+<Content value={post.data.content} collection="posts" terms={post.data.terms} id={post.id} title={post.data.title} />
+```
+
+Use `<Content>` in place of `<PortableText>` for every body that may be locked, because plain `<PortableText>` shows everything. You don't have to find them by hand: `redeemidGuard()` scans the site's `.astro` files at build time, and the Status page names each template, with its line, that renders a gated collection's body with `<PortableText>`. While any rule is on, it also lists templates whose collection it can't tell (such as a component given the body as a prop), so you can check them.
+
+## 6. Check it
+
+1. Finish EmDash setup as staff first. Store customers can't create the first account.
+2. Open **Plugins → RedeemID → Setup**. Work down the steps until it says RedeemID is set up (it registers the webhooks for you). **Status** lists every setting as Set or Missing.
+3. Tag a test customer `member` in Shopify, open a locked post, and sign in as that customer. The post opens.
+4. Remove the tag in Shopify. The post locks again once the webhook arrives.

package/docs/production.md

@@ -0,0 +1,52 @@
+# Running in production
+
+## Caching
+
+`redeemidGuard()` keeps every page private for a signed-in visitor or a visitor with a cart: `Cache-Control: private, no-store`, and out of Astro's route cache (it calls `cache.set(false)` after the page sets its own hint). Other visitors all get the same page, so their pages stay cacheable.
+
+Astro's route cache keys pages by URL and serves a stored page without running any code, so whoever asks next gets the same copy. Don't call `Astro.cache.set()` yourself on pages that show entries. Use RedeemID's helpers in the page's frontmatter instead:
+
+```astro
+---
+import { getEmDashEntry, getEmDashCollection } from "emdash";
+import { cacheEntry, cachePage } from "@redeemid/emdash/cache";
+
+// An entry's page: cached only when it reads the same for everyone.
+const { entry: post, cacheHint } = await getEmDashEntry("posts", slug);
+await cacheEntry(Astro, "posts", post, cacheHint);
+
+// A list, or any page without a gated body.
+const { entries, cacheHint: listHint } = await getEmDashCollection("posts");
+cachePage(Astro, listHint);
+---
+```
+
+- **`cacheEntry(Astro, collection, entry, cacheHint)`** caches the page only when no rule covers the entry (content type, terms or its Access panel), it isn't free just until a date, and its body has no Members only part, Sold on its own, Plan or Preferences block. Any other page stays out of the route cache, even if a layout sets a hint afterwards: `redeemidGuard()` takes it out again once the page has rendered. It returns whether the page was cached. `Cache-Control` is left as it was, since a visitor's copy is the same for every visitor.
+- **`cachePage(Astro, cacheHint)`** caches a page as the hint says. Use it for lists and pages that show no gated body.
+- **`noRouteCache(Astro)`** keeps any page out of the route cache.
+
+RedeemID's own components also keep their page out when what they show depends on the reader, so a route rule (`routeRules` in `astro.config.mjs`) or an old `Astro.cache.set()` can't store one reader's copy: `<Content>` for a locked entry, a Members only part, a Sold on its own block or a free-until window; `<Gate>` with a rule; `<Plan>`; `<MemberCard>`, `<Preferences>` and `<YourData>`. `<AccessBadge>` and `<Account>` don't, so lists and other pages stay cacheable; on a cached page a member sees the visitor's badges and header. Still use the helpers in page frontmatter: they decide before anything renders, and they tag the page for purging.
+
+Both caching helpers add the tag `redeemid` (`CACHE_TAG`). Saving on the Access page or an entry's Access panel purges that tag, so cached pages follow the new rules at once. EmDash purges an entry's own pages when the entry is saved. A page cached by a route rule alone has no `redeemid` tag; add it to the rule (`routeRules: { "/posts/[slug]": { maxAge: 300, tags: ["redeemid"] } }`). A deploy that changes the rules in `astro.config.mjs` purges nothing: purge the tag with your cache provider, or wait for `maxAge`.
+
+A cached page is the same for everyone, signed-in members included, since nothing runs on a hit. Keep member-aware parts of cached pages, such as the header's Account link or a cart count, in the browser with [`window.redeemid`](developer-api.md), or leave those pages out of the cache.
+
+The Status page lists templates that call `Astro.cache.set()` on pages of a gated collection.
+
+## Rate limits
+
+On Cloudflare Workers, `redeemidGuard({ rateLimit: true })` limits how often one visitor can start Sign in, Buy, a cart change or a catalog search (`api/search`), the routes that call Shopify. Add a [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) named `REDEEMID_RATE_LIMIT`, which sets the limit and period:
+
+```jsonc
+"ratelimits": [{ "name": "REDEEMID_RATE_LIMIT", "namespace_id": "1001", "simple": { "limit": 20, "period": 60 } }]
+```
+
+Each action counts separately per visitor (by `CF-Connecting-IP`), and Cloudflare's count is approximate. A visitor over the limit goes back to their page with the `too_many_requests` notice; the JSON routes answer `429` with `{ "error": "too_many_requests" }`. If the binding is missing or fails, nothing is limited. Off by default; leave it off on Node.
+
+## Troubleshooting
+
+- **A setting shows Missing on the Status page.** Check the name: the Status page lists any `REDEEMID_` variable it doesn't read. Set it as a runtime secret, not a build variable. On Workers, a deploy can remove plain-text dashboard variables, so use encrypted secrets.
+- **Sign-in comes back with a notice.** The code says why; see [notices](reference.md#notices). `sign_in_unavailable` means store discovery failed, usually a wrong `shop`. `not_configured` means the client ID or `shop` is missing.
+- **Register webhooks names a refused topic.** The app lacks a scope, such as `read_customer_merge` for `customers/merge`. Add it to the app, have the store accept the new version, and press Register again.
+- **Tags changed in Shopify but the site didn't follow.** Check Webhooks → Received and Health, and App events with Problems only. Resync the member from their page, or ask them to press Refresh membership.
+- **A member sees the visitor's page.** A cache is serving it. See [caching](#caching).

package/docs/reference.md

@@ -0,0 +1,128 @@
+# Reference
+
+## Config
+
+Pass one object to both `redeemid(config)` and `redeemidPlugin(config)`. `levels`, `rules`, `meter`, `features`, `files`, `combine`, `teaser` and `join` are defaults that the Access page can replace.
+
+| Option | Type | What it does |
+| --- | --- | --- |
+| `shop` | `string` | The store's `*.myshopify.com` domain. A custom domain works for sign-in, but the Admin API (staff tools, webhook registration, tag reads) answers only on myshopify.com, and the Status page warns when the app is set up with a custom domain. Leave it out to read `REDEEMID_SHOPIFY_STORE_DOMAIN`. |
+| `label` | `string` | The sign-in button's label. Default "Sign in". |
+| `levels` | `{ slug, name, tags?, match?, groups?, includes?, wall?, joinUrl?, products?, home?, badge? }[]` | Levels from customer tags. See [levels](access.md#levels). |
+| `rules` | `{ collection, taxonomy?, term?, levels, open?, drip?, meter? }[]` | What needs which levels. See [rules](access.md#rules). |
+| `combine` | `"all"` \| `"any"` | How several term rules on one entry combine. Default `"all"`. |
+| `join` | `{ href, label? }` | The wall's join link. |
+| `teaser` | `{ [collection]: words }` | Teaser length for locked entries with no paywall break. |
+| `meter` | `{ limit, period?, collections? }` | Free reads for signed-in readers. |
+| `features` | `{ slug, name, levels?, tags? }[]` | Perks held through levels or tags. |
+| `preferences` | `{ key, access? }[]` | Customer metafields members see (`access: "view"`) or change. |
+| `files` | `{ folder, levels?, features?, entries? }[]` | Protected media folders. |
+| `text` | `{ [original]: replacement }` | Replacement text, one string at a time. |
+| `events` | `{ url, only? }` | Signed outbound events. |
+| `agents` | `{ actions?: boolean }` | Also offer resync and tag edits to agents and the command line. |
+| `market` | `{ country?, language? }` | Local prices: a fixed two-letter `country`, or `"visitor"` for each visitor's own. |
+| `checkout` | `{ signIn?: false }` | `signIn: false` stops passing a member's store sign-in to checkout. |
+| `schema` | `false` | Turn off the paywalled-content JSON-LD. |
+| `memberPaths` | `string[]` | Extra `/_emdash` path prefixes signed-in members may use. Everything else there is refused to them. |
+| `entries` | `{ ["collection:id"]: EntryRule }` | Entries' own rules. Usually set in the editor's Access panel. |
+| `allowInsecureShop` | `boolean` | Local tests only: lets `shop` be an `http://` fake store. Never set it on a live site. |
+
+`redeemidGuard(options)` takes `{ rateLimit?: boolean }`.
+
+## Secrets
+
+| Variable | Needed for | What it is |
+| --- | --- | --- |
+| `REDEEMID_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID` | Sign-in | Client ID of the Headless storefront's Customer Account API client |
+| `REDEEMID_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_SECRET` | Sign-in, confidential clients | Its client secret. Leave unset for a public client. |
+| `REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_SECRET` | Webhooks | Client secret of the app that sends the webhooks. Shopify signs each webhook with it. |
+| `REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID` | Webhook registration, staff tools, preferences, membership dates, Shopify erasure requests | Client ID of that same app. Optional, but most of the admin needs it. |
+| `REDEEMID_SHOPIFY_STOREFRONT_PRIVATE_TOKEN` | Plans, shop, checkout | Storefront API private access token, used server-side. Optional if the site sells nothing. |
+| `REDEEMID_SHOPIFY_STOREFRONT_PUBLIC_TOKEN` | Plans, shop, checkout | Public access token, only used without the private one |
+| `REDEEMID_SHOPIFY_STORE_DOMAIN` | Discovery | The store's domain, only when `shop` isn't in the config |
+| `REDEEMID_EVENTS_SECRET` | Events | Signs outbound events. Set it with `events.url`. |
+
+The Status page shows each one as Set or Missing, and lists any `REDEEMID_` variable that is set but not read, by name only, so a misspelt name stands out. Authorization, token and logout endpoints need no setting: RedeemID reads them from the store's discovery documents.
+
+## Components
+
+Import each from `@redeemid/emdash/components/<Name>.astro`.
+
+| Component | Props | Use |
+| --- | --- | --- |
+| `Content` | `value`, `collection`, `terms`, `id`, `title`; slot `locked` | An entry body with breaks, Members only parts, teaser, meter and wall |
+| `Gate` | `collection`, `terms`, `id`, `levels`; slot `locked` | Locks any part of a template |
+| `LockedPanel` | `reason`, `required`, … | The wall on its own |
+| `AccessBadge` | `collection`, `terms`, `content`, `id`, `free`, `class` | What an entry needs, with a lock for readers kept out |
+| `Account` | | Sign in, or the member's name, levels, Account and Sign out |
+| `MemberCard` | `title` | Levels, renewal, end and gift dates, past levels, meter, features, Refresh membership |
+| `Preferences` | `title`, `heading`, `label`; slot `signed-out` | The member's preference form |
+| `YourData` | `title`, `heading` | Download or delete my data |
+| `Feature` | `slug`; slot `else` | Shows its content to members holding the feature |
+| `Notices` | `messages` | The message for `?redeemid_notice=` |
+| `Plan` | `handle`, `label`, `title`, `levels`, `heldLabel`, `renewLabel`, `upgradeLabel` | A product with a buy button that fits the member |
+| `Product` | `handle`, `heading`, `compact`, `html`, `schema`, `addLabel`, `buyLabel` | A product page |
+| `Collection` | `handle`, `limit`, `productHref`, `showTitle`, `browse`, `quickAdd` | A grid of products, with filters and pages |
+| `ProductSearch` | `productHref`, `limit`, `boxOnly`, `action`, `label`, `quickAdd` | Product search |
+| `Recommendations` | `handle`, `intent`, `limit`, `productHref`, `title`, `quickAdd` | Shopify's recommendations |
+| `ProductGrid` | `products`, `productHref`, `heading`, `quickAdd` | Product cards, for your own lists |
+| `BrowseControls` | `filters`, `pageInfo`, `id`, `search`, `query` | Sort, filter and page controls, for your own lists from `collectionPage()` or `searchProducts()` |
+| `Cart` | `label`, `href`, `drawer` | The cart count, linking to checkout or opening the drawer |
+| `CartView` | `productHref`, `empty` | A cart page |
+| `CartDrawer` | `title` | The cart in a slide-in dialog |
+| `RedeemIDClient` | | The browser client, `window.redeemid` |
+| `Contribution` | `handle`, `amounts`, `initial`, `label`, `title` | Pay what you want |
+
+## Editor blocks
+
+`redeemidPlugin()` adds these Portable Text blocks to the EmDash editor. `<Content>` renders them.
+
+| Block | Type | Does |
+| --- | --- | --- |
+| Paywall break | `redeemid-paywall` | Everyone reads up to here; the rest follows the entry's rule |
+| Members only / Members only: end | `redeemid-members`, `redeemid-members-end` | A members-only part in the middle of a body |
+| Sold on its own | `redeemid-item` | Sells the entry by itself to holders of a tag |
+| Plan | `redeemid-plan` | A product with a buy button |
+| Product | `redeemid-product` | A product with variants and Add to cart |
+| Collection | `redeemid-collection` | A grid of products, optionally with filters, pages and Add to cart |
+| Product search | `redeemid-search` | A search box with Shopify's results |
+| Contribution | `redeemid-contribution` | Pay what you want |
+| Preferences | `redeemid-preferences` | The member's preference form |
+
+## Modules
+
+| Import | Gives |
+| --- | --- |
+| `@redeemid/emdash` | `redeemid()`, `redeemidPlugin()`, `redeemidGuard()`, config types |
+| `@redeemid/emdash/access` | `siteConfig()`, `canRead()`, `readEntry()`, `entryRequirement()`, `viewer()`, and links: `signInUrl()`, `signOutUrl()`, `accountUrl()`, `cartUrl()`, `refreshUrl()` |
+| `@redeemid/emdash/features` | `hasFeature()`, `viewerFeatures()` |
+| `@redeemid/emdash/preferences` | `readPreferences()`, `savePreferences()` |
+| `@redeemid/emdash/storefront` | `product()`, `collection()`, `plan()`, `money()` and the cart calls |
+| `@redeemid/emdash/catalog` | `searchProducts()`, `collectionPage()`, `suggest()`, `recommendations()`, `productSitemap()` |
+| `@redeemid/emdash/events` | `signBody(body, secret)`, the signature a receiver checks against `X-RedeemID-Signature` |
+| `@redeemid/emdash/text` | `STRINGS`, the list of every replaceable string |
+| `@redeemid/emdash/search` | `readableResults()`, for a search page that calls EmDash's `search()` |
+| `@redeemid/emdash/contract` | The stable API as a list, and `API_VERSION` |
+
+The full developer API (stable exports, JSON routes, the browser client and its events, MCP tools) is in [docs/developer-api.md](developer-api.md).
+
+## Routes
+
+Under `/_emdash/api/auth/redeemid/`: `login`, `callback`, `logout`, `webhook`, `buy`, `cart`, `cart-edit`, `account`, `preferences` and `privacy`, and the JSON routes `api/state`, `api/cart` and `api/search`. Staff-only routes for the admin, agents and the command line are under `/_emdash/api/plugins/redeemid/`.
+
+In the Customer Account API client, set the callback URI to `https://<site>/_emdash/api/auth/redeemid/callback`, the logout URI to `https://<site>/`, and (public clients) the JavaScript origin to `https://<site>`. Point webhooks at `https://<site>/_emdash/api/auth/redeemid/webhook`: `customers/create`, `customers/update`, `customers/delete`, `customers/disable`, `customers/enable`, `customers/merge`, `customer.tags_added` and `customer.tags_removed` (the Setup page registers these for you). The compliance topics `customers/data_request`, `customers/redact` and `shop/redact` go to the same URL, set in the app's own configuration.
+
+## Notices
+
+Routes send readers back with `?redeemid_notice=<code>`, and `<Notices />` shows the message.
+
+| From | Codes |
+| --- | --- |
+| Sign in | `not_configured`, `sign_in_unavailable`, `sign_in_expired`, `staff_account`, `account_disabled`, `site_not_ready`, `email_required`, `token_failed`, `bad_id_token`, `identity_failed` |
+| Buy and cart | `plan_unavailable`, `checkout_failed`, `cart_empty`, `cart_added`, `cart_updated`, `discount_applied`, `discount_not_applicable` |
+| Account | `account_unavailable`, `refreshed` |
+| Preferences | `preferences_saved`, `preferences_refused`, `preferences_unavailable` |
+| Privacy | `data_erased`, `erase_unconfirmed` |
+| Rate limits | `too_many_requests` |
+
+Reword one with `messages={{ cart_empty: "…" }}`, or for every page with `text`.