@redeemid/emdash 0.0.0-stage → 0.0.3

package/src/storage.ts

@@ -0,0 +1,95 @@
+/**
+ * The member mirror: what Shopify says about each linked customer.
+ *
+ * Stored with EmDash's auth-provider storage (namespace `auth:redeemid`), the
+ * one plugin-style store that is public API for provider routes and page code
+ * alike. Nothing on the site grants access: a member's levels are
+ * computed from these mirrored tags only.
+ */
+
+import type { StorageCollection } from "emdash";
+import { getAuthProviderStorage } from "emdash/api/route-utils";
+
+import { PROVIDER_ID } from "./config.js";
+
+export interface MemberRecord {
+	/** Numeric Shopify customer id, also the record id. */
+	customerId: string;
+	/** EmDash user id once the customer has signed in. */
+	userId: string | null;
+	email: string | null;
+	firstName: string | null;
+	lastName: string | null;
+	tags: string[];
+	/** From customers/enable|disable webhooks only. */
+	status: "enabled" | "disabled";
+	/** Shopify updated_at (ms) of the last profile write, to drop out-of-order webhooks. */
+	profileUpdatedAt: number | null;
+	/** Shopify updated_at (ms) of the last status write. */
+	statusUpdatedAt: number | null;
+	/** When anything was last written, ISO. */
+	syncedAt: string;
+	/** What wrote it last: sign-in or a webhook topic. */
+	source: string;
+}
+
+export interface DeliveryRecord {
+	topic: string;
+	receivedAt: string;
+}
+
+export const STORAGE_CONFIG = {
+	members: { indexes: ["email", "userId"] },
+	deliveries: { indexes: ["receivedAt"] },
+};
+
+export interface Stores {
+	members: StorageCollection<MemberRecord>;
+	deliveries: StorageCollection<DeliveryRecord>;
+}
+
+export function stores(db: unknown): Stores {
+	const s = getAuthProviderStorage(db as Parameters<typeof getAuthProviderStorage>[0], PROVIDER_ID, STORAGE_CONFIG);
+	return s as unknown as Stores;
+}
+
+export function emptyMember(customerId: string): MemberRecord {
+	return {
+		customerId,
+		userId: null,
+		email: null,
+		firstName: null,
+		lastName: null,
+		tags: [],
+		status: "enabled",
+		profileUpdatedAt: null,
+		statusUpdatedAt: null,
+		syncedAt: new Date().toISOString(),
+		source: "",
+	};
+}
+
+export async function memberForUser(s: Stores, userId: string): Promise<MemberRecord | null> {
+	const { items } = await s.members.query({ where: { userId }, limit: 1 });
+	return items[0]?.data ?? null;
+}
+
+/** Clean a tag list the way Shopify stores them: trimmed, unique, no blanks. */
+export function cleanTags(raw: unknown): string[] {
+	const list = typeof raw === "string" ? raw.split(",") : Array.isArray(raw) ? raw : [];
+	const out: string[] = [];
+	for (const tag of list) {
+		if (typeof tag !== "string") continue;
+		const t = tag.trim();
+		if (t !== "" && !out.some((o) => o.toLowerCase() === t.toLowerCase())) out.push(t);
+	}
+	return out;
+}
+
+/** "gid://shopify/Customer/123" or 123 → "123". */
+export function numericId(raw: unknown): string | null {
+	if (typeof raw === "number" && Number.isSafeInteger(raw) && raw > 0) return String(raw);
+	if (typeof raw !== "string") return null;
+	const m = /^(?:gid:\/\/shopify\/Customer\/)?(\d+)$/.exec(raw.trim());
+	return m?.[1] ?? null;
+}

package/src/storefront.ts

@@ -0,0 +1,186 @@
+/**
+ * Shopify Storefront API: plan details and checkout carts.
+ *
+ * Server-side calls use the private token (with the buyer's IP, as Shopify
+ * asks), fall back to the public token, then to tokenless access, which
+ * covers products and carts. Prices and availability always come from
+ * Shopify; nothing here decides who gets access.
+ */
+
+import { env, ENV, shopOrigin, type RedeemIDConfig } from "./config.js";
+import { USER_AGENT } from "./shopify.js";
+
+export const STOREFRONT_API_VERSION = "2026-10";
+
+export interface Plan {
+	handle: string;
+	title: string;
+	description: string;
+	availableForSale: boolean;
+	variantId: string | null;
+	sellingPlanId: string | null;
+	price: { amount: string; currencyCode: string } | null;
+}
+
+const PLAN_TTL_MS = 5 * 60 * 1000;
+const planCache = new Map<string, { at: number; value: Plan | null }>();
+
+export function resetStorefrontCache(): void {
+	planCache.clear();
+}
+
+export async function storefront<T>(
+	config: RedeemIDConfig,
+	query: string,
+	variables: Record<string, unknown> = {},
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<T> {
+	const headers: Record<string, string> = {
+		"Content-Type": "application/json",
+		Accept: "application/json",
+		"User-Agent": USER_AGENT,
+	};
+	const priv = env(ENV.storefrontPrivateToken);
+	const pub = env(ENV.storefrontPublicToken);
+	if (priv) {
+		headers["Shopify-Storefront-Private-Token"] = priv;
+		if (opts.buyerIp) headers["Shopify-Storefront-Buyer-IP"] = opts.buyerIp;
+	} else if (pub) {
+		headers["X-Shopify-Storefront-Access-Token"] = pub;
+	}
+	const res = await (opts.fetcher ?? fetch)(`${shopOrigin(config)}/api/${STOREFRONT_API_VERSION}/graphql.json`, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({ query, variables }),
+	});
+	const body = (await res.json().catch(() => ({}))) as { data?: T; errors?: unknown };
+	if (!res.ok || !body.data) throw new Error(`Storefront API request failed (${res.status}).`);
+	return body.data;
+}
+
+const PLAN_QUERY = `query Plan($handle: String!) {
+  product(handle: $handle) {
+    handle title description availableForSale requiresSellingPlan
+    variants(first: 1) { nodes { id availableForSale price { amount currencyCode } } }
+    sellingPlanGroups(first: 1) { nodes { sellingPlans(first: 1) { nodes { id } } } }
+  }
+}`;
+
+interface PlanData {
+	product: {
+		handle: string;
+		title: string;
+		description: string;
+		availableForSale: boolean;
+		requiresSellingPlan: boolean;
+		variants: { nodes: Array<{ id: string; availableForSale: boolean; price: { amount: string; currencyCode: string } }> };
+		sellingPlanGroups: { nodes: Array<{ sellingPlans: { nodes: Array<{ id: string }> } }> };
+	} | null;
+}
+
+/** A product by handle, cached for five minutes. Null when Shopify has no such product. */
+export async function plan(config: RedeemIDConfig, handle: string, fetcher?: typeof fetch): Promise<Plan | null> {
+	const key = `${shopOrigin(config)}|${handle}`;
+	const hit = planCache.get(key);
+	if (hit && Date.now() - hit.at < PLAN_TTL_MS) return hit.value;
+
+	const { product: p } = await storefront<PlanData>(config, PLAN_QUERY, { handle }, { fetcher });
+	const variant = p?.variants.nodes[0] ?? null;
+	const value: Plan | null = p
+		? {
+				handle: p.handle,
+				title: p.title,
+				description: p.description,
+				availableForSale: p.availableForSale && (variant?.availableForSale ?? false),
+				variantId: variant?.id ?? null,
+				// Subscription-only products need a selling plan in the cart line.
+				sellingPlanId: p.requiresSellingPlan ? (p.sellingPlanGroups.nodes[0]?.sellingPlans.nodes[0]?.id ?? null) : null,
+				price: variant?.price ?? null,
+			}
+		: null;
+	planCache.set(key, { at: Date.now(), value });
+	return value;
+}
+
+const CART_CREATE = `mutation Cart($input: CartInput!) {
+  cartCreate(input: $input) { cart { checkoutUrl } userErrors { message } }
+}`;
+
+/** Create a one-line cart and return its checkout URL. */
+export async function checkoutUrl(
+	config: RedeemIDConfig,
+	line: { variantId: string; sellingPlanId?: string | null },
+	opts: { email?: string | null; buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<string> {
+	const input: Record<string, unknown> = {
+		lines: [{ merchandiseId: line.variantId, quantity: 1, ...(line.sellingPlanId ? { sellingPlanId: line.sellingPlanId } : {}) }],
+	};
+	if (opts.email) input.buyerIdentity = { email: opts.email };
+	const data = await storefront<{ cartCreate: { cart: { checkoutUrl: string } | null; userErrors: Array<{ message: string }> } }>(
+		config,
+		CART_CREATE,
+		{ input },
+		opts,
+	);
+	const url = data.cartCreate.cart?.checkoutUrl;
+	if (!url) throw new Error(data.cartCreate.userErrors[0]?.message ?? "Shopify returned no checkout.");
+	return url;
+}
+
+// ---------------------------------------------------------------- cart
+
+export interface Cart {
+	id: string;
+	checkoutUrl: string;
+	totalQuantity: number;
+}
+
+const CART_FIELDS = "id checkoutUrl totalQuantity";
+
+const CART_GET = `query Cart($id: ID!) { cart(id: $id) { ${CART_FIELDS} } }`;
+
+const CART_NEW = `mutation CartNew($input: CartInput!) {
+  cartCreate(input: $input) { cart { ${CART_FIELDS} } userErrors { message } }
+}`;
+
+const CART_ADD = `mutation CartAdd($id: ID!, $lines: [CartLineInput!]!) {
+  cartLinesAdd(cartId: $id, lines: $lines) { cart { ${CART_FIELDS} } userErrors { message } }
+}`;
+
+type CartResult = { cart: Cart | null; userErrors: Array<{ message: string }> };
+
+/**
+ * A cart by id. Null once Shopify no longer has it, which is what happens
+ * after its checkout completes.
+ */
+export async function getCart(
+	config: RedeemIDConfig,
+	id: string,
+	opts: { buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<Cart | null> {
+	const data = await storefront<{ cart: Cart | null }>(config, CART_GET, { id }, opts);
+	return data.cart;
+}
+
+/**
+ * Add one line to the visitor's cart, creating the cart when there is none
+ * (or Shopify has dropped it). A new cart carries the member's email.
+ */
+export async function addToCart(
+	config: RedeemIDConfig,
+	cartId: string | null,
+	line: { variantId: string; sellingPlanId?: string | null },
+	opts: { email?: string | null; buyerIp?: string | null; fetcher?: typeof fetch } = {},
+): Promise<Cart> {
+	const lines = [{ merchandiseId: line.variantId, quantity: 1, ...(line.sellingPlanId ? { sellingPlanId: line.sellingPlanId } : {}) }];
+	if (cartId) {
+		const data = await storefront<{ cartLinesAdd: CartResult }>(config, CART_ADD, { id: cartId, lines }, opts).catch(() => null);
+		if (data?.cartLinesAdd.cart) return data.cartLinesAdd.cart;
+	}
+	const input: Record<string, unknown> = { lines };
+	if (opts.email) input.buyerIdentity = { email: opts.email };
+	const data = await storefront<{ cartCreate: CartResult }>(config, CART_NEW, { input }, opts);
+	const cart = data.cartCreate.cart;
+	if (!cart) throw new Error(data.cartCreate.userErrors[0]?.message ?? "Shopify returned no cart.");
+	return cart;
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "0.0.3";

package/src/webhooks.ts

@@ -0,0 +1,161 @@
+/**
+ * Shopify webhooks → member mirror.
+ *
+ * Shopify is the only source of entitlements: these handlers copy what Shopify
+ * says and never invent access. Status comes from customers/disable|enable
+ * only; a profile payload without `tags` never means "tags removed".
+ */
+
+import { cleanTags, emptyMember, numericId, type MemberRecord, type Stores } from "./storage.js";
+
+export type Kind = "profile" | "delete" | "status" | "tags" | "merge" | "compliance" | "ignored";
+
+const TOPICS: Record<string, Kind> = {
+	"customers/create": "profile",
+	"customers/update": "profile",
+	"customers/delete": "delete",
+	"customers/disable": "status",
+	"customers/enable": "status",
+	"customers/merge": "merge",
+	"customer.tags_added": "tags",
+	"customer.tags_removed": "tags",
+	"customers/redact": "compliance",
+	"customers/data_request": "compliance",
+	"shop/redact": "compliance",
+	"customer_account_settings/update": "ignored",
+};
+
+export function kindOf(topic: string): Kind | null {
+	return TOPICS[topic.trim().toLowerCase()] ?? null;
+}
+
+/** Shopify signs the raw body with the app's client secret (HMAC-SHA256, base64). */
+export async function verifyHmac(body: Uint8Array<ArrayBuffer>, header: string, secret: string): Promise<boolean> {
+	if (!secret || !header) return false;
+	const key = await crypto.subtle.importKey(
+		"raw",
+		new TextEncoder().encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["verify"],
+	);
+	let sig: Uint8Array<ArrayBuffer>;
+	try {
+		sig = Uint8Array.from(atob(header.trim()), (c) => c.charCodeAt(0));
+	} catch {
+		return false;
+	}
+	// crypto.subtle.verify compares in constant time.
+	return crypto.subtle.verify("HMAC", key, sig, body);
+}
+
+export async function sign(body: Uint8Array<ArrayBuffer>, secret: string): Promise<string> {
+	const key = await crypto.subtle.importKey(
+		"raw",
+		new TextEncoder().encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign"],
+	);
+	const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, body));
+	let s = "";
+	for (const b of mac) s += String.fromCharCode(b);
+	return btoa(s);
+}
+
+function time(raw: unknown): number | null {
+	if (typeof raw !== "string") return null;
+	const t = Date.parse(raw);
+	return Number.isFinite(t) ? t : null;
+}
+
+function str(raw: unknown): string | null {
+	return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+}
+
+function customerOf(payload: Record<string, unknown>): string | null {
+	const nested = (payload.customer as { id?: unknown } | undefined)?.id;
+	for (const c of [payload.id, payload.customerId, payload.customer_id, nested]) {
+		const id = numericId(c);
+		if (id) return id;
+	}
+	return null;
+}
+
+export type Outcome = "processed" | "skipped" | "stale" | "ignored";
+
+/**
+ * Apply one webhook to the mirror. Throws on storage errors so the caller can
+ * answer 500 and let Shopify retry.
+ */
+export async function apply(s: Stores, topic: string, payload: Record<string, unknown>): Promise<Outcome> {
+	const kind = kindOf(topic);
+	if (!kind || kind === "ignored") return "ignored";
+
+	if (kind === "compliance") {
+		// customers/redact: drop the mirror for that customer. data_request and
+		// shop/redact need staff action (or are covered by deleting the app).
+		if (topic === "customers/redact") {
+			const id = customerOf(payload);
+			if (id) await s.members.delete(id);
+			return "processed";
+		}
+		return "skipped";
+	}
+
+	if (kind === "merge") {
+		if (payload.status === "failed") return "skipped";
+		const kept = numericId(payload.admin_graphql_api_customer_kept_id);
+		const gone = numericId(payload.admin_graphql_api_customer_deleted_id);
+		if (!kept || !gone) return "skipped";
+		const old = await s.members.get(gone);
+		if (old?.userId) {
+			const survivor = (await s.members.get(kept)) ?? emptyMember(kept);
+			if (!survivor.userId) survivor.userId = old.userId;
+			survivor.syncedAt = new Date().toISOString();
+			survivor.source = topic;
+			await s.members.put(kept, survivor);
+		}
+		await s.members.delete(gone);
+		return "processed";
+	}
+
+	const id = customerOf(payload);
+	if (!id) return "skipped";
+
+	if (kind === "delete") {
+		await s.members.delete(id);
+		return "processed";
+	}
+
+	const current: MemberRecord = (await s.members.get(id)) ?? emptyMember(id);
+	const updatedAt = time(payload.updated_at);
+
+	if (kind === "profile") {
+		if (updatedAt !== null && current.profileUpdatedAt !== null && updatedAt < current.profileUpdatedAt) {
+			return "stale";
+		}
+		current.email = str(payload.email)?.toLowerCase() ?? current.email;
+		current.firstName = str(payload.first_name) ?? current.firstName;
+		current.lastName = str(payload.last_name) ?? current.lastName;
+		if ("tags" in payload) current.tags = cleanTags(payload.tags);
+		current.profileUpdatedAt = updatedAt ?? current.profileUpdatedAt;
+	} else if (kind === "status") {
+		if (updatedAt !== null && current.statusUpdatedAt !== null && updatedAt < current.statusUpdatedAt) {
+			return "stale";
+		}
+		current.status = topic.endsWith("/disable") ? "disabled" : "enabled";
+		current.statusUpdatedAt = updatedAt ?? current.statusUpdatedAt;
+	} else if (kind === "tags") {
+		const change = cleanTags(payload.tags);
+		const lower = new Set(change.map((t) => t.toLowerCase()));
+		current.tags = topic.endsWith("tags_added")
+			? cleanTags([...current.tags, ...change])
+			: current.tags.filter((t) => !lower.has(t.toLowerCase()));
+	}
+
+	current.syncedAt = new Date().toISOString();
+	current.source = topic;
+	await s.members.put(id, current);
+	return "processed";
+}