@nano133/nanoterra 0.1.0 → 0.2.0

package/dist/looks/look.js

@@ -4,11 +4,22 @@
 export const HATS = ["cap", "beanie", "crown", "tophat"];
 export const ID_PATTERN = /^[a-z0-9-]{1,40}$/;
 export const COLOR_PATTERN = /^#[0-9a-f]{6}$/i;
+/** At most this many slots on a look. */
+export const SLOTS_MAX = 8;
+/** A slot's name: 1 to 24 lowercase letters, digits or dashes, starting with a letter. */
+export const SLOT_NAME_PATTERN = /^[a-z][a-z0-9-]{0,23}$/;
+/** Names that a slot may not have: they mean something to an object (`constructor`, `prototype`). */
+export const RESERVED_SLOT_NAMES = ["constructor", "prototype"];
+/** A slot's value that is a word: 1 to 40 lowercase letters, digits or dashes. (The other kind of value is a colour, COLOR_PATTERN.) */
+export const SLOT_WORD_PATTERN = /^[a-z0-9-]{1,40}$/;
 export const NAME_MAX = 40;
 export const PRICE_MAX_USD = 1000;
-/** Whether a price has no fraction of a cent. `Math.round(x * 100) === x * 100` is wrong for 0.07, 0.29 and 1.1 (floating point). */
+/**
+ * Whether a price has no fraction of a cent. `Math.round(x * 100) === x * 100` is wrong for 0.07, 0.29 and 1.1 (floating point), and a tolerance is wrong the other way (0.300000001
+ * and 1e-9 would pass): a price is whole cents when it is exactly the number that its own two-decimal text names.
+ */
 export function wholeCents(usd) {
-    return Math.abs(usd * 100 - Math.round(usd * 100)) < 1e-6;
+    return typeof usd === "number" && Number.isFinite(usd) && Number(usd.toFixed(2)) === usd;
 }
 /** Every mistake in a list of looks (looks.json as it was read), in the order of the list. An empty array means the list is good. */
 export function lookProblems(raw) {
@@ -41,17 +52,62 @@ export function lookProblems(raw) {
             add("change.hat", `"change.hat" must be one of ${HATS.join(", ")}`);
         if (v.change?.hatColor !== undefined && (typeof v.change.hatColor !== "string" || !COLOR_PATTERN.test(v.change.hatColor)))
             add("change.hatColor", '"change.hatColor" must be a colour like "#1c6e4f"');
+        if (v.slots !== undefined)
+            slotProblems(v.slots).forEach((s) => add(s.field, s.message));
     });
     if (!out.length && !free)
         out.push({ look: null, field: "free", message: "looks.json needs at least one free look (priceUsd 0): every player starts with it" });
     return out;
 }
+/** Whether `v` is a plain object (not null, not a list, not a class instance). */
+const isPlain = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+/** Whether a slot's value is good: a word or a colour. */
+export const slotValueOk = (v) => typeof v === "string" && (SLOT_WORD_PATTERN.test(v) || COLOR_PATTERN.test(v));
+/** The mistakes in one look's `slots` (the look's own message is added by the caller): the field is "slots" or "slots.<name>". */
+function slotProblems(slots) {
+    if (!isPlain(slots))
+        return [{ field: "slots", message: '"slots" must be an object of names and values, like { "wings": "ember" }' }];
+    const names = Object.keys(slots);
+    const out = [];
+    if (names.length > SLOTS_MAX)
+        out.push({ field: "slots", message: `"slots" can have at most ${SLOTS_MAX} slots (this one has ${names.length})` });
+    for (const name of names) {
+        if (!SLOT_NAME_PATTERN.test(name))
+            out.push({ field: `slots.${name}`, message: `the slot name "${name}" must be 1 to 24 lowercase letters, digits or dashes, starting with a letter` });
+        else if (RESERVED_SLOT_NAMES.includes(name))
+            out.push({ field: `slots.${name}`, message: `the slot name "${name}" is reserved: choose another` });
+        else if (!slotValueOk(slots[name]))
+            out.push({ field: `slots.${name}`, message: `"slots.${name}" must be a word (1 to 40 lowercase letters, digits or dashes) or a colour like "#ffcf5a"` });
+    }
+    return out;
+}
+/**
+ * The slots as a clean copy, or undefined when there are none (an empty `slots` is the same as none). The creator's order of names is kept. A COLOUR is written in lower case
+ * ("#ffcf5a"), so the game always reads one text for one colour: a change of only the case of a colour is then no change at all, for the game as for the check.
+ */
+export function cleanSlots(slots) {
+    if (!slots)
+        return undefined;
+    const names = Object.keys(slots);
+    return names.length ? Object.fromEntries(names.map((n) => [n, typeof slots[n] === "string" && COLOR_PATTERN.test(slots[n]) ? slots[n].toLowerCase() : slots[n]])) : undefined;
+}
 /** The looks, or an Error that says the first mistake in plain words. The same words as the starter's `checkLooks`. */
-export function checkLooks(raw) {
+export function checkLooks(rawInput) {
+    // One snapshot of the data is checked AND copied: a getter or a changing value cannot be good for the check and something else for the copy. (JSON cannot hold one.)
+    let raw = rawInput;
+    try {
+        raw = rawInput === undefined ? undefined : JSON.parse(JSON.stringify(rawInput));
+    }
+    catch {
+        throw new Error("looks.json must be plain JSON data");
+    }
     const first = lookProblems(raw)[0];
     if (first)
         throw new Error(first.message);
-    return raw.map((l) => ({ id: l.id, name: l.name, priceUsd: l.priceUsd, change: { body: l.change.body, hat: l.change.hat, hatColor: l.change.hatColor } }));
+    return raw.map((l) => {
+        const slots = cleanSlots(l.slots);
+        return { id: l.id, name: l.name, priceUsd: l.priceUsd, change: { body: l.change.body, hat: l.change.hat, hatColor: l.change.hatColor }, ...(slots ? { slots } : {}) };
+    });
 }
 /** "$0.25" */
 export const usdText = (usd) => `$${usd.toFixed(2)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano133/nanoterra",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Nanoterra for a creator's game, in one package: the player's sign-in ticket, the player's character (a toon body on the island's skeleton) and the looks ladder.",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,13 @@
     "./character": { "types": "./dist/character/index.d.ts", "import": "./dist/character/index.js" },
     "./character/record": { "types": "./dist/character/pure.d.ts", "import": "./dist/character/pure.js" },
     "./ticket": { "types": "./dist/ticket/index.d.ts", "import": "./dist/ticket/index.js" },
-    "./looks": { "types": "./dist/looks/index.d.ts", "import": "./dist/looks/index.js" }
+    "./looks": { "types": "./dist/looks/index.d.ts", "import": "./dist/looks/index.js" },
+    "./admin": { "types": "./dist/admin/index.d.ts", "import": "./dist/admin/index.js" },
+    "./admin/conformance": { "types": "./dist/admin/conformance.d.ts", "import": "./dist/admin/conformance.js" },
+    "./admin/d1": { "types": "./dist/admin/adapters/d1.d.ts", "import": "./dist/admin/adapters/d1.js" },
+    "./admin/firestore": { "types": "./dist/admin/adapters/firestore.d.ts", "import": "./dist/admin/adapters/firestore.js" },
+    "./admin/panel": { "types": "./dist/admin/panel/index.d.ts", "import": "./dist/admin/panel/index.js" },
+    "./admin/style.css": "./src/admin/panel/style.css"
   },
   "sideEffects": false,
   "files": ["dist", "src", "README.md", "CHANGELOG.md", "LICENSE", "ai"],
@@ -25,6 +31,7 @@
   "devDependencies": {
     "@types/node": "^26.6.3",
     "@types/three": "^0.186.0",
+    "happy-dom": "^20.14.6",
     "three": "^0.186.0",
     "tsx": "^4.23.15",
     "typescript": "5.9"

package/src/admin/adapters/d1.ts

@@ -0,0 +1,94 @@
+// The admin store for a game on Cloudflare D1, with the tables of the game starter (migrations/0001_init.sql): `meta`, `orders` and `owned`.
+// It writes ONLY the two settings (`setting:character`, `setting:signin` in `meta`); everything else it does is a read, except when the game turns the sign-in list on
+// (`logins: true`): then the one other write is `DELETE FROM sessions WHERE scope = 'admin'` ("sign out everywhere").
+//
+//   import { createD1Store } from "@nano133/nanoterra/admin/d1";
+//   const store = createD1Store(env.DB);
+
+import { ORDERS_SHOWN, moneyOf, parseRate, shapeOrders, shapePlayers, type OrderRow } from "../summary.js";
+import type { AdminStore, StoreSummary } from "../store.js";
+import type { GamePatch } from "../switches.js";
+
+/** The part of D1 that the adapter uses. Cloudflare's `D1Database` fits it. */
+export interface D1StatementLike {
+  bind(...values: unknown[]): D1StatementLike;
+  all<T = unknown>(): Promise<{ results: T[] }>;
+  first<T = unknown>(): Promise<T | null>;
+  run(): Promise<unknown>;
+}
+export interface D1Like {
+  prepare(query: string): D1StatementLike;
+  batch(statements: D1StatementLike[]): Promise<unknown[]>;
+}
+
+export const D1_KEYS = { character: "setting:character", signin: "setting:signin" } as const;
+
+type Row = { id: string; player: string; look_id: string; usd: string; amount: string; status: string; created_at: number; expires_at: number; paid_at: number | null; payer: string | null; hash: string | null };
+
+/**
+ * The admin store for D1. With `logins: true` it also lists the last admin sign-ins (the table `admin_logins`: at, country, browser) and can sign the owner out everywhere
+ * (`DELETE FROM sessions WHERE scope = 'admin'`, and `UPDATE signin_requests SET delivered = 1, expires_at = 0 WHERE scope = 'admin' AND delivered = 0` so that a request signed a moment ago
+ * cannot make a new login afterwards, and a wallet app that is answered later is told that the request has ended): the game's `sessions` and `signin_requests` tables must have a `scope` column ('admin' for an admin login or request) and the game must write
+ * `admin_logins` when it makes an admin login. Without the option the store has neither call, so a game that has not made those tables is not broken by it.
+ */
+export function createD1Store(db: D1Like, options: { logins?: boolean } = {}): AdminStore {
+  const store: AdminStore = {
+    async readSettings() {
+      const rows = (await db.prepare("SELECT key, value FROM meta WHERE key IN (?, ?)").bind(D1_KEYS.character, D1_KEYS.signin).all<{ key: string; value: string }>()).results;
+      const row = (key: string) => rows.find((r) => r.key === key)?.value;
+      return { character: row(D1_KEYS.character), signin: row(D1_KEYS.signin) };
+    },
+
+    async saveSettings(patch: GamePatch, now: number) {
+      const write = (key: string, value: string) =>
+        db.prepare("INSERT INTO meta (key, value, at) VALUES (?, ?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value, at = excluded.at").bind(key, value, now);
+      const batch = [];
+      if (patch.character) batch.push(write(D1_KEYS.character, patch.character));
+      if (patch.signin) batch.push(write(D1_KEYS.signin, patch.signin));
+      if (batch.length) await db.batch(batch);
+    },
+
+    async summary(now: number): Promise<StoreSummary> {
+      // The game starter's own queries: the counts and the totals are over ALL orders, the list is the newest ORDERS_SHOWN.
+      const orders = (
+        await db
+          .prepare("SELECT id, player, look_id, usd, amount, status, created_at, expires_at, paid_at, payer, hash FROM orders ORDER BY created_at DESC LIMIT ?")
+          .bind(ORDERS_SHOWN)
+          .all<Row>()
+      ).results;
+      const owned = (await db.prepare("SELECT player, look_id, granted_at FROM owned ORDER BY player, granted_at").all<{ player: string; look_id: string; granted_at: number }>()).results;
+      const sums = (await db.prepare("SELECT status, amount, usd FROM orders WHERE status IN ('paid', 'paid_late')").all<{ status: string; amount: string; usd: string }>()).results;
+      const grouped = (await db.prepare("SELECT status, expires_at < ? AS past, COUNT(*) AS n FROM orders GROUP BY status, past").bind(now).all<{ status: string; past: number; n: number }>()).results;
+      const rate = await db.prepare("SELECT value, at FROM meta WHERE key = 'rate'").first<{ value: string; at: number }>();
+
+      const counts = { open: 0, paid: 0, expired: 0, paid_late: 0 };
+      for (const c of grouped) {
+        const key = c.status === "open" && c.past ? "expired" : c.status;
+        if (Object.hasOwn(counts, key)) counts[key as keyof typeof counts] += c.n;
+      }
+      const money = (status: string) => moneyOf(sums.filter((s) => s.status === status).map((s) => ({ amountRaw: s.amount, usd: s.usd })));
+      const rows: OrderRow[] = orders.map((o) => ({ id: o.id, player: o.player, lookId: o.look_id, usd: o.usd, amountRaw: o.amount, status: o.status, createdAt: o.created_at, expiresAt: o.expires_at, paidAt: o.paid_at, payer: o.payer, hash: o.hash }));
+      return {
+        counts,
+        totals: { paid: money("paid"), paidLate: money("paid_late") },
+        orders: shapeOrders(rows, now),
+        players: shapePlayers(owned.map((o) => ({ player: o.player, lookId: o.look_id, at: o.granted_at }))),
+        rate: parseRate(rate?.value, rate?.at),
+      };
+    },
+  };
+  if (options.logins) {
+    store.recentLogins = async (limit) => {
+      const n = Math.min(Math.max(Math.floor(Number(limit)) || 0, 0), 50);
+      const rows = (await db.prepare("SELECT at, country, browser FROM admin_logins ORDER BY at DESC, id DESC LIMIT ?").bind(n).all<{ at: number; country: string | null; browser: string }>()).results;
+      return rows.map((r) => ({ at: r.at, country: r.country, browser: r.browser }));
+    };
+    // One batch: the admin sessions are deleted, AND every admin sign-in request that was started but not delivered is marked delivered, so a request that the owner signed a moment
+    // ago cannot make a new admin login after "Sign out everywhere" (its check would answer "used").
+    store.signOutEverywhere = async () => {
+      const done = (await db.batch([db.prepare("DELETE FROM sessions WHERE scope = 'admin'"), db.prepare("UPDATE signin_requests SET delivered = 1, expires_at = 0 WHERE scope = 'admin' AND delivered = 0")])) as ({ meta?: { changes?: number } } | undefined)[];
+      return done[0]?.meta?.changes ?? 0;
+    };
+  }
+  return store;
+}

package/src/admin/adapters/firestore.ts

@@ -0,0 +1,78 @@
+// The admin 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 writes ONLY the two settings; everything else it does is a read.
+//
+// The data model (the names a game must have; only the three collection names can be changed):
+//   meta/{key}          { value: string, at: number }          keys "setting:character", "setting:signin", "rate" (value is JSON { usd, sources })
+//   orders/{id}         { player, lookId, usd, amount, status, createdAt, expiresAt, paidAt, payer, hash }   `amount` is the raw amount as text
+//   owned/{player__lookId}  { player, lookId, orderId, grantedAt }
+//
+// The summary reads the newest 5000 orders (the counts and the totals are over those) and every owned look: for a small game. A big game should keep running totals.
+
+import { parseRate, summarize, type OrderRow } from "../summary.js";
+import type { AdminStore, StoreSummary } from "../store.js";
+import type { GamePatch } from "../switches.js";
+
+export interface FirestoreDocLike {
+  get(): Promise<{ exists: boolean; data(): Record<string, unknown> | undefined }>;
+}
+export interface FirestoreQueryLike {
+  orderBy(field: string, direction?: "asc" | "desc"): FirestoreQueryLike;
+  limit(n: number): FirestoreQueryLike;
+  get(): Promise<{ docs: { id: string; data(): Record<string, unknown> }[] }>;
+}
+export interface FirestoreCollectionLike extends FirestoreQueryLike {
+  doc(id: string): FirestoreDocLike;
+}
+export interface FirestoreBatchLike {
+  set(doc: FirestoreDocLike, data: Record<string, unknown>, options?: { merge?: boolean }): unknown;
+  commit(): Promise<unknown>;
+}
+export interface FirestoreLike {
+  collection(name: string): FirestoreCollectionLike;
+  batch(): FirestoreBatchLike;
+}
+
+export const FIRESTORE_SCAN_LIMIT = 5000;
+export const FIRESTORE_KEYS = { character: "setting:character", signin: "setting:signin" } as const;
+
+const text = (v: unknown, fallback = ""): string => (typeof v === "string" ? v : fallback);
+const num = (v: unknown, fallback = 0): number => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
+const orNull = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+export function createFirestoreStore(db: FirestoreLike, collections: { meta?: string; orders?: string; owned?: string } = {}): AdminStore {
+  const meta = collections.meta ?? "meta";
+  const orders = collections.orders ?? "orders";
+  const owned = collections.owned ?? "owned";
+  const valueOf = async (key: string) => {
+    const snap = await db.collection(meta).doc(key).get();
+    return snap.exists ? snap.data() : undefined;
+  };
+  return {
+    async readSettings() {
+      const [character, signin] = await Promise.all([valueOf(FIRESTORE_KEYS.character), valueOf(FIRESTORE_KEYS.signin)]);
+      return { character: character?.value, signin: signin?.value };
+    },
+
+    async saveSettings(patch: GamePatch, now: number) {
+      const batch = db.batch();
+      let n = 0;
+      if (patch.character) (batch.set(db.collection(meta).doc(FIRESTORE_KEYS.character), { value: patch.character, at: now }), n++);
+      if (patch.signin) (batch.set(db.collection(meta).doc(FIRESTORE_KEYS.signin), { value: patch.signin, at: now }), n++);
+      if (n) await batch.commit();
+    },
+
+    async summary(now: number): Promise<StoreSummary> {
+      const [orderDocs, ownedDocs, rate] = await Promise.all([
+        db.collection(orders).orderBy("createdAt", "desc").limit(FIRESTORE_SCAN_LIMIT).get(),
+        db.collection(owned).get(),
+        valueOf("rate"),
+      ]);
+      const rows: OrderRow[] = orderDocs.docs.map((d) => {
+        const o = d.data();
+        return { id: d.id, player: text(o.player), lookId: text(o.lookId), usd: text(o.usd, "0"), amountRaw: text(o.amount, "0"), status: text(o.status, "open"), createdAt: num(o.createdAt), expiresAt: num(o.expiresAt), paidAt: typeof o.paidAt === "number" ? o.paidAt : null, payer: orNull(o.payer), hash: orNull(o.hash) };
+      });
+      const list = ownedDocs.docs.map((d) => ({ player: text(d.data().player), lookId: text(d.data().lookId), at: num(d.data().grantedAt) }));
+      return summarize(rows, list, parseRate(rate?.value, rate?.at), now);
+    },
+  };
+}

package/src/admin/amount.ts

@@ -0,0 +1,14 @@
+// Nano amounts for the summary. 1 XNO is 10^30 raw, more than a JavaScript number holds exactly, so amounts are decimal strings and the sums are BigInt.
+
+export const RAW_PER_XNO = 10n ** 30n;
+
+/** A raw amount as XNO with every significant digit: "0.2512". Throws on text that is not a whole number. */
+export function xnoText(raw: string): string {
+  const n = BigInt(raw);
+  const whole = n / RAW_PER_XNO;
+  const frac = (n % RAW_PER_XNO).toString().padStart(30, "0").replace(/0+$/, "");
+  return frac ? `${whole}.${frac}` : `${whole}`;
+}
+
+/** A raw amount that can be added: digits only, at most 39 of them. Anything else is not counted (a bad row must not break the summary). */
+export const isRawText = (s: unknown): s is string => typeof s === "string" && /^[0-9]{1,39}$/.test(s);