@nano133/nanoterra 0.8.0 → 0.9.0

package/dist/shop/adapters/d1.js

@@ -0,0 +1,200 @@
+// The shop store for a game on Cloudflare D1, on the game starter's own tables (migrations/0001_init.sql): `orders`, `owned` and `meta`. The package
+// ships the same tables as "@nano133/nanoterra/shop/d1.sql" (CREATE ... IF NOT EXISTS) for a new game; the starter has them already, so it switches with
+// no migration and keeps every order and owned look.
+//
+//   import { createD1Shop } from "@nano133/nanoterra/shop/d1";
+//   const store = createD1Shop(env.DB);
+//
+// It reads and writes ONLY those three tables (in `meta`, only the keys "rate" and "scan"). The table names can be changed (`tables`), but the admin's
+// D1 store ("@nano133/nanoterra/admin/d1") reads the starter's names: keep them unless the game has its own admin store.
+//
+// The money rules are in the statements themselves: `amount_lock` and `hash` are UNIQUE (no two held orders ask for one amount, one payment pays one
+// order), the payment and the grant are ONE batch (a D1 transaction), and the scan's claim is one upsert that only one caller in a gap can win.
+import { parseRate } from "../../admin/summary.js";
+import { paidStatus } from "../orders.js";
+import { FORGOTTEN } from "../store.js";
+const STATUSES = ["open", "paid", "expired", "paid_late"];
+const orderOf = (r) => ({
+    id: r.id,
+    player: r.player,
+    lookId: r.look_id,
+    usd: r.usd,
+    rate: Number(r.rate),
+    amount: r.amount,
+    amountLock: r.amount_lock ?? null,
+    status: STATUSES.includes(r.status) ? r.status : "expired",
+    createdAt: Number(r.created_at),
+    expiresAt: Number(r.expires_at),
+    holdUntil: Number(r.hold_until),
+    hash: r.hash ?? null,
+    payer: r.payer ?? null,
+    paidAt: r.paid_at === null || r.paid_at === undefined ? null : Number(r.paid_at),
+    visitor: r.visitor ?? null,
+});
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const changes = (res) => Number(res?.meta?.changes ?? 0);
+const isUnique = (e) => /UNIQUE/i.test(String(e?.message ?? e));
+/** D1 takes at most 100 bound values in one statement. */
+const CHUNK = 90;
+const tableName = (v, fallback) => {
+    const name = v ?? fallback;
+    if (!NAME.test(name))
+        throw new Error(`the table name "${name}" must be plain (letters, digits and _)`);
+    return name;
+};
+async function sha256Hex(text) {
+    const bytes = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * True while `key` has made at most `limit` calls in this fixed window, counted in D1 (the table `hits`: one count for the whole game, every location).
+ * The game starter's `d1Limit`. Old windows stay until the game deletes them (the starter's cron deletes those older than a day).
+ */
+export async function d1Limit(db, key, limit, windowMs, now = Date.now(), tables = {}) {
+    const hits = tableName(tables.hits, "hits");
+    const win = Math.floor(now / windowMs);
+    const row = await db.prepare(`INSERT INTO ${hits} (key, win, count) VALUES (?, ?, 1) ON CONFLICT (key, win) DO UPDATE SET count = count + 1 RETURNING count`).bind(key, win).first();
+    return Number(row?.count ?? 1) <= limit;
+}
+/** The visitor's IP address as Cloudflare saw it (CF-Connecting-IP); an IPv6 address by its /64 (one home network). "local" when there is none. */
+export function visitorIp(req) {
+    const ip = req.headers.get("CF-Connecting-IP") ?? "local";
+    return ip.includes(":") ? ip.split(":").slice(0, 4).join(":") + "::/64" : ip;
+}
+/**
+ * The visitor's key: a hash of a random salt (made once per game and kept in `meta` as "salt") and the IP address, never the address itself. The game
+ * starter's `visitorKey`: the same salt row, so the keys stay the same after a switch.
+ */
+export async function visitorKey(db, req, tables = {}) {
+    const meta = tableName(tables.meta, "meta");
+    let row = await db.prepare(`SELECT value FROM ${meta} WHERE key = 'salt'`).first();
+    if (!row) {
+        const fresh = Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), (x) => x.toString(16).padStart(2, "0")).join("");
+        await db.prepare(`INSERT OR IGNORE INTO ${meta} (key, value, at) VALUES ('salt', ?, ?)`).bind(fresh, Date.now()).run();
+        row = await db.prepare(`SELECT value FROM ${meta} WHERE key = 'salt'`).first();
+    }
+    return (await sha256Hex(`${row.value}|${visitorIp(req)}`)).slice(0, 32);
+}
+export function createD1Shop(db, options = {}) {
+    const T = { orders: tableName(options.tables?.orders, "orders"), owned: tableName(options.tables?.owned, "owned"), meta: tableName(options.tables?.meta, "meta") };
+    const COLS = "id, player, look_id, usd, rate, amount, amount_lock, status, created_at, expires_at, hold_until, hash, payer, paid_at, visitor";
+    async function inChunks(sql, values, col) {
+        const out = new Set();
+        for (let i = 0; i < values.length; i += CHUNK) {
+            const part = values.slice(i, i + CHUNK);
+            const rows = (await db.prepare(sql(part.map(() => "?").join(", "))).bind(...part).all()).results;
+            for (const r of rows)
+                out.add(r[col]);
+        }
+        return out;
+    }
+    const tidy = async (now) => {
+        await db.batch([
+            db.prepare(`UPDATE ${T.orders} SET status = 'expired' WHERE status = 'open' AND expires_at < ?`).bind(now),
+            db.prepare(`UPDATE ${T.orders} SET amount_lock = NULL WHERE amount_lock IS NOT NULL AND hold_until < ?`).bind(now),
+        ]);
+    };
+    const waiting = async (player) => db.prepare(`SELECT COUNT(*) AS n, MAX(hold_until) AS until FROM ${T.orders} WHERE player = ? AND amount_lock IS NOT NULL`).bind(player).first();
+    return {
+        tidy,
+        heldAmounts: (amounts) => inChunks((m) => `SELECT amount_lock FROM ${T.orders} WHERE amount_lock IN (${m})`, amounts, "amount_lock"),
+        async insert(o) {
+            try {
+                await db
+                    .prepare(`INSERT INTO ${T.orders} (id, player, look_id, usd, rate, amount, amount_lock, status, created_at, expires_at, hold_until, visitor) VALUES (?, ?, ?, ?, ?, ?, ?, 'open', ?, ?, ?, ?)`)
+                    .bind(o.id, o.player, o.lookId, o.usd, o.rate, o.amount, o.amount, o.createdAt, o.expiresAt, o.holdUntil, o.visitor)
+                    .run();
+                return true;
+            }
+            catch (e) {
+                // Another order took this amount since the read. Any other failure stops.
+                if (isUnique(e))
+                    return false;
+                throw e;
+            }
+        },
+        async order(id) {
+            const r = await db.prepare(`SELECT ${COLS} FROM ${T.orders} WHERE id = ?`).bind(id).first();
+            return r ? orderOf(r) : null;
+        },
+        async openOrder(player, lookId, until) {
+            const r = await db
+                .prepare(`SELECT ${COLS} FROM ${T.orders} WHERE player = ? AND look_id = ? AND status = 'open' AND expires_at > ? ORDER BY created_at DESC LIMIT 1`)
+                .bind(player, lookId, until)
+                .first();
+            return r ? orderOf(r) : null;
+        },
+        async countOpen(player, now) {
+            const r = await db.prepare(`SELECT COUNT(*) AS n FROM ${T.orders} WHERE player = ? AND status = 'open' AND expires_at > ?`).bind(player, now).first();
+            return Number(r?.n ?? 0);
+        },
+        async owns(player, lookId) {
+            return Boolean(await db.prepare(`SELECT 1 AS one FROM ${T.owned} WHERE player = ? AND look_id = ?`).bind(player, lookId).first());
+        },
+        async owned(player) {
+            return (await db.prepare(`SELECT look_id FROM ${T.owned} WHERE player = ? ORDER BY granted_at, look_id`).bind(player).all()).results.map((r) => r.look_id);
+        },
+        async held() {
+            return (await db.prepare(`SELECT ${COLS} FROM ${T.orders} WHERE amount_lock IS NOT NULL`).all()).results.map(orderOf);
+        },
+        usedHashes: (hashes) => inChunks((m) => `SELECT hash FROM ${T.orders} WHERE hash IN (${m})`, hashes, "hash"),
+        async settle(order, pay, now) {
+            const status = paidStatus(order, pay.seenMs);
+            try {
+                const [update] = await db.batch([
+                    db
+                        .prepare(`UPDATE ${T.orders} SET status = ?, hash = ?, payer = ?, paid_at = ?, amount_lock = NULL WHERE id = ? AND status IN ('open', 'expired') AND amount_lock IS NOT NULL`)
+                        .bind(status, pay.hash, pay.payer, pay.seenMs, order.id),
+                    db
+                        .prepare(`INSERT OR IGNORE INTO ${T.owned} (player, look_id, order_id, granted_at) SELECT player, look_id, id, ? FROM ${T.orders} WHERE id = ? AND status = 'paid' AND hash = ?`)
+                        .bind(now, order.id, pay.hash),
+                ]);
+                return changes(update) === 1 ? status : "taken";
+            }
+            catch (e) {
+                if (isUnique(e))
+                    return "used";
+                throw e;
+            }
+        },
+        async claimScan(now, gapMs) {
+            const r = await db
+                .prepare(`INSERT INTO ${T.meta} (key, value, at) VALUES ('scan', '', ?) ON CONFLICT (key) DO UPDATE SET at = excluded.at WHERE ${T.meta}.at <= ?`)
+                .bind(now, now - gapMs)
+                .run();
+            return changes(r) === 1;
+        },
+        async readRate() {
+            const r = await db.prepare(`SELECT value, at FROM ${T.meta} WHERE key = 'rate'`).first();
+            return r ? parseRate(r.value, Number(r.at)) : null;
+        },
+        async saveRate(rate) {
+            await db
+                .prepare(`INSERT INTO ${T.meta} (key, value, at) VALUES ('rate', ?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value, at = excluded.at`)
+                .bind(JSON.stringify({ usd: rate.usd, sources: rate.sources }), rate.at)
+                .run();
+        },
+        async forget(player, now) {
+            await tidy(now);
+            const w = await waiting(player);
+            if (Number(w?.n ?? 0) > 0)
+                return { deleted: 0, kept: 0, waitUntil: Number(w.until) };
+            // One batch, and each statement holds the money gate again: an order made meanwhile stops every one of them.
+            const gate = `NOT EXISTS (SELECT 1 FROM ${T.orders} WHERE player = ?1 AND amount_lock IS NOT NULL)`;
+            const done = await db.batch([
+                db.prepare(`DELETE FROM ${T.owned} WHERE player = ?1 AND ${gate}`).bind(player),
+                db.prepare(`DELETE FROM ${T.orders} WHERE player = ?1 AND hash IS NULL AND amount_lock IS NULL AND ${gate}`).bind(player),
+                // A paid order keeps no payer; a paid-late one keeps it: the creator sends that payment back by hand.
+                db.prepare(`UPDATE ${T.orders} SET payer = ?2 WHERE payer = ?1 AND status = 'paid' AND ${gate}`).bind(player, FORGOTTEN),
+                db.prepare(`UPDATE ${T.orders} SET player = ?2, visitor = NULL WHERE player = ?1 AND hash IS NOT NULL AND ${gate}`).bind(player, FORGOTTEN),
+            ]);
+            const [owned, orders, , kept] = done.map(changes);
+            if (owned + orders + kept === 0) {
+                const again = await waiting(player);
+                if (Number(again?.n ?? 0) > 0)
+                    return { deleted: 0, kept: 0, waitUntil: Number(again.until) };
+            }
+            return { deleted: owned + orders, kept, waitUntil: null };
+        },
+    };
+}

package/dist/shop/adapters/firestore.d.ts

@@ -0,0 +1,53 @@
+import { type ShopStore } from "../store.js";
+export type ShopDocSnap = {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+};
+export interface ShopDocRef {
+    get(): Promise<ShopDocSnap>;
+}
+export type ShopQuerySnap = {
+    docs: {
+        id: string;
+        ref: ShopDocRef;
+        data(): Record<string, unknown>;
+    }[];
+};
+export interface ShopQuery {
+    where(field: string, op: "==" | "<", value: unknown): ShopQuery;
+    limit(n: number): ShopQuery;
+    get(): Promise<ShopQuerySnap>;
+}
+export interface ShopCollection extends ShopQuery {
+    doc(id: string): ShopDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface ShopTransaction {
+    get(ref: ShopDocRef): Promise<ShopDocSnap>;
+    set(ref: ShopDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: ShopDocRef): unknown;
+}
+export interface ShopBatch {
+    set(ref: ShopDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: ShopDocRef): unknown;
+    commit(): Promise<unknown>;
+}
+export interface FirestoreShopLike {
+    collection(name: string): ShopCollection;
+    runTransaction<T>(fn: (tx: ShopTransaction) => Promise<T>): Promise<T>;
+    batch(): ShopBatch;
+}
+export type ShopCollections = {
+    orders?: string;
+    owned?: string;
+    meta?: string;
+    amounts?: string;
+    hashes?: string;
+};
+/** The most documents one query reads: a small game's orders of one player, or its held amounts. */
+export declare const FIRESTORE_SHOP_SCAN = 2000;
+export declare function createFirestoreShop(db: FirestoreShopLike, collections?: ShopCollections): ShopStore;

package/dist/shop/adapters/firestore.js

@@ -0,0 +1,245 @@
+// The shop store for a game on Firestore (the Admin SDK). The package has no Firebase dependency: the adapter uses the small interface below, which the
+// Admin SDK's `Firestore` fits. It reads and writes ONLY its five collections.
+//
+//   import { createFirestoreShop } from "@nano133/nanoterra/shop/firestore";
+//   const store = createFirestoreShop(getFirestore());
+//
+// The data model (the five collection names can be changed; the first three are the ones the admin's Firestore store reads):
+//   orders/{id}               { player, lookId, usd, rate, amount, amountLock, status, createdAt, expiresAt, holdUntil, hash, payer, paidAt, visitor }
+//   owned/{player__lookId}    { player, lookId, orderId, grantedAt }       (the player's id with encodeURIComponent: a Nano address stays as it is)
+//   meta/rate                 { value: JSON { usd, sources }, at }          meta/scan { value: "", at }
+//   shop_amounts/{amount}     { orderId, holdUntil }   the reservation: a document for each held amount, so two orders cannot hold one (a transaction makes it)
+//   shop_hashes/{hash}        { orderId }              one payment pays one order: a document for each recorded payment
+// Every write that a rule depends on is a transaction that reads what it checks. Indexes: the single-field indexes Firestore makes by itself are enough
+// (the queries are equalities, and one `<` on shop_amounts.holdUntil).
+import { paidStatus } from "../orders.js";
+import { FORGOTTEN } from "../store.js";
+/** The most documents one query reads: a small game's orders of one player, or its held amounts. */
+export const FIRESTORE_SHOP_SCAN = 2000;
+const text = (v, fallback = "") => (typeof v === "string" ? v : fallback);
+const num = (v, fallback = 0) => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
+const orNull = (v) => (typeof v === "string" ? v : null);
+const STATUSES = ["open", "paid", "expired", "paid_late"];
+function orderOf(id, d) {
+    return {
+        id,
+        player: text(d.player),
+        lookId: text(d.lookId),
+        usd: text(d.usd, "0"),
+        rate: num(d.rate),
+        amount: text(d.amount, "0"),
+        amountLock: orNull(d.amountLock),
+        status: STATUSES.includes(d.status) ? d.status : "expired",
+        createdAt: num(d.createdAt),
+        expiresAt: num(d.expiresAt),
+        holdUntil: num(d.holdUntil),
+        hash: orNull(d.hash),
+        payer: orNull(d.payer),
+        paidAt: typeof d.paidAt === "number" ? d.paidAt : null,
+        visitor: orNull(d.visitor),
+    };
+}
+const dataOf = (o) => ({
+    player: o.player,
+    lookId: o.lookId,
+    usd: o.usd,
+    rate: o.rate,
+    amount: o.amount,
+    amountLock: o.amountLock,
+    status: o.status,
+    createdAt: o.createdAt,
+    expiresAt: o.expiresAt,
+    holdUntil: o.holdUntil,
+    hash: o.hash,
+    payer: o.payer,
+    paidAt: o.paidAt,
+    visitor: o.visitor,
+});
+export function createFirestoreShop(db, collections = {}) {
+    const C = {
+        orders: collections.orders ?? "orders",
+        owned: collections.owned ?? "owned",
+        meta: collections.meta ?? "meta",
+        amounts: collections.amounts ?? "shop_amounts",
+        hashes: collections.hashes ?? "shop_hashes",
+    };
+    const col = (name) => db.collection(C[name]);
+    const ownedId = (player, lookId) => `${encodeURIComponent(player)}__${lookId}`;
+    const ordersOf = (player) => col("orders").where("player", "==", player).limit(FIRESTORE_SHOP_SCAN);
+    async function commitAll(writes) {
+        // A batch holds at most 500 writes.
+        for (let i = 0; i < writes.length; i += 400) {
+            const batch = db.batch();
+            for (const w of writes.slice(i, i + 400))
+                w(batch);
+            await batch.commit();
+        }
+    }
+    const tidy = async (now) => {
+        // Each change reads the document again in a transaction: a blind write could undo a payment that was recorded meanwhile.
+        const open = (await col("orders").where("status", "==", "open").limit(FIRESTORE_SHOP_SCAN).get()).docs.filter((d) => num(d.data().expiresAt) < now);
+        for (const d of open) {
+            await db.runTransaction(async (tx) => {
+                const snap = await tx.get(d.ref);
+                const o = snap.exists ? snap.data() : undefined;
+                if (o && o.status === "open" && num(o.expiresAt) < now)
+                    tx.set(d.ref, { status: "expired" }, { merge: true });
+            });
+        }
+        const stale = (await col("amounts").where("holdUntil", "<", now).limit(FIRESTORE_SHOP_SCAN).get()).docs;
+        for (const d of stale) {
+            await db.runTransaction(async (tx) => {
+                const snap = await tx.get(d.ref);
+                const lock = snap.exists ? snap.data() : undefined;
+                if (!lock || num(lock.holdUntil) >= now)
+                    return;
+                const orderRef = col("orders").doc(text(lock.orderId));
+                const order = await tx.get(orderRef);
+                tx.delete(d.ref);
+                if (order.exists && order.data()?.amountLock === d.id)
+                    tx.set(orderRef, { amountLock: null }, { merge: true });
+            });
+        }
+    };
+    return {
+        tidy,
+        async heldAmounts(amounts) {
+            const want = new Set(amounts);
+            return new Set((await col("amounts").limit(FIRESTORE_SHOP_SCAN).get()).docs.map((d) => d.id).filter((id) => want.has(id)));
+        },
+        async insert(o) {
+            const lockRef = col("amounts").doc(o.amount);
+            const orderRef = col("orders").doc(o.id);
+            return db.runTransaction(async (tx) => {
+                const [lock, order] = [await tx.get(lockRef), await tx.get(orderRef)];
+                if (lock.exists || order.exists)
+                    return false;
+                tx.set(lockRef, { orderId: o.id, holdUntil: o.holdUntil });
+                tx.set(orderRef, dataOf({ ...o, amountLock: o.amount, status: "open", hash: null, payer: null, paidAt: null }));
+                return true;
+            });
+        },
+        async order(id) {
+            const snap = await col("orders").doc(id).get();
+            const d = snap.exists ? snap.data() : undefined;
+            return d ? orderOf(id, d) : null;
+        },
+        async openOrder(player, lookId, until) {
+            const docs = (await ordersOf(player).where("lookId", "==", lookId).where("status", "==", "open").get()).docs;
+            const list = docs.map((d) => orderOf(d.id, d.data())).filter((o) => o.player === player && o.expiresAt > until).sort((a, b) => b.createdAt - a.createdAt);
+            return list[0] ?? null;
+        },
+        async countOpen(player, now) {
+            return (await ordersOf(player).where("status", "==", "open").get()).docs.map((d) => orderOf(d.id, d.data())).filter((o) => o.player === player && o.expiresAt > now).length;
+        },
+        async owns(player, lookId) {
+            const snap = await col("owned").doc(ownedId(player, lookId)).get();
+            return snap.exists && snap.data()?.player === player;
+        },
+        async owned(player) {
+            const rows = (await col("owned").where("player", "==", player).limit(FIRESTORE_SHOP_SCAN).get()).docs.map((d) => d.data());
+            return rows
+                .filter((r) => r.player === player)
+                .sort((a, b) => num(a.grantedAt) - num(b.grantedAt) || (text(a.lookId) < text(b.lookId) ? -1 : 1))
+                .map((r) => text(r.lookId));
+        },
+        async held() {
+            const locks = (await col("amounts").limit(FIRESTORE_SHOP_SCAN).get()).docs;
+            const out = [];
+            for (const l of locks) {
+                const id = text(l.data().orderId);
+                const snap = await col("orders").doc(id).get();
+                const d = snap.exists ? snap.data() : undefined;
+                if (d && d.amountLock === l.id)
+                    out.push(orderOf(id, d));
+            }
+            return out;
+        },
+        async usedHashes(hashes) {
+            const snaps = await Promise.all(hashes.map(async (h) => [h, await col("hashes").doc(h).get()]));
+            return new Set(snaps.filter(([, s]) => s.exists).map(([h]) => h));
+        },
+        async settle(order, pay, now) {
+            const orderRef = col("orders").doc(order.id);
+            const hashRef = col("hashes").doc(pay.hash);
+            return db.runTransaction(async (tx) => {
+                const hash = await tx.get(hashRef);
+                const snap = await tx.get(orderRef);
+                const d = snap.exists ? snap.data() : undefined;
+                const lockRef = col("amounts").doc(text(d?.amountLock, order.amount));
+                const lock = await tx.get(lockRef);
+                const o = d ? orderOf(order.id, d) : null;
+                const ownedRef = col("owned").doc(ownedId(o?.player ?? order.player, o?.lookId ?? order.lookId));
+                const owned = await tx.get(ownedRef);
+                if (!o || (o.status !== "open" && o.status !== "expired") || o.amountLock === null)
+                    return "taken";
+                if (hash.exists)
+                    return "used";
+                const status = paidStatus(o, pay.seenMs);
+                tx.set(orderRef, dataOf({ ...o, status, hash: pay.hash, payer: pay.payer, paidAt: pay.seenMs, amountLock: null }));
+                if (lock.exists && lock.data()?.orderId === order.id)
+                    tx.delete(lockRef);
+                tx.set(hashRef, { orderId: order.id });
+                if (status === "paid" && !owned.exists)
+                    tx.set(ownedRef, { player: o.player, lookId: o.lookId, orderId: o.id, grantedAt: now });
+                return status;
+            });
+        },
+        async claimScan(now, gapMs) {
+            const ref = col("meta").doc("scan");
+            return db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                const at = snap.exists ? num(snap.data()?.at, -Infinity) : -Infinity;
+                if (at > now - gapMs)
+                    return false;
+                tx.set(ref, { value: "", at: now });
+                return true;
+            });
+        },
+        async readRate() {
+            const snap = await col("meta").doc("rate").get();
+            const d = snap.exists ? snap.data() : undefined;
+            if (!d || typeof d.value !== "string" || typeof d.at !== "number")
+                return null;
+            try {
+                const v = JSON.parse(d.value);
+                if (typeof v.usd !== "number" || !Number.isFinite(v.usd) || !Array.isArray(v.sources) || !v.sources.every((s) => typeof s === "string"))
+                    return null;
+                return { usd: v.usd, sources: v.sources, at: d.at };
+            }
+            catch {
+                return null;
+            }
+        },
+        async saveRate(rate) {
+            const batch = db.batch();
+            batch.set(col("meta").doc("rate"), { value: JSON.stringify({ usd: rate.usd, sources: rate.sources }), at: rate.at });
+            await batch.commit();
+        },
+        async forget(player, now) {
+            await tidy(now);
+            const mine = (await ordersOf(player).get()).docs.map((d) => ({ ref: d.ref, o: orderOf(d.id, d.data()) })).filter((x) => x.o.player === player);
+            const waiting = mine.filter((x) => x.o.amountLock !== null);
+            if (waiting.length)
+                return { deleted: 0, kept: 0, waitUntil: Math.max(...waiting.map((x) => x.o.holdUntil)) };
+            const owned = (await col("owned").where("player", "==", player).limit(FIRESTORE_SHOP_SCAN).get()).docs.filter((d) => d.data().player === player);
+            const paidBy = (await col("orders").where("payer", "==", player).limit(FIRESTORE_SHOP_SCAN).get()).docs.filter((d) => d.data().status === "paid");
+            const writes = [];
+            let deleted = 0;
+            let kept = 0;
+            for (const d of owned)
+                (writes.push((b) => b.delete(d.ref)), deleted++);
+            for (const { ref, o } of mine) {
+                if (o.hash === null)
+                    (writes.push((b) => b.delete(ref)), deleted++);
+                else
+                    (writes.push((b) => b.set(ref, { player: FORGOTTEN, visitor: null }, { merge: true })), kept++);
+            }
+            // A paid order keeps no payer; a paid-late one keeps it: the creator sends that payment back by hand.
+            for (const d of paidBy)
+                writes.push((b) => b.set(d.ref, { payer: FORGOTTEN }, { merge: true }));
+            await commitAll(writes);
+            return { deleted, kept, waitUntil: null };
+        },
+    };
+}

package/dist/shop/address.d.ts

@@ -0,0 +1,14 @@
+/** The address that belongs to nobody (its key is all zeros): the example in the game starter's wrangler.jsonc. A shop with it is in test mode. */
+export declare const EXAMPLE_ADDRESS = "nano_1111111111111111111111111111111111111111111111111111hifc8npp";
+/** BLAKE2b of at most 128 bytes (one block), `outLen` bytes, no key (RFC 7693). Enough for a checksum of a 32-byte key. */
+export declare function blake2bShort(input: Uint8Array, outLen: number): Uint8Array;
+/**
+ * True for a whole Nano address: "nano_" (or "xrb_"), its shape, and its checksum (the last 8 characters: the BLAKE2b-40 of the key, bytes reversed).
+ * One wrong character fails it.
+ */
+export declare function validAddress(address: unknown): address is string;
+/**
+ * The payee as the shop uses it: a whole address in lower case with the "nano_" prefix, or null (no address, the example, or a wrong checksum). With
+ * null the shop is in test mode: no pay screen shows an address, a QR code or a wallet link.
+ */
+export declare function payeeOf(address: unknown): string | null;

package/dist/shop/address.js

@@ -0,0 +1,104 @@
+// The creator's address (the payee): a whole Nano address, its shape AND its checksum. A typo in a receive address would send every payment to an
+// account nobody holds the key for, so the shop sells only to an address whose checksum is right (the game starter checks it with @nano133/signin's
+// `validAddress`; this package has no dependency, so it carries the 5-byte BLAKE2b that the checksum needs, and nothing else of it).
+/** The address that belongs to nobody (its key is all zeros): the example in the game starter's wrangler.jsonc. A shop with it is in test mode. */
+export const EXAMPLE_ADDRESS = "nano_1111111111111111111111111111111111111111111111111111hifc8npp";
+const ALPHABET = "13456789abcdefghijkmnopqrstuwxyz";
+const SHAPE = /^nano_[13][13456789abcdefghijkmnopqrstuwxyz]{59}$/;
+const MASK = (1n << 64n) - 1n;
+const IV = [
+    0x6a09e667f3bcc908n, 0xbb67ae8584caa73bn, 0x3c6ef372fe94f82bn, 0xa54ff53a5f1d36f1n, 0x510e527fade682d1n, 0x9b05688c2b3e6c1fn, 0x1f83d9abfb41bd6bn, 0x5be0cd19137e2179n,
+];
+const SIGMA = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+    [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+    [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4],
+    [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+    [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13],
+    [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+    [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11],
+    [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+    [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5],
+    [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+];
+const rotr = (x, n) => ((x >> n) | (x << (64n - n))) & MASK;
+/** BLAKE2b of at most 128 bytes (one block), `outLen` bytes, no key (RFC 7693). Enough for a checksum of a 32-byte key. */
+export function blake2bShort(input, outLen) {
+    if (input.length > 128 || outLen < 1 || outLen > 64)
+        throw new Error("blake2bShort: one block of at most 128 bytes, 1 to 64 bytes out");
+    const h = IV.slice();
+    h[0] ^= 0x01010000n ^ BigInt(outLen);
+    const block = new Uint8Array(128);
+    block.set(input);
+    const m = [];
+    for (let i = 0; i < 16; i++) {
+        let w = 0n;
+        for (let b = 7; b >= 0; b--)
+            w = (w << 8n) | BigInt(block[i * 8 + b]);
+        m.push(w);
+    }
+    const v = [...h, ...IV];
+    v[12] ^= BigInt(input.length);
+    v[14] ^= MASK;
+    const g = (a, b, c, d, x, y) => {
+        v[a] = (v[a] + v[b] + x) & MASK;
+        v[d] = rotr(v[d] ^ v[a], 32n);
+        v[c] = (v[c] + v[d]) & MASK;
+        v[b] = rotr(v[b] ^ v[c], 24n);
+        v[a] = (v[a] + v[b] + y) & MASK;
+        v[d] = rotr(v[d] ^ v[a], 16n);
+        v[c] = (v[c] + v[d]) & MASK;
+        v[b] = rotr(v[b] ^ v[c], 63n);
+    };
+    for (let r = 0; r < 12; r++) {
+        const s = SIGMA[r % 10];
+        g(0, 4, 8, 12, m[s[0]], m[s[1]]);
+        g(1, 5, 9, 13, m[s[2]], m[s[3]]);
+        g(2, 6, 10, 14, m[s[4]], m[s[5]]);
+        g(3, 7, 11, 15, m[s[6]], m[s[7]]);
+        g(0, 5, 10, 15, m[s[8]], m[s[9]]);
+        g(1, 6, 11, 12, m[s[10]], m[s[11]]);
+        g(2, 7, 8, 13, m[s[12]], m[s[13]]);
+        g(3, 4, 9, 14, m[s[14]], m[s[15]]);
+    }
+    const out = new Uint8Array(outLen);
+    for (let i = 0; i < outLen; i++)
+        out[i] = Number(((h[i >> 3] ^ v[i >> 3] ^ v[(i >> 3) + 8]) >> BigInt(8 * (i & 7))) & 0xffn);
+    return out;
+}
+/** Base-32 text (Nano's alphabet) as a big number. */
+const bitsOf = (text) => [...text].reduce((n, c) => (n << 5n) | BigInt(ALPHABET.indexOf(c)), 0n);
+/**
+ * True for a whole Nano address: "nano_" (or "xrb_"), its shape, and its checksum (the last 8 characters: the BLAKE2b-40 of the key, bytes reversed).
+ * One wrong character fails it.
+ */
+export function validAddress(address) {
+    if (typeof address !== "string")
+        return false;
+    const a = address.replace(/^xrb_/, "nano_");
+    if (!SHAPE.test(a))
+        return false;
+    const body = a.slice(5);
+    // 52 characters are 260 bits: 4 bits that must be zero, then the 32-byte key.
+    const key = bitsOf(body.slice(0, 52));
+    if (key >> 256n !== 0n)
+        return false;
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        bytes[i] = Number((key >> BigInt(8 * (31 - i))) & 0xffn);
+    const check = blake2bShort(bytes, 5).reverse();
+    const want = check.reduce((n, b) => (n << 8n) | BigInt(b), 0n);
+    return bitsOf(body.slice(52)) === want;
+}
+/**
+ * The payee as the shop uses it: a whole address in lower case with the "nano_" prefix, or null (no address, the example, or a wrong checksum). With
+ * null the shop is in test mode: no pay screen shows an address, a QR code or a wallet link.
+ */
+export function payeeOf(address) {
+    if (typeof address !== "string")
+        return null;
+    const a = address.trim().toLowerCase().replace(/^xrb_/, "nano_");
+    if (!a || a === EXAMPLE_ADDRESS)
+        return null;
+    return validAddress(a) ? a : null;
+}

package/dist/shop/amount.d.ts

@@ -0,0 +1,26 @@
+export { RAW_PER_XNO, xnoText } from "../admin/amount.js";
+/** One step: 0.0001 XNO. */
+export declare const STEP_RAW: bigint;
+/** Sane bounds for dollars per XNO: outside them a price feed is wrong, not the market. */
+export declare const MIN_RATE = 0.05;
+export declare const MAX_RATE = 100;
+/** The highest price a look can have, in US dollars (the looks file allows up to PRICE_MAX_USD, $1000). */
+export declare const MAX_USD = 10000;
+/** A raw amount: digits only, no leading zero, not zero, at most 39 digits. */
+export declare function isRaw(s: unknown): s is string;
+/** Whole steps of 0.0001 XNO, so at most four decimals. */
+export declare function isClean(raw: unknown): raw is string;
+/**
+ * The number of 0.0001 XNO steps for `usd` dollars at `rate` dollars per XNO, rounded UP (the creator never gets less than the price), or null when
+ * the price or the rate can't be used.
+ */
+export declare function stepsFromUsd(usd: number, rate: number): number | null;
+export declare function rawFromSteps(steps: number | bigint): string;
+/** The clean price in raw, or null. */
+export declare function priceRaw(usd: number, rate: number): string | null;
+/** A clean amount plus `more` steps. */
+export declare function plusSteps(raw: string, more: number): string;
+/** -1, 0 or 1. */
+export declare function compareRaw(a: string, b: string): number;
+/** The standard payment link: the amount in raw, every digit (docs.nano.org, URI and QR code standards). */
+export declare function nanoUri(address: string, raw: string): string;