@redeemid/emdash 0.0.19 → 0.0.20

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.19, 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.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.
 
 ## Contents
 
@@ -30,13 +30,13 @@ Readers sign in with the store's own customer account. Their Shopify customer ta
 4. **Rules.** You say which content types or terms need which levels, in the admin (Plugins → RedeemID → Access) or in code. Each entry can have its own rule in the editor's Access panel, and editors can drop a Paywall break or a Members only block into any body.
 5. **Render.** Templates render bodies with `<Content>`. Readers who pass see everything. Everyone else gets a teaser and the wall, and the locked part never reaches the page.
 
-Selling a membership is ordinary Shopify: a product, a checkout, and a Flow workflow that tags the customer when the order is paid. RedeemID shows the product and starts checkout, and access follows the tag.
+Selling a membership is ordinary Shopify: a product, a checkout, and a Flow workflow that tags the customer when the order is paid. RedeemID shows the product and starts checkout, and access follows the tag. [docs/shopify-flow.md](docs/shopify-flow.md) has the workflows: paid order, refund, cancelled subscription, and a pass that ends.
 
 ## What you get
 
 **For members**
 - Sign in, Account (orders, profile and addresses on the store) and Sign out, which ends the store session too. Members never see the word "Shopify".
-- A member card with their levels and when each started, past levels, the meter, and Refresh membership to read their tags again after a purchase.
+- A member card with their levels and when each started, when the membership renews or ends and any gift membership (from Shopify), past levels, the meter, and Refresh membership to read their tags again after a purchase.
 - Preferences they can change, such as topics or a newsletter choice, saved on the Shopify customer.
 - Download or delete what the site keeps about them.
 
@@ -53,7 +53,8 @@ Selling a membership is ordinary Shopify: a product, a checkout, and a Flow work
 - Webhooks page: what Shopify sent and what became of it, delivery health with a daily check and email warnings, and the subscriptions with a Register button.
 - App events: webhooks, sign-ins and refusals, Admin API calls, staff actions and settings saves, filterable, kept 30 days.
 - Reports: members by level, who joined and left by week, sign-ins and metered reads.
-- Status page: every setting, store discovery, levels and rules.
+- Setup page: connecting a store step by step, with the exact values to paste into Shopify, the command for each secret, a Register button for the webhooks and a form for the first level. Each step checks the site as it is.
+- Status page: every setting, store discovery, levels and rules, and any template that would show a locked body in full.
 - Access test, Privacy page, and a dashboard widget.
 
 **For developers**
@@ -75,7 +76,7 @@ Selling a membership is ordinary Shopify: a product, a checkout, and a Flow work
 
 ### 1. Set up Shopify
 
-Follow [docs/shopify-setup.md](docs/shopify-setup.md). It gives you a Customer Account API client, Storefront API tokens and a webhook app.
+Follow [docs/shopify-setup.md](docs/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
 
@@ -147,12 +148,12 @@ 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.
+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.
 
 ### 6. Check it
 
 1. Finish EmDash setup as staff first. Store customers can't create the first account.
-2. Open **Plugins → RedeemID → Status**. Every setting should say Set. Then open **Webhooks → Setup** and press **Register**.
+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.
 
@@ -188,9 +189,9 @@ Pass `id` on the entry's own page. It lets the meter count the read, and a locke
 
 **`<Notices />`** goes near the top of the layout. It shows the message for a `?redeemid_notice=` code (see [notices](#notices)) and nothing otherwise.
 
-**`<MemberCard />`** is for an account page: levels with start 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.
+**`<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](#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). With `levels`, members who already hold one see "You're on this plan." in place of the button.
+**`<Plan>`** sells a membership: a Shopify product's title and price with a button that starts checkout (members check out with their email). With `levels`, members who already hold one see "You're on this plan." in place of the button, and a member who held one before (Shopify has since removed its tag) gets **Renew** (`renewLabel`) instead of `label`. 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"]}>
@@ -242,7 +243,7 @@ Everything about who reads what can be set in the EmDash admin, so a new content
 - **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 and read once per request.
+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:
 
@@ -253,7 +254,7 @@ Each saved entry also gets an **Access** panel in the editor. It shows who can r
 | 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 |
 
-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. 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.
 
 ### Meter and drip
 
@@ -329,7 +330,7 @@ Products, collections, search and the cart come from the Storefront API. Shopify
 
 Everything works without JavaScript: the forms post to `/_emdash/api/auth/redeemid/cart-edit`, which reads every product, variant, option and selling plan from Shopify again and only changes the visitor's own cart. `<RedeemIDClient />` adds the drawer, option pickers that follow the choice, and search suggestions. A new cart carries the `_redeemid_page` attribute (the page the first item was added on), which shows on the order in Shopify admin. Editors get the same with the Product, Collection, Product search and Contribution blocks.
 
-**Signed-in checkout.** When a signed-in member checks out, RedeemID puts their store sign-in (the Customer Account API access token, kept only in the server-side session and renewed when it's about to expire) on the cart, so Shopify's checkout opens signed in and the order lands on their customer record, where your Flow or apps tag it. If that can't be done, they check out as a guest with their email filled in. Set `checkout: { signIn: false }` to always use a guest checkout.
+**Signed-in checkout.** When a signed-in member checks out, RedeemID puts their store sign-in (the Customer Account API access token, kept only in the server-side session, encrypted with a key kept in the site's database, and renewed when it's about to expire) on the cart, so Shopify's checkout opens signed in and the order lands on their customer record, where your Flow or apps tag it. If that can't be done, they check out as a guest with their email filled in. Set `checkout: { signIn: false }` to always use a guest checkout; then the tokens aren't kept at all.
 
 **Local prices.** Set `market: { country: "visitor" }` to show each visitor prices in their own market (from Cloudflare's `CF-IPCountry`), or a fixed `country` and `language`. Markets are set up in Shopify.
 
@@ -383,7 +384,7 @@ Limits: only EmDash's file route is checked, so don't give the storage bucket a
 
 ### Privacy requests
 
-What RedeemID keeps about a member: the synced record (Shopify customer ID, email, name, tags and when each started, account status, first sign-in, last sync) and their meter. Preference answers stay on the Shopify customer, and webhook deliveries keep only a topic and a time. Erasing on the site never erases Shopify data; it can only ask Shopify to.
+What RedeemID keeps about a member: the synced record (Shopify customer ID, email, name, tags and when each started, account status, first sign-in, last sync, whether the email was verified, email and SMS marketing consent, and the membership dates) and their meter. Preference answers stay on the Shopify customer, and webhook deliveries keep only a topic and a time. Erasing on the site never erases Shopify data; it can only ask Shopify to.
 
 | Started by | What happens |
 | --- | --- |
@@ -393,7 +394,7 @@ What RedeemID keeps about a member: the synced record (Shopify customer ID, emai
 | Shopify `customers/redact` | The member's record and meter are erased. |
 | Shopify `shop/redact` | Every member record and meter is erased. |
 
-The Privacy page shows each request's source and Shopify customer ID, never an email or a name. An erase sends the `member.erased` event so a CRM can delete its copy too. The site's own user account stays; delete it under Users if the person asks. The JSON route is `/_emdash/api/auth/redeemid/privacy`: `GET` downloads, `POST` with `confirm=yes` erases, only for the signed-in member and only from the site's own origin.
+The Privacy page shows each request's source and Shopify customer ID, never an email or a name. The daily check deletes finished requests after a year; open ones stay until staff mark them done. An erase sends the `member.erased` event so a CRM can delete its copy too. The site's own user account stays; delete it under Users if the person asks. The JSON route is `/_emdash/api/auth/redeemid/privacy`: `GET` downloads, `POST` with `confirm=yes` erases, only for the signed-in member and only from the site's own origin.
 
 ### Staff tools
 
@@ -404,7 +405,20 @@ With `REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID` set, RedeemID gets an Admin API toke
 - **Webhook subscriptions.** Webhooks → Setup lists the store's subscriptions to this site and registers any that are missing. A topic Shopify refuses, such as `customers/merge` without `read_customer_merge`, is named with the reason and doesn't stop the others. `customers/redact` stays in the app's own settings.
 - **Access test.** A collection, an entry, terms and a reader's tags in; the verdict out.
 
-Resync updates email, name and tags. Enabled or disabled status comes only from the enable and disable webhooks.
+Resync updates email, name, tags, email marketing consent and the membership dates. Enabled or disabled status comes only from the enable and disable webhooks. With the app set up, two more things read the customer from the Admin API as it is now: every sign-in (and Refresh membership), and every `customer.tags_added` or `customer.tags_removed` webhook. Those topics carry only the change and can arrive out of order, so reading the current tags keeps the mirror right. Without the app, or when the read fails, the webhook's change is applied as sent.
+
+#### Membership dates
+
+A subscription app or Shopify Flow can keep these customer metafields, as dates (`YYYY-MM-DD`):
+
+| Metafield | Shown |
+| --- | --- |
+| `membership.member_since` | As the start date on the member card, in place of when the tag arrived |
+| `membership.renews_on` | "Renews on ..." |
+| `membership.ends_on` | "Ends on ...", for a pass that doesn't renew |
+| `membership.gift_until` | "Gift membership until ...", while it's in the future |
+
+RedeemID reads them with the Admin API (resync, sign-in, tag webhooks), so they need the Admin API app. They're for display only: access still comes from tags alone, and nothing on the site ends access on these dates. Time-boxed access is a Flow that waits and removes the tag (see [Shopify Flow recipes](docs/shopify-flow.md)).
 
 ### Webhooks, app events and reports
 
@@ -413,7 +427,7 @@ Members gain and lose access only when Shopify sends tag changes, so RedeemID sh
 - **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 → 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.
+- **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.
 
 App events and delivery records are kept 30 days. The daily check runs from EmDash's scheduler: on Node it runs by itself; on Cloudflare Workers, add a Cron Trigger to the site's Worker as EmDash's deployment guide describes. The plugin asks for `email:send` only to send these warnings.
@@ -467,7 +481,7 @@ A replacement may use its original's placeholders (such as `{level}`, or `{signI
 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. A send waits at most 3 seconds and never breaks the page; a failed send is logged, not retried.
+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` |
 | --- | --- |
@@ -488,7 +502,7 @@ A route cache keys pages by URL alone and serves stored pages without running an
 
 ### Rate limits
 
-On Cloudflare Workers, `redeemidGuard({ rateLimit: true })` limits how often one visitor can start Sign in, Buy or a cart change, 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:
+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 } }]
@@ -553,12 +567,12 @@ Import each from `@redeemid/emdash/components/<Name>.astro`.
 | `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, past levels, meter, features, Refresh membership |
+| `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` | A product with a buy button |
+| `Plan` | `handle`, `label`, `title`, `levels`, `heldLabel`, `renewLabel` | A product with a buy button |
 | `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 |
@@ -628,10 +642,11 @@ Reword one with `messages={{ cart_empty: "…" }}`, or for every page with `text
 - Shopify is the only source of entitlements. Nothing on the site grants access.
 - Levels read the mirrored tags as they are, however old. They change only when Shopify sends new ones.
 - Enabled or disabled status comes only from the `customers/enable` and `customers/disable` webhooks.
-- Locked content never reaches the page, the content API, search, feeds or the sitemap for readers kept out. Members are refused EmDash's own APIs except what they need.
+- Locked content never reaches the content API, search, feeds or the sitemap for readers kept out, nor a page that renders bodies with `<Content>` (the Status page flags templates that use `<PortableText>` for a gated collection). The end-to-end test checks each of these. Members are refused EmDash's own APIs except what they need.
 - Staff accounts (any EmDash role above Subscriber) can't sign in through the store, even with a matching email. When that happens, the store session ends too, so the next sign-in attempt starts fresh.
 - Customers can't create the first (admin) account on a new site.
 - Webhooks are checked against the app's signature before anything changes.
+- Access fails closed: when the saved access settings can't be read, a server keeps the ones it last read, and with none it locks every entry.
 
 ## Troubleshooting
 

package/docs/developer-api.md

@@ -47,7 +47,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.19", "signedIn": true, "linked": true,
+  { "apiVersion": "1.0.0", "version": "0.0.20", "signedIn": true, "linked": true,
     "levels": ["gold"], "features": ["ad-free"], "cart": { "count": 2 },
     "meter": { "used": 1, "limit": 3, "period": "month" } }
   ```

package/docs/shopify-flow.md

@@ -0,0 +1,70 @@
+# Shopify Flow recipes
+
+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.
+
+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.
+
+The examples use a product called "Membership" and the tag `member`. Use your own product and the tag your level maps to, which you can see under **Plugins → RedeemID → Access**.
+
+## 1. A paid order adds the tag
+
+- **Trigger:** Order paid
+- **Condition:** at least one of `order.lineItems` has `product.title` equal to `Membership`. If you sell several plans, match the product ID or a product tag such as `plan-member` instead, which keeps working after a rename.
+- **Action:** Add customer tags, with `member`.
+
+Use **Order paid** rather than Order created, so an unpaid order (for example, a payment that's still pending) doesn't open anything. Also add `order.customer` exists to the condition. A checkout always has an email, but a draft order may not have a customer.
+
+If the plan is meant to show as a gift, also add an **Update customer metafield** action that sets `membership.gift_until` (type date). See [membership dates](../README.md#membership-dates).
+
+## 2. A refund removes it
+
+- **Trigger:** Refund created
+- **Condition:** at least one of `refund.refundLineItems` has `lineItem.product.title` equal to `Membership`.
+- **Action:** Remove customer tags, with `member`.
+
+A partial refund of something else in the same order matches nothing, so the tag stays. Shipping-only refunds match nothing either.
+
+## 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.
+
+- **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`.
+
+Many apps can tag customers themselves (for example, "tag active subscribers"). If you use that, don't also run recipes 1 and 3 for the same tag, or one will undo the other.
+
+To show the next billing date, add **Update customer metafield** to the app's "billing attempt succeeded" (or renewal) trigger, setting `membership.renews_on` to the next billing date.
+
+## 4. A pass that ends: wait, then remove
+
+For a fixed-term pass that doesn't renew, such as a 30-day pass:
+
+- **Trigger:** Order paid
+- **Condition:** the order contains the pass product, as in recipe 1.
+- **Actions:**
+  1. Add customer tags, with `pass`.
+  2. Update customer metafield `membership.ends_on`, set to the order date plus 30 days. This step is optional and is only used for display.
+  3. Wait 30 days.
+  4. Remove customer tags, with `pass`.
+
+The wait lives in Flow, not on the site. RedeemID doesn't end access on the `ends_on` date. It only shows that date, so the tag is still what decides access.
+
+If a member buys a second pass while the first is still running, the first workflow's removal takes the tag away early. Give each length its own tag (`pass-30`, `pass-90`), or make the last step check the newest order before it removes the tag.
+
+## 5. A member's own Shopify account
+
+None of these recipes need anything from RedeemID. A customer who buys while signed out is tagged on their customer record by email. The next time they sign in on the site, the tag is already there.
+
+When a member buys while signed in, RedeemID opens the checkout signed in as them, so the order goes on the same customer record.
+
+After a purchase, **Refresh membership** on the member card reads their tags again straight away. That helps if Flow ran before the member got back to the site.
+
+## Check a recipe
+
+1. Under **Plugins → RedeemID → Webhooks**, make sure `customers/update` is registered. The Setup page does this 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.
+5. Refund the order. The tag and the level should both go.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@redeemid/emdash",
-	"version": "0.0.19",
+	"version": "0.0.20",
 	"description": "Shopify customer accounts, member levels and paywalls for EmDash sites. Shopify runs commerce; EmDash runs content.",
 	"type": "module",
 	"license": "MIT",
@@ -15,6 +15,7 @@
 		"./access": "./src/access.ts",
 		"./guard.ts": "./src/guard.ts",
 		"./rate-limit-cloudflare.ts": "./src/rate-limit-cloudflare.ts",
+		"./templates.ts": "./src/templates.ts",
 		"./storefront": "./src/storefront.ts",
 		"./catalog": "./src/catalog.ts",
 		"./features": "./src/features.ts",

package/src/access-admin.ts

@@ -19,11 +19,13 @@ import { applyEntryRule, describe, requirement, ruleSource, SIGNED_IN, termTree,
 import type { FeatureConfig, FileRule, LevelConfig, MeterConfig, RedeemIDConfig, RuleConfig } from "./config.js";
 import {
 	days,
+	deleteAccess,
 	entryKey,
 	list,
 	MANAGED,
 	mergeAccess,
 	overridden,
+	putAccess,
 	SITE_ID,
 	slugify,
 	validSlug,
@@ -435,7 +437,7 @@ async function saveSite(env: AccessEnv, change: (site: SiteAccess, now: RedeemID
 	const out = change(site, now);
 	if (typeof out === "string") return out;
 	out.updatedAt = new Date().toISOString();
-	await env.store.put(SITE_ID, out);
+	await putAccess(env.store, SITE_ID, out);
 	env.saved = { ...env.saved, site: out };
 	return null;
 }
@@ -741,14 +743,18 @@ export async function entrySave(env: AccessEnv, entry: PanelEntry, values: Recor
 	rule.lockedUntil = isoDay(values.locked_until);
 	rule.openUntil = isoDay(values.open_until);
 	const empty = mode === "inherit" && !rule.drip && rule.meter !== false && !rule.lockedUntil && !rule.openUntil;
-	if (empty) await env.store.delete(entryKey(entry.id));
-	else await env.store.put(entryKey(entry.id), rule);
+	if (empty) await deleteAccess(env.store, entryKey(entry.id));
+	else await putAccess(env.store, entryKey(entry.id), rule);
 	env.saved = { ...env.saved, entries: [...env.saved.entries.filter((e) => e.entryId !== entry.id), ...(empty ? [] : [rule])] };
 	return entryPanel(env, entry, { type: "success", message: empty ? "This entry follows the site rules." : "Access saved." });
 }
 
-/** Keep an entry's own rule in step with its slug, and drop it with the entry. */
-export async function entrySlugChanged(store: StorageCollection<AccessRecord>, collection: string, id: string, slug: string | null): Promise<void> {
+/**
+ * Keep an entry's own rule in step with its slug. A trashed entry passes a
+ * null slug: its rule stays (by id) for a restore, but gives up the slug, so
+ * a new entry that takes the slug doesn't inherit the rule.
+ */
+export async function entrySlugChanged(store: StorageCollection<AccessRecord>, collection: string | null, id: string, slug: string | null): Promise<void> {
 	const rule = (await store.get(entryKey(id))) as EntryRule | null;
-	if (rule?.kind === "entry" && rule.collection === collection && rule.slug !== slug) await store.put(entryKey(id), { ...rule, slug });
+	if (rule?.kind === "entry" && (collection === null || rule.collection === collection) && (rule.slug ?? null) !== slug) await putAccess(store, entryKey(id), { ...rule, slug });
 }

package/src/access.ts

@@ -11,9 +11,9 @@
  */
 
 import type { LevelConfig, RedeemIDConfig, RuleConfig } from "./config.js";
-import type { EntryRule } from "./settings.js";
+import { UNAVAILABLE, type EntryRule } from "./settings.js";
 import { siteConfig } from "./site-config.js";
-import { memberForUser, stores, type MemberRecord } from "./storage.js";
+import { memberForUser, stores, type MemberRecord, type MeterRecord } from "./storage.js";
 
 /** The parts of Astro's global that access checks read. */
 export interface AstroLike {
@@ -336,7 +336,7 @@ export function passes(held: string[], required: string[][]): boolean {
  */
 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 name = (slug: string) => (slug === UNAVAILABLE ? "Members" : (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(" + ") : signedIn;
 }
@@ -384,6 +384,8 @@ export async function entryRequirement(
 	id?: string | null,
 ): Promise<Requirement> {
 	if (!config) return null;
+	// Saved settings can't be read: nobody passes this.
+	if (config.unavailable) return [[UNAVAILABLE]];
 	const own = entryRuleFor(config, collection, id);
 	if (own && (own.mode === "open" || own.mode === "levels") && !own.openUntil && !own.lockedUntil) return applyEntryRule(null, own);
 	const tree = await termTree(config.rules, collection, terms);
@@ -445,7 +447,7 @@ export async function canRead(
 	const v = await viewer(astro);
 
 	if (required === null) return { allowed: true, reason: "open", required: [], viewer: v };
-	if (!config) return { allowed: false, reason: "unconfigured", required, viewer: v };
+	if (!config || config.unavailable) return { allowed: false, reason: "unconfigured", required, viewer: v };
 	if (!v.signedIn) return { allowed: false, reason: "sign_in", required, viewer: v };
 	if (v.member?.status === "disabled") return { allowed: false, reason: "disabled", required, viewer: v };
 	if (!v.member) return { allowed: false, reason: "upgrade", required, viewer: v };
@@ -529,12 +531,31 @@ export async function readEntry(
 	const key = `${user.id}:${periodKey(new Date(), period)}`;
 	try {
 		const s = stores(db);
-		const record = (await s.meter.get(key)) ?? { userId: user.id, period: periodKey(new Date(), period), items: [] };
-		const used = consume(record.items, `${entry.collection}:${entry.id}`, meter.limit);
 		const info = { limit: meter.limit, period };
-		if (!used.allowed) return { ...verdict, meterLeft: 0, meter: info };
-		if (used.items !== record.items) {
-			await s.meter.put(key, { ...record, items: used.items });
+		// Read, count and write with compare-and-set, so parallel requests
+		// can't each take the last free entry.
+		let record: MeterRecord | null = null;
+		let used: ReturnType<typeof consume> | null = null;
+		let wrote = false;
+		for (let attempt = 0; attempt < 3 && !used; attempt++) {
+			const current = await s.meter.getVersioned(key);
+			const r = current?.value ?? { userId: user.id, period: periodKey(new Date(), period), items: [] };
+			const next = consume(r.items, `${entry.collection}:${entry.id}`, meter.limit);
+			if (!next.allowed || next.items === r.items) {
+				record = r;
+				used = next;
+				break;
+			}
+			const write = await s.meter.compareAndSet(key, current?.revision ?? null, { ...r, items: next.items });
+			if (write.applied) {
+				record = r;
+				used = next;
+				wrote = true;
+			}
+		}
+		// Lost every race: count it as used up rather than open one too many.
+		if (!used || !record || !used.allowed) return { ...verdict, meterLeft: 0, meter: info };
+		if (wrote) {
 			const { emit } = await import("./events.js");
 			const data = { userId: user.id, entry: `${entry.collection}:${entry.id}`, used: used.items.length, limit: meter.limit, period: record.period };
 			const { record: log } = await import("./log.js");

package/src/admin-api.ts

@@ -11,7 +11,7 @@
 
 import { env, ENV, shopOrigin, type RedeemIDConfig } from "./config.js";
 import { USER_AGENT } from "./shopify.js";
-import { cleanTags, emptyMember, stampTags, type MemberRecord, type Stores } from "./storage.js";
+import { cleanTags, emptyMember, metaDate, stampTags, type MemberRecord, type MembershipDates, type Stores } from "./storage.js";
 import { timed } from "./log.js";
 
 export const ADMIN_API_VERSION = "2026-10";
@@ -100,15 +100,32 @@ export interface AdminCustomer {
 	lastName: string | null;
 	tags: string[];
 	updatedAt: number | null;
+	emailMarketing: string | null;
+	dates: MembershipDates;
 }
 
+/** The membership.* customer metafields read with each customer (see MemberRecord.dates). */
+const DATE_FIELDS = `since: metafield(namespace: "membership", key: "member_since") { value } renews: metafield(namespace: "membership", key: "renews_on") { value } ends: metafield(namespace: "membership", key: "ends_on") { value } gift: metafield(namespace: "membership", key: "gift_until") { value }`;
+
 /** Up to 100 customers by numeric id. Customers Shopify no longer has are left out. */
 export async function customers(config: RedeemIDConfig, ids: string[], fetcher: typeof fetch = fetch): Promise<AdminCustomer[]> {
 	if (ids.length === 0) return [];
-	type Node = { id: string; firstName: string | null; lastName: string | null; tags: string[]; updatedAt: string; defaultEmailAddress: { emailAddress: string | null } | null } | null;
+	type Meta = { value: string | null } | null;
+	type Node = {
+		id: string;
+		firstName: string | null;
+		lastName: string | null;
+		tags: string[];
+		updatedAt: string;
+		defaultEmailAddress: { emailAddress: string | null; marketingState?: string | null } | null;
+		since?: Meta;
+		renews?: Meta;
+		ends?: Meta;
+		gift?: Meta;
+	} | null;
 	const data = await admin<{ nodes: Node[] }>(
 		config,
-		`query RedeemIDCustomers($ids: [ID!]!) { nodes(ids: $ids) { ... on Customer { id firstName lastName tags updatedAt defaultEmailAddress { emailAddress } } } }`,
+		`query RedeemIDCustomers($ids: [ID!]!) { nodes(ids: $ids) { ... on Customer { id firstName lastName tags updatedAt defaultEmailAddress { emailAddress marketingState } ${DATE_FIELDS} } } }`,
 		{ ids: ids.slice(0, 100).map(gid) },
 		fetcher,
 	);
@@ -121,11 +138,14 @@ export async function customers(config: RedeemIDConfig, ids: string[], fetcher:
 			lastName: n.lastName || null,
 			tags: cleanTags(n.tags),
 			updatedAt: Number.isFinite(Date.parse(n.updatedAt)) ? Date.parse(n.updatedAt) : null,
+			emailMarketing: n.defaultEmailAddress?.marketingState ?? null,
+			dates: { since: metaDate(n.since?.value), renews: metaDate(n.renews?.value), ends: metaDate(n.ends?.value), gift: metaDate(n.gift?.value) },
 		}));
 }
 
 /**
- * Read members from Shopify again and update the mirror: profile and tags.
+ * Read members from Shopify again and update the mirror: profile, tags,
+ * email marketing state and the membership dates.
  * Status stays with the enable/disable webhooks. Members Shopify no longer
  * has are reported in `missing` and left alone.
  */
@@ -142,6 +162,8 @@ export async function resync(config: RedeemIDConfig, s: Stores, ids: string[], s
 		m.lastName = c.lastName ?? m.lastName;
 		m.tags = c.tags;
 		m.profileUpdatedAt = c.updatedAt ?? m.profileUpdatedAt;
+		m.emailMarketing = c.emailMarketing ?? m.emailMarketing ?? null;
+		m.dates = c.dates;
 		m.syncedAt = new Date().toISOString();
 		m.source = source;
 		await s.members.put(c.customerId, stampTags(m));

package/src/cart-ops.ts

@@ -11,6 +11,7 @@
 import { readCart, saveCart } from "./cart.js";
 import type { RedeemIDConfig } from "./config.js";
 import { memberForUser, stores } from "./storage.js";
+import { sessionUser } from "./routes/shared.js";
 import { addToCart, cartDetails, product, realOptions, removeLines, setDiscountCodes, storeContext, updateLines, variantFor, type Cart, type CartDetails, type Product, type Variant } from "./storefront.js";
 
 export const MAX_QUANTITY = 1000;
@@ -100,8 +101,8 @@ export async function editCart(input: CartInput, ctx: CartContext): Promise<Cart
 		const variant = p ? pickVariant(p, input) : undefined;
 		const plan = p ? pickSellingPlan(p, input.sellingPlan) : undefined;
 		if (!p || !variant?.availableForSale || plan === undefined) return { notice: "plan_unavailable", cart: null };
-		const user = (await session?.get("user")) as { id?: string } | undefined;
-		const member = user?.id && ctx.db ? await memberForUser(stores(ctx.db), user.id) : null;
+		const user = await sessionUser(session, ctx.db);
+		const member = user && ctx.db ? await memberForUser(stores(ctx.db), user.id) : null;
 		const current = await readCart(session);
 		const cart = await addToCart(
 			config,

package/src/checkout.ts

@@ -4,7 +4,7 @@
  * A signed-in member's cart gets their Customer Account API access token
  * (cartBuyerIdentityUpdate), so checkout opens signed in and the order lands
  * on their Shopify customer, where the shop's Flow or apps tag it. The token
- * lives only in the server-side session and is renewed with its refresh
+ * lives only in the server-side session, sealed (token-vault.ts), and is renewed with its refresh
  * token when it's about to expire. Anything that fails falls back to a guest
  * checkout: buying never breaks because sign-in couldn't be carried over.
  */
@@ -13,6 +13,7 @@ import { env, ENV, type RedeemIDConfig } from "./config.js";
 import { SESSION_CUSTOMER_TOKEN, callbackUrl, type CustomerToken } from "./routes/shared.js";
 import { discover, refreshTokens } from "./shopify.js";
 import { signInCart } from "./storefront.js";
+import { seal, unseal } from "./token-vault.js";
 
 type Session = { get(key: string): unknown; set(key: string, value: unknown): void; delete?(key: string): void } | undefined;
 
@@ -23,9 +24,9 @@ const RENEW_MS = 2 * 60 * 1000;
 export async function customerToken(
 	config: RedeemIDConfig,
 	session: Session,
-	opts: { url: URL; emdashConfig?: unknown; fetcher?: typeof fetch; now?: number },
+	opts: { url: URL; emdashConfig?: unknown; fetcher?: typeof fetch; now?: number; db?: unknown },
 ): Promise<string | null> {
-	const t = (await session?.get(SESSION_CUSTOMER_TOKEN)) as CustomerToken | undefined;
+	const t = await unseal(await session?.get(SESSION_CUSTOMER_TOKEN), opts.db);
 	if (!t?.accessToken) return null;
 	const now = opts.now ?? Date.now();
 	if (!t.expiresAt || t.expiresAt - now > RENEW_MS) return t.accessToken;
@@ -45,7 +46,7 @@ export async function customerToken(
 			{ clientId, clientSecret: env(ENV.clientSecret), origin: new URL(redirect).origin, refreshToken: t.refreshToken },
 			opts.fetcher,
 		);
-		session?.set(SESSION_CUSTOMER_TOKEN, next satisfies CustomerToken);
+		session?.set(SESSION_CUSTOMER_TOKEN, await seal(next satisfies CustomerToken, opts.db));
 		return next.accessToken;
 	} catch {
 		forget();

package/src/components/LockedPanel.astro

@@ -8,7 +8,7 @@
  * and `joinUrl` come from the level's config, the join link from `join`.
  * Anything in the default slot is shown above the built-in text.
  */
-import { passes, signInUrl, type Reason } from "../access.js";
+import { membership, passes, refreshUrl, signInUrl, viewer, type Reason } from "../access.js";
 import type { SoldItem } from "../blocks-names.js";
 import { plan as loadPlan } from "../storefront.js";
 import { siteConfig } from "../site-config.js";
@@ -39,6 +39,9 @@ const config = await siteConfig(Astro.locals);
 const missing = required.find((clause) => clause.length > 0 && !passes(held, [clause]));
 const level = missing ? config?.levels?.find((l) => l.slug === missing[0]) : undefined;
 const joinHref = level?.joinUrl ?? config?.join?.href;
+// A member who held the level before is offered it back ("Renew"), not "Join" as if new.
+const member = reason === "upgrade" && level ? (await viewer(Astro)).member : null;
+const lapsed = Boolean(member && member.status !== "disabled" && membership(member, config?.levels).past.some((p) => p.slug === level?.slug));
 const joinLabel = config?.join?.label ?? text(config, "Become a member");
 const week = meterPeriod === "week";
 // "Buy just this": the item's product and price, read from Shopify.
@@ -73,7 +76,14 @@ const here = Astro.url.pathname + Astro.url.search;
 			{opens ? textParts(config, "This opens for you on {date}.", { date: <time datetime={opensAt?.toISOString()}>{opens}</time> }) : text(config, "This opens for you after you've been a member a little longer.")}
 		</p>
 	)}
-	{reason === "upgrade" && (
+	{reason === "upgrade" && lapsed && level && (
+		<p class="redeemid-locked__renew">
+			{text(config, "Your {level} membership has ended.", { level: level.name })}
+			{joinHref && <> <a href={joinHref}>{text(config, "Renew {level}", { level: level.name })}</a></>}
+			{" "}{textParts(config, "Already renewed? {refresh}", { refresh: <a href={refreshUrl(here)}>{text(config, "Refresh")}</a> })}
+		</p>
+	)}
+	{reason === "upgrade" && !lapsed && (
 		<p>
 			{level ? text(config, "This is for {level} members.", { level: level.name }) : text(config, "Your membership doesn't include this yet.")}
 			{joinHref && <> <a href={joinHref}>{joinLabel}</a></>}