@redeemid/emdash 0.0.25 → 0.0.27

package/README.md

@@ -4,13 +4,13 @@
 [![Release](https://github.com/webmultipliers/redeemid-emdash/actions/workflows/release.yml/badge.svg)](https://github.com/webmultipliers/redeemid-emdash/actions/workflows/release.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-Memberships and paywalls for [EmDash](https://github.com/emdash-cms/emdash) sites, run by Shopify.
+Shopify commerce for [EmDash](https://github.com/emdash-cms/emdash) sites: a storefront, a cart, Shopify checkout, customer accounts, and memberships and paywalls that Shopify decides.
 
-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.
+Shopify keeps the store, checkout, orders, subscriptions and customer accounts. EmDash keeps the content. RedeemID joins them: shoppers browse products and fill a cart on your EmDash site, check out with Shopify, and sign in with the store's own customer account. What a reader can read comes from their Shopify customer tags, so there is one source of truth for who paid for what.
 
 ![The RedeemID Access page in the EmDash admin: three levels, Member, Pro and Gold, each mapped to Shopify customer tags, with Gold including Pro](.github/images/access-levels.png)
 
-> **Status: 0.0.24, 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 every feature. Expect changes before 1.0.
+> **Status: early (0.0.x).** 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 every feature. Expect changes before 1.0.
 
 ## How it works
 
@@ -24,6 +24,7 @@ Selling a membership is ordinary Shopify: a product, a checkout, and a Flow work
 
 ## Features
 
+- **For shoppers:** product pages with options, subscriptions and Product structured data, a product sitemap, collections with Shopify's filters and sorting, product search, recommendations, a cart page and cart drawer, discount codes, local prices by market, and a checkout that opens signed in for members. It all works without JavaScript.
 - **For members:** sign in, Account and Sign out without ever seeing the word "Shopify"; a member card with levels, renewal and end dates; preferences saved on their customer record; download or delete what the site keeps about them.
 - **For editors:** Paywall break, Members only, Sold on its own, Plan, Product, Collection, Product search, Contribution and Preferences blocks; an Access panel on every entry; teasers, a monthly or weekly meter, drip, badges and protected file downloads.
 - **For staff:** Access, Members, Webhooks, App events, Reports, Setup, Status, Access test and Privacy pages in the EmDash admin. New content types and taxonomies appear on their own, so access never needs a code change.

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.4.0** (`API_VERSION` in `@redeemid/emdash/contract`, also in `api/state` and `window.redeemid.apiVersion`).
+What site code, other plugins and AI agents can rely on in `@redeemid/emdash`. API version **1.5.0** (`API_VERSION` in `@redeemid/emdash/contract`, also in `api/state` and `window.redeemid.apiVersion`).
 
 Everything on this page is stable: it changes only with a changelog entry and an API version bump (minor when something is added, major when something changes or goes). Anything not listed is internal, even when a module exports it. `src/contract.ts` is the same list as code, and a test fails when the code, that list and this page disagree.
 
@@ -21,7 +21,7 @@ Import these in Astro pages, components and endpoints.
 | `@redeemid/emdash/features` | `hasFeature`, `viewerFeatures`, `featuresFor` |
 | `@redeemid/emdash/preferences` | `readPreferences`, `savePreferences`, `preferenceFields` |
 | `@redeemid/emdash/storefront` | `plan`, `product`, `collection`, `money`, `realOptions`, `variantFor`, `storeContext`, `cartDetails`, `addToCart`, `updateLines`, `removeLines`, `setDiscountCodes` |
-| `@redeemid/emdash/catalog` | `searchProducts`, `collectionPage`, `suggest`, `recommendations`, `browseFromUrl`, `browseHref`, `parseFilters`, `priceFilter`, `SORTS` |
+| `@redeemid/emdash/catalog` | `searchProducts`, `collectionPage`, `suggest`, `recommendations`, `browseFromUrl`, `browseHref`, `parseFilters`, `priceFilter`, `SORTS`, `productSitemap` |
 | `@redeemid/emdash/events` | `signBody` |
 | `@redeemid/emdash/text` | `STRINGS`, `text`, `textParts` |
 | `@redeemid/emdash/search` | `readableResults` |
@@ -56,7 +56,7 @@ Under `/_emdash/api/auth/redeemid/`. Same-origin only: EmDash checks `Origin` on
 - `api/state` (GET): the visitor's own state.
 
   ```json
-  { "apiVersion": "1.4.0", "version": "0.0.25", "signedIn": true, "linked": true,
+  { "apiVersion": "1.5.0", "version": "0.0.27", "signedIn": true, "linked": true,
     "levels": ["gold"], "features": ["ad-free"], "cart": { "count": 2 },
     "meter": { "used": 1, "limit": 3, "period": "month" } }
   ```

package/docs/reference.md

@@ -98,7 +98,7 @@ Import each from `@redeemid/emdash/components/<Name>.astro`.
 | `@redeemid/emdash/features` | `hasFeature()`, `viewerFeatures()` |
 | `@redeemid/emdash/preferences` | `readPreferences()`, `savePreferences()` |
 | `@redeemid/emdash/storefront` | `product()`, `collection()`, `plan()`, `money()` and the cart calls |
-| `@redeemid/emdash/catalog` | `searchProducts()`, `collectionPage()`, `suggest()`, `recommendations()` |
+| `@redeemid/emdash/catalog` | `searchProducts()`, `collectionPage()`, `suggest()`, `recommendations()`, `productSitemap()` |
 | `@redeemid/emdash/events` | `signBody(body, secret)`, the signature a receiver checks against `X-RedeemID-Signature` |
 | `@redeemid/emdash/text` | `STRINGS`, the list of every replaceable string |
 | `@redeemid/emdash/search` | `readableResults()`, for a search page that calls EmDash's `search()` |

package/docs/shop.md

@@ -37,6 +37,35 @@ Everything works without JavaScript: the forms post to `/_emdash/api/auth/redeem
 
 **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.
 
+**Product pages in search.** `<Product heading="h1">` prints Product structured data. Give the page the product's own title and description, and answer 404 for a handle Shopify doesn't have, by reading the product in the page (the same cached read `<Product>` makes):
+
+```astro
+---
+// src/pages/shop/[handle].astro
+import { siteConfig } from "@redeemid/emdash/access";
+import { product, storeContext } from "@redeemid/emdash/storefront";
+
+const config = await siteConfig(Astro.locals);
+const p = config ? await product(config, Astro.params.handle, undefined, storeContext(config, Astro.request)).catch(() => null) : null;
+if (!p) Astro.response.status = 404;
+const title = p?.seo?.title || p?.title;
+const description = p?.seo?.description || p?.description.slice(0, 160);
+---
+```
+
+EmDash's sitemap lists content entries only, so add one for products. `productSitemap()` lists every product the Headless channel sells (up to 5,000), newest change first, linked with the same pattern as the cards:
+
+```ts
+// src/pages/sitemap-products.xml.ts
+import { siteConfig } from "@redeemid/emdash/access";
+import { productSitemap } from "@redeemid/emdash/catalog";
+import type { APIRoute } from "astro";
+
+export const GET: APIRoute = async ({ locals, url }) => productSitemap(await siteConfig(locals), url, { productHref: "/shop/{handle}/" });
+```
+
+Then submit it to search engines, or list it in robots.txt. A custom robots.txt in EmDash's SEO settings replaces the generated one, so keep both lines in it: `Sitemap: https://<your site>/sitemap.xml` and `Sitemap: https://<your site>/sitemap-products.xml`. If the store's Online Store channel is open too, search engines find two pages for each product; headless stores usually password-protect the Online Store or redirect it to the site.
+
 **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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@redeemid/emdash",
-	"version": "0.0.25",
-	"description": "Shopify customer accounts, member levels and paywalls for EmDash sites. Shopify runs commerce; EmDash runs content.",
+	"version": "0.0.27",
+	"description": "Shopify commerce for EmDash sites: storefront, cart, checkout, customer accounts, memberships and paywalls. Shopify runs commerce; EmDash runs content.",
 	"type": "module",
 	"license": "MIT",
 	"author": "Vinny S. Green, LLC",
@@ -39,7 +39,15 @@
 	],
 	"keywords": [
 		"emdash",
+		"emdash-plugin",
 		"shopify",
+		"headless-commerce",
+		"ecommerce",
+		"storefront",
+		"cart",
+		"checkout",
+		"astro",
+		"cloudflare-workers",
 		"paywall",
 		"membership",
 		"customer-accounts"

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.4.0";
+export const API_VERSION = "1.5.0";

package/src/catalog.ts

@@ -285,3 +285,81 @@ export function browseHref(current: URL, change: Record<string, string | null>):
 }
 
 export type { Money };
+
+const SITEMAP_QUERY = `query SitemapProducts($first: Int!, $after: String) {
+  products(first: $first, after: $after, sortKey: UPDATED_AT, reverse: true) {
+    pageInfo { hasNextPage endCursor }
+    nodes { handle updatedAt }
+  }
+}`;
+
+/** One product in the sitemap: its handle and when Shopify last changed it. */
+export interface SitemapProduct {
+	handle: string;
+	updatedAt: string;
+}
+
+/** The most products one sitemap lists (20 Storefront API pages of 250). */
+export const SITEMAP_LIMIT = 5000;
+
+function escapeXml(s: string): string {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+/**
+ * Every product the site's sales channel can sell, newest change first, up
+ * to SITEMAP_LIMIT. Cached for five minutes.
+ */
+export async function sitemapProducts(config: RedeemIDConfig, opts: { fetcher?: typeof fetch } = {}): Promise<SitemapProduct[]> {
+	return cachedRead(`${shopOrigin(config)}|sitemap`, async () => {
+		const out: SitemapProduct[] = [];
+		let after: string | null = null;
+		while (out.length < SITEMAP_LIMIT) {
+			type Data = { products: { pageInfo: { hasNextPage: boolean; endCursor: string | null }; nodes: SitemapProduct[] } };
+			const data: Data = await storefront<Data>(config, SITEMAP_QUERY, { first: 250, after }, opts);
+			out.push(...data.products.nodes.filter((n) => typeof n.handle === "string" && n.handle));
+			if (!data.products.pageInfo.hasNextPage || !data.products.pageInfo.endCursor) break;
+			after = data.products.pageInfo.endCursor;
+		}
+		return out.slice(0, SITEMAP_LIMIT);
+	});
+}
+
+/**
+ * A sitemap of the site's product pages, for search engines. EmDash's own
+ * sitemap lists content entries only, so products need this one:
+ *
+ *   // src/pages/sitemap-products.xml.ts
+ *   export const GET: APIRoute = async ({ locals, url }) =>
+ *     productSitemap(await siteConfig(locals), url, { productHref: "/shop/{handle}/" });
+ *
+ * `productHref` is the same pattern the product cards link with. Answers an
+ * empty sitemap (not an error) when the store can't be read, so a crawler
+ * never caches a broken page.
+ */
+export async function productSitemap(
+	config: RedeemIDConfig | null,
+	url: URL,
+	opts: { productHref: string; fetcher?: typeof fetch },
+): Promise<Response> {
+	let products: SitemapProduct[] = [];
+	if (config) {
+		try {
+			products = await sitemapProducts(config, { fetcher: opts.fetcher });
+		} catch {
+			products = [];
+		}
+	}
+	const lines = ['<?xml version="1.0" encoding="UTF-8"?>', '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'];
+	for (const p of products) {
+		const loc = new URL(opts.productHref.replace("{handle}", encodeURIComponent(p.handle)), url).href;
+		lines.push("  <url>", `    <loc>${escapeXml(loc)}</loc>`);
+		if (p.updatedAt) lines.push(`    <lastmod>${escapeXml(p.updatedAt)}</lastmod>`);
+		lines.push("  </url>");
+	}
+	lines.push("</urlset>");
+	return new Response(lines.join("\n"), {
+		status: 200,
+		headers: { "Content-Type": "application/xml; charset=utf-8", "Cache-Control": "public, max-age=3600" },
+	});
+}

package/src/contract.ts

@@ -20,7 +20,7 @@ export const MODULES = {
 	"@redeemid/emdash/features": ["hasFeature", "viewerFeatures", "featuresFor"],
 	"@redeemid/emdash/preferences": ["readPreferences", "savePreferences", "preferenceFields"],
 	"@redeemid/emdash/storefront": ["plan", "product", "collection", "money", "realOptions", "variantFor", "storeContext", "cartDetails", "addToCart", "updateLines", "removeLines", "setDiscountCodes"],
-	"@redeemid/emdash/catalog": ["searchProducts", "collectionPage", "suggest", "recommendations", "browseFromUrl", "browseHref", "parseFilters", "priceFilter", "SORTS"],
+	"@redeemid/emdash/catalog": ["searchProducts", "collectionPage", "suggest", "recommendations", "browseFromUrl", "browseHref", "parseFilters", "priceFilter", "SORTS", "productSitemap"],
 	"@redeemid/emdash/events": ["signBody"],
 	"@redeemid/emdash/text": ["STRINGS", "text", "textParts"],
 	"@redeemid/emdash/search": ["readableResults"],

package/src/route-cache.ts

@@ -80,6 +80,15 @@ export function hasMemberBlocks(data: Record<string, unknown> | null | undefined
 	return false;
 }
 
+/**
+ * An entry as EmDash's queries return it. `data` is `object` so the
+ * interfaces `emdash types` generates for each collection fit.
+ */
+export interface CacheableEntry {
+	id?: string;
+	data?: object | null;
+}
+
 /**
  * May this entry's page be stored and served to everyone? Only when it reads
  * the same for every visitor, now and until the cache could expire.
@@ -87,18 +96,19 @@ export function hasMemberBlocks(data: Record<string, unknown> | null | undefined
 export async function cacheable(
 	astro: AstroLike,
 	collection: string,
-	entry: { id?: string; data?: Record<string, unknown> | null } | null | undefined,
+	entry: CacheableEntry | null | undefined,
 ): Promise<boolean> {
 	if (!entry) return false;
+	const data = entry.data as Record<string, unknown> | null | undefined;
 	const config = await siteConfig(astro.locals);
-	if (!config) return !hasMemberBlocks(entry.data);
+	if (!config) return !hasMemberBlocks(data);
 	if (config.unavailable) return false;
-	const terms = entry.data?.terms as Terms | undefined;
+	const terms = data?.terms as Terms | undefined;
 	if ((await entryRequirement(config, collection, terms, entry.id)) !== null) return false;
 	// Free until a date: a stored copy would outlive the window.
 	const own = entryRuleFor(config, collection, entry.id);
 	if (own?.openUntil && Date.now() < Date.parse(own.openUntil)) return false;
-	return !hasMemberBlocks(entry.data);
+	return !hasMemberBlocks(data);
 }
 
 /**
@@ -108,7 +118,7 @@ export async function cacheable(
 export async function cacheEntry(
 	astro: CacheAstro,
 	collection: string,
-	entry: { id?: string; data?: Record<string, unknown> | null } | null | undefined,
+	entry: CacheableEntry | null | undefined,
 	hint?: Hint | null,
 ): Promise<boolean> {
 	if (keptOut(astro.locals)) return false;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.0.25";
+export const VERSION = "0.0.27";