@redeemid/emdash 0.0.17 → 0.0.19

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.17, 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.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.
 
 ## Contents
 
@@ -41,7 +41,7 @@ Selling a membership is ordinary Shopify: a product, a checkout, and a Flow work
 - Download or delete what the site keeps about them.
 
 **For editors**
-- Paywall break, Members only, Sold on its own, Plan, Product, Collection, Contribution and Preferences blocks in the EmDash editor.
+- Paywall break, Members only, Sold on its own, Plan, Product, Collection, Product search, Contribution and Preferences blocks in the EmDash editor.
 - An Access panel on every entry: follow the site rules, free to everyone, only some levels, or the site rules plus a level, with drip, meter and date windows.
 - Rules by content type, term (with child terms) or site default, plus terms that open entries to everyone.
 - Teasers, a monthly or weekly meter, drip by days of membership, and badges that show what an entry needs.
@@ -58,8 +58,9 @@ Selling a membership is ordinary Shopify: a product, a checkout, and a Flow work
 
 **For developers**
 - Astro components for every piece, plus `canRead()`, `readEntry()` and `hasFeature()` for your own code.
-- Product pages, collection grids, a cart page and pay-what-you-want from the Storefront API.
-- Signed outbound events for a CRM or email tool, MCP tools for AI agents, and a `redeemid-emdash` command.
+- A storefront from the Storefront API: product pages with options, subscriptions and galleries, collection grids with Shopify's filters, sorting and pages, product search, recommendations, a cart page and a cart drawer, pay-what-you-want, local prices, and a checkout that opens signed in for members.
+- A browser client, `window.redeemid`, with `subscribe()` events for any analytics or CRM tool, cart methods and search, plus JSON routes for state, the cart and the catalog. See [docs/developer-api.md](docs/developer-api.md).
+- Signed outbound events for a CRM or email tool, MCP tools for AI agents (members, access and the catalog), and a `redeemid-emdash` command.
 - Replacement text for every string readers see, Google's paywalled-content markup, cache safety and optional rate limits.
 
 ## Requirements
@@ -297,26 +298,42 @@ import { hasFeature } from "@redeemid/emdash/features";
 
 ### Shop
 
-Products, collections and the cart come from the Storefront API. Shopify works out prices, discounts, taxes and stock.
+Products, collections, search and the cart come from the Storefront API. Shopify works out prices, discounts, taxes and stock, and runs checkout. EmDash has no Shopify plugin underneath, so these components are the storefront.
 
 ```astro
-<!-- /shop/ -->
-<Collection handle="shop" productHref="/shop/{handle}/" showTitle />
+<!-- layout, once -->
+<Cart drawer />
+<CartDrawer />
+<RedeemIDClient />
+<!-- /shop/ (rendered on demand for filters and pages) -->
+<Collection handle="shop" productHref="/shop/{handle}/" showTitle browse quickAdd />
 <!-- /shop/[handle]/ -->
 <Product handle={Astro.params.handle} heading="h1"><p>No such product.</p></Product>
+<Recommendations handle={Astro.params.handle} productHref="/shop/{handle}/" />
+<!-- /search/ -->
+<ProductSearch productHref="/shop/{handle}/" />
 <!-- /cart/ -->
 <CartView productHref="/shop/{handle}/" />
 <!-- anywhere -->
 <Contribution handle="support" amounts={[5, 10, 25]} />
 ```
 
-- `<Product>`: image, title, price, description, variants (sold-out ones shown but not choosable), quantity, Add to cart and Buy now.
-- `<Collection>`: up to 50 products as cards linking to `productHref`.
+- `<Product>`: images (with thumbnails), title, price and sale price, description (`html` for Shopify's formatted one), a picker per option (Size, Color…), one-time or subscription when the product has selling plans, quantity, Add to cart and Buy now. On a product's own page (`heading="h1"`) it prints Product structured data.
+- `<Collection>`: up to 50 products as cards linking to `productHref`. `browse` adds Shopify's filters (set up in the Search & Discovery app), sort orders and pages, read from the page URL. `quickAdd` adds Add to cart on cards that need no choice.
+- `<ProductSearch>`: a search box with Shopify's matches, filters, sorting and pages. `boxOnly` gives just the box, for a header, sending searches to `action`.
+- `<Recommendations>`: Shopify's "You may also like" (`intent="related"`) or "Pair it with" (`intent="complementary"`) for a product.
 - `<CartView>`: each line with a quantity to change (0 removes it) and Remove, a discount code field, the totals and Checkout.
+- `<CartDrawer>`: the same cart in a modal dialog that slides in. With `<RedeemIDClient />` on the page, Add to cart opens it in place and `<Cart drawer />` opens it instead of going to checkout.
 - `<Contribution>`: pay what you want. Price a product at 1.00, and the amount the reader picks becomes the quantity.
-- `<Cart>`: the item count, linking to checkout.
+- `<Cart>`: the item count, linking to checkout, or to `href` (a cart page), or opening the drawer with `drawer`.
 
-The forms post to `/_emdash/api/auth/redeemid/cart-edit`, which reads every product and variant from Shopify again and only changes the visitor's own cart. 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 and Contribution blocks.
+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.
+
+**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.
+
+**Shoppers' agents.** Shopify runs a Storefront MCP server for every store at `https://<store domain>/api/mcp`, for AI agents that browse, build a cart and check out. Point shopping agents there; RedeemID's own tools are for staff.
 
 ### Preferences
 
@@ -413,6 +430,9 @@ Staff questions as data, for AI agents and scripts. Every one needs an administr
 | `get_member` | `member <id or email>` | One member: status, tags, levels with start dates, past levels, features, last sync |
 | `site_health` | `health` | Each setting (set or not, never a value), the last webhook, open privacy requests, ignored text replacements |
 | `level_changes` | `changes --since <date>` | Who joined or left a level since a date |
+| `find_products` | `products <words>` | Search the Shopify catalog: handles, titles, prices, stock |
+| `get_product` | `product <handle>` | One product: options, variants, prices, selling plans |
+| `get_collection` | `collection <handle>` | One collection: its products and the filters Shopify offers |
 
 With `agents: { actions: true }`, three actions are offered too: `resync_member` (`resync <customer id>`), `resync_batch` (`resync-batch`, 25 members) and `edit_member_tags` (`tags <customer id> --add a,b --remove c`, marked destructive for agents).
 
@@ -498,6 +518,8 @@ Pass one object to both `redeemid(config)` and `redeemidPlugin(config)`. `levels
 | `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. |
@@ -537,10 +559,15 @@ Import each from `@redeemid/emdash/components/<Name>.astro`.
 | `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 |
-| `Product` | `handle`, `heading`, `compact`, `addLabel`, `buyLabel` | A product page |
-| `Collection` | `handle`, `limit`, `productHref`, `showTitle` | A grid of products |
-| `Cart` | `label` | The cart count, linking to checkout |
+| `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 |
+| `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
@@ -554,7 +581,8 @@ Import each from `@redeemid/emdash/components/<Name>.astro`.
 | 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 |
+| 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 |
 
@@ -563,16 +591,20 @@ Import each from `@redeemid/emdash/components/<Name>.astro`.
 | Import | Gives |
 | --- | --- |
 | `@redeemid/emdash` | `redeemid()`, `redeemidPlugin()`, `redeemidGuard()`, config types |
-| `@redeemid/emdash/access` | `canRead()`, `readEntry()`, `entryRequirement()`, and links: `signInUrl()`, `signOutUrl()`, `accountUrl()`, `cartUrl()`, `refreshUrl()` |
+| `@redeemid/emdash/access` | `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 the shop components use |
+| `@redeemid/emdash/storefront` | `product()`, `collection()`, `plan()`, `money()` and the cart calls |
+| `@redeemid/emdash/catalog` | `searchProducts()`, `collectionPage()`, `suggest()`, `recommendations()` |
 | `@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/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](docs/developer-api.md).
 
 ### Routes
 
-Under `/_emdash/api/auth/redeemid/`: `login`, `callback`, `logout`, `webhook`, `buy`, `cart`, `cart-edit`, `account`, `preferences` and `privacy`. Staff-only routes for the admin, agents and the command line are under `/_emdash/api/plugins/redeemid/`.
+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`.
 

package/bin/redeemid-emdash.mjs

@@ -27,6 +27,9 @@ Commands:
   member <id or email>    One synced member
   health                  What's set up (never the values)
   changes --since <date>  Who joined or left a level [--level <slug>]
+  products <words>        Search the Shopify catalog for handles and prices
+  product <handle>        One product: options, variants, selling plans
+  collection <handle>     One collection: its products and filters
   resync <customer id>    Read one member from Shopify again *
   resync-batch            Read the 25 members synced longest ago *
   tags <customer id>      Edit tags in Shopify: --add a,b --remove c *
@@ -82,6 +85,15 @@ function request() {
 		case "changes":
 			if (!o.since) throw new Error("changes needs --since <date>");
 			return ["level-changes", { since: o.since, level: o.level }];
+		case "products":
+			if (!arg) throw new Error("products needs search words");
+			return ["find-products", { query: positionals.slice(1).join(" ") }];
+		case "product":
+			if (!arg) throw new Error("product needs a handle");
+			return ["get-product", { handle: arg }];
+		case "collection":
+			if (!arg) throw new Error("collection needs a handle");
+			return ["get-collection", { handle: arg }];
 		case "resync":
 			if (!arg) throw new Error("resync needs a customer id");
 			return ["resync-member", { customerId: arg }];
@@ -131,7 +143,7 @@ async function main() {
 	} catch {
 		throw new Error(`${res.status} from the site: ${text.slice(0, 200)}`);
 	}
-	if (res.status === 404) throw new Error(`The site has no "${route}" route. Actions need agents: { actions: true }, and every command needs @redeemid/emdash 0.0.11 or later.`);
+	if (res.status === 404) throw new Error(`The site has no "${route}" route. Actions need agents: { actions: true }, and every command needs @redeemid/emdash 0.0.11 or later (products, product and collection need 0.0.18).`);
 	if (!res.ok) throw new Error(json?.error?.message ?? `${res.status} from the site`);
 	const out = json?.data ?? json;
 	if (out && out.ok === false) throw new Error(out.error);

package/docs/developer-api.md

@@ -0,0 +1,126 @@
+# 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`).
+
+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.
+
+Three rules hold everywhere:
+
+- **Shopify decides.** Levels and features come only from the member's Shopify tags; prices, stock, discounts and checkout come only from Shopify. Nothing here grants access or sets a price.
+- **Nothing personal leaves the server.** Browser-facing answers and events never carry an email, a name, a customer id or a Shopify tag. Match people by `customerId` only in signed server events.
+- **Vendor-agnostic.** RedeemID never sends anything to an analytics tool, CRM or tag manager. You subscribe and forward what you choose.
+
+## Server modules
+
+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/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/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:
+
+```astro
+---
+import { canRead, viewer } from "@redeemid/emdash/access";
+import { hasFeature } from "@redeemid/emdash/features";
+import { searchProducts } from "@redeemid/emdash/catalog";
+
+const verdict = await canRead(Astro, { collection: "posts", terms: post.data.terms, id: post.id });
+const adFree = await hasFeature(Astro, "ad-free");
+---
+```
+
+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
+
+Under `/_emdash/api/auth/redeemid/`. Same-origin only: EmDash checks `Origin` on every POST, and the browser client also sends `X-EmDash-Request: 1`. Member answers are `Cache-Control: private, no-store`.
+
+- `api/state` (GET): the visitor's own state.
+
+  ```json
+  { "apiVersion": "1.0.0", "version": "0.0.19", "signedIn": true, "linked": true,
+    "levels": ["gold"], "features": ["ad-free"], "cart": { "count": 2 },
+    "meter": { "used": 1, "limit": 3, "period": "month" } }
+  ```
+
+- `api/cart` (GET, POST): the Shopify cart. GET answers `{ cart }` (null without one). POST takes `{ action, ... }`:
+  - `add`: `product` (handle), then `variant` (an id of that product's) or `options` (`{ "Size": "M" }`), optional `sellingPlan` (one of the product's, or `""` for one-time), `quantity` (1 to 1000);
+  - `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.
+- `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).
+- `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`.
+
+## Browser client
+
+Add `<RedeemIDClient />` once to the site layout (from `@redeemid/emdash/components/RedeemIDClient.astro`). It defines `window.redeemid` and sends nothing anywhere by itself.
+
+```js
+const stop = window.redeemid.subscribe((name, props, event) => {
+  // event: { name, version, time, props }, props are scalars only
+});
+```
+
+A subscriber also gets the events that fired before it subscribed (`{ replay: false }` skips them), so it can wait for consent. Each event is also dispatched on `document` as a `CustomEvent` named `redeemid:<name>`.
+
+| Member | What it does |
+| --- | --- |
+| `version`, `apiVersion` | Package and API versions |
+| `events` | The event names below |
+| `subscribe(fn, { replay })` | Listen; returns an unsubscribe function |
+| `emit(name, props)` | Send your own event; names must start `site_` |
+| `state()`, `refresh()` | The visitor's `api/state`, read once (or again) |
+| `signIn(returnTo?)`, `signOut(returnTo?)` | Go to sign-in; sign out (a POST) |
+| `cart` | `get()`, `add({ product, variant?, options?, sellingPlan?, quantity? })`, `update(line, quantity)`, `remove(line)`, `discount(code)`, `checkout()` |
+| `openCart()`, `closeCart()` | The cart drawer, when `<CartDrawer />` is on the page |
+| `search(q, { first, after, sort })`, `suggest(q, limit)`, `collection(handle, { first, after, sort })` | The `api/search` answers |
+
+Events:
+
+| Event | Props |
+| --- | --- |
+| `ready` | `api_version` |
+| `state` | `signedIn`, `linked`, `levels` and `features` (comma-separated slugs), `cartCount` |
+| `wall_shown` | `entry`, `level`, `reason` |
+| `metered_view` | `left` |
+| `sign_in_click` | `source` (`page`, `wall`, `drawer`) |
+| `checkout_click` | `source`, `product` |
+| `cart_changed` | `action`, `notice`, `count`, `product`, `quantity`, `subscription` |
+| `cart_opened` | `source` (`link`, `add`, `api`) |
+| `search` | `query_length` (never the words) |
+
+The client also enhances RedeemID's markup: with `<CartDrawer />` on the page, Add to cart updates the cart in place and opens the drawer, and `<Cart drawer />` opens it. Product option pickers keep the price, sale price, image and stock in step, and `<ProductSearch>` suggests as you type. Without JavaScript every form still works.
+
+## 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)`.
+
+## 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:
+
+- `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`).
+
+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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@redeemid/emdash",
-	"version": "0.0.17",
+	"version": "0.0.19",
 	"description": "Shopify customer accounts, member levels and paywalls for EmDash sites. Shopify runs commerce; EmDash runs content.",
 	"type": "module",
 	"license": "MIT",
@@ -16,10 +16,12 @@
 		"./guard.ts": "./src/guard.ts",
 		"./rate-limit-cloudflare.ts": "./src/rate-limit-cloudflare.ts",
 		"./storefront": "./src/storefront.ts",
+		"./catalog": "./src/catalog.ts",
 		"./features": "./src/features.ts",
 		"./events": "./src/events.ts",
 		"./preferences": "./src/preferences.ts",
 		"./text": "./src/text.ts",
+		"./contract": "./src/contract.ts",
 		"./plugin": "./src/plugin.ts",
 		"./blocks": "./src/blocks/index.ts",
 		"./components/*": "./src/components/*",

package/src/agents.ts

@@ -182,3 +182,58 @@ export async function levelChanges(config: RedeemIDConfig, s: Stores, input: { s
 	} while (cursor);
 	return out.sort((a, b) => String(a.at).localeCompare(String(b.at)));
 }
+
+// ---------------------------------------------------------------- catalog
+
+/**
+ * Catalog lookups for agents and editors: product and collection handles,
+ * prices and options, read from the Storefront API (public data). Use the
+ * handles in Product, Collection and Plan blocks.
+ */
+export async function findProducts(config: RedeemIDConfig, input: { query: string; first?: number }): Promise<Record<string, unknown>> {
+	const { searchProducts } = await import("./catalog.js");
+	const q = String(input.query ?? "").trim();
+	if (!q) throw new AgentError("query is required");
+	const page = await searchProducts(config, q, { first: Math.max(1, Math.min(25, input.first ?? 10)) });
+	return {
+		total: page.total ?? page.products.length,
+		products: page.products.map((p) => ({ handle: p.handle, title: p.title, availableForSale: p.availableForSale, price: p.price, compareAtPrice: p.compareAtPrice ?? null })),
+	};
+}
+
+export async function getProduct(config: RedeemIDConfig, input: { handle: string }): Promise<Record<string, unknown>> {
+	const { product, realOptions } = await import("./storefront.js");
+	const handle = String(input.handle ?? "").trim();
+	if (!/^[a-z0-9][a-z0-9-]*$/i.test(handle)) throw new AgentError("handle must be a Shopify product handle");
+	const p = await product(config, handle);
+	if (!p) throw new AgentError(`Shopify has no product "${handle}" on this storefront`);
+	return {
+		handle: p.handle,
+		title: p.title,
+		vendor: p.vendor ?? null,
+		productType: p.productType ?? null,
+		description: p.description,
+		availableForSale: p.availableForSale,
+		options: realOptions(p),
+		variants: p.variants.map((v) => ({ id: v.id, title: v.title, availableForSale: v.availableForSale, price: v.price, compareAtPrice: v.compareAtPrice ?? null, sku: v.sku ?? null, options: v.selectedOptions ?? [] })),
+		requiresSellingPlan: Boolean(p.requiresSellingPlan),
+		sellingPlans: p.sellingPlans ?? [],
+		images: (p.images ?? []).length,
+	};
+}
+
+export async function getCollection(config: RedeemIDConfig, input: { handle: string; first?: number }): Promise<Record<string, unknown>> {
+	const { collectionPage } = await import("./catalog.js");
+	const handle = String(input.handle ?? "").trim();
+	if (!/^[a-z0-9][a-z0-9-]*$/i.test(handle)) throw new AgentError("handle must be a Shopify collection handle");
+	const c = await collectionPage(config, handle, { first: Math.max(1, Math.min(50, input.first ?? 25)) });
+	if (!c) throw new AgentError(`Shopify has no collection "${handle}" on this storefront`);
+	return {
+		handle: c.handle,
+		title: c.title,
+		description: c.description,
+		filters: c.filters.map((f) => ({ label: f.label, type: f.type, values: f.values.map((v) => v.label) })),
+		products: c.products.map((p) => ({ handle: p.handle, title: p.title, availableForSale: p.availableForSale, price: p.price })),
+		more: c.pageInfo.hasNextPage,
+	};
+}

package/src/api-version.ts

@@ -0,0 +1,6 @@
+/**
+ * The developer API's version (docs/developer-api.md): the minor part bumps
+ * 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";

package/src/blocks/CollectionBlock.astro

@@ -3,13 +3,14 @@
 import Collection from "../components/Collection.astro";
 
 interface Props {
-	node: { handle?: string; limit?: string; link?: string };
+	node: { handle?: string; limit?: string; link?: string; extras?: string[] };
 }
 
 const { node } = Astro.props;
 const handle = (node.handle ?? "").trim();
 const limit = Number.parseInt(node.limit ?? "", 10);
 const link = (node.link ?? "").trim();
+const extras = Array.isArray(node.extras) ? node.extras : [];
 ---
 
 {handle && (
@@ -18,5 +19,7 @@ const link = (node.link ?? "").trim();
 		limit={Number.isFinite(limit) ? limit : 12}
 		productHref={link.startsWith("/") && link.includes("{handle}") ? link : undefined}
 		showTitle
+		browse={extras.includes("browse")}
+		quickAdd={extras.includes("quick-add")}
 	/>
 )}

package/src/blocks/SearchBlock.astro

@@ -0,0 +1,14 @@
+---
+/** The "Product search" block: a search box with Shopify's results, filters, sorting and paging. */
+import ProductSearch from "../components/ProductSearch.astro";
+
+interface Props {
+	node: { link?: string; label?: string };
+}
+
+const { node } = Astro.props;
+const link = (node.link ?? "").trim();
+const label = (node.label ?? "").trim();
+---
+
+<ProductSearch productHref={link.startsWith("/") && link.includes("{handle}") ? link : undefined} label={label || undefined} />

package/src/blocks/index.ts

@@ -8,6 +8,7 @@ import ContributionBlock from "./ContributionBlock.astro";
 import PlanBlock from "./PlanBlock.astro";
 import PreferencesBlock from "./PreferencesBlock.astro";
 import ProductBlock from "./ProductBlock.astro";
+import SearchBlock from "./SearchBlock.astro";
 
 export const blockComponents = {
 	"redeemid-paywall": Marker,
@@ -17,6 +18,7 @@ export const blockComponents = {
 	"redeemid-plan": PlanBlock,
 	"redeemid-product": ProductBlock,
 	"redeemid-collection": CollectionBlock,
+	"redeemid-search": SearchBlock,
 	"redeemid-contribution": ContributionBlock,
 	"redeemid-preferences": PreferencesBlock,
 };

package/src/blocks-names.ts

@@ -3,6 +3,7 @@ export const PAYWALL_BLOCK = "redeemid-paywall";
 export const PLAN_BLOCK = "redeemid-plan";
 export const PRODUCT_BLOCK = "redeemid-product";
 export const COLLECTION_BLOCK = "redeemid-collection";
+export const SEARCH_BLOCK = "redeemid-search";
 export const CONTRIBUTION_BLOCK = "redeemid-contribution";
 export const PREFERENCES_BLOCK = "redeemid-preferences";
 /** Starts a members-only part of the body; it runs to the next end block. */

package/src/cart-ops.ts

@@ -0,0 +1,164 @@
+/**
+ * Cart changes, shared by the form route (cart-edit, which redirects back
+ * with a notice) and the JSON route (api/cart, for the browser client and
+ * the cart drawer).
+ *
+ * Prices, discounts and availability come from Shopify; nothing posted is
+ * trusted beyond the ids it names, and each is checked against what Shopify
+ * says the product or cart holds.
+ */
+
+import { readCart, saveCart } from "./cart.js";
+import type { RedeemIDConfig } from "./config.js";
+import { memberForUser, stores } from "./storage.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;
+
+export type CartNotice =
+	| "cart_added"
+	| "cart_updated"
+	| "discount_applied"
+	| "discount_not_applicable"
+	| "plan_unavailable"
+	| "cart_empty"
+	| "checkout_failed";
+
+export interface CartInput {
+	action: string;
+	/** add: product handle. */
+	product?: string;
+	/** add: a variant id of that product. */
+	variant?: string;
+	/** add: chosen option values by option name, when no variant is given. */
+	options?: Record<string, string>;
+	/** add: a selling plan id of that product, or "" for one-time. */
+	sellingPlan?: string | null;
+	quantity?: number | string;
+	/** update / remove: the cart line id. */
+	line?: string;
+	/** discount: the code ("" clears). */
+	code?: string;
+	/** add: the page the buyer was on, kept as a hidden cart attribute. */
+	page?: string;
+}
+
+export interface CartContext {
+	config: RedeemIDConfig;
+	session: { get(key: string): unknown; set(key: string, value: unknown): void; delete?(key: string): void } | undefined;
+	request: Request;
+	db?: unknown;
+}
+
+export interface CartOutcome {
+	notice: CartNotice;
+	/** The cart after the change, when it could be read. */
+	cart: CartDetails | null;
+	/** The cart's id, checkout URL and count after an add (lines aren't read back). */
+	base?: Cart;
+	/** add: the line's variant, for analytics. */
+	added?: { product: string; variant: string; quantity: number; sellingPlan: boolean };
+}
+
+const HANDLE = /^[a-z0-9][a-z0-9-]*$/i;
+
+/** Pick the variant an add names: by id, by option values, or the first one for sale. */
+export function pickVariant(p: Product, input: Pick<CartInput, "variant" | "options">): Variant | undefined {
+	if (input.variant) return p.variants.find((v) => v.id === input.variant);
+	const opts = realOptions(p);
+	if (opts.length && input.options && Object.keys(input.options).length) {
+		const chosen: Record<string, string> = {};
+		for (const o of opts) {
+			const v = input.options[o.name];
+			if (typeof v === "string" && o.values.includes(v)) chosen[o.name] = v;
+		}
+		if (Object.keys(chosen).length !== opts.length) return undefined;
+		return variantFor(p, chosen);
+	}
+	return p.variants.find((v) => v.availableForSale);
+}
+
+/** The selling plan an add uses: one the product offers, the first one when it can only be bought on a plan, or none. */
+export function pickSellingPlan(p: Product, wanted: string | null | undefined): string | null | undefined {
+	const plans = p.sellingPlans ?? [];
+	if (wanted) return plans.some((sp) => sp.id === wanted) ? wanted : undefined;
+	if (p.requiresSellingPlan) return plans[0]?.id ?? p.sellingPlanId ?? undefined;
+	return null;
+}
+
+export async function editCart(input: CartInput, ctx: CartContext): Promise<CartOutcome> {
+	const { config, session, request } = ctx;
+	const buyerIp = request.headers.get("cf-connecting-ip");
+	const context = storeContext(config, request);
+	const save = (c: { id: string; totalQuantity: number }) => saveCart(session, { id: c.id, count: c.totalQuantity });
+
+	if (input.action === "add") {
+		const handle = String(input.product ?? "").trim();
+		const quantity = Number.parseInt(String(input.quantity ?? "1"), 10);
+		if (!HANDLE.test(handle) || !Number.isFinite(quantity) || quantity < 1 || quantity > MAX_QUANTITY) return { notice: "plan_unavailable", cart: null };
+		const p = await product(config, handle, undefined, context);
+		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 current = await readCart(session);
+		const cart = await addToCart(
+			config,
+			current?.id ?? null,
+			{ variantId: variant.id, sellingPlanId: plan, quantity },
+			{ email: member?.email ?? null, attributes: input.page ? { _redeemid_page: input.page } : {}, buyerIp, context },
+		);
+		save(cart);
+		return { notice: "cart_added", cart: null, base: cart, added: { product: p.handle, variant: variant.id, quantity, sellingPlan: Boolean(plan) } };
+	}
+
+	const ref = await readCart(session);
+	if (!ref) return { notice: "cart_empty", cart: null };
+	const cart = await cartDetails(config, ref.id, { buyerIp });
+	if (!cart) {
+		saveCart(session, null);
+		return { notice: "cart_empty", cart: null };
+	}
+	const line = String(input.line ?? "");
+	const owns = cart.lines.some((l) => l.id === line);
+
+	if (input.action === "update" || input.action === "remove") {
+		if (!owns) return { notice: "cart_updated", cart };
+		const quantity = input.action === "remove" ? 0 : Number.parseInt(String(input.quantity ?? ""), 10);
+		if (!Number.isFinite(quantity) || quantity < 0 || quantity > MAX_QUANTITY) return { notice: "cart_updated", cart };
+		const next = quantity === 0 ? await removeLines(config, cart.id, [line], { buyerIp }) : await updateLines(config, cart.id, [{ id: line, quantity }], { buyerIp });
+		save(next);
+		return { notice: "cart_updated", cart: next };
+	}
+
+	if (input.action === "discount") {
+		const code = String(input.code ?? "").trim().slice(0, 100);
+		const next = await setDiscountCodes(config, cart.id, code ? [code] : [], { buyerIp });
+		save(next);
+		if (!code) return { notice: "cart_updated", cart: next };
+		const applied = next.discountCodes.find((d) => d.code.toLowerCase() === code.toLowerCase());
+		return { notice: applied?.applicable ? "discount_applied" : "discount_not_applicable", cart: next };
+	}
+
+	return { notice: "cart_updated", cart };
+}
+
+/** Read the add fields from a posted form: option.<Name> fields become `options`. */
+export function cartInputFromForm(form: FormData | null): CartInput {
+	const field = (k: string) => String(form?.get(k) ?? "").trim();
+	const options: Record<string, string> = {};
+	form?.forEach((value, key) => {
+		if (key.startsWith("option.") && typeof value === "string") options[key.slice(7)] = value;
+	});
+	return {
+		action: field("action"),
+		product: field("product"),
+		variant: field("variant"),
+		options,
+		sellingPlan: form?.has("selling_plan") ? field("selling_plan") : null,
+		quantity: field("quantity") || "1",
+		line: field("line"),
+		code: field("code"),
+	};
+}