@openmobilehub/credentagent-storefront 0.2.0

package/dist/index.js

@@ -0,0 +1,159 @@
+// @openmobilehub/credentagent-storefront — the agentic storefront core (v0.1 slice).
+//
+// The cart → priced-cart → order model an MCP shopping app needs, **catalog-injected**
+// (bring your own products). Own-the-code: fork it and edit your catalog. This slice
+// is the pure pricing/order model; the MCP tools + widget bundle that render it are
+// tracked in the roadmap.
+import { PRODUCT_IMAGES } from "./generated-images.js";
+/** Default loyalty discount, in percent. Override per-call via PriceOpts. */
+export const LOYALTY_DISCOUNT_PCT = 10;
+/** `_meta` keys the storefront tools use to embed the catalog / cart for the widget to read. */
+export const CATALOG_META_KEY = "product-picker/catalog";
+export const CART_META_KEY = "product-picker/cart";
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/**
+ * Price a cart against an injected catalog. Unknown ids are collected, not
+ * thrown. Pure — no globals, so the same function serves any storefront.
+ */
+export function priceCart(items, catalog, opts = {}) {
+    const byId = new Map(catalog.map((p) => [p.id, p]));
+    const lines = [];
+    const unknownIds = [];
+    let hasAgeRestricted = false;
+    for (const { productId, quantity } of items) {
+        const product = byId.get(productId);
+        if (!product) {
+            unknownIds.push(productId);
+            continue;
+        }
+        if (quantity <= 0)
+            continue;
+        if (product.minimumAge != null)
+            hasAgeRestricted = true;
+        lines.push({
+            id: product.id,
+            name: product.name,
+            unitPrice: product.price,
+            currency: product.currency,
+            quantity,
+            lineTotal: round2(product.price * quantity),
+            // Re-derived onto the line so a priced Order is gate-ready (inv #2).
+            ...(product.minimumAge != null ? { minimumAge: product.minimumAge } : {}),
+            category: product.category,
+        });
+    }
+    const itemCount = lines.reduce((sum, l) => sum + l.quantity, 0);
+    const subtotal = round2(lines.reduce((sum, l) => sum + l.lineTotal, 0));
+    const loyaltyApplied = !!opts.loyaltyApplied;
+    const pct = opts.loyaltyDiscountPct ?? LOYALTY_DISCOUNT_PCT;
+    const discount = loyaltyApplied ? round2(subtotal * (pct / 100)) : 0;
+    const total = round2(subtotal - discount);
+    const currency = lines[0]?.currency ?? "USD";
+    return {
+        lines,
+        itemCount,
+        subtotal,
+        discount,
+        total,
+        currency,
+        unknownIds,
+        hasAgeRestricted,
+        ageVerified: !!opts.ageVerified,
+        loyaltyApplied,
+    };
+}
+/** The strictest minimum age across the cart's products, or null if none. */
+export function requiredAgeForLines(lines, catalog) {
+    const byId = new Map(catalog.map((p) => [p.id, p]));
+    let max = null;
+    for (const { id } of lines) {
+        const m = byId.get(id)?.minimumAge;
+        if (m != null && (max === null || m > max))
+            max = m;
+    }
+    return max;
+}
+/** Snapshot a priced cart into an immutable order. */
+export function createOrder(items, id, catalog, opts = {}) {
+    const { lines, itemCount, subtotal, discount, total, currency } = priceCart(items, catalog, opts);
+    return { id, lines, itemCount, subtotal, discount, total, currency, createdAt: new Date().toISOString() };
+}
+/** Look up a product by id in the injected catalog. */
+export function getProduct(catalog, productId) {
+    return catalog.find((p) => p.id === productId);
+}
+/** Reviews for a product, from the injected reviews map (empty if none). */
+export function getReviews(reviews, productId) {
+    return reviews?.[productId] ?? [];
+}
+/** Wrap a static product array as a {@link CatalogSource} — the zero-config default (never fails). */
+export function staticCatalog(products) {
+    return { load: async () => products, current: () => products };
+}
+/** True when `x` is a {@link CatalogSource} (has a `load` method) rather than a plain `Product[]`. */
+export function isCatalogSource(x) {
+    return !!x && !Array.isArray(x) && typeof x.load === "function";
+}
+/** A tiny runnable catalog (incl. one age-restricted item) so the package demos itself. */
+// Generated, self-contained product images (see generated-images.ts) — emoji tiles
+// embedded as data URIs, so the catalog needs no external image service.
+export const SAMPLE_CATALOG = [
+    {
+        id: "aurora-headphones",
+        name: "Aurora Wireless Headphones",
+        price: 199.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["aurora-headphones"],
+        category: "Audio",
+        description: "Over-ear ANC headphones with 40h battery life.",
+    },
+    {
+        id: "oak-whiskey",
+        name: "Oak Reserve Whiskey Collection",
+        price: 124.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["oak-whiskey"],
+        category: "Beverages",
+        description: "Trio of small-batch aged whiskeys. 21+ only.",
+        minimumAge: 21,
+    },
+    {
+        id: "drift-mouse",
+        name: "Drift Wireless Mouse",
+        price: 49.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["drift-mouse"],
+        category: "Electronics",
+        description: "Ergonomic silent-click wireless mouse, 6-month battery.",
+    },
+    {
+        id: "celebration-champagne",
+        name: "Celebration Champagne Duo",
+        price: 89.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["celebration-champagne"],
+        category: "Beverages",
+        description: "Brut champagne duo with two crystal flutes. 21+ only.",
+        minimumAge: 21,
+    },
+    {
+        id: "summit-backpack",
+        name: "Summit Trail Backpack",
+        price: 129.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["summit-backpack"],
+        category: "Outdoors",
+        description: "35L weatherproof hiking backpack with a stowaway rain cover.",
+    },
+    {
+        id: "lumen-desk-lamp",
+        name: "Lumen LED Desk Lamp",
+        price: 59.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["lumen-desk-lamp"],
+        category: "Home",
+        description: "Dimmable LED desk lamp with a USB-C charging base.",
+    },
+];

package/dist/redis.d.ts

@@ -0,0 +1,31 @@
+import type { StorageProvider } from "./server.js";
+/** The minimal slice of the Upstash client the adapters use (also the injectable test seam). */
+export interface RedisLike {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+}
+/** Optional loader seam so the missing-peer-dependency path is testable while the dep is installed. */
+export type UpstashLoader = () => Promise<{
+    new (config: {
+        url: string;
+        token: string;
+    }): RedisLike;
+}>;
+export interface RedisStorageOptions {
+    /** Upstash REST URL (with `token`). */
+    url?: string;
+    /** Upstash REST token (with `url`). */
+    token?: string;
+    /** Inject a pre-built / fake client instead of `url`+`token` (tests, custom backends). */
+    client?: RedisLike;
+    /** Key prefix isolating tenants on a shared backend. Default `"credentagent-storefront"`. */
+    namespace?: string;
+    /** @internal Override how `@upstash/redis` is loaded (for tests). */
+    _load?: UpstashLoader;
+}
+/**
+ * Build a {@link StorageProvider} backed by an Upstash-compatible Redis. Pass the result as
+ * `createStorefront({ storage })`. Supply either `{ url, token }` or an injected `{ client }`.
+ */
+export declare function redisStorage(options: RedisStorageOptions): StorageProvider;

package/dist/redis.js

@@ -0,0 +1,140 @@
+// redisStorage() — first-class persistence for createStorefront().
+//
+// Builds all four stores (cart, created-order, completed-order, verification) over an
+// Upstash-compatible Redis, so a production/serverless deployment gets shared,
+// cross-instance state with ONE option instead of hand-written adapters:
+//
+//   import { createStorefront } from "@openmobilehub/credentagent-storefront/server";
+//   import { redisStorage } from "@openmobilehub/credentagent-storefront/redis";
+//   const store = createStorefront({ storage: redisStorage({ url, token, namespace: "my-shop" }) });
+//
+// `@upstash/redis` is an OPTIONAL peer dependency: it is loaded LAZILY, only when a real
+// Redis op runs on the { url, token } path. Importing this module, calling `redisStorage`,
+// and the injected-`client` path all need no dependency (Security-lean in-memory story).
+//
+// Keys are `${namespace}:${kind}:${orderId}` — order/verification state is scoped per
+// order id (never process-global; Security Invariant #4) and `namespace` isolates tenants
+// sharing one backend. This layer PERSISTS state only; it is not a trust anchor and never
+// affects `trust_level`.
+const DEFAULT_NAMESPACE = "credentagent-storefront";
+function joinKey(...parts) {
+    return parts.join(":");
+}
+class RedisCartStore {
+    redis;
+    namespace;
+    // Keyed per session (`${namespace}:cart:${sessionId}`) so concurrent buyers on one
+    // provider get independent carts (Security invariant 4).
+    constructor(redis, namespace) {
+        this.redis = redis;
+        this.namespace = namespace;
+    }
+    keyFor(sessionId) {
+        return joinKey(this.namespace, "cart", sessionId);
+    }
+    async read(sessionId) {
+        const obj = (await this.redis.get(this.keyFor(sessionId))) ?? {};
+        return new Map(Object.entries(obj));
+    }
+    async write(sessionId, cart) {
+        await this.redis.set(this.keyFor(sessionId), Object.fromEntries(cart));
+    }
+}
+class RedisOrderStore {
+    redis;
+    namespace;
+    kind;
+    // The `kind` distinguishes the two order slots (created vs completed) so their keys
+    // never collide under one namespace (U1).
+    constructor(redis, namespace, kind) {
+        this.redis = redis;
+        this.namespace = namespace;
+        this.kind = kind;
+    }
+    keyFor(orderId) {
+        return joinKey(this.namespace, "order", this.kind, orderId);
+    }
+    async read(orderId) {
+        return (await this.redis.get(this.keyFor(orderId))) ?? null;
+    }
+    async write(orderId, order) {
+        await this.redis.set(this.keyFor(orderId), order);
+    }
+    async clear(orderId) {
+        await this.redis.del(this.keyFor(orderId));
+    }
+}
+class RedisVerificationStore {
+    redis;
+    namespace;
+    // Full-record get/set per order id. The ceremony merges fields at the call site before
+    // writing, so no adapter-level merge is needed; isolation is per-order keying.
+    constructor(redis, namespace) {
+        this.redis = redis;
+        this.namespace = namespace;
+    }
+    keyFor(orderId) {
+        return joinKey(this.namespace, "verification", orderId);
+    }
+    async read(orderId) {
+        return (await this.redis.get(this.keyFor(orderId))) ?? undefined;
+    }
+    async write(orderId, record) {
+        await this.redis.set(this.keyFor(orderId), record);
+    }
+    async clear(orderId) {
+        await this.redis.del(this.keyFor(orderId));
+    }
+}
+// A RedisLike that loads `@upstash/redis` and constructs the real client on FIRST use.
+// Deferring the import keeps `redisStorage()` synchronous and means the dependency is
+// only required when a Redis op actually runs (never at import / construction time).
+function lazyUpstashClient(url, token, load) {
+    let clientP;
+    const client = () => {
+        if (!clientP) {
+            clientP = load()
+                .then((Redis) => new Redis({ url, token }))
+                .catch((cause) => {
+                throw new Error("redisStorage: `@upstash/redis` is required for the { url, token } path but could not be " +
+                    "loaded. Install it (`npm i @upstash/redis`) or pass a `client`.", { cause });
+            });
+        }
+        return clientP;
+    };
+    return {
+        async get(key) {
+            return (await client()).get(key);
+        },
+        async set(key, value) {
+            return (await client()).set(key, value);
+        },
+        async del(key) {
+            return (await client()).del(key);
+        },
+    };
+}
+const defaultLoader = async () => (await import("@upstash/redis")).Redis;
+function resolveClient(options) {
+    if (options.client)
+        return options.client;
+    const { url, token } = options;
+    if (!url || !token) {
+        throw new Error("redisStorage: provide a `client`, or both `url` and `token`.");
+    }
+    return lazyUpstashClient(url, token, options._load ?? defaultLoader);
+}
+/**
+ * Build a {@link StorageProvider} backed by an Upstash-compatible Redis. Pass the result as
+ * `createStorefront({ storage })`. Supply either `{ url, token }` or an injected `{ client }`.
+ */
+export function redisStorage(options) {
+    const namespace = options.namespace ?? DEFAULT_NAMESPACE;
+    const redis = resolveClient(options);
+    return {
+        cartStore: new RedisCartStore(redis, namespace),
+        createdOrderStore: new RedisOrderStore(redis, namespace, "created"),
+        orderStore: new RedisOrderStore(redis, namespace, "completed"),
+        verificationStore: new RedisVerificationStore(redis, namespace),
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,124 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Express, Request } from "express";
+import type { CatalogSource, Order, Product, Review } from "./index.js";
+export type { CatalogSource } from "./index.js";
+import type { CartStore, OrderStore } from "./state.js";
+export type { CartStore, OrderStore } from "./state.js";
+import { type CeremonyOrder, type VerificationStore } from "@openmobilehub/credentagent-gate";
+/** Given a priced order, return the `requires` manifest (or `undefined` = ungated). */
+export type GateResolver = (order: Order) => unknown[] | undefined;
+/**
+ * A persistence provider that supplies all four stores at once (e.g. `redisStorage(...)`
+ * from `@openmobilehub/credentagent-storefront/redis`). Passed as `StorefrontOptions.storage`
+ * so a production deployment gets shared, cross-instance state with one option instead of
+ * hand-written adapters. An explicit per-slot store (`cartStore`, `orderStore`, …) still
+ * takes precedence over the provider's store for that slot (the custom-backend escape hatch).
+ */
+export interface StorageProvider {
+    cartStore: CartStore;
+    createdOrderStore: OrderStore<Order>;
+    orderStore: OrderStore<CompletedOrderRecord>;
+    verificationStore: VerificationStore;
+}
+export interface StorefrontOptions {
+    /**
+     * Products to sell. Defaults to the package's `SAMPLE_CATALOG`. Pass a plain `Product[]`
+     * for the zero-config static catalog, or a {@link CatalogSource} (e.g.
+     * `firestoreCatalog(...)` from `@openmobilehub/credentagent-storefront/firestore`) for a
+     * live, editable catalog the module loads + caches server-side. Prices and age
+     * thresholds always re-derive from this catalog server-side (Security invariant 2).
+     */
+    catalog?: Product[] | CatalogSource;
+    /** Reviews per product id, backing `get-product-reviews`. */
+    reviews?: Record<string, Review[]>;
+    /** Origin the checkout links resolve from. Default `http://localhost:<port>`. */
+    baseUrl?: string;
+    /** Cart store; default in-memory. */
+    cartStore?: CartStore;
+    /** Completed-order store (read by `get-order-status`); default in-memory. */
+    orderStore?: OrderStore<CompletedOrderRecord>;
+    /**
+     * Created-but-not-yet-completed orders (read by the checkout page + place-order),
+     * keyed by order id. Default in-memory. Inject a shared store (e.g. Redis) on a
+     * multi-instance serverless deployment, or the checkout page lands on a cold
+     * instance that never saw the order.
+     */
+    createdOrderStore?: OrderStore<Order>;
+    /**
+     * Per-order verification state the mounted ceremony writes (age proven / loyalty
+     * applied) and this server's `completion` seam reads back to re-price + enforce
+     * the age gate. Default in-memory; inject a shared store on a serverless
+     * deployment. Published on `app.locals.credentagent` so `credentagent.mount(store.app)`
+     * wires the rails against the SAME state (Security invariant 4).
+     */
+    verificationStore?: VerificationStore;
+    /**
+     * A persistence provider (e.g. `redisStorage({ url, token, namespace })`) that supplies
+     * all four stores at once. Optional — omit for the in-memory default. An explicit store
+     * above (`cartStore` / `orderStore` / `createdOrderStore` / `verificationStore`) takes
+     * precedence over the provider's store for that slot.
+     */
+    storage?: StorageProvider;
+    /**
+     * Stable HMAC key for the ceremony's challenge nonce (e.g. `process.env.GATE_SECRET`).
+     * Required so an options→verify hop survives an instance split on serverless. When
+     * absent, `allowEphemeralKey` defaults true so a single-process dev server / tests
+     * just run with a per-process key.
+     */
+    signingKey?: string;
+    /** Allow a per-process ephemeral signing key (default: true unless `signingKey` is set). */
+    allowEphemeralKey?: boolean;
+    /**
+     * Opt-in (default false): carry the created order in a signed Cart Mandate on the
+     * checkout link (`?order=<id>&cart=<base64url>`) instead of a `createdOrderStore`
+     * write, so a checkout survives an instance split with no shared created-order store
+     * (gate FR-007). Forces a concrete `signingKey` (generated if none) so the mandate the
+     * checkout tool issues is the one the gate rails verify. Verification + completion
+     * state still use their stores.
+     */
+    statelessOrders?: boolean;
+    /**
+     * Optional demo-mode settlement seam (e.g. on-chain). Throwing GATES completion:
+     * a configured-but-failed settle records nothing and leaves the cart intact.
+     */
+    settle?: (order: CeremonyOrder) => Promise<Record<string, unknown> & {
+        network: string;
+        txId: string;
+        status: string;
+    }>;
+}
+/**
+ * A completed-order record the widget poll + `get-order-status` read. The standalone
+ * demo `place-order` writes the lean shape (orderId/amount/currency/method/completedAt);
+ * the mounted ceremony's shared `completeOrder` writes the richer one (mandate id,
+ * gate outcomes, instrument, settlement) — both satisfy this superset so the poll
+ * reads either.
+ */
+export interface CompletedOrderRecord {
+    orderId: string;
+    amount: number;
+    currency: string;
+    method: string;
+    completedAt: string;
+    mandateId?: string;
+    instrument?: unknown;
+    gates?: {
+        gate: string;
+        pass: boolean;
+        detail: string;
+    }[];
+    settlement?: unknown;
+}
+export interface Storefront {
+    app: Express;
+    /** The current catalog. Static source: the injected array; dynamic source: last-known-good. */
+    catalog: Product[];
+    gate(resolve: GateResolver): void;
+    listen(port?: number): Promise<{
+        url: string;
+        port: number;
+    }>;
+    mcpServer(): McpServer;
+}
+export declare function originFromRequest(req: Request): string;
+export declare function createStorefront(opts?: StorefrontOptions): Storefront;