@redeemid/emdash 0.0.20 → 0.0.21

package/README.md

@@ -7,7 +7,7 @@ Memberships and paywalls for [EmDash](https://github.com/emdash-cms/emdash) site
 
 Readers sign in with the store's own customer account. Their Shopify customer tags decide what they can read. Shopify keeps the store, checkout, orders and subscriptions, and EmDash keeps the content. Nothing on the site grants access by itself, so there is one source of truth for who paid for what.
 
-**Status: 0.0.20, early.** Runs on Node and Cloudflare Workers. Every feature below is covered by unit tests and an end-to-end test that boots a real EmDash site against a fake Shopify store. Expect changes before 1.0.
+**Status: 0.0.21, early.** Runs on Node and Cloudflare Workers. Unit tests and an end-to-end test that boots a real EmDash site against a fake Shopify store cover the features below. Expect changes before 1.0.
 
 ## Contents
 
@@ -129,10 +129,10 @@ Set them as runtime secrets of the site (`.env` locally, `wrangler secret put` o
 ```sh
 REDEEMID_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID=…       # sign-in
 REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_SECRET=…          # verifies webhooks
-REDEEMID_SHOPIFY_STOREFRONT_PRIVATE_TOKEN=…         # plans, shop and checkout
+REDEEMID_SHOPIFY_STOREFRONT_PRIVATE_TOKEN=…         # only to sell on the site: plans, shop and checkout
 ```
 
-The [secrets reference](#secrets) lists the optional ones.
+The [secrets reference](#secrets) lists the rest. The Setup page prints the command for each secret its steps need.
 
 ### 5. Render content through RedeemID
 
@@ -148,7 +148,7 @@ import Notices from "@redeemid/emdash/components/Notices.astro";
 <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. Plain `<PortableText>` shows everything. The Status page checks: `redeemidGuard()` scans the site's `.astro` files at build time, and Status names any template that renders a gated collection's body with EmDash's `<PortableText>`, with its line. A template whose collection it can't see (a component given the body as a prop) is listed to check while any rule is on.
+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
 
@@ -202,15 +202,19 @@ Pass `id` on the entry's own page. It lets the meter count the read, and a locke
 **In your own code** (`@redeemid/emdash/access`):
 
 ```ts
-import { canRead, entryRequirement, readEntry } from "@redeemid/emdash/access";
+import { canRead, entryRequirement, readEntry, siteConfig } from "@redeemid/emdash/access";
 
-const verdict = await canRead(Astro, { collection: "posts", terms: post.data.terms });
+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
 ```
 
-`entryRequirement(config, collection, terms)` gives what an entry needs: a list of clauses, each passed by any of its levels, or `null` when it's open.
+`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.
 
 ## Guides
 
@@ -251,10 +255,12 @@ Each saved entry also gets an **Access** panel in the editor. It shows who can r
 | --- | --- |
 | Follow the site rules | What the rules say (the default) |
 | Free to everyone | Nothing |
-| Only the levels ticked | One of those levels (none ticked: any signed-in member) |
-| The site rules, and also a level ticked | What the rules say and one of those levels |
+| 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. It 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
 
@@ -359,7 +365,7 @@ Define each field in Shopify (**Settings → Custom data → Customers**); the d
 | Decimal | A number, as a string |
 | Date | `YYYY-MM-DD` |
 
-Every value is checked against the definition first. One refusal saves nothing, and an empty value clears the field. Scripts can `GET` `/_emdash/api/auth/redeemid/preferences` for `{ fields }`, or `POST` JSON `{ values: { "namespace.key": value } }`. 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`). `readPreferences()` and `savePreferences()` in `@redeemid/emdash/preferences` do the same from your code.
+Every value is checked against the definition first. One refusal saves nothing, and an empty value clears the field. Scripts can `GET` `/_emdash/api/auth/redeemid/preferences` for `{ fields }`, or `POST` JSON `{ values: { "namespace.key": value } }`. 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(config, customerId)` and `savePreferences(config, customerId, values)` in `@redeemid/emdash/preferences` do the same (no rate limit there; `config` comes from `siteConfig()`).
 
 ### Protected files
 
@@ -425,7 +431,7 @@ RedeemID reads them with the Admin API (resync, sign-in, tag webhooks), so they
 Members gain and lose access only when Shopify sends tag changes, so RedeemID shows what arrived and warns when deliveries stop.
 
 - **Webhooks → Received.** Each delivery's topic, what became of it (processed, skipped, older than what's stored, not used) and the customer ID, with counts of deliveries turned away (bad signature) and failed (storage errors; Shopify sends those again).
-- **Webhooks → Health.** Once a day RedeemID registers again any subscription Shopify dropped (with the Admin API app), and warns when no webhook has come in for a number of days (3 by default, 0 turns it off), or when deliveries were turned away or failed in the last day. **Check now** runs it at once. Warnings show on the page and the dashboard widget, and go by email to the address you set when the site has an EmDash email provider: once when problems start or change, then once a week while they last.
+- **Webhooks → Health.** Once a day RedeemID registers again any subscription Shopify dropped (with the Admin API app), and warns when no webhook has come in for a number of days (3 by default, 0 turns it off), or when deliveries were turned away or failed in the last day. **Check now** runs it at once. Warnings show on the page and the dashboard widget. If you enter an address on the Health tab and the site has an EmDash email provider, they also go by email: once when problems start or change, then once a week while they last.
 - **Webhooks → Setup.** The endpoint, whether signatures can be checked, and the subscriptions.
 - **App events.** What RedeemID did and what came of it: webhooks received, turned away and failed, sign-ins and refusals (by reason), Admin API calls (by operation, with timings), resyncs, tag edits, webhook registrations, settings saves, outbound events that failed, metered reads and the health checks. Filter by event or show problems only. Entries hold ids, labels and outcomes, never bodies, tokens or emails. Failed outbound events also keep the event body (ids and levels, never an email or a name) so they can be sent again.
 - **Reports.** Members on each level, who joined and left in the last 30 days and by week for 12 weeks (from each member's tag dates), sign-ins and metered reads.
@@ -459,7 +465,7 @@ npx -p @redeemid/emdash redeemid-emdash access posts --id my-story --tags gold-m
 npx -p @redeemid/emdash redeemid-emdash member jane@example.com
 ```
 
-Each command calls a staff-only route at `/_emdash/api/plugins/redeemid/<name>`, which scripts can POST to directly.
+Each command POSTs JSON to a staff-only route under `/_emdash/api/plugins/redeemid/`, named after its tool with hyphens (`explain_access` is `explain-access`). Scripts can call those routes directly.
 
 ### Replacement text
 
@@ -508,7 +514,7 @@ On Cloudflare Workers, `redeemidGuard({ rateLimit: true })` limits how often one
 "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. If the binding is missing or fails, nothing is limited. Off by default; leave it off on Node.
+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.
 
 ## Reference
 
@@ -548,8 +554,8 @@ Pass one object to both `redeemid(config)` and `redeemidPlugin(config)`. `levels
 | `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` | Staff tools, preferences, privacy erasure requests | Client ID of that same app. Optional. |
-| `REDEEMID_SHOPIFY_STOREFRONT_PRIVATE_TOKEN` | Plans, shop, checkout | Storefront API private access token, used server-side |
+| `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`. |
@@ -578,6 +584,7 @@ Import each from `@redeemid/emdash/components/<Name>.astro`.
 | `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 |
@@ -605,7 +612,7 @@ Import each from `@redeemid/emdash/components/<Name>.astro`.
 | Import | Gives |
 | --- | --- |
 | `@redeemid/emdash` | `redeemid()`, `redeemidPlugin()`, `redeemidGuard()`, config types |
-| `@redeemid/emdash/access` | `canRead()`, `readEntry()`, `entryRequirement()`, `viewer()`, and links: `signInUrl()`, `signOutUrl()`, `accountUrl()`, `cartUrl()`, `refreshUrl()` |
+| `@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 |
@@ -620,7 +627,7 @@ The full developer API (stable exports, JSON routes, the browser client and its
 
 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`, `customer.tags_removed` and `customers/redact`.
+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
 

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.0.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.1.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.
 
@@ -17,7 +17,7 @@ Import these in Astro pages, components and endpoints.
 | Import | Stable exports |
 | --- | --- |
 | `@redeemid/emdash` | `redeemid`, `redeemidGuard`, `redeemidPlugin` |
-| `@redeemid/emdash/access` | `viewer`, `canRead`, `readEntry`, `entryRequirement`, `meterUsage`, `membership`, `levelsFor`, `signInUrl`, `signOutUrl`, `accountUrl`, `cartUrl`, `refreshUrl`, `safeReturn` |
+| `@redeemid/emdash/access` | `siteConfig`, `viewer`, `canRead`, `readEntry`, `entryRequirement`, `meterUsage`, `membership`, `levelsFor`, `signInUrl`, `signOutUrl`, `accountUrl`, `cartUrl`, `refreshUrl`, `safeReturn` |
 | `@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` |
@@ -25,16 +25,19 @@ Import these in Astro pages, components and endpoints.
 | `@redeemid/emdash/events` | `signBody` |
 | `@redeemid/emdash/text` | `STRINGS`, `text`, `textParts` |
 
-The site's config for a request comes from `siteConfig(Astro.locals)` (code config with the admin's saved settings laid over it). A few examples:
+Functions that take a `config` want the site's config for the request: `await siteConfig(Astro.locals)`, which is the code's config with the admin's saved settings laid over it. Passing the object from `astro.config.mjs` instead skips what staff saved on the Access page. A few examples:
 
 ```astro
 ---
-import { canRead, viewer } from "@redeemid/emdash/access";
+import { canRead, siteConfig } from "@redeemid/emdash/access";
 import { hasFeature } from "@redeemid/emdash/features";
 import { searchProducts } from "@redeemid/emdash/catalog";
+import { storeContext } from "@redeemid/emdash/storefront";
 
 const verdict = await canRead(Astro, { collection: "posts", terms: post.data.terms, id: post.id });
 const adFree = await hasFeature(Astro, "ad-free");
+const config = await siteConfig(Astro.locals);
+const totes = config && (await searchProducts(config, "tote", {}, { context: storeContext(config, Astro.request) }));
 ---
 ```
 
@@ -47,7 +50,7 @@ Under `/_emdash/api/auth/redeemid/`. Same-origin only: EmDash checks `Origin` on
 - `api/state` (GET): the visitor's own state.
 
   ```json
-  { "apiVersion": "1.0.0", "version": "0.0.20", "signedIn": true, "linked": true,
+  { "apiVersion": "1.1.0", "version": "0.0.21", "signedIn": true, "linked": true,
     "levels": ["gold"], "features": ["ad-free"], "cart": { "count": 2 },
     "meter": { "used": 1, "limit": 3, "period": "month" } }
   ```
@@ -57,16 +60,16 @@ Under `/_emdash/api/auth/redeemid/`. Same-origin only: EmDash checks `Origin` on
   - `update`: `line`, `quantity` (0 removes); `remove`: `line`; `discount`: `code` (`""` clears);
   - `checkout`: answers `{ checkoutUrl }`, signed in for members.
 
-  Other actions answer `{ notice, cart, added? }`. An add Shopify can't fill answers 422 with `notice: "plan_unavailable"`. Over the rate limit (with `redeemidGuard({ rateLimit: true })`) POST answers 429.
+  Other actions answer `{ notice, cart, added? }`. An add Shopify can't fill answers 422 with `notice: "plan_unavailable"`. Over the rate limit (with `redeemidGuard({ rateLimit: true })`) POST answers 429 with `{ "error": "too_many_requests" }`.
 - `api/search` (GET): public catalog data, `Cache-Control: public, max-age=60` (private when `market.country` is `"visitor"`).
   - `?q=tote&suggest=1[&limit=6]`: `{ queries, products, collections }`, for search-as-you-type;
   - `?q=tote`: `{ products, filters, pageInfo, total }`;
   - `?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).
+  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.
 
-Form routes, which redirect back with `?redeemid_notice=<code>`: `login`, `callback`, `logout`, `webhook`, `buy`, `cart`, `cart-edit`, `account`.
+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.
 
 ## Browser client
 
@@ -114,13 +117,13 @@ Signed outbound webhooks to config `events.url` (see the README): `member.signed
 
 ## MCP and the command line
 
-RedeemID's tools join EmDash's MCP server once staff turn them on for RedeemID under Plugins. They need a staff token (permission `users:read`). Always offered, read-only:
+RedeemID's tools join EmDash's MCP server once staff turn them on for RedeemID under Plugins. They need an administrator's API token (the routes ask for `users:read`, which only Admins hold) with the `mcp:tools` or `mcp:tools:redeemid` scope. Always offered, read-only:
 
 - `explain_access`, `list_levels`, `get_rules`, `get_member`, `site_health`, `level_changes`
 - `find_products`, `get_product`, `get_collection`: the Shopify catalog the site sells, so an agent writing content can find the right product and collection handles.
 
 Only with config `agents: { actions: true }`: `resync_member`, `resync_batch`, `edit_member_tags`.
 
-The `redeemid-emdash` command line calls the same routes (`npx redeemid-emdash --help`).
+The `redeemid-emdash` command line calls the same routes (`npx -p @redeemid/emdash redeemid-emdash --help`).
 
 For shoppers' own agents (browsing products, building a cart, checking out), point them at Shopify's Storefront MCP server for the store, `https://<store domain>/api/mcp`. It runs on Shopify, where checkout and prices already live, so RedeemID doesn't repeat it.

package/docs/shopify-flow.md

@@ -2,7 +2,7 @@
 
 RedeemID never grants access itself. A member's levels come from tags on their Shopify customer, and something in Shopify has to put those tags on and take them off. That is usually [Shopify Flow](https://help.shopify.com/manual/shopify-flow), which comes free with every Shopify plan, or a subscription app.
 
-When a tag changes, Shopify sends `customers/update` and RedeemID reads the customer again. Access follows within seconds, and nobody has to sign in again.
+When a tag changes, Shopify sends a `customer.tags_added` or `customer.tags_removed` webhook. With the Admin API app's client ID set, RedeemID reads the customer's tags as they are now; without it, it applies the change the webhook carries. Access follows within seconds, and nobody has to sign in again.
 
 Each recipe below is one Flow workflow. In Flow, open **Create workflow**, pick the trigger, add the condition, then add the action. The trigger and action names here are the ones Flow shows in English. The field paths in conditions can read slightly differently in Flow's picker. Subscription triggers come from your subscription app, so their names depend on the app.
 
@@ -28,7 +28,7 @@ A partial refund of something else in the same order matches nothing, so the tag
 
 ## 3. A cancelled subscription removes it
 
-Subscription apps that work with Flow add their own triggers, such as "Subscription contract cancelled" or "Subscription contract status updated". Most subscription apps add triggers like these, each with its own names. Check your app's Flow listing.
+Subscription apps that work with Flow add their own triggers, such as "Subscription contract cancelled" or "Subscription contract status updated". The names vary by app, so check your app's Flow listing.
 
 - **Trigger:** your app's cancel trigger. If the app only offers a status-changed trigger, add the condition status is `CANCELLED`, and treat `EXPIRED` the same way.
 - **Action:** Remove customer tags, with `member`.
@@ -63,7 +63,7 @@ After a purchase, **Refresh membership** on the member card reads their tags aga
 
 ## Check a recipe
 
-1. Under **Plugins → RedeemID → Webhooks**, make sure `customers/update` is registered. The Setup page does this for you.
+1. Under **Plugins → RedeemID → Webhooks → Setup**, make sure `customer.tags_added` and `customer.tags_removed` show as Registered. The Setup page registers them for you.
 2. Buy the product with a test customer, using Shopify's Bogus Gateway or a 100% discount code.
 3. In Flow, open the workflow's **Recent runs**. The run should show the tag added.
 4. Open **Plugins → RedeemID → Members**, then the customer. The tag and level should be there.

package/docs/shopify-setup.md

@@ -2,6 +2,8 @@
 
 What to set up in Shopify, and on the site, to run RedeemID on an EmDash site. One store can serve several sites: each site gets its own Headless storefront for sign-in, and each receives webhooks.
 
+Once the package is installed, **Plugins → RedeemID → Setup** in the EmDash admin walks through these same steps with your site's own addresses filled in, checks each one, and registers the webhooks for you.
+
 ## 1. Sign-in: a Headless storefront
 
 1. In Shopify admin, open **Sales channels → Headless** (add the channel if it isn't there) and **Create storefront**. Name it after the site.
@@ -23,15 +25,17 @@ The store must use the new customer accounts (Settings → Customer accounts). C
 
 ## 2. Webhooks
 
-RedeemID keeps tags and status current from webhooks. Point these topics at `https://<site>/_emdash/api/auth/redeemid/webhook`:
+RedeemID keeps tags and status current from webhooks sent by a Shopify app on the store (for example a Dev Dashboard app). Shopify signs every webhook with that app's **client secret**, which is the site's webhook secret.
+
+Give the app the `read_customers` and `write_customers` Admin API scopes, plus `read_customer_merge` for `customers/merge`, and set its **client ID** on the site as well. Then the Setup page (or **Webhooks → Setup**) registers these topics at `https://<site>/_emdash/api/auth/redeemid/webhook` with one button:
 
-`customers/create`, `customers/update`, `customers/delete`, `customers/disable`, `customers/enable`, `customers/merge`, `customer.tags_added`, `customer.tags_removed`, `customers/redact`
+`customers/create`, `customers/update`, `customers/delete`, `customers/disable`, `customers/enable`, `customers/merge`, `customer.tags_added`, `customer.tags_removed`
 
-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.
+Without the client ID, subscribe them to that URL yourself. If the app already sends webhooks to another site, add this URL as extra subscriptions.
 
-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.
+The client ID and those scopes also run the staff tools (member resync and tag edits written to Shopify), member preferences, and the reads that keep tags in order (see the README). 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.
+Shopify's compliance topics (`customers/data_request`, `customers/redact`, `shop/redact`) can't be registered by the button: they 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 and acts on it (see the README's privacy requests).
 
 ## 3. The site
 
@@ -46,12 +50,14 @@ npx wrangler secret put REDEEMID_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_SECRET # confid
 npx wrangler secret put REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_SECRET        # the webhook app's client secret
 npx wrangler secret put REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID            # optional; the webhook app's client ID, for the staff tools
 npx wrangler secret put REDEEMID_EVENTS_SECRET                          # optional; signs outbound events (events.url)
-npx wrangler secret put REDEEMID_SHOPIFY_STOREFRONT_PRIVATE_TOKEN       # Headless storefront's Storefront API private token (plans, checkout)
+npx wrangler secret put REDEEMID_SHOPIFY_STOREFRONT_PRIVATE_TOKEN       # optional; the Storefront API private token, to sell on the site (plans, shop, checkout)
 npx wrangler secret put REDEEMID_SHOPIFY_STOREFRONT_PUBLIC_TOKEN        # optional; used only without the private token
 ```
 
 The Workers free plan is enough: RedeemID is a native plugin and doesn't need sandboxing. Worker secrets reach the code through `nodejs_compat`, which EmDash's Cloudflare templates turn on.
 
+On Workers, also add a Cron Trigger to the site's Worker, as EmDash's deployment guide describes, so EmDash's scheduler runs RedeemID's daily webhook health check.
+
 ## 4. Try it
 
 1. Finish EmDash setup as staff first. Store customers can't create the first account.
@@ -59,4 +65,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. Preferences return `preferences_saved`, `preferences_refused` or `preferences_unavailable`.
+If sign-in sends you back with `?redeemid_notice=…`, the code says why: `not_configured` means the client ID or `shop` is missing, and `sign_in_unavailable` means store discovery failed, usually a wrong `shop`. The README lists [every notice](../README.md#notices).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@redeemid/emdash",
-	"version": "0.0.20",
+	"version": "0.0.21",
 	"description": "Shopify customer accounts, member levels and paywalls for EmDash sites. Shopify runs commerce; EmDash runs content.",
 	"type": "module",
 	"license": "MIT",

package/src/access.ts

@@ -15,6 +15,9 @@ import { UNAVAILABLE, type EntryRule } from "./settings.js";
 import { siteConfig } from "./site-config.js";
 import { memberForUser, stores, type MemberRecord, type MeterRecord } from "./storage.js";
 
+/** The site's config for a request: the code's config with the admin's saved settings laid over it. */
+export { siteConfig };
+
 /** The parts of Astro's global that access checks read. */
 export interface AstroLike {
 	locals: unknown;

package/src/api-version.ts

@@ -3,4 +3,4 @@
  * when something is added, the major part when something stable changes or
  * goes. Separate from the package version.
  */
-export const API_VERSION = "1.0.0";
+export const API_VERSION = "1.1.0";

package/src/contract.ts

@@ -16,7 +16,7 @@ export { API_VERSION } from "./api-version.js";
 /** Stable exports, by import path. */
 export const MODULES = {
 	"@redeemid/emdash": ["redeemid", "redeemidGuard", "redeemidPlugin"],
-	"@redeemid/emdash/access": ["viewer", "canRead", "readEntry", "entryRequirement", "meterUsage", "membership", "levelsFor", "signInUrl", "signOutUrl", "accountUrl", "cartUrl", "refreshUrl", "safeReturn"],
+	"@redeemid/emdash/access": ["siteConfig", "viewer", "canRead", "readEntry", "entryRequirement", "meterUsage", "membership", "levelsFor", "signInUrl", "signOutUrl", "accountUrl", "cartUrl", "refreshUrl", "safeReturn"],
 	"@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"],

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.0.20";
+export const VERSION = "0.0.21";