@nano133/nanoterra 0.1.0 → 0.2.0

package/src/admin/summary.ts

@@ -0,0 +1,103 @@
+// The numbers of the summary from the rows of the orders, the same for every adapter: the counts by status, the totals and the shape of an order.
+// An adapter reads its rows; this file turns them into a `StoreSummary`.
+
+import { isRawText, xnoText } from "./amount.js";
+import type { AdminOrder, Money, StoreSummary } from "./store.js";
+
+/** An order as an adapter reads it: the amount is the raw amount (digits), the times are ms. */
+export type OrderRow = {
+  id: string;
+  player: string;
+  lookId: string;
+  usd: string;
+  amountRaw: string;
+  status: string;
+  createdAt: number;
+  expiresAt: number;
+  paidAt: number | null;
+  payer: string | null;
+  hash: string | null;
+};
+
+export const ORDERS_SHOWN = 500;
+
+/** Cents from a dollar text like "0.25". Anything that is not plain dollars (a sign, an exponent, hex) counts as 0: a bad row must not change a total. */
+const toCents = (usd: string): number => {
+  if (typeof usd !== "string" || !/^\d{1,9}(\.\d{1,8})?$/.test(usd)) return 0;
+  return Math.round(Number(usd) * 100);
+};
+
+/** Money from rows that are all of one status: the count, the XNO text of the raw sum and the dollars (summed in cents, so 0.1 + 0.2 is 0.30). */
+export function moneyOf(rows: readonly { amountRaw: string; usd: string }[]): Money {
+  let raw = 0n;
+  let cents = 0;
+  for (const r of rows) {
+    if (isRawText(r.amountRaw)) raw += BigInt(r.amountRaw);
+    cents += toCents(r.usd);
+  }
+  return { count: rows.length, xno: xnoText(raw.toString()), usd: (cents / 100).toFixed(2) };
+}
+
+/** Where an order counts: an open order past its expiry counts as expired. */
+export const statusOf = (status: string, expiresAt: number, now: number): string => (status === "open" && expiresAt < now ? "expired" : status);
+
+/** The orders as the page lists them: newest first, at most ORDERS_SHOWN, an open one past its expiry read as "expired". */
+export function shapeOrders(rows: readonly OrderRow[], now: number): Omit<AdminOrder, "look">[] {
+  return [...rows]
+    .sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? -1 : 1))
+    .slice(0, ORDERS_SHOWN)
+    .map((o) => ({
+      id: o.id,
+      player: o.player,
+      lookId: o.lookId,
+      usd: o.usd,
+      xno: isRawText(o.amountRaw) ? xnoText(o.amountRaw) : "0",
+      status: statusOf(o.status, o.expiresAt, now),
+      createdAt: o.createdAt,
+      expiresAt: o.expiresAt,
+      paidAt: o.paidAt,
+      payer: o.payer,
+      hash: o.hash,
+    }));
+}
+
+/** The looks that players own, by player (players and their looks in a steady order). */
+export function shapePlayers(owned: readonly { player: string; lookId: string; at: number }[]): StoreSummary["players"] {
+  const players = new Map<string, { player: string; looks: { id: string; at: number }[] }>();
+  for (const o of [...owned].sort((a, b) => (a.player < b.player ? -1 : a.player > b.player ? 1 : a.at - b.at))) {
+    const p = players.get(o.player) ?? { player: o.player, looks: [] };
+    p.looks.push({ id: o.lookId, at: o.at });
+    players.set(o.player, p);
+  }
+  return [...players.values()];
+}
+
+/** The whole summary from ALL the rows (for a store that reads the rows itself: Firestore, memory). */
+export function summarize(rows: readonly OrderRow[], owned: readonly { player: string; lookId: string; at: number }[], rate: StoreSummary["rate"], now: number): StoreSummary {
+  const counts = { open: 0, paid: 0, expired: 0, paid_late: 0 };
+  for (const o of rows) {
+    const key = statusOf(o.status, o.expiresAt, now);
+    if (Object.hasOwn(counts, key)) counts[key as keyof typeof counts]++;
+  }
+  return {
+    counts,
+    totals: { paid: moneyOf(rows.filter((o) => o.status === "paid")), paidLate: moneyOf(rows.filter((o) => o.status === "paid_late")) },
+    orders: shapeOrders(rows, now),
+    players: shapePlayers(owned),
+    rate,
+  };
+}
+
+/** The `rate` row of the meta table: JSON { usd, sources } kept with the time. Anything that is not that is no rate. */
+export function parseRate(value: unknown, at: unknown): StoreSummary["rate"] {
+  if (typeof value !== "string" || typeof at !== "number") return null;
+  try {
+    const v: unknown = JSON.parse(value);
+    if (!v || typeof v !== "object") return null;
+    const { usd, sources } = v as { usd?: unknown; sources?: unknown };
+    if (typeof usd !== "number" || !Number.isFinite(usd) || !Array.isArray(sources) || !sources.every((s) => typeof s === "string")) return null;
+    return { usd, sources: sources as string[], at };
+  } catch {
+    return null;
+  }
+}

package/src/admin/switches.ts

@@ -0,0 +1,74 @@
+// The two switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
+// draws the card from `SWITCHES`. A switch changes ONLY these two settings; never a look, a price or an order.
+
+/** Which character the player is: Nanoterra's island character (the one the player has there) or the game's own. */
+export type Character = "nanoterra" | "own";
+/** How the game signs a Nanoterra player in: the code exchange, a signed ticket (a game with no server), or not at all. */
+export type Signin = "exchange" | "ticket" | "none";
+export type GameSettings = { character: Character; signin: Signin };
+/** What a press can set: sign-in is on ("exchange": a game with a server) or off ("none"). */
+export type GamePatch = { character?: Character; signin?: "exchange" | "none" };
+/** The settings as they are now, and which ones /admin has set (the others still have the game's default). */
+export type GameState = GameSettings & { fromAdmin: { character: boolean; signin: boolean } };
+
+export const isCharacter = (v: unknown): v is Character => v === "nanoterra" || v === "own";
+export const isSigninChoice = (v: unknown): v is "exchange" | "none" => v === "exchange" || v === "none";
+export const isSignin = (v: unknown): v is Signin => v === "exchange" || v === "ticket" || v === "none";
+/** The sign-in switch is on for any way but "none". */
+export const signinOn = (s: Signin): boolean => s !== "none";
+
+/** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
+export function parsePatch(body: unknown): { ok: true; patch: GamePatch } | { ok: false; error: string } {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character" or "signin".' };
+  const patch: GamePatch = {};
+  for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+    if (key === "character" && isCharacter(value)) patch.character = value;
+    else if (key === "signin" && isSigninChoice(value)) patch.signin = value;
+    else if (key === "character") return { ok: false, error: '"character" must be "nanoterra" or "own".' };
+    else if (key === "signin") return { ok: false, error: '"signin" must be "exchange" or "none".' };
+    else return { ok: false, error: `"${key}" is not a game switch.` };
+  }
+  if (!Object.keys(patch).length) return { ok: false, error: 'Send "character" or "signin".' };
+  return { ok: true, patch };
+}
+
+/** The settings from what the store kept and the game's defaults. A stored value that is not one of the known words is ignored. */
+export function mergeSettings(stored: { character?: unknown; signin?: unknown }, defaults: GameSettings): GameState {
+  return {
+    character: isCharacter(stored.character) ? stored.character : defaults.character,
+    signin: isSigninChoice(stored.signin) ? stored.signin : defaults.signin,
+    fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin) },
+  };
+}
+
+/** One switch of the card: its title, and one plain sentence for each state. */
+export type SwitchId = "character" | "signin";
+export const SWITCHES: Record<SwitchId, { title: string; on: string; off: string }> = {
+  character: {
+    title: "Players use their Nanoterra character",
+    on: "On: a player who signs in from Nanoterra plays as the character they picked there. Anyone else plays as the island's first character.",
+    off: "Off: every player plays as this game's own character.",
+  },
+  signin: {
+    title: "Players can sign in with Nanoterra",
+    on: "On: this game's listing file says players can sign in with Nanoterra, and the game accepts that sign-in.",
+    off: "Off: the listing file says no sign-in, and the game refuses it: a link made before still signs nobody in.",
+  },
+};
+
+/**
+ * The character comes through the sign-in: only a player who signs in from Nanoterra brings one. So the character switch is shown with its dependency. With sign-in Off the
+ * card says what a player gets: the island's first character, every player, a player who signed in from Nanoterra before included ("Off means Off"). That is the GAME's page
+ * to do (the starter's src/client/ui/player.ts draws no Nanoterra character while sign-in is Off); the card only says it.
+ */
+export const CHARACTER_NEEDS_SIGNIN = "This needs “Players can sign in with Nanoterra” to be On: only a player who signs in from Nanoterra brings a character.";
+export const CHARACTER_SIGNIN_OFF = "Sign-in from Nanoterra is Off, so every player plays as the island's first character, a player who signed in from Nanoterra before included.";
+
+/** What to tell the creator under the sign-in switch about Nanoterra's review. A game cannot see that review: it says so. */
+export const REVIEW_NOTE =
+  "Your choice is saved here at once. The sign-in word is part of your listing file, and Nanoterra's review decides what Nanoterra shows for a game that is listed. This page cannot see that review. Check it on Nanoterra's launch page (step 6).";
+export const REVIEW_LINK = "https://nano133.com/build/nanoterra/launch";
+
+/** The state of a switch from the settings, and the patch that a press sends (the other state). */
+export const stateOf = (id: SwitchId, s: GameSettings): boolean => (id === "character" ? s.character === "nanoterra" : signinOn(s.signin));
+export const pressOf = (id: SwitchId, s: GameSettings): GamePatch => (id === "character" ? { character: s.character === "nanoterra" ? "own" : "nanoterra" } : { signin: signinOn(s.signin) ? "none" : "exchange" });

package/src/looks/change.ts

@@ -1,28 +1,46 @@
-import type { Look, Problem } from "./look.js";
+import { COLOR_PATTERN, cleanSlots, type Look, type Problem, type Slots } from "./look.js";
+
+/** Whether two looks have the same slots: the same names with the same values, in any order. No slots and empty slots are the same; a colour is the same in upper and lower case. */
+export function sameSlots(a: Slots | undefined, b: Slots | undefined): boolean {
+  const x = cleanSlots(a) ?? {};
+  const y = cleanSlots(b) ?? {};
+  const names = Object.keys(x);
+  if (names.length !== Object.keys(y).length) return false;
+  const norm = (v: string) => (COLOR_PATTERN.test(v) ? v.toLowerCase() : v);
+  return names.every((n) => Object.prototype.hasOwnProperty.call(y, n) && norm(x[n]) === norm(y[n]));
+}
 
 // What a change of the list does, before it goes live. Owned looks are stored by id: a look that someone owns must stay in the file.
 
 /**
  * The mistakes that a new list would make for the players: an id that someone owns (a paid order gave it to them) is gone from the new
- * list. `owned` is every look id that any player owns. The free look is not owned by an order: it is every player's.
+ * list, or its slots changed (the game reads the slots of the id that a player owns, so a new slot changes what they own: add a new look instead).
+ * `owned` is every look id that any player owns. The free look is not owned by an order: it is every player's, and its slots may change.
+ * A change of a price, a name, a body colour or a hat on an owned look is allowed.
  */
 export function removalProblems(before: readonly Look[], after: readonly Look[], owned: Iterable<string>): Problem[] {
   const now = new Set(after.map((l) => l.id));
   const own = new Set(owned);
   const out: Problem[] = [];
+  const next = new Map(after.map((l, i) => [l.id, { look: l, place: i + 1 }]));
   for (const l of before) {
-    if (now.has(l.id) || !own.has(l.id)) continue;
-    out.push({ look: null, field: "id", message: `The look "${l.id}" (${l.name}) is owned by a player and is not in the new list. Keep it in the file; change its price if you do not want to sell it.` });
+    if (!own.has(l.id)) continue;
+    const kept = next.get(l.id);
+    if (!kept) {
+      out.push({ look: null, field: "id", message: `The look "${l.id}" (${l.name}) is owned by a player and is not in the new list. Keep it in the file; change its price if you do not want to sell it.` });
+    } else if (!sameSlots(l.slots, kept.look.slots)) {
+      out.push({ look: kept.place, field: "slots", message: `The slots of the look "${l.id}" (${l.name}) changed, and a player owns it. Keep its slots as they were, or add a new look with the new slots.` });
+    }
   }
   return out;
 }
 
-export type LookField = "name" | "priceUsd" | "body" | "hat" | "hatColor";
+export type LookField = "name" | "priceUsd" | "body" | "hat" | "hatColor" | "slots";
 
 export type LooksDiff = {
   added: Look[];
   removed: Look[];
-  /** Looks with the same id and a different name, price, colour or hat. */
+  /** Looks with the same id and a different name, price, colour, hat or slots. */
   changed: { id: string; before: Look; after: Look; fields: LookField[] }[];
 };
 
@@ -40,6 +58,7 @@ export function diffLooks(before: readonly Look[], after: readonly Look[]): Look
     if (a.change.body.toLowerCase() !== b.change.body.toLowerCase()) fields.push("body");
     if (a.change.hat !== b.change.hat) fields.push("hat");
     if ((a.change.hatColor ?? "").toLowerCase() !== (b.change.hatColor ?? "").toLowerCase()) fields.push("hatColor");
+    if (!sameSlots(a.slots, b.slots)) fields.push("slots");
     if (fields.length) diff.changed.push({ id: a.id, before: b, after: a, fields });
   }
   return diff;

package/src/looks/index.ts

@@ -1,7 +1,7 @@
-export { HATS, ID_PATTERN, COLOR_PATTERN, NAME_MAX, PRICE_MAX_USD, wholeCents, lookProblems, checkLooks, usdText } from "./look.js";
-export type { Hat, Look, Problem } from "./look.js";
+export { HATS, ID_PATTERN, COLOR_PATTERN, NAME_MAX, PRICE_MAX_USD, SLOTS_MAX, SLOT_NAME_PATTERN, SLOT_WORD_PATTERN, RESERVED_SLOT_NAMES, wholeCents, lookProblems, checkLooks, cleanSlots, slotValueOk, usdText } from "./look.js";
+export type { Hat, Look, Problem, Slots } from "./look.js";
 export { PRICE_LADDER, rungUsd, rungOf, priceText } from "./ladder.js";
 export type { Rung } from "./ladder.js";
-export { removalProblems, diffLooks } from "./change.js";
+export { removalProblems, diffLooks, sameSlots } from "./change.js";
 export type { LooksDiff, LookField } from "./change.js";
 export { looksJson, slugId } from "./json.js";

package/src/looks/json.ts

@@ -1,15 +1,17 @@
-import { ID_PATTERN, type Look } from "./look.js";
+import { cleanSlots, ID_PATTERN, type Look } from "./look.js";
 
 /**
- * The text of looks.json for a list of looks: one look on each line, in the order id, name, priceUsd, change, as the game starter's
- * file is written, so a change of one look is a change of one line in a diff. It ends with a new line.
+ * The text of looks.json for a list of looks: one look on each line, in the order id, name, priceUsd, change (and slots, when the look has any), as the game
+ * starter's file is written, so a change of one look is a change of one line in a diff. A look with no slots is written exactly as before. It ends with a new line.
  */
 export function looksJson(looks: readonly Look[]): string {
   const row = (l: Look) => {
     const change = [`"body": ${JSON.stringify(l.change.body)}`];
     if (l.change.hat !== undefined) change.push(`"hat": ${JSON.stringify(l.change.hat)}`);
     if (l.change.hatColor !== undefined) change.push(`"hatColor": ${JSON.stringify(l.change.hatColor)}`);
-    return `  { "id": ${JSON.stringify(l.id)}, "name": ${JSON.stringify(l.name)}, "priceUsd": ${l.priceUsd}, "change": { ${change.join(", ")} } }`;
+    const slots = cleanSlots(l.slots);
+    const tail = slots ? `, "slots": { ${Object.keys(slots).map((k) => `${JSON.stringify(k)}: ${JSON.stringify(slots[k])}`).join(", ")} }` : "";
+    return `  { "id": ${JSON.stringify(l.id)}, "name": ${JSON.stringify(l.name)}, "priceUsd": ${l.priceUsd}, "change": { ${change.join(", ")} }${tail} }`;
   };
   return `[\n${looks.map(row).join(",\n")}\n]\n`;
 }

package/src/looks/look.ts

@@ -13,10 +13,27 @@ export type Look = {
   /** The price in US dollars with at most 2 decimals, for example 0.25. 0 means free for everyone. */
   priceUsd: number;
   change: { body: string; hat?: Hat; hatColor?: string };
+  /**
+   * What a game defines for itself: up to 8 slots, each a name and a value, that the game's own code reads ("wings": "ember", "trail": "#ffcf5a"). A name is 1 to 24
+   * lowercase letters, digits or dashes, starting with a letter; a value is a word (1 to 40 lowercase letters, digits or dashes) or a colour ("#rrggbb"). Optional: a look
+   * without `slots`, or with an empty one, is the same look. Because players own a look by its id, the slots of a look that someone owns must not change.
+   */
+  slots?: Slots;
 };
 
+/** The slots of a look: names and values, words or colours. */
+export type Slots = Record<string, string>;
+
 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: readonly string[] = ["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;
 
@@ -24,14 +41,17 @@ export const PRICE_MAX_USD = 1000;
 export type Problem = {
   /** The place of the look in the list, from 1, or null for a mistake of the whole list. */
   look: number | null;
-  /** The field: "list", "id", "name", "priceUsd", "change.body", "change.hat", "change.hatColor" or "free". */
+  /** The field: "list", "id", "name", "priceUsd", "change.body", "change.hat", "change.hatColor", "slots", "slots.<name>" or "free". (The change rules also use "slots" for a slot that changed on a look that players own.) */
   field: string;
   message: string;
 };
 
-/** 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: number): boolean {
-  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. */
@@ -54,16 +74,57 @@ export function lookProblems(raw: unknown): Problem[] {
     if (typeof v.change?.body !== "string" || !COLOR_PATTERN.test(v.change.body)) add("change.body", '"change.body" must be a colour like "#4aa8ff"');
     if (v.change?.hat !== undefined && !(HATS as readonly unknown[]).includes(v.change.hat)) 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: unknown): v is Record<string, unknown> => 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: unknown): v is string => 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: unknown): { field: string; message: string }[] {
+  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: { field: string; message: string }[] = [];
+  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: Slots | undefined): Slots | undefined {
+  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: unknown): Look[] {
+export function checkLooks(rawInput: unknown): Look[] {
+  // 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: unknown = 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 as Look[]).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 as Look[]).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" */