5789095
@@ -40,6 +40,17 @@
admin's three live pages load one small file — see
  changes to what the shop sells and what it charges are a ledger too: a
  price, a slug, a discount code or a tax rate that moves writes a row at
  `/admin/changes` naming who moved it and what it was before.
- **The audit trail**: every stock movement, payment, refund, order event,
  gift-card movement and use of a code names the actor who caused it — the
  buyer for a purchase, the admin for an admin's action, `stripe` for a
  webhook, `system` for the seed, and the forge's account for anything typed
  at the terminal. `/admin/audit` reads those five ledgers as one timeline,
  newest first, narrowed to one order by its number and paged with a cursor;
  it is an admin's page, and an admin's alone, as is the `audit` tab in the
  terminal. For one order it shows the arithmetic rather than a claim:
  charges plus the gift card, less refunds and what went back on the card,
  against what the order says was paid. Rows written before the actor column
  existed say `unknown`, which is the truth about them.
- **Simulated unless you configure it**: the payment. With no Stripe keys the
  store uses a **mock gateway** — a page labelled as a mock, with Approve and
  Decline buttons, that moves no money.
@@ -487,10 +498,10 @@
is written to the same database, and — because an event is a row in it — a
stock move or a refund made here reaches an admin's open `/admin` over the
live stream within about a second, not on that page's next load. `1`–`7`
switch between stock, orders, the outbox, discount codes, gift cards, the tax
table and the changes an admin made to any of it — everything `/admin`
can see — and `j`/`k` move. A tab whose rows are the shop's own business is an
table, the changes an admin made to any of it and the audit trail — everything
`/admin` can see — and `j`/`k` move. A tab whose rows are the shop's own business is an
admin's to open: a non-admin gets stock, tax and their own orders, the other
four are marked with a `·` in the tab bar and answer without leaving the tab
five are marked with a `·` in the tab bar and answer without leaving the tab
they are on:
| Tab | Keys |
@@ -500,6 +511,7 @@
they are on:
| codes | `n` writes a code (`CODE 20% [min 25] [uses 100] [until 2026-12-31]`), `t` turns one on or off, `c` looks a code up |
| cards | `i` issues a card (`25 a sorry-for-the-wait card`) and prints its code once, `v` voids or revives one, `c` looks a code up |
| tax | `e` sets a rate (`COUNTRY / REGION / 8.75 / what to call it`), `d` sets the rate for anywhere the table does not name, `x` removes one |
| audit | reads only: the five money ledgers as one timeline, newest first, the terminal's half of `/admin/audit`. `/` narrows it to one order by its number, and the foot says what that order's rows add up to against what the order says was paid |
| changes | reads only: the last hundred changes an admin made to the catalog, the codes or the tax table, newest first — the terminal's half of `/admin/changes`. A change made here writes one of these rows too, naming the account the forge put at the keyboard |
`q` leaves. The first line says who the forge named and what they may read;
@@ -0,0 +1,72 @@
/**
 * Who caused a row.
 *
 * Every ledger in this shop says what happened and why. This is the last
 * column: who. A stock correction, a refund, a movement of a gift card's
 * balance — each of them was caused by somebody, and an auditor's first
 * question about any of them is whose hand it was.
 *
 * There are five kinds of hand and no more:
 *
 * - an admin, whom the forge named and `src/who.ts` verified;
 * - a shopper, the account an order belongs to;
 * - `stripe`, for a row a webhook caused — the gateway told us, nobody asked;
 * - `system`, for a seed or a boot-time job, which is nobody in particular;
 * - `unknown`, for a row written before this column existed, and for anyone
 *   the forge did not name.
 *
 * The actor is never a form field and never a header the caller wrote: the
 * caller does not get to sign the trail that is about them. It is also not a
 * second place that says who bought an order — `order.buyer_id` is the one
 * answer to that, and this says who caused this row.
 */
import { atKeyboard, type Who } from "./who.ts";
import type { Order } from "./db.ts";
export type Role = "admin" | "user" | "stripe" | "system" | "unknown";
export type Actor = { id: string; name: string; role: Role };
/** Nobody the forge named, and the rows written before there was a column. */
export const UNKNOWN: Actor = { id: "", name: "unknown", role: "unknown" };
/** The app itself: a seed, or a job that runs because the process started. */
export const SYSTEM: Actor = { id: "", name: "system", role: "system" };
/** The gateway, when it is the gateway that told us rather than a person. */
export const STRIPE: Actor = { id: "", name: "stripe", role: "stripe" };
/** Whoever the forge signed in, as an actor. Anonymous is nobody. */
export const of = (who: Who): Actor =>
  who.role === "anon" ? UNKNOWN : { id: who.id, name: who.name, role: who.role };
/**
 * Who is at the keyboard of the app's terminal. There are no headers on an
 * ssh session; the forge names the person in the environment before it starts
 * us, which is the same trust as the socket itself.
 */
export const atDesk = (): Actor => of(atKeyboard());
/** The account an order belongs to. A guest order from before accounts is nobody's. */
export const buyerOf = (order: Pick<Order, "buyer_id" | "buyer_name">): Actor =>
  order.buyer_id === "" ? UNKNOWN : { id: order.buyer_id, name: order.buyer_name, role: "user" };
/**
 * Who is paying: whoever the forge has signed in, or — for a shopper holding
 * nothing but an order's access token — the account the order belongs to.
 */
export const paying = (who: Who, order: Pick<Order, "buyer_id" | "buyer_name">): Actor =>
  who.role === "anon" ? buyerOf(order) : of(who);
/** How long a name or an id is allowed to be in a row: enough, and no more. */
const CAP = 64;
/**
 * The three columns a ledger row keeps, clipped to what the columns hold.
 * Spread into the parameters of an INSERT, in the order id, name, role.
 */
export const cells = (by: Actor): [string, string, string] => [
  by.id.slice(0, CAP),
  (by.name || "unknown").slice(0, CAP),
  by.role,
];
@@ -7,6 +7,8 @@
 * saying who asked and why.
 */
import * as actors from "./actor.ts";
import * as audit from "./audit.ts";
import * as catalog from "./catalog.ts";
import * as changes from "./changes.ts";
import * as discounts from "./discounts.ts";
@@ -67,7 +69,7 @@
const guard = (ctx: Ctx): Response | null =>
 * src/who.ts, and it is the only source there is: a form field or a header
 * that named someone else would be the caller signing their own trail.
 */
const actor = (ctx: Ctx): changes.Actor => changes.actorOf(ctx.who);
const actor = (ctx: Ctx): actors.Actor => actors.of(ctx.who);
/** A rate as the tax table says it. */
const percent = (bp: number): string => `${(bp / 100).toFixed(2)}%`;
@@ -78,6 +80,42 @@
export function changeList(ctx: Ctx): Response {
  return render(ctx, { title: "Changes", admin: true }, pages.changes(changes.recent(100)));
}
/**
 * The whole money trail on one page: the five ledgers merged, newest first,
 * narrowed to one order by its number and paged with a cursor. The number is
 * looked up before anything is read, so what reaches the query is an id; the
 * cursor is parsed to a stamp and two numbers or thrown away.
 */
export function auditList(ctx: Ctx): Response {
  const blocked = guard(ctx);
  if (blocked) return blocked;
  const query = (ctx.url.searchParams.get("q") ?? "").slice(0, 20).trim().toUpperCase();
  const order = query === "" ? null : orders.byNumber(query);
  const before = audit.readCursor(ctx.url.searchParams.get("before") ?? "");
  const found =
    query !== "" && !order ? [] : audit.timeline({ orderId: order?.id, before, limit: AUDIT_PAGE });
  const rows = found.slice(0, AUDIT_PAGE);
  const last = rows[rows.length - 1];
  const older =
    found.length > AUDIT_PAGE && last
      ? `/admin/audit?q=${encodeURIComponent(query)}&before=${encodeURIComponent(audit.cursorOf(last))}`
      : null;
  return render(
    ctx,
    { title: "Audit", admin: true },
    pages.audit(rows, {
      query,
      order,
      balance: order ? audit.balanceOf(order) : null,
      shop: audit.shopBalance(),
      older,
    }),
  );
}
/** How much of the timeline one page shows. */
const AUDIT_PAGE = 60;
// --- the door ---------------------------------------------------------------
export function dashboard(ctx: Ctx): Response {
@@ -245,7 +283,7 @@
export function variantCreate(ctx: Ctx): Response {
    // Opening stock is not a field of the trail: it moves through the stock
    // ledger, which already says who and why.
    db.transaction(() => {
      const id = catalog.createVariant({ product_id: found.id, sku, name, price_cents: price, stock });
      const id = catalog.createVariant({ product_id: found.id, sku, name, price_cents: price, stock, by: actor(ctx) });
      changes.changed(actor(ctx), "variant", id, {}, { sku, name, price: formatCents(price) });
    })();
    return redirect(`/admin/products/${found.id}?m=variant-added`);
@@ -306,8 +344,8 @@
export function inventoryMove(ctx: Ctx): Response {
  const reason = field(ctx.form, "reason", 120);
  const variant = variantId === undefined ? null : catalog.variantById(variantId);
  if (!variant || delta === undefined || delta === 0 || reason === "") return redirect("/admin/inventory?m=bad-delta");
  if (delta > 0) inventory.addStock(variant.id, delta, reason);
  else inventory.setStock(variant.id, Math.max(0, variant.stock + delta), reason);
  if (delta > 0) inventory.addStock(variant.id, delta, reason, actor(ctx));
  else inventory.setStock(variant.id, Math.max(0, variant.stock + delta), reason, actor(ctx));
  return redirect("/admin/inventory?m=stocked");
}
@@ -365,14 +403,22 @@
export async function orderRefund(ctx: Ctx): Promise<Response> {
  if (order.gateway === "stripe" && order.payment_ref?.startsWith("pi_")) {
    const result = await gateway.refundCharge(order.payment_ref, amount, key);
    if (!result.ok) {
      orders.note(order.id, "refund-failed", result.error);
      orders.note(order.id, "refund-failed", actor(ctx), result.error);
      return redirect(`/admin/orders/${order.number}?m=refund-failed`);
    }
    gatewayRef = result.value.id;
  }
  const done = orders.refund({ order, amount_cents: amount, reason, restock, gateway_ref: gatewayRef, idempotencyKey: key });
  const done = orders.refund({
    order,
    amount_cents: amount,
    reason,
    restock,
    gateway_ref: gatewayRef,
    idempotencyKey: key,
    by: actor(ctx),
  });
  if (!done.ok) {
    orders.note(order.id, "refund-refused", done.error);
    orders.note(order.id, "refund-refused", actor(ctx), done.error);
    return redirect(`/admin/orders/${order.number}?m=bad-amount`);
  }
  return redirect(`/admin/orders/${order.number}?m=refunded`);
@@ -383,7 +429,7 @@
export function orderCancel(ctx: Ctx): Response {
  if (blocked) return blocked;
  const order = orders.byNumber((ctx.params.number ?? "").slice(0, 20));
  if (!order) return notFound(ctx);
  orders.cancel(order, field(ctx.form, "reason", 200) || "cancelled in admin");
  orders.cancel(order, field(ctx.form, "reason", 200) || "cancelled in admin", actor(ctx));
  return redirect(`/admin/orders/${order.number}?m=cancelled`);
}
@@ -501,7 +547,7 @@
export function giftCardIssue(ctx: Ctx): Response {
  if (blocked) return blocked;
  const amount = parseCents(field(ctx.form, "amount", 12));
  if (amount === undefined || amount <= 0) return redirect("/admin/giftcards?m=bad-amount");
  const issued = giftcards.issue({ cents: amount, note: field(ctx.form, "note", 120), orderId: undefined });
  const issued = giftcards.issue({ cents: amount, note: field(ctx.form, "note", 120), by: actor(ctx) });
  return giftCardList(ctx, issued.code);
}
@@ -514,7 +560,7 @@
export function giftCardAdjust(ctx: Ctx): Response {
  const reason = field(ctx.form, "reason", 120) || "adjusted in admin";
  const asked = field(ctx.form, "void", 1);
  if (asked !== "") {
    giftcards.setActive(card.id, asked === "0", reason);
    giftcards.setActive(card.id, asked === "0", reason, actor(ctx));
    return redirect("/admin/giftcards?m=saved");
  }
  const raw = field(ctx.form, "amount", 12).replace(/^\+/, "");
@@ -522,8 +568,8 @@
export function giftCardAdjust(ctx: Ctx): Response {
  const cents = parseCents(down ? raw.slice(1) : raw);
  if (cents === undefined || cents === 0) return redirect("/admin/giftcards?m=bad-amount");
  const moved = down
    ? giftcards.spend(card.id, cents, reason)
    : giftcards.credit(card.id, cents, reason, undefined, `admin:${crypto.randomUUID()}`);
    ? giftcards.spend(card.id, cents, reason, actor(ctx))
    : giftcards.credit(card.id, cents, reason, actor(ctx), undefined, `admin:${crypto.randomUUID()}`);
  return redirect(`/admin/giftcards?m=${moved ? "saved" : "bad-amount"}`);
}
@@ -0,0 +1,273 @@
/**
 * The money trail, as one timeline.
 *
 * Five tables say what this shop did with money and goods: `stock_entry`,
 * `payment`, `order_event`, `gift_card_entry` and `discount_redemption`. Each
 * is authoritative about its own thing and each is read on its own page. This
 * module reads all five at once, newest first, so that an auditor's question —
 * what happened, in what order, and who did it — has one answer on one page.
 *
 * It is a bounded read per table and a merge in memory, never five scans: each
 * table is ordered by an index on (at DESC, id DESC) and asked for one page's
 * worth, so the work is the same whether the shop has a hundred rows or a
 * million. Paging is a cursor rather than an offset, for the same reason — and
 * because rows arriving while somebody reads must not shift the page under
 * them. The cursor is (when, which table, which row), which is exactly the
 * ordering, so it is unambiguous even when a second holds a dozen rows.
 *
 * Nothing here reads a column the order page does not already show: no gift
 * card codes (only the last four, as everywhere), no gateway secrets.
 */
import { creditedForOrder } from "./giftcards.ts";
import { db, type Order } from "./db.ts";
/** Which ledger a row came from. */
export type Source = "stock" | "payment" | "event" | "gift_card" | "discount";
/**
 * The tie-break between two rows written in the same second. It is arbitrary
 * but fixed: the cursor and the ordering have to agree, or paging would skip.
 */
const RANK: Record<Source, number> = { stock: 0, payment: 1, event: 2, gift_card: 3, discount: 4 };
export type Entry = {
  source: Source;
  id: number;
  at: string;
  actor_id: string;
  actor_name: string;
  actor_role: string;
  /** The kind of thing that happened, in one or two words. */
  what: string;
  /** The row's own words: a reason, a reference, a SKU. */
  detail: string;
  order_id: number | null;
  order_number: string | null;
  /** Money as the shop's balance felt it: positive in, negative out, null for goods. */
  cents: number | null;
};
/** Where a page of the timeline stops: the ordering, written down. */
export type Cursor = { at: string; rank: number; id: number };
export const PAGE = 100;
export const cursorOf = (entry: Entry): string => `${entry.at}|${RANK[entry.source]}|${entry.id}`;
/**
 * A cursor as it came back from a URL. A stamp, a rank and an id, or nothing:
 * whatever else was typed there is not a place in this timeline.
 */
export function readCursor(raw: string): Cursor | undefined {
  const fields = /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\|([0-4])\|(\d{1,15})$/.exec(raw.slice(0, 40));
  if (!fields) return undefined;
  return { at: fields[1]!, rank: Number(fields[2]), id: Number(fields[3]) };
}
type Raw = {
  id: number;
  at: string;
  actor_id: string;
  actor_name: string;
  actor_role: string;
  order_id: number | null;
  order_number: string | null;
  a: string;
  b: string;
  n: number;
};
/**
 * The five reads. Each selects the same shape — when, who, which order, and
 * three loose columns the mapping below turns into words — and each is ordered
 * by the index its table has for exactly this. `$where` is the only thing that
 * varies, and it is built below from an id and a cursor, never from text.
 */
type Read = { alias: string; stamp: string; sql: (where: string) => string };
const READS: Record<Source, Read> = {
  stock: {
    alias: "s",
    stamp: "at",
    sql: (where) => `
      SELECT s.id, s.at, s.actor_id, s.actor_name, s.actor_role, s.order_id,
             (SELECT number FROM "order" o WHERE o.id = s.order_id) AS order_number,
             (SELECT sku FROM variant v WHERE v.id = s.variant_id) AS a, s.reason AS b, s.delta AS n
      FROM stock_entry s WHERE ${where} ORDER BY s.at DESC, s.id DESC LIMIT $limit`,
  },
  payment: {
    alias: "p",
    stamp: "created_at",
    sql: (where) => `
      SELECT p.id, p.created_at AS at, p.actor_id, p.actor_name, p.actor_role, p.order_id,
             (SELECT number FROM "order" o WHERE o.id = p.order_id) AS order_number,
             p.kind AS a, p.gateway || CASE WHEN p.gateway_ref = '' THEN '' ELSE ' ' || p.gateway_ref END AS b,
             p.amount_cents AS n
      FROM payment p WHERE ${where} ORDER BY p.created_at DESC, p.id DESC LIMIT $limit`,
  },
  event: {
    alias: "e",
    stamp: "at",
    sql: (where) => `
      SELECT e.id, e.at, e.actor_id, e.actor_name, e.actor_role, e.order_id,
             (SELECT number FROM "order" o WHERE o.id = e.order_id) AS order_number,
             e.kind AS a, e.detail AS b, 0 AS n
      FROM order_event e WHERE ${where} ORDER BY e.at DESC, e.id DESC LIMIT $limit`,
  },
  gift_card: {
    alias: "g",
    stamp: "at",
    sql: (where) => `
      SELECT g.id, g.at, g.actor_id, g.actor_name, g.actor_role, g.order_id,
             (SELECT number FROM "order" o WHERE o.id = g.order_id) AS order_number,
             (SELECT last4 FROM gift_card c WHERE c.id = g.gift_card_id) AS a, g.reason AS b, g.delta AS n
      FROM gift_card_entry g WHERE ${where} ORDER BY g.at DESC, g.id DESC LIMIT $limit`,
  },
  discount: {
    alias: "r",
    stamp: "at",
    sql: (where) => `
      SELECT r.id, r.at, r.actor_id, r.actor_name, r.actor_role, r.order_id,
             (SELECT number FROM "order" o WHERE o.id = r.order_id) AS order_number,
             r.kind AS a, (SELECT code FROM discount d WHERE d.id = r.discount_id) AS b, r.amount_cents AS n
      FROM discount_redemption r WHERE ${where} ORDER BY r.at DESC, r.id DESC LIMIT $limit`,
  },
};
/**
 * One table's page, as raw rows. Both conditions are built here and never from
 * anything a caller typed: the order is an id looked up first, and the cursor
 * is a stamp and two numbers. The table's own rank against the cursor's is
 * decided in this process, so the statement takes the same parameters however
 * the two compare.
 */
function page(source: Source, options: { orderId?: number; before?: Cursor; limit: number }): Raw[] {
  const { alias, stamp, sql } = READS[source];
  const when = `${alias}.${stamp}`;
  const where = [
    options.orderId === undefined ? "" : `${alias}.order_id = $order`,
    options.before === undefined
      ? ""
      : `(${when} < $at OR (${when} = $at AND ($below = 1 OR ($equal = 1 AND ${alias}.id < $id))))`,
  ].filter((part) => part !== "");
  return db.query<Raw, any>(sql(where.length === 0 ? "1 = 1" : where.join(" AND "))).all({
    ...(options.orderId === undefined ? {} : { $order: options.orderId }),
    ...(options.before === undefined
      ? {}
      : {
          $at: options.before.at,
          $below: RANK[source] < options.before.rank ? 1 : 0,
          $equal: RANK[source] === options.before.rank ? 1 : 0,
          $id: options.before.id,
        }),
    $limit: options.limit,
  });
}
const sign = (value: number, negative: boolean): number => (negative ? -value : value);
/** A raw row as the timeline says it: source by source, in the shop's words. */
function read(source: Source, row: Raw): Entry {
  const common = {
    source,
    id: row.id,
    at: row.at,
    actor_id: row.actor_id,
    actor_name: row.actor_name,
    actor_role: row.actor_role,
    order_id: row.order_id,
    order_number: row.order_number,
  };
  if (source === "stock")
    return { ...common, what: "stock", detail: `${row.a} ${row.n > 0 ? "+" : ""}${row.n} — ${row.b}`, cents: null };
  if (source === "payment")
    return { ...common, what: row.a, detail: row.b, cents: sign(row.n, row.a === "refund") };
  if (source === "event") return { ...common, what: row.a, detail: row.b, cents: null };
  if (source === "gift_card")
    return { ...common, what: "gift card", detail: `····${row.a} — ${row.b}`, cents: row.n };
  return { ...common, what: row.a, detail: row.b ?? "", cents: sign(row.n, row.a === "redeemed") };
}
/**
 * The timeline, newest first. Five short reads, merged and cut to the limit:
 * the merge is over at most five pages' worth of rows, and the ordering is the
 * one the cursor speaks. One row more than the limit comes back when there is
 * one, so the page can say whether there is another without counting anything.
 */
export function timeline(options: { orderId?: number; before?: Cursor; limit?: number } = {}): Entry[] {
  const limit = Math.max(1, Math.min(PAGE, Math.trunc(options.limit ?? PAGE) || PAGE));
  const asked = { orderId: options.orderId, before: options.before, limit: limit + 1 };
  const all: Entry[] = [];
  for (const source of Object.keys(READS) as Source[])
    for (const row of page(source, asked)) all.push(read(source, row));
  all.sort(
    (one, two) =>
      (one.at < two.at ? 1 : one.at > two.at ? -1 : 0) ||
      RANK[two.source] - RANK[one.source] ||
      two.id - one.id,
  );
  return all.slice(0, limit + 1);
}
/**
 * What an order's ledgers add up to, beside what the order itself says was
 * paid. Every figure is a sum of rows anyone can check on this page; the
 * order's own claim is the one thing that is not, which is the point of
 * holding them up against each other.
 */
export type Balance = {
  charged_cents: number;
  refunded_cents: number;
  gift_card_cents: number;
  gift_card_back_cents: number;
  /** Charges and gift card, less refunds and what went back on the card. */
  held_cents: number;
  /** What the order row says has been paid and not given back. */
  says_cents: number;
  agrees: boolean;
};
const PAID = ["paid", "partially_refunded", "refunded"];
const sumPayments = (orderId: number, kind: "charge" | "refund"): number =>
  db
    .query<{ total: number }, [number, string]>(
      `SELECT COALESCE(SUM(amount_cents), 0) AS total FROM payment
       WHERE order_id = ?1 AND kind = ?2 AND status = 'succeeded'`,
    )
    .get(orderId, kind)!.total;
export function balanceOf(order: Order): Balance {
  const charged = sumPayments(order.id, "charge");
  const refunded = sumPayments(order.id, "refund");
  const spent = db
    .query<{ total: number }, [number]>(
      "SELECT COALESCE(-SUM(delta), 0) AS total FROM gift_card_entry WHERE order_id = ?1 AND delta < 0",
    )
    .get(order.id)!.total;
  const back = creditedForOrder(order.id);
  const held = charged + spent - refunded - back;
  const says = PAID.includes(order.status) ? order.total_cents - (refunded + back) : 0;
  return {
    charged_cents: charged,
    refunded_cents: refunded,
    gift_card_cents: spent,
    gift_card_back_cents: back,
    held_cents: held,
    says_cents: says,
    agrees: held === says,
  };
}
/** The same sum over the whole shop: every charge, less every refund. */
export const shopBalance = (): { charged_cents: number; refunded_cents: number; held_cents: number } => {
  const row = db
    .query<{ charged: number; refunded: number }, []>(
      `SELECT
        (SELECT COALESCE(SUM(amount_cents), 0) FROM payment WHERE kind = 'charge' AND status = 'succeeded') AS charged,
        (SELECT COALESCE(SUM(amount_cents), 0) FROM payment WHERE kind = 'refund' AND status = 'succeeded') AS refunded`,
    )
    .get()!;
  return { charged_cents: row.charged, refunded_cents: row.refunded, held_cents: row.charged - row.refunded };
};
@@ -4,6 +4,7 @@
 * carts, orders or money beyond the integer cents it stores.
 */
import { SYSTEM, type Actor } from "./actor.ts";
import { db, type Category, type Product, type Variant } from "./db.ts";
import { addStock } from "./inventory.ts";
@@ -170,13 +171,18 @@
export function updateProduct(
  });
}
/** A new variant starts at zero stock; stock only ever moves through the ledger. */
/**
 * A new variant starts at zero stock; stock only ever moves through the
 * ledger, so opening stock is a row like any other and names whoever opened it.
 */
export function createVariant(input: {
  product_id: number;
  sku: string;
  name: string;
  price_cents: number;
  stock: number;
  /** Who is adding it: an admin, or the seed that fills an empty shop. */
  by: Actor;
  /** Non-zero makes this variant a gift card of that face value. */
  gift_card_cents?: number;
}): number {
@@ -194,7 +200,7 @@
export function createVariant(input: {
      $price_cents: input.price_cents,
      $gift_card_cents: input.gift_card_cents ?? 0,
    });
  if (input.stock > 0) addStock(row!.id, input.stock, "opening stock");
  if (input.stock > 0) addStock(row!.id, input.stock, "opening stock", input.by);
  return row!.id;
}
@@ -238,7 +244,7 @@
export function seedGiftCards(): void {
      ["GFT-CARD-50", "$50", 5000],
      ["GFT-CARD-100", "$100", 10000],
    ] as [string, string, number][])
      createVariant({ product_id: productId, sku, name, price_cents: cents, stock: 1000, gift_card_cents: cents });
      createVariant({ product_id: productId, sku, name, price_cents: cents, stock: 1000, gift_card_cents: cents, by: SYSTEM });
  })();
}
@@ -343,7 +349,7 @@
export function seed(): void {
          active: true,
        });
        for (const [sku, name, price_cents, stock] of product.variants) {
          createVariant({ product_id: productId, sku, name, price_cents, stock });
          createVariant({ product_id: productId, sku, name, price_cents, stock, by: SYSTEM });
        }
      }
    }
@@ -11,7 +11,8 @@
 * The actor is whoever the forge named: `ctx.who` on the web, the account the
 * forge put in the environment at the terminal. It is never a form field and
 * never a header the caller wrote — the caller does not get to sign the trail
 * that is about them.
 * that is about them. `src/actor.ts` is where an actor comes from, here and
 * in every other ledger; this table keeps the id and the name of one.
 *
 * Nothing spendable is recorded. A discount code is printed on a poster; a
 * gift card's code is bearer money and its balance has a ledger of its own,
@@ -19,10 +20,9 @@
 */
import { db, type AdminChange } from "./db.ts";
import { atKeyboard, type Who } from "./who.ts";
import type { Actor } from "./actor.ts";
export type Change = AdminChange;
export type Actor = { id: string; name: string };
export type Field = { field: string; before: string; after: string };
/** A value as an audit row says it: plain data in, one short string out. */
@@ -58,17 +58,6 @@
export const flat = (value: Value): string =>
/** A value as a row says it: flat, and short enough to be a row. */
export const say = (value: Value): string => clip(flat(value));
/** Who the forge says is asking, as an actor. Anonymous cannot be an admin. */
export const actorOf = (who: Who): Actor =>
  who.role === "anon" ? { id: "", name: "unknown" } : { id: who.id, name: who.name };
/**
 * Who is at the keyboard of the app's terminal. There are no headers on an
 * ssh session; the forge names the person in the environment before it starts
 * us, which is the same trust as the socket itself.
 */
export const atDesk = (): Actor => actorOf(atKeyboard());
/**
 * The fields of two snapshots that differ. A form submitted with nothing
 * changed produces an empty list, and an empty list writes nothing.
@@ -276,8 +276,32 @@
function migrate(handle: Database): void {
  addColumn(handle, "order", "buyer_id", "TEXT NOT NULL DEFAULT ''");
  addColumn(handle, "order", "buyer_name", "TEXT NOT NULL DEFAULT ''");
  handle.exec('CREATE INDEX IF NOT EXISTS order_buyer ON "order"(buyer_id, id DESC)');
  // Who caused the row. The ledgers already said what happened and why; these
  // three columns say whose hand it was — see src/actor.ts for the five kinds
  // of hand there are. The rows written before the column tell the truth about
  // themselves: no id, and a name and a role of "unknown", because nobody
  // wrote down who they were and this is not the place to guess.
  for (const table of ["stock_entry", "payment", "order_event", "gift_card_entry", "discount_redemption"]) {
    addColumn(handle, table, "actor_id", "TEXT NOT NULL DEFAULT ''");
    addColumn(handle, table, "actor_name", "TEXT NOT NULL DEFAULT 'unknown'");
    addColumn(handle, table, "actor_role", "TEXT NOT NULL DEFAULT 'unknown'");
  }
  // /admin/audit reads those five newest-first and merges them. Each ordering
  // is an index, so the timeline is five short reads however many rows there
  // are — never five scans.
  handle.exec(`
    CREATE INDEX IF NOT EXISTS stock_entry_at ON stock_entry(at DESC, id DESC);
    CREATE INDEX IF NOT EXISTS payment_at ON payment(created_at DESC, id DESC);
    CREATE INDEX IF NOT EXISTS order_event_at ON order_event(at DESC, id DESC);
    CREATE INDEX IF NOT EXISTS gift_card_entry_at ON gift_card_entry(at DESC, id DESC);
    CREATE INDEX IF NOT EXISTS discount_redemption_at ON discount_redemption(at DESC, id DESC);
  `);
}
/** The three columns every ledger row carries about who caused it. */
export type ActorColumns = { actor_id: string; actor_name: string; actor_role: string };
/**
 * Open the database kept in a directory: the directory is made if it is not
 * there, the file is opened, the pragmas are set, the schema is created and
@@ -430,7 +454,7 @@
export type TaxRate = {
  label: string;
  active: number;
};
export type Payment = {
export type Payment = ActorColumns & {
  id: number;
  order_id: number;
  kind: "charge" | "refund";
@@ -21,6 +21,7 @@
 * it is a function from `Who` to rows, so the rule is tested without a pty.
 */
import * as actors from "./actor.ts";
import * as changes from "./changes.ts";
import * as discounts from "./discounts.ts";
import * as giftcards from "./giftcards.ts";
@@ -41,7 +42,7 @@
const percent = (bp: number): string => `${(bp / 100).toFixed(2)}%`;
 * the same row. The actor is the account the forge named at the keyboard —
 * the environment it started us with, which is the same trust as the socket.
 */
export const TABS = ["stock", "orders", "outbox", "codes", "cards", "tax", "changes"] as const;
export const TABS = ["stock", "orders", "outbox", "codes", "cards", "tax", "changes", "audit"] as const;
export type Tab = (typeof TABS)[number];
/**
@@ -112,6 +113,12 @@
const DESK: Record<Tab, { read: "anyone" | "own" | "admin"; keys: Offer[] }> = {
  // Who changed a price, a code or a rate is the shop's own business, and it
  // names people: the same gate the orders and the cards are behind.
  changes: { read: "admin", keys: [] },
  // The five money ledgers as one timeline — the same rows /admin/audit shows,
  // and the same gate: it names people, and it says what every order took.
  audit: {
    read: "admin",
    keys: [{ key: "/", label: "/ one order", press: "admin" }],
  },
};
/**
@@ -218,7 +225,7 @@
export function newDiscount(line: string): Done {
        expires_at: expires,
      });
      changes.changed(
        changes.atDesk(),
        actors.atDesk(),
        "discount",
        made,
        {},
@@ -250,7 +257,7 @@
export function toggleDiscount(id: number): Done {
  if (!found) return no("No code selected.");
  db.transaction(() => {
    discounts.setActive(found.id, found.active !== 1);
    changes.changed(changes.atDesk(), "discount", found.id, { active: found.active === 1 }, { active: found.active !== 1 });
    changes.changed(actors.atDesk(), "discount", found.id, { active: found.active === 1 }, { active: found.active !== 1 });
  })();
  return yes(`${found.code} is now ${found.active === 1 ? "off" : "on"}.`);
}
@@ -260,7 +267,11 @@
export function issueCard(line: string): Done {
  const parts = words(line);
  const cents = parseCents(parts[0] ?? "");
  if (cents === undefined || cents <= 0) return no("A card is worth an amount of money, like 25 or 25.00.");
  const issued = giftcards.issue({ cents, note: parts.slice(1).join(" ").slice(0, 120) || "issued at the terminal" });
  const issued = giftcards.issue({
    cents,
    note: parts.slice(1).join(" ").slice(0, 120) || "issued at the terminal",
    by: actors.atDesk(),
  });
  return yes(`${issued.code} — ${formatCents(cents)}. This is the only copy of the code.`);
}
@@ -268,7 +279,7 @@
export function toggleCard(id: number, reason: string): Done {
  const card = giftcards.byId(id);
  if (!card) return no("No card selected.");
  const reviving = card.active !== 1;
  giftcards.setActive(card.id, reviving, reason.trim() || "voided at the terminal");
  giftcards.setActive(card.id, reviving, reason.trim() || "voided at the terminal", actors.atDesk());
  return yes(
    reviving
      ? `····${card.last4} can be used again; it holds ${formatCents(giftcards.byId(card.id)!.balance_cents)}.`
@@ -316,7 +327,7 @@
export function setRate(line: string): Done {
  db.transaction(() => {
    const id = tax.upsertRate({ country, region, rate_bp: points, label, active: true });
    changes.changed(
      changes.atDesk(),
      actors.atDesk(),
      "tax_rate",
      id,
      existing ? { rate: percent(existing.rate_bp), label: existing.label, active: existing.active === 1 } : {},
@@ -332,7 +343,7 @@
export function setDefaultRate(text: string): Done {
  const was = tax.defaultRateBp();
  db.transaction(() => {
    tax.setDefaultRateBp(points);
    changes.changed(changes.atDesk(), "tax_default", 0, { rate: percent(was) }, { rate: percent(points) });
    changes.changed(actors.atDesk(), "tax_default", 0, { rate: percent(was) }, { rate: percent(points) });
  })();
  return yes(`Anywhere the table does not name is taxed at ${(points / 100).toFixed(2)}%.`);
}
@@ -343,7 +354,7 @@
export function removeRate(id: number, confirmation: string): Done {
  if (!/^y(es)?$/i.test(confirmation.trim())) return no(`${rate.country} ${rate.region} kept.`);
  db.transaction(() => {
    tax.removeRate(rate.id);
    changes.record(changes.atDesk(), "tax_rate", rate.id, [
    changes.record(actors.atDesk(), "tax_rate", rate.id, [
      {
        field: "removed",
        before: `${rate.country}${rate.region ? ` ${rate.region}` : ""} ${percent(rate.rate_bp)} ${rate.label}`,
@@ -11,6 +11,7 @@
 * A discount never applies to a gift card: money is not bought at a discount.
 */
import { cells, type Actor } from "./actor.ts";
import { db, type Discount } from "./db.ts";
import { formatCents } from "./money.ts";
@@ -106,7 +107,13 @@
export function evaluate(code: string, base_cents: number, now = new Date()): Ch
 * said the same thing a moment earlier, but only this decides, so a code that
 * expired or was switched off in between is not taken anyway.
 */
export function redeem(discountId: number, orderId: number, amount_cents: number, now = new Date()): boolean {
export function redeem(
  discountId: number,
  orderId: number,
  amount_cents: number,
  by: Actor,
  now = new Date(),
): boolean {
  const changes = db
    .query(
      `UPDATE discount SET used_count = used_count + 1
@@ -116,18 +123,20 @@
export function redeem(discountId: number, orderId: number, amount_cents: number
    .run(discountId, stampOf(now)).changes;
  if (changes !== 1) return false;
  db.query(
    "INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents) VALUES (?1, ?2, 'redeemed', ?3)",
  ).run(discountId, orderId, amount_cents);
    `INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents, actor_id, actor_name, actor_role)
     VALUES (?1, ?2, 'redeemed', ?3, ?4, ?5, ?6)`,
  ).run(discountId, orderId, amount_cents, ...cells(by));
  return true;
}
/** An order that never happened gives its use back, and says so in a row. */
export function release(discountId: number, orderId: number, amount_cents: number): void {
export function release(discountId: number, orderId: number, amount_cents: number, by: Actor): void {
  db.transaction(() => {
    db.query("UPDATE discount SET used_count = MAX(0, used_count - 1) WHERE id = ?1").run(discountId);
    db.query(
      "INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents) VALUES (?1, ?2, 'released', ?3)",
    ).run(discountId, orderId, amount_cents);
      `INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents, actor_id, actor_name, actor_role)
       VALUES (?1, ?2, 'released', ?3, ?4, ?5, ?6)`,
    ).run(discountId, orderId, amount_cents, ...cells(by));
  })();
}
@@ -12,7 +12,8 @@
 * so two checkouts racing for the last $5 cannot both win.
 */
import { dataDir, db, type GiftCard } from "./db.ts";
import { cells, type Actor } from "./actor.ts";
import { dataDir, db, type ActorColumns, type GiftCard } from "./db.ts";
import { hmac, loadSecret } from "./sign.ts";
import type { Order, OrderItem } from "./db.ts";
@@ -21,7 +22,7 @@
const secret = loadSecret(dataDir);
/** No I, O, 0 or 1: a code is read aloud and typed by hand. */
const ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
export type Entry = {
export type Entry = ActorColumns & {
  id: number;
  gift_card_id: number;
  delta: number;
@@ -112,7 +113,7 @@
export type Issued = { card: GiftCard; code: string };
 * Make a card. The plain code is returned once, to be printed on a receipt or
 * shown to the admin who asked for it, and then it exists nowhere else.
 */
export function issue(input: { cents: number; note: string; orderId?: number }): Issued {
export function issue(input: { cents: number; note: string; by: Actor; orderId?: number }): Issued {
  const code = freshCode();
  const card = db.transaction(() => {
    const row = db
@@ -127,7 +128,7 @@
export function issue(input: { cents: number; note: string; orderId?: number }):
        $note: input.note,
        $order: input.orderId ?? null,
      })!;
    credit(row.id, input.cents, input.orderId ? "issued with an order" : "issued", input.orderId);
    credit(row.id, input.cents, input.orderId ? "issued with an order" : "issued", input.by, input.orderId);
    return byId(row.id)!;
  })();
  return { card, code };
@@ -142,6 +143,7 @@
export function credit(
  giftCardId: number,
  cents: number,
  reason: string,
  by: Actor,
  orderId?: number,
  idempotencyKey?: string,
): boolean {
@@ -149,10 +151,11 @@
export function credit(
  return db.transaction(() => {
    const inserted = db
      .query(
        `INSERT OR IGNORE INTO gift_card_entry (gift_card_id, delta, reason, order_id, idempotency_key)
         VALUES (?1, ?2, ?3, ?4, ?5)`,
        `INSERT OR IGNORE INTO gift_card_entry (gift_card_id, delta, reason, order_id, idempotency_key,
           actor_id, actor_name, actor_role)
         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)`,
      )
      .run(giftCardId, cents, reason, orderId ?? null, idempotencyKey ?? null).changes;
      .run(giftCardId, cents, reason, orderId ?? null, idempotencyKey ?? null, ...cells(by)).changes;
    if (inserted !== 1) return false;
    db.query("UPDATE gift_card SET balance_cents = balance_cents + ?2 WHERE id = ?1").run(giftCardId, cents);
    return true;
@@ -163,35 +166,32 @@
export function credit(
 * Take money off a card. False and nothing written when the balance is not
 * there or the card is void; the caller turns that into a refusal.
 */
export function spend(giftCardId: number, cents: number, reason: string, orderId?: number): boolean {
export function spend(giftCardId: number, cents: number, reason: string, by: Actor, orderId?: number): boolean {
  if (cents <= 0) return true;
  return db.transaction(() => {
    const changes = db
      .query("UPDATE gift_card SET balance_cents = balance_cents - ?2 WHERE id = ?1 AND active = 1 AND balance_cents >= ?2")
      .run(giftCardId, cents).changes;
    if (changes !== 1) return false;
    db.query("INSERT INTO gift_card_entry (gift_card_id, delta, reason, order_id) VALUES (?1, ?2, ?3, ?4)").run(
      giftCardId,
      -cents,
      reason,
      orderId ?? null,
    );
    db.query(
      `INSERT INTO gift_card_entry (gift_card_id, delta, reason, order_id, actor_id, actor_name, actor_role)
       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)`,
    ).run(giftCardId, -cents, reason, orderId ?? null, ...cells(by));
    return true;
  })();
}
/** Void a card by writing its balance away, or bring it back to life. */
export function setActive(giftCardId: number, active: boolean, reason: string): void {
export function setActive(giftCardId: number, active: boolean, reason: string, by: Actor): void {
  const card = byId(giftCardId);
  if (!card) return;
  db.transaction(() => {
    if (!active && card.balance_cents > 0) {
      db.query("UPDATE gift_card SET balance_cents = 0 WHERE id = ?1").run(giftCardId);
      db.query("INSERT INTO gift_card_entry (gift_card_id, delta, reason) VALUES (?1, ?2, ?3)").run(
        giftCardId,
        -card.balance_cents,
        reason || "voided",
      );
      db.query(
        `INSERT INTO gift_card_entry (gift_card_id, delta, reason, actor_id, actor_name, actor_role)
         VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
      ).run(giftCardId, -card.balance_cents, reason || "voided", ...cells(by));
    }
    db.query("UPDATE gift_card SET active = ?2 WHERE id = ?1").run(giftCardId, active ? 1 : 0);
  })();
@@ -202,7 +202,7 @@
export function setActive(giftCardId: number, active: boolean, reason: string):
 * quantity three issues three cards, each with its own code, each worth what
 * was paid for it. Idempotent — an order that already issued issues nothing.
 */
export function issueForOrder(order: Order, items: OrderItem[]): Issued[] {
export function issueForOrder(order: Order, items: OrderItem[], by: Actor): Issued[] {
  const lines = items.filter((item) => item.gift_card_cents > 0);
  if (lines.length === 0) return [];
  const already = db
@@ -212,7 +212,7 @@
export function issueForOrder(order: Order, items: OrderItem[]): Issued[] {
  const issued: Issued[] = [];
  for (const line of lines)
    for (let n = 0; n < line.quantity; n++)
      issued.push(issue({ cents: line.gift_card_cents, note: `bought on ${order.number}`, orderId: order.id }));
      issued.push(issue({ cents: line.gift_card_cents, note: `bought on ${order.number}`, by, orderId: order.id }));
  return issued;
}
@@ -5,10 +5,11 @@
 * cannot both win, because the UPDATE only matches while stock is enough.
 */
import { db } from "./db.ts";
import { cells, type Actor } from "./actor.ts";
import { db, type ActorColumns } from "./db.ts";
import { emit } from "./live.ts";
export type StockEntry = {
export type StockEntry = ActorColumns & {
  id: number;
  variant_id: number;
  delta: number;
@@ -18,15 +19,13 @@
export type StockEntry = {
  sku: string;
};
/** The row that says why stock moved. Prepared on the handle in use, never
 *  held across one: `db.query` caches the statement on the database itself. */
const record = (variantId: number, delta: number, reason: string, orderId?: number): void => {
  db.query("INSERT INTO stock_entry (variant_id, delta, reason, order_id) VALUES (?1, ?2, ?3, ?4)").run(
    variantId,
    delta,
    reason,
    orderId ?? null,
  );
/** The row that says why stock moved, and who moved it. Prepared on the handle
 *  in use, never held across one: `db.query` caches it on the database itself. */
const record = (variantId: number, delta: number, reason: string, by: Actor, orderId?: number): void => {
  db.query(
    `INSERT INTO stock_entry (variant_id, delta, reason, order_id, actor_id, actor_name, actor_role)
     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)`,
  ).run(variantId, delta, reason, orderId ?? null, ...cells(by));
};
/**
@@ -41,12 +40,16 @@
const announce = (variantId: number): void => {
  if (row) emit("stock.moved", { id: variantId, sku: row.sku });
};
/** Add stock (a delivery, a correction, a restock after a refund). */
export function addStock(variantId: number, quantity: number, reason: string, orderId?: number): void {
/**
 * Add stock (a delivery, a correction, a restock after a refund). The actor is
 * required, and every mover of stock is named: an anonymous correction is the
 * one row an auditor cannot follow.
 */
export function addStock(variantId: number, quantity: number, reason: string, by: Actor, orderId?: number): void {
  if (quantity <= 0) return;
  db.transaction(() => {
    db.query("UPDATE variant SET stock = stock + ?2 WHERE id = ?1").run(variantId, quantity);
    record(variantId, quantity, reason, orderId);
    record(variantId, quantity, reason, by, orderId);
  })();
  announce(variantId);
}
@@ -55,14 +58,20 @@
export function addStock(variantId: number, quantity: number, reason: string, or
 * Take stock for a sale. Returns false and changes nothing when there is not
 * enough; the caller turns that into "out of stock" at the boundary.
 */
export function takeStock(variantId: number, quantity: number, reason: string, orderId?: number): boolean {
export function takeStock(
  variantId: number,
  quantity: number,
  reason: string,
  by: Actor,
  orderId?: number,
): boolean {
  if (quantity <= 0) return true;
  const took = db.transaction(() => {
    const changes = db
      .query("UPDATE variant SET stock = stock - ?2 WHERE id = ?1 AND stock >= ?2")
      .run(variantId, quantity).changes;
    if (changes !== 1) return false;
    record(variantId, -quantity, reason, orderId);
    record(variantId, -quantity, reason, by, orderId);
    return true;
  })();
  if (took) announce(variantId);
@@ -70,15 +79,15 @@
export function takeStock(variantId: number, quantity: number, reason: string, o
}
/** Set stock to a number by writing the difference as a correction. */
export function setStock(variantId: number, target: number, reason: string): void {
export function setStock(variantId: number, target: number, reason: string, by: Actor): void {
  const current = db.query<{ stock: number }, [number]>("SELECT stock FROM variant WHERE id = ?1").get(variantId);
  if (!current) return;
  const delta = target - current.stock;
  if (delta === 0) return;
  if (delta > 0) return addStock(variantId, delta, reason);
  if (delta > 0) return addStock(variantId, delta, reason, by);
  db.transaction(() => {
    db.query("UPDATE variant SET stock = stock + ?2 WHERE id = ?1").run(variantId, delta);
    record(variantId, delta, reason);
    record(variantId, delta, reason, by);
  })();
  announce(variantId);
}
@@ -16,10 +16,12 @@
 * webhook arriving twice writes one row, so it announces one thing.
 */
import * as actors from "./actor.ts";
import * as discounts from "./discounts.ts";
import * as giftcards from "./giftcards.ts";
import { randomBytes } from "node:crypto";
import { db, type Order, type OrderItem, type Payment } from "./db.ts";
import { cells, type Actor } from "./actor.ts";
import { db, type ActorColumns, type Order, type OrderItem, type Payment } from "./db.ts";
import { addStock, takeStock } from "./inventory.ts";
import { dueCents, sumLines } from "./money.ts";
import { emit } from "./live.ts";
@@ -38,8 +40,13 @@
export type Address = {
  country: string;
};
/** The account an order belongs to: who the forge signed in, and nothing else. */
export type Buyer = { id: string; name: string };
/**
 * The account an order belongs to: who the forge signed in, and nothing else.
 * It is also the actor of every row the order writes as it is placed — the
 * stock it takes, the code it redeems, the balance it spends — because a
 * shopper buying something is who caused all of them.
 */
export type Buyer = Actor;
export type PlaceResult = { ok: true; order: Order; reused: boolean } | { ok: false; error: string };
@@ -61,15 +68,22 @@
export const itemsOf = (orderId: number): OrderItem[] =>
export const paymentsOf = (orderId: number): Payment[] =>
  db.query<Payment, [number]>("SELECT * FROM payment WHERE order_id = ?1 ORDER BY id").all(orderId);
export const eventsOf = (orderId: number) =>
export type OrderEvent = ActorColumns & { id: number; kind: string; detail: string; at: string };
export const eventsOf = (orderId: number): OrderEvent[] =>
  db
    .query<{ id: number; kind: string; detail: string; at: string }, [number]>(
      "SELECT id, kind, detail, at FROM order_event WHERE order_id = ?1 ORDER BY id",
    .query<OrderEvent, [number]>(
      `SELECT id, kind, detail, at, actor_id, actor_name, actor_role FROM order_event
       WHERE order_id = ?1 ORDER BY id`,
    )
    .all(orderId);
export const note = (orderId: number, kind: string, detail = ""): void => {
  db.query("INSERT INTO order_event (order_id, kind, detail) VALUES (?1, ?2, ?3)").run(orderId, kind, detail);
/** An event on an order's history, and who caused it. */
export const note = (orderId: number, kind: string, by: Actor, detail = ""): void => {
  db.query(
    `INSERT INTO order_event (order_id, kind, detail, actor_id, actor_name, actor_role)
     VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
  ).run(orderId, kind, detail, ...cells(by));
};
/** A needle for LIKE: the shopper's text is data, and `%` and `_` are theirs to type. */
@@ -238,15 +252,18 @@
export function place(input: {
      // out first stops the whole order rather than half of it.
      if (priced.discount_code !== "") {
        const discount = discounts.byCode(priced.discount_code)!;
        if (!discounts.redeem(discount.id, created.id, priced.discount_cents))
        if (!discounts.redeem(discount.id, created.id, priced.discount_cents, input.buyer))
          throw new Error(`CODE_GONE:${priced.discount_code} stopped applying while you were checking out.`);
        note(created.id, "discount", `${discount.code} — ${discounts.describe(discount)}`);
        note(created.id, "discount", input.buyer, `${discount.code} — ${discounts.describe(discount)}`);
      }
      if (priced.gift_card_cents > 0) {
        const card = giftcards.byCode(input.codes.gift);
        if (!card || !giftcards.spend(card.id, priced.gift_card_cents, `paid on ${created.number}`, created.id))
        if (
          !card ||
          !giftcards.spend(card.id, priced.gift_card_cents, `paid on ${created.number}`, input.buyer, created.id)
        )
          throw new Error("CODE_GONE:That gift card no longer has that much on it.");
        note(created.id, "gift-card", `····${card.last4} paid ${(priced.gift_card_cents / 100).toFixed(2)}`);
        note(created.id, "gift-card", input.buyer, `····${card.last4} paid ${(priced.gift_card_cents / 100).toFixed(2)}`);
      }
      const insertItem = db.query(
@@ -264,12 +281,13 @@
export function place(input: {
          item.quantity,
          item.gift_card_cents,
        );
        if (!takeStock(item.variant_id, item.quantity, `sold on ${created.number}`, created.id))
        if (!takeStock(item.variant_id, item.quantity, `sold on ${created.number}`, input.buyer, created.id))
          throw new Error(`OUT_OF_STOCK:${item.product_title} (${item.variant_name})`);
      }
      note(
        created.id,
        "placed",
        input.buyer,
        `${itemRows.length} line${itemRows.length === 1 ? "" : "s"}, awaiting payment${
          created.buyer_name === "" ? "" : ` — ${created.buyer_name}`
        }`,
@@ -289,7 +307,7 @@
export function place(input: {
  emit("order.placed", { id: placed.id, number: placed.number, cents: placed.total_cents });
  for (const item of itemRows) emit("stock.moved", { id: item.variant_id, sku: item.sku });
  // A gift card that covered the lot leaves nothing for a gateway to take.
  return { ok: true, order: dueCents(placed) === 0 ? payWithGiftCard(placed) : placed, reused: false };
  return { ok: true, order: dueCents(placed) === 0 ? payWithGiftCard(placed, input.buyer) : placed, reused: false };
}
export type Charge = { gateway: string; ref: string; amount_cents: number };
@@ -332,7 +350,7 @@
const alreadyShort = (orderId: number): boolean =>
    .query<{ n: number }, [number]>("SELECT COUNT(*) AS n FROM order_event WHERE order_id = ?1 AND kind = 'short-payment'")
    .get(orderId)!.n > 0;
export function settleFromGateway(order: Order, charge: Charge): Order {
export function settleFromGateway(order: Order, charge: Charge, by: Actor): Order {
  // A gateway may say anything; a charge is a whole number of cents, and the
  // payment ledger has no room for a row that moved nothing.
  const amount = Number.isFinite(charge.amount_cents) ? Math.trunc(charge.amount_cents) : 0;
@@ -344,10 +362,11 @@
export function settleFromGateway(order: Order, charge: Charge): Order {
      amount > 0
        ? db
            .query(
              `INSERT OR IGNORE INTO payment (order_id, kind, amount_cents, gateway, gateway_ref, status, idempotency_key)
               VALUES (?1, 'charge', ?2, ?3, ?4, 'succeeded', ?5)`,
              `INSERT OR IGNORE INTO payment (order_id, kind, amount_cents, gateway, gateway_ref, status,
                 idempotency_key, actor_id, actor_name, actor_role)
               VALUES (?1, 'charge', ?2, ?3, ?4, 'succeeded', ?5, ?6, ?7, ?8)`,
            )
            .run(fresh.id, amount, charge.gateway, ref, `charge:${fresh.number}`).changes
            .run(fresh.id, amount, charge.gateway, ref, `charge:${fresh.number}`, ...cells(by)).changes
        : 0;
    // Already recorded: the other arrival settled this order, whichever way.
    if (inserted === 0 && amount > 0) return { paid: false, order: byId(fresh.id)! };
@@ -358,7 +377,7 @@
export function settleFromGateway(order: Order, charge: Charge): Order {
        `UPDATE "order" SET status = 'paid', paid_at = datetime('now'), payment_ref = ?2, gateway = ?3
         WHERE id = ?1 AND status = 'pending_payment'`,
      ).run(fresh.id, ref, charge.gateway).changes;
      note(fresh.id, "paid", `${charge.gateway} ${ref}`);
      note(fresh.id, "paid", by, `${charge.gateway} ${ref}`);
      return { paid: changed === 1, order: byId(fresh.id)! };
    }
    // Short. The order stays where it was; the gateway's handle is kept so
@@ -374,6 +393,7 @@
export function settleFromGateway(order: Order, charge: Charge): Order {
    note(
      fresh.id,
      "short-payment",
      by,
      `asked ${(due / 100).toFixed(2)} ${fresh.currency}, ${charge.gateway} paid ${(amount / 100).toFixed(2)} — ` +
        `${((due - amount) / 100).toFixed(2)} short${ref ? ` (${ref})` : ""}`,
    );
@@ -392,7 +412,7 @@
export function settleFromGateway(order: Order, charge: Charge): Order {
 * charge to record — the money moved when the balance did, and that row is
 * already written.
 */
export function payWithGiftCard(order: Order): Order {
export function payWithGiftCard(order: Order, by: Actor): Order {
  const took = db.transaction(() => {
    const changed = db
      .query(
@@ -400,7 +420,8 @@
export function payWithGiftCard(order: Order): Order {
         WHERE id = ?1 AND status = 'pending_payment'`,
      )
      .run(order.id).changes;
    if (changed === 1) note(order.id, "paid", `gift card ····${giftcards.cardSpentOn(order.id)?.last4 ?? "????"}`);
    if (changed === 1)
      note(order.id, "paid", by, `gift card ····${giftcards.cardSpentOn(order.id)?.last4 ?? "????"}`);
    return { charged: changed === 1, order: byId(order.id)! };
  })();
  const paid = settle(took.order);
@@ -416,7 +437,9 @@
export function payWithGiftCard(order: Order): Order {
function settle(order: Order): Order {
  if (order.status !== "paid") return order;
  const items = itemsOf(order.id);
  const issued = giftcards.issueForOrder(order, items);
  // The cards an order bought were caused by whoever bought it, not by the
  // gateway that happened to say the money arrived.
  const issued = giftcards.issueForOrder(order, items, actors.buyerOf(order));
  if (!hasReceipt(order.id)) writeReceipt(order, items, issued.map((one) => one.code));
  return order;
}
@@ -439,6 +462,8 @@
export function refund(input: {
  restock: boolean;
  gateway_ref: string;
  idempotencyKey: string;
  /** Whoever is giving the money back: an admin, on a page or at the terminal. */
  by: Actor;
}): RefundResult {
  const { order } = input;
  if (input.amount_cents <= 0) return { ok: false, error: "A refund is more than nothing." };
@@ -456,12 +481,15 @@
export function refund(input: {
      if (input.amount_cents > left) return { ok: false, error: "That is more than the order has left to refund." };
      const split = splitRefund(fresh, input.amount_cents);
      const [actorId, actorName, actorRole] = cells(input.by);
      let payment: Payment | null = null;
      if (split.gateway_cents > 0)
        payment = db
          .query<Payment, any>(
            `INSERT INTO payment (order_id, kind, amount_cents, gateway, gateway_ref, status, idempotency_key)
             VALUES ($order_id, 'refund', $amount, $gateway, $ref, 'succeeded', $key) RETURNING *`,
            `INSERT INTO payment (order_id, kind, amount_cents, gateway, gateway_ref, status, idempotency_key,
               actor_id, actor_name, actor_role)
             VALUES ($order_id, 'refund', $amount, $gateway, $ref, 'succeeded', $key,
               $actor_id, $actor_name, $actor_role) RETURNING *`,
          )
          .get({
            $order_id: fresh.id,
@@ -469,6 +497,9 @@
export function refund(input: {
            $gateway: fresh.gateway,
            $ref: input.gateway_ref,
            $key: input.idempotencyKey,
            $actor_id: actorId,
            $actor_name: actorName,
            $actor_role: actorRole,
          })!;
      if (split.gift_card_cents > 0) {
        const card = giftcards.cardSpentOn(fresh.id);
@@ -477,11 +508,17 @@
export function refund(input: {
          card.id,
          split.gift_card_cents,
          `refunded from ${fresh.number}`,
          input.by,
          fresh.id,
          `${input.idempotencyKey}:card`,
        );
        if (!put) return { ok: false, error: "That refund has already gone back to the card." };
        note(fresh.id, "gift-card", `····${card.last4} took back ${(split.gift_card_cents / 100).toFixed(2)}`);
        note(
          fresh.id,
          "gift-card",
          input.by,
          `····${card.last4} took back ${(split.gift_card_cents / 100).toFixed(2)}`,
        );
      }
      const refunded = refundedCents(fresh.id);
@@ -489,10 +526,11 @@
export function refund(input: {
      db.query('UPDATE "order" SET status = ?2 WHERE id = ?1').run(fresh.id, status);
      if (input.restock)
        for (const item of itemsOf(fresh.id))
          addStock(item.variant_id, item.quantity, `restocked from ${fresh.number}`, fresh.id);
          addStock(item.variant_id, item.quantity, `restocked from ${fresh.number}`, input.by, fresh.id);
      note(
        fresh.id,
        "refunded",
        input.by,
        `${(input.amount_cents / 100).toFixed(2)} ${fresh.currency}${input.reason ? ` — ${input.reason}` : ""}${
          input.restock ? " (restocked)" : ""
        }`,
@@ -515,16 +553,16 @@
export function refund(input: {
 * An unpaid order an admin gives up on: the stock goes back on the shelf, the
 * code gets its use back and the gift card gets its balance back.
 */
export function cancel(order: Order, reason: string): Order {
export function cancel(order: Order, reason: string, by: Actor): Order {
  const ended = db.transaction(() => {
    const fresh = byId(order.id)!;
    if (fresh.status !== "pending_payment") return { cancelled: false, order: fresh, items: [] as OrderItem[] };
    db.query('UPDATE "order" SET status = \'cancelled\' WHERE id = ?1').run(fresh.id);
    for (const item of itemsOf(fresh.id))
      addStock(item.variant_id, item.quantity, `cancelled ${fresh.number}`, fresh.id);
      addStock(item.variant_id, item.quantity, `cancelled ${fresh.number}`, by, fresh.id);
    if (fresh.discount_code !== "") {
      const discount = discounts.byCode(fresh.discount_code);
      if (discount) discounts.release(discount.id, fresh.id, fresh.discount_cents);
      if (discount) discounts.release(discount.id, fresh.id, fresh.discount_cents, by);
    }
    if (fresh.gift_card_cents > 0) {
      const card = giftcards.cardSpentOn(fresh.id);
@@ -533,11 +571,12 @@
export function cancel(order: Order, reason: string): Order {
          card.id,
          fresh.gift_card_cents,
          `released from ${fresh.number}`,
          by,
          fresh.id,
          `release:${fresh.number}`,
        );
    }
    note(fresh.id, "cancelled", reason);
    note(fresh.id, "cancelled", by, reason);
    return { cancelled: true, order: byId(fresh.id)!, items: itemsOf(fresh.id) };
  })();
@@ -16,13 +16,14 @@
import { formatCents } from "../money.ts";
import { itemsTable, orderTotals, statusPill } from "./checkout.ts";
import { describe } from "../discounts.ts";
import { href, nameOf, type Reading } from "../changes.ts";
import type { Balance, Entry } from "../audit.ts";
import type { DiscountStats } from "../discounts.ts";
import type { ProductWithPrice } from "../catalog.ts";
import type { Category, GiftCard, Order, OrderItem, Payment, TaxRate, Variant } from "../db.ts";
import type { StockEntry } from "../inventory.ts";
import type { Email } from "../mail.ts";
import type { Session } from "../session.ts";
import type { Shortfall } from "../orders.ts";
import type { OrderEvent, Shortfall } from "../orders.ts";
/** What the ledger emits about an order, and about a stock movement. */
const ORDER_EVENTS = "order.placed order.paid order.refunded order.cancelled";
@@ -46,6 +47,7 @@
export const nav = (current: string): string =>
    ["/admin/tax", "Tax", "tax"],
    ["/admin/mail", "Outbox", "mail"],
    ["/admin/changes", "Changes", "changes"],
    ["/admin/audit", "Audit", "audit"],
  ]
    .map(([href, label, key]) =>
      key === current ? `<strong>${escape(label)}</strong>` : `<a href="${escape(href)}">${escape(label)}</a>`,
@@ -141,11 +143,21 @@
${nav("orders")}
${live("order-list", ORDER_EVENTS, orderRows(list))}
`;
/**
 * Who caused a row, as a ledger says it: the name the forge knew them by, and
 * under it the part that does not change — the role, and the account's id.
 * A row from before the column says "unknown", which is the truth about it.
 */
const who = (row: { actor_name: string; actor_role: string; actor_id: string }): string =>
  `${escape(row.actor_name || "unknown")}<div class="muted" style="font-size:.8rem">${escape(row.actor_role)}${
    row.actor_id === "" ? "" : ` · ${escape(row.actor_id)}`
  }</div>`;
export function order(
  found: Order,
  items: OrderItem[],
  payments: Payment[],
  events: { kind: string; detail: string; at: string }[],
  events: OrderEvent[],
  refunded: number,
  refundable: number,
  email: Email | null,
@@ -203,11 +215,12 @@
${orderTotals(found, refunded)}
    ${
      payments.length === 0
        ? '<p class="muted">No payments recorded.</p>'
        : `<table><thead><tr><th>When</th><th>Kind</th><th class="num">Amount</th><th>Reference</th></tr></thead>
        : `<table><thead><tr><th>When</th><th>Kind</th><th class="num">Amount</th><th>Who</th><th>Reference</th></tr></thead>
      <tbody>${payments
        .map(
          (payment) => `<tr><td class="muted">${escape(payment.created_at)}</td><td>${escape(payment.kind)}</td>
        <td class="num price">${escape(formatCents(payment.kind === "refund" ? -payment.amount_cents : payment.amount_cents))}</td>
        <td>${who(payment)}</td>
        <td class="muted" style="word-break:break-all">${escape(payment.gateway_ref || "—")}</td></tr>`,
        )
        .join("")}</tbody></table>`
@@ -218,7 +231,7 @@
${orderTotals(found, refunded)}
        (event) =>
          `<tr><td class="muted" style="white-space:nowrap">${escape(event.at)}</td><td><strong>${escape(
            event.kind,
          )}</strong> ${escape(event.detail)}</td></tr>`,
          )}</strong> ${escape(event.detail)}</td><td>${who(event)}</td></tr>`,
      )
      .join("")}</tbody></table>
    ${
@@ -433,6 +446,100 @@
${
}
`;
/**
 * The audit page: five ledgers as one timeline, newest first.
 *
 * Every column here is a column some other admin page already shows — the
 * gift card's last four, the gateway's reference, the reason somebody typed —
 * and every one of them goes out through `escape`. The figures above the table
 * are sums of the rows below it, so a reader can add them up rather than
 * believe them.
 */
export function audit(
  rows: Entry[],
  view: {
    query: string;
    order: Order | null;
    balance: Balance | null;
    shop: { charged_cents: number; refunded_cents: number; held_cents: number };
    older: string | null;
  },
): string {
  const figure = (label: string, cents: number, strong = false): string =>
    `<tr><td>${strong ? `<strong>${escape(label)}</strong>` : escape(label)}</td>
     <td class="num price">${strong ? "<strong>" : ""}${escape(formatCents(cents))}${strong ? "</strong>" : ""}</td></tr>`;
  return `
${nav("audit")}
<h1>Audit</h1>
<p class="lede">Every stock movement, payment, refund, order event, gift-card movement and use of a code, in the
order they happened, and who caused each one. This is the same five tables the pages above read one at a time.</p>
<form method="get" action="/admin/audit" class="row-actions" style="margin-bottom:1rem">
  <input name="q" value="${escape(view.query)}" placeholder="Order number, like BZ-XXXXXXXX" maxlength="20"
    style="max-width:22rem" aria-label="Order number">
  <button class="btn ghost">Show that order</button>
  ${view.query === "" ? "" : '<a class="btn ghost" href="/admin/audit">Everything</a>'}
</form>
${
  view.order && view.balance
    ? `<div class="notice">
  <h2 style="margin-top:0">${escape(view.order.number)} adds up</h2>
  <table class="steady" style="max-width:26rem">
    <colgroup><col style="width:65%"><col style="width:35%"></colgroup>
    <tbody>
      ${figure("Charged through the gateway", view.balance.charged_cents)}
      ${figure("Paid with a gift card", view.balance.gift_card_cents)}
      ${figure("Refunded through the gateway", -view.balance.refunded_cents)}
      ${figure("Put back on the card", -view.balance.gift_card_back_cents)}
      ${figure("The ledgers hold", view.balance.held_cents, true)}
      ${figure("The order says it was paid", view.balance.says_cents, true)}
    </tbody>
  </table>
  <p>${
    view.balance.agrees
      ? '<span class="pill ok">these agree</span>'
      : `<span class="pill warn">these do not agree</span> ${
          view.order.status === "pending_payment"
            ? "Money arrived for an order that is still awaiting payment — see the shortfall on the order itself."
            : "Somebody should look at this order."
        }`
  }</p>
</div>`
    : view.query === ""
      ? `<p class="notice">Every charge in this shop comes to ${escape(formatCents(view.shop.charged_cents))}, every
  refund to ${escape(formatCents(view.shop.refunded_cents))}: <strong>${escape(
    formatCents(view.shop.held_cents),
  )}</strong> taken and not given back.</p>`
      : `<p class="notice bad">No order called ${escape(view.query)}.</p>`
}
${
  rows.length === 0
    ? '<p class="muted">Nothing here.</p>'
    : `<table class="steady">
  <colgroup><col style="width:15%"><col style="width:15%"><col style="width:12%"><col style="width:33%">
    <col style="width:13%"><col style="width:12%"></colgroup>
  <thead><tr><th>When</th><th>Who</th><th>What</th><th>Detail</th><th>Order</th><th class="num">Amount</th></tr></thead>
  <tbody>${rows
    .map(
      (row) => `<tr>
    <td class="muted" style="white-space:nowrap">${escape(row.at)}</td>
    <td>${who(row)}</td>
    <td>${escape(row.what)}</td>
    <td class="muted">${escape(row.detail)}</td>
    <td>${
      row.order_number === null
        ? '<span class="muted">—</span>'
        : `<a href="/admin/orders/${escape(row.order_number)}">${escape(row.order_number)}</a>`
    }</td>
    <td class="num price">${row.cents === null ? '<span class="muted">—</span>' : escape(formatCents(row.cents))}</td>
  </tr>`,
    )
    .join("\n")}</tbody>
</table>`
}
${view.older === null ? "" : `<p><a class="btn ghost" href="${escape(view.older)}">Older →</a></p>`}
`;
}
// --- codes, cards and tax ----------------------------------------------------
const dateCell = (value: string | null): string => escape(value ?? "—");
@@ -75,6 +75,7 @@
export const routes: Route[] = [
  { method: "POST", pattern: "/admin/orders/:number/cancel", handler: admin.orderCancel },
  { method: "GET", pattern: "/admin/mail", handler: admin.mailbox },
  { method: "GET", pattern: "/admin/changes", handler: admin.changeList },
  { method: "GET", pattern: "/admin/audit", handler: admin.auditList },
];
export type Match = { route: Route; params: Record<string, string> };
@@ -99,6 +99,9 @@
class Shopper {
  }
}
/** Somebody, for the rows a test writes by hand: every ledger names one. */
const ADA = { id: "u_1", name: "ada", role: "admin" } as const;
/** An admin, the way the forge signs one in. */
const asAdmin = (): Shopper => new Shopper({ id: "u_1", name: "ada", role: "admin" });
@@ -421,8 +424,8 @@
test("a discount, a part-spent gift card and a state's rate become an order that
  limit.forget();
  const shopper = asCustomer();
  // A card someone has already spent $15 of, so $35 of its $50 is left.
  const { card, code } = giftcards.issue({ cents: 5000, note: "bought earlier" });
  expect(giftcards.spend(card.id, 1500, "spent at another till")).toBe(true);
  const { card, code } = giftcards.issue({ cents: 5000, note: "bought earlier", by: ADA });
  expect(giftcards.spend(card.id, 1500, "spent at another till", ADA)).toBe(true);
  await addToCart(shopper, "COF-GUJI-250", 3); // $57.00 of goods
  await addToCart(shopper, "GFT-CARD-25", 1); // $25.00 of money, which is not a sale
@@ -500,7 +503,7 @@
test("a discount, a part-spent gift card and a state's rate become an order that
test("two orders on one gift card spend what is on it and no more", async () => {
  limit.forget();
  const { card, code } = giftcards.issue({ cents: 3000, note: "one card, two shoppers" });
  const { card, code } = giftcards.issue({ cents: 3000, note: "one card, two shoppers", by: ADA });
  // Two shoppers hold the same code, each with $23.32 to pay.
  const first = asCustomer();
@@ -876,6 +879,73 @@
test("an unsigned webhook is refused", async () => {
  expect(response.status).toBe(400);
});
test("every ledger row names who caused it, and /admin/audit is the five of them at once", async () => {
  limit.forget();
  const person = account();
  const shopper = new Shopper(person);
  const { number } = await buy(shopper, "COF-DECAF-250", 1);
  const order = orderNamed(number);
  // The buyer caused the sale: the stock it took, the charge and the events.
  const rowsOf = (table: string, where: string): any[] =>
    db.query<any, [number]>(`SELECT * FROM ${table} WHERE ${where} = ?1 ORDER BY id`).all(order.id);
  const sold = rowsOf("stock_entry", "order_id").find((row) => row.delta < 0)!;
  expect([sold.actor_id, sold.actor_name, sold.actor_role]).toEqual([person.id, person.name, "user"]);
  const charge = rowsOf("payment", "order_id").find((row) => row.kind === "charge")!;
  expect([charge.actor_id, charge.actor_role]).toEqual([person.id, "user"]);
  expect(rowsOf("order_event", "order_id").every((row) => row.actor_id === person.id)).toBe(true);
  // The admin caused the refund, and their name is on that row and no other.
  const admin = asAdmin();
  const orderPage = await admin.page(`/admin/orders/${number}`);
  const refunded = await admin.post(
    `/admin/orders/${number}/refund`,
    { amount: "1.00", reason: "a tear in the bag", restock: "" },
    Shopper.tokenIn(orderPage),
  );
  expect(refunded.status).toBe(303);
  const refund = rowsOf("payment", "order_id").find((row) => row.kind === "refund")!;
  expect([refund.actor_id, refund.actor_name, refund.actor_role]).toEqual(["u_1", "ada", "admin"]);
  // The order page says who, on every payment and every event it lists.
  const detail = await admin.page(`/admin/orders/${number}`);
  expect(detail).toContain(">ada<");
  expect(detail).toContain(person.name);
  // And the timeline reads all five, newest first: the refund is above the
  // charge, both name their actor, and each links to the order.
  const page = await admin.page(`/admin/audit?q=${number}`);
  expect(page.indexOf("refund")).toBeLessThan(page.indexOf("charge"));
  expect(page).toContain(`href="/admin/orders/${number}"`);
  expect(page).toContain("ada");
  expect(page).toContain(person.name);
  // It reconciles: what the ledgers hold is what the order says was paid.
  expect(page).toContain("these agree");
  expect(page).toContain(`${((order.total_cents - 100) / 100).toFixed(2)}`);
  // A number nobody has is not a way to read the whole trail.
  expect(await admin.page("/admin/audit?q=BZ-NOSUCHROW")).toContain("No order called BZ-NOSUCHROW");
});
test("the audit trail is an admin's, and it pages from a cursor", async () => {
  limit.forget();
  const admin = asAdmin();
  expect((await new Shopper().get("/admin/audit")).status).toBe(403);
  expect((await asCustomer().get("/admin/audit")).status).toBe(403);
  const page = await admin.page("/admin/audit");
  expect(page).toContain("Audit");
  const older = /href="(\/admin\/audit\?q=&amp;before=[^"]+)"/.exec(page)?.[1]?.replace(/&amp;/g, "&");
  expect(older).toBeDefined();
  // The link leads to a page of the same trail; src/units.test.ts is where
  // the cursor is held to not repeating or skipping a row.
  expect(await admin.page(older!)).toContain("Audit");
  // A cursor that is not one is not a place: the newest page comes back.
  expect(await admin.page("/admin/audit?before=' OR 1=1 --")).toContain("Audit");
});
test("/admin opens for an admin the forge signed, and refunds and restocks", async () => {
  limit.forget();
  const shopper = asCustomer();
@@ -1161,8 +1231,8 @@
test("an admin adds a product and a variant, and the shop sells it", async () =>
test("whoever holds a gift card's code can see what is left on it, and nobody else learns anything", async () => {
  limit.forget();
  const { card, code } = giftcards.issue({ cents: 2500, note: "a present" });
  expect(giftcards.spend(card.id, 1000, "spent on something else")).toBe(true);
  const { card, code } = giftcards.issue({ cents: 2500, note: "a present", by: ADA });
  expect(giftcards.spend(card.id, 1000, "spent on something else", ADA)).toBe(true);
  const holder = new Shopper();
  const form = await holder.page("/gift-cards");
@@ -1243,8 +1313,8 @@
test("reading a balance does not use up the tokens for spending a code", async (
test("a long ledger says it was cut off, and a void card offers nothing to spend", async () => {
  limit.forget();
  const { card, code } = giftcards.issue({ cents: 100, note: "much used" });
  for (let n = 0; n < 22; n++) expect(giftcards.credit(card.id, 100, `top-up ${n}`)).toBe(true);
  const { card, code } = giftcards.issue({ cents: 100, note: "much used", by: ADA });
  for (let n = 0; n < 22; n++) expect(giftcards.credit(card.id, 100, `top-up ${n}`, ADA)).toBe(true);
  const holder = new Shopper();
  const form = await holder.page("/gift-cards");
@@ -1254,22 +1324,22 @@
test("a long ledger says it was cut off, and a void card offers nothing to spend
  expect(page).toContain("Spend it in your cart"); // live card, money on it
  // Voided: the balance is written away, so there is nothing to spend.
  giftcards.setActive(card.id, false, "lost in the post");
  giftcards.setActive(card.id, false, "lost in the post", ADA);
  const voided = await holder.post("/gift-cards", { code }, Shopper.tokenIn(form)).then((r) => r.text());
  expect(voided).toContain("Void — nothing can be spent");
  expect(voided).not.toContain("Spend it in your cart");
  // A live card with nothing left is the same: no link, and no cut-off note.
  const empty = giftcards.issue({ cents: 500, note: "spent out" });
  expect(giftcards.spend(empty.card.id, 500, "spent at another till")).toBe(true);
  const empty = giftcards.issue({ cents: 500, note: "spent out", by: ADA });
  expect(giftcards.spend(empty.card.id, 500, "spent at another till", ADA)).toBe(true);
  const flat = await holder.post("/gift-cards", { code: empty.code }, Shopper.tokenIn(form)).then((r) => r.text());
  expect(flat).not.toContain("Spend it in your cart");
  expect(flat).not.toContain("The last 20 movements");
  // Exactly as many movements as the window holds is not a cut-off: issuing
  // wrote the first row, so nineteen more make twenty and nothing is hidden.
  const exact = giftcards.issue({ cents: 100, note: "twenty on the nose" });
  for (let n = 0; n < 19; n++) expect(giftcards.credit(exact.card.id, 100, `top-up ${n}`)).toBe(true);
  const exact = giftcards.issue({ cents: 100, note: "twenty on the nose", by: ADA });
  for (let n = 0; n < 19; n++) expect(giftcards.credit(exact.card.id, 100, `top-up ${n}`, ADA)).toBe(true);
  const full = await holder.post("/gift-cards", { code: exact.code }, Shopper.tokenIn(form)).then((r) => r.text());
  expect(full).toContain("$20.00"); // twenty rows of a dollar, all of them shown
  expect(full).not.toContain("The last 20 movements");
@@ -9,6 +9,7 @@
 * and payment are rate limited. Nothing that takes money happens on a GET.
 */
import * as actors from "./actor.ts";
import * as cart from "./cart.ts";
import * as codes from "./codes.ts";
import * as discounts from "./discounts.ts";
@@ -283,7 +284,9 @@
export function placeOrder(ctx: Ctx): Response {
  // An order belongs to an account, so there is nothing to place without one:
  // no row, no stock taken, no code redeemed. Back to the page that says so.
  if (ctx.who.role === "anon") return redirect("/checkout");
  const buyer = { id: ctx.who.id, name: ctx.who.name };
  // The buyer is the order's account and the actor of every row placing it
  // writes: the stock it takes, the code it redeems, the balance it spends.
  const buyer = actors.of(ctx.who);
  const values = {
    email: field(ctx.form, "email", 200),
    name: field(ctx.form, "name", 120),
@@ -380,15 +383,19 @@
export function payMock(ctx: Ctx): Response {
  if (chosen().kind !== "mock") return redirect(orderLink(ctx, order, "pay"));
  const decision = field(ctx.form, "decision", 10);
  if (decision !== "approve") {
    orders.note(order.id, "declined", "the mock gateway was asked to decline");
    orders.note(order.id, "declined", actors.paying(ctx.who, order), "the mock gateway was asked to decline");
    ctx.params.number = order.number;
    return payPageFor(ctx, order, "The mock gateway declined this payment. Nothing was charged; try again.");
  }
  const paid = orders.settleFromGateway(order, {
    gateway: "mock",
    ref: `mock_${crypto.randomUUID().replace(/-/g, "").slice(0, 20)}`,
    amount_cents: dueCents(order),
  });
  const paid = orders.settleFromGateway(
    order,
    {
      gateway: "mock",
      ref: `mock_${crypto.randomUUID().replace(/-/g, "").slice(0, 20)}`,
      amount_cents: dueCents(order),
    },
    actors.paying(ctx.who, order),
  );
  return redirect(orderLink(ctx, paid));
}
@@ -415,7 +422,7 @@
export async function payStripe(ctx: Ctx): Promise<Response> {
    cancel: `${publicOrigin()}/pay/${order.number}?token=${encodeURIComponent(order.access_token)}`,
  });
  if (!session.ok) return payPageFor(ctx, order, session.error);
  orders.note(order.id, "checkout-started", session.value.id);
  orders.note(order.id, "checkout-started", actors.paying(ctx.who, order), session.value.id);
  orders.rememberGatewayRef(order, session.value.id);
  // A form POST answered with a redirect off-site: the response says where it
  // goes, so the policy on it allows that one hop and no other.
@@ -427,7 +434,7 @@
export async function payStripe(ctx: Ctx): Promise<Response> {
export async function orderPage(ctx: Ctx): Promise<Response> {
  let order = openOrder(ctx, "query");
  if (!order) return notFound(ctx);
  order = await settleStripe(order);
  order = await settleStripe(order, actors.paying(ctx.who, order));
  const refunded = orders.refundedCents(order.id);
  return render(
    ctx,
@@ -510,7 +517,7 @@
export function findOrder(ctx: Ctx): Response {
  if (!order || !matched) return ordersPage(ctx, NOT_FOUND, values);
  // The address, not the header: what goes in the trail has to be a fact.
  orders.note(order.id, "looked-up", `found from ${ctx.peer.address}`);
  orders.note(order.id, "looked-up", actors.of(ctx.who), `found from ${ctx.peer.address}`);
  rememberOrder(ctx, order);
  return redirect(orderLink(ctx, order));
}
@@ -530,18 +537,22 @@
export async function receiptPage(ctx: Ctx): Promise<Response> {
 * wins because the charge has an idempotency key. Stripe's amount is recorded,
 * not trusted: what it means for the order is decided there, against the total.
 */
async function settleStripe(order: Order): Promise<Order> {
async function settleStripe(order: Order, by: actors.Actor): Promise<Order> {
  if (order.status !== "pending_payment") return order;
  if (order.gateway !== "stripe" || !order.payment_ref?.startsWith("cs_")) return order;
  const session = await gateway.readCheckout(order.payment_ref);
  if (!session.ok || session.value.payment_status !== "paid") return order;
  // Stripe's own number for what it took, believed as a number and no further:
  // settleFromGateway compares it to what the order owes.
  return orders.settleFromGateway(order, {
    gateway: "stripe",
    ref: session.value.payment_intent ?? order.payment_ref,
    amount_cents: session.value.amount_total ?? 0,
  });
  return orders.settleFromGateway(
    order,
    {
      gateway: "stripe",
      ref: session.value.payment_intent ?? order.payment_ref,
      amount_cents: session.value.amount_total ?? 0,
    },
    by,
  );
}
/**
@@ -565,11 +576,16 @@
export function stripeWebhook(ctx: Ctx): Response {
    const number = String(session.client_reference_id ?? session.metadata?.order_number ?? "").slice(0, 20);
    const order = number ? orders.byNumber(number) : null;
    if (order && session.payment_status === "paid")
      orders.settleFromGateway(order, {
        gateway: "stripe",
        ref: typeof session.payment_intent === "string" ? session.payment_intent : String(session.id ?? ""),
        amount_cents: typeof session.amount_total === "number" ? session.amount_total : 0,
      });
      // Nobody asked for this row: Stripe told us, so Stripe is what it names.
      orders.settleFromGateway(
        order,
        {
          gateway: "stripe",
          ref: typeof session.payment_intent === "string" ? session.payment_intent : String(session.id ?? ""),
          amount_cents: typeof session.amount_total === "number" ? session.amount_total : 0,
        },
        actors.STRIPE,
      );
  }
  return text("ok");
}
@@ -568,6 +568,8 @@
test("a signed webhook pays an order that never came back", async () => {
  expect(charges.length).toBe(1);
  expect(charges[0].amount_cents).toBe(dueOf(placed.number));
  expect(charges[0].gateway_ref).toBe(sessions.get(sessionId)!.payment_intent);
  // Nobody asked for this row: Stripe told us, so Stripe is what it names.
  expect([charges[0].actor_id, charges[0].actor_name, charges[0].actor_role]).toEqual(["", "stripe", "stripe"]);
  // And the shopper who finally comes back is shown the order, not a charge.
  expect((await comeBack(shopper, placed)).status).toBe(200);
@@ -18,15 +18,17 @@
 * `src/desk.ts` holds the one table all of these gates read, and `ordersFor`
 * is the one place the rows are chosen.
 *
 * 1..7 switch between stock, orders, the outbox, discount codes, gift cards,
 * the tax table and the changes an admin made to any of it — everything
 * /admin can see. j/k move, and each tab says at its foot what it can do: s
 * moves stock with a reason, / narrows the orders in front of you by number,
 * name or email, r refunds what is left of an order and puts it back on the
 * shelf, n writes a code, i issues a card, e sets a tax rate, c looks a code
 * up. q leaves. Plain ANSI, no dependencies.
 * 1..8 switch between stock, orders, the outbox, discount codes, gift cards,
 * the tax table, the changes an admin made to any of it and the audit trail —
 * everything /admin can see. j/k move, and each tab says at its foot what it
 * can do: s moves stock with a reason, / narrows the orders in front of you by
 * number, name or email — or, on the audit tab, the trail to one order — r
 * refunds what is left of an order and puts it back on the shelf, n writes a
 * code, i issues a card, e sets a tax rate, c looks a code up. q leaves.
 * Plain ANSI, no dependencies.
 */
import * as audit from "./audit.ts";
import * as desk from "./desk.ts";
import * as discounts from "./discounts.ts";
import * as giftcards from "./giftcards.ts";
@@ -37,8 +39,10 @@
import { formatCents } from "./money.ts";
import { history, addStock, setStock } from "./inventory.ts";
import { itemsOf, paymentsOf, refund, refundableCents, refundedCents, shortfall } from "./orders.ts";
import { outbox } from "./mail.ts";
import { atDesk } from "./actor.ts";
import { atKeyboard } from "./who.ts";
import { nameOf, recent as recentChanges, type Reading } from "./changes.ts";
import { byNumber } from "./orders.ts";
import type { GiftCard, Order, TaxRate } from "./db.ts";
const person = atKeyboard();
@@ -91,6 +95,14 @@
let filter = "";
// is the shop's, anybody else's is their own account's — narrowed by `/`.
const orderRows = (): Order[] => desk.ordersFor(person, filter);
// What the audit tab is narrowed to: one order, by its number, or the shop.
let trailFilter = "";
const auditRows = (): audit.Entry[] => {
  const order = trailFilter === "" ? null : byNumber(trailFilter);
  return trailFilter !== "" && !order ? [] : audit.timeline({ orderId: order?.id, limit: 60 });
};
const rowsFor = (): unknown[] =>
  tab === "stock"
    ? stockRows()
@@ -104,7 +116,9 @@
const rowsFor = (): unknown[] =>
            ? giftcards.all()
            : tab === "tax"
              ? tax.rates()
              : recentChanges(100);
              : tab === "changes"
                ? recentChanges(100)
                : auditRows();
/** A message from the desk, with a refusal marked so it cannot be missed. */
const say = (done: desk.Done): string => (done.ok ? done.message : `${esc}33m${done.message}${esc}0m`);
@@ -130,10 +144,11 @@
const may = (key: string): boolean => desk.mayPress(tab, key, person);
 */
const hints = (): string =>
  [
    "1-7 tabs",
    `1-${TABS.length} tabs`,
    "j/k move",
    ...desk.offered(tab, person),
    ...(tab === "orders" && filter !== "" ? [`showing “${filter}”`] : []),
    ...(tab === "audit" && trailFilter !== "" ? [`showing “${trailFilter}”`] : []),
    "q quit",
  ].join(" · ");
@@ -251,7 +266,46 @@
function draw(): void {
      ).slice(0, 20)}`;
      lines.push(`${mark} ${i === cursor ? bold(text) : text}`);
    });
  if (tab === "audit")
    (rows as audit.Entry[]).forEach((row, i) => {
      const mark = i === cursor ? "▸" : " ";
      const text = `${row.at.padEnd(20)} ${row.actor_name.padEnd(12).slice(0, 12)} ${row.what
        .padEnd(14)
        .slice(0, 14)} ${(row.order_number ?? "—").padEnd(12)} ${(row.cents === null
        ? "—"
        : formatCents(row.cents)
      ).padStart(10)}  ${row.detail.slice(0, 34)}`;
      lines.push(`${mark} ${i === cursor ? bold(text) : text}`);
    });
  lines.push("");
  if (tab === "audit") {
    // The same figure the page reconciles: charges less refunds, against what
    // the order says was paid.
    const order = trailFilter === "" ? null : byNumber(trailFilter);
    if (order) {
      const balance = audit.balanceOf(order);
      lines.push(
        dim(
          `  ${order.number}: ${formatCents(balance.charged_cents)} charged + ${formatCents(
            balance.gift_card_cents,
          )} card − ${formatCents(balance.refunded_cents + balance.gift_card_back_cents)} back = ${formatCents(
            balance.held_cents,
          )}; the order says ${formatCents(balance.says_cents)}${balance.agrees ? "" : " — these do not agree"}`,
        ),
        "",
      );
    } else if (trailFilter === "") {
      const shop = audit.shopBalance();
      lines.push(
        dim(
          `  ${formatCents(shop.charged_cents)} charged − ${formatCents(shop.refunded_cents)} refunded = ${formatCents(
            shop.held_cents,
          )} held`,
        ),
        "",
      );
    }
  }
  if (message) lines.push(message, "");
  lines.push(prompt === undefined ? dim(hints()) : `${prompt.label} ${prompt.text}${esc}7m ${esc}0m`);
  out(`${esc}2J${esc}H` + lines.join("\r\n"));
@@ -267,8 +321,8 @@
function moveStock(value: string): string {
  const reason = rest.join(" ").trim();
  if (delta === undefined || delta === 0) return "A move is a whole number, like 12 or -3.";
  if (reason === "") return "A move needs a reason.";
  if (delta > 0) addStock(row.id, delta, reason);
  else setStock(row.id, Math.max(0, row.stock + delta), reason);
  if (delta > 0) addStock(row.id, delta, reason, atDesk());
  else setStock(row.id, Math.max(0, row.stock + delta), reason, atDesk());
  return `${row.sku}: ${delta > 0 ? "+" : ""}${delta} — ${reason}`;
}
@@ -281,6 +335,14 @@
function findOrders(value: string): string {
  return found === 0 ? `Nothing matches “${filter}”.` : `${found} order${found === 1 ? "" : "s"} match “${filter}”.`;
}
/** `/` on the audit tab: one order's trail, or the shop's when it is cleared. */
function findTrail(value: string): string {
  trailFilter = value.trim().slice(0, 20).toUpperCase();
  cursor = 0;
  if (trailFilter === "") return "Showing the whole trail.";
  return byNumber(trailFilter) ? `The trail of ${trailFilter}.` : `No order called ${trailFilter}.`;
}
function refundRest(reason: string): string {
  const order = orderRows()[cursor];
  if (!order) return "No order selected.";
@@ -293,6 +355,7 @@
function refundRest(reason: string): string {
    restock: true,
    gateway_ref: `tty_refund_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`,
    idempotencyKey: `refund:${order.number}:${refundedCents(order.id)}:${left}`,
    by: atDesk(),
  });
  return done.ok ? `${order.number}: refunded ${formatCents(left)} and restocked.` : done.error;
}
@@ -335,6 +398,8 @@
process.stdin.on("data", (key: string) => {
    prompt = { label: "Move (e.g. 12 a delivery arrived):", text: "", run: moveStock };
  if (key === "/" && tab === "orders" && may("/"))
    prompt = { label: "Find an order (number, name or email):", text: filter, run: findOrders };
  if (key === "/" && tab === "audit" && may("/"))
    prompt = { label: "The trail of one order (its number, or nothing for all):", text: trailFilter, run: findTrail };
  if (key === "r" && tab === "orders" && may("r")) prompt = { label: "Refund the rest — reason:", text: "", run: refundRest };
  if (key === "c" && (tab === "codes" || tab === "cards") && may("c"))
    prompt = { label: "Check a code:", text: "", run: (value) => say(desk.look(value)) };
@@ -17,6 +17,9 @@
const mine = await import("./mine.ts");
const peer = await import("./peer.ts");
const { escape } = await import("./html.ts");
const catalog = await import("./catalog.ts");
const actors = await import("./actor.ts");
const audit = await import("./audit.ts");
const inventory = await import("./inventory.ts");
const changes = await import("./changes.ts");
const desk = await import("./desk.ts");
const discounts = await import("./discounts.ts");
@@ -35,6 +38,9 @@
tax.seed();
const variantId = (sku: string): number =>
  db.query<{ id: number }, [string]>("SELECT id FROM variant WHERE sku = ?1").get(sku)!.id;
/** Somebody, for the rows these tests write by hand: every ledger names one. */
const ADA = { id: "u_9", name: "ada", role: "admin" } as const;
test("money is integer cents in and out", () => {
  expect(formatCents(129900)).toBe("$1,299.00");
  expect(formatCents(0)).toBe("$0.00");
@@ -106,8 +112,8 @@
test("a percent discount, a part-spent gift card and a regional rate reconcile i
  const money = variantId("GFT-CARD-25"); // $25.00 of money, which is not a sale
  // A card someone has already spent $15 of: what is left is what it can pay.
  const { card, code } = giftcards.issue({ cents: 5000, note: "used once already" });
  expect(giftcards.spend(card.id, 1500, "spent at another till")).toBe(true);
  const { card, code } = giftcards.issue({ cents: 5000, note: "used once already", by: ADA });
  expect(giftcards.spend(card.id, 1500, "spent at another till", ADA)).toBe(true);
  expect(giftcards.byId(card.id)!.balance_cents).toBe(3500);
  const priced = quote(
@@ -175,17 +181,17 @@
test("the rate follows the address, and tax is taken after the discount", () =>
});
test("two redemptions of one gift card cannot drive its balance negative", () => {
  const { card } = giftcards.issue({ cents: 2500, note: "one card, two tills" });
  const { card } = giftcards.issue({ cents: 2500, note: "one card, two tills", by: ADA });
  // Two tills reach for the same $25 with $20 each: only the first is paid.
  expect(giftcards.spend(card.id, 2000, "till one")).toBe(true);
  expect(giftcards.spend(card.id, 2000, "till two")).toBe(false);
  expect(giftcards.spend(card.id, 2000, "till one", ADA)).toBe(true);
  expect(giftcards.spend(card.id, 2000, "till two", ADA)).toBe(false);
  expect(giftcards.byId(card.id)!.balance_cents).toBe(500);
  // The second till may still have what is actually there, and no more.
  expect(giftcards.spend(card.id, 500, "till two, for what is left")).toBe(true);
  expect(giftcards.spend(card.id, 500, "till two, for what is left", ADA)).toBe(true);
  expect(giftcards.byId(card.id)!.balance_cents).toBe(0);
  expect(giftcards.spend(card.id, 1, "till three")).toBe(false);
  expect(giftcards.spend(card.id, 1, "till three", ADA)).toBe(false);
  // A refusal writes nothing, and the balance is the sum of what was written.
  const entries = giftcards.entriesOf(card.id).reverse();
@@ -319,7 +325,7 @@
test("an audit row is one field that moved, capped, and a no-op is no row at all
  expect(row.actor_name).toBe("ada");
  // Whoever the forge did not name is nobody, and a boolean reads as a word.
  expect(changes.actorOf({ role: "anon" })).toEqual({ id: "", name: "unknown" });
  expect(actors.of({ role: "anon" })).toEqual({ id: "", name: "unknown", role: "unknown" });
  expect(changes.say(true)).toBe("yes");
  expect(changes.say(undefined)).toBe("");
});
@@ -400,7 +406,7 @@
test("a code's limits and expiry are enforced where the use is taken, not only w
    starts_at: null,
    expires_at: "2020-01-01 23:59:59",
  });
  expect(discounts.redeem(expired, orderId, 500)).toBe(false);
  expect(discounts.redeem(expired, orderId, 500, ADA)).toBe(false);
  expect(used(expired)).toBe(0);
  expect(rows(expired)).toBe(0);
@@ -414,7 +420,7 @@
test("a code's limits and expiry are enforced where the use is taken, not only w
    starts_at: "2099-01-01 00:00:00",
    expires_at: null,
  });
  expect(discounts.redeem(early, orderId, 500)).toBe(false);
  expect(discounts.redeem(early, orderId, 500, ADA)).toBe(false);
  expect(used(early)).toBe(0);
  // One that is live, with one use: the first takes it and the second cannot.
@@ -427,8 +433,8 @@
test("a code's limits and expiry are enforced where the use is taken, not only w
    starts_at: null,
    expires_at: "2099-12-31 23:59:59",
  });
  expect(discounts.redeem(once, orderId, 500)).toBe(true);
  expect(discounts.redeem(once, orderId, 500)).toBe(false);
  expect(discounts.redeem(once, orderId, 500, ADA)).toBe(true);
  expect(discounts.redeem(once, orderId, 500, ADA)).toBe(false);
  expect(used(once)).toBe(1);
  expect(rows(once)).toBe(1);
@@ -443,11 +449,11 @@
test("a code's limits and expiry are enforced where the use is taken, not only w
    starts_at: null,
    expires_at: "2099-12-31 23:59:59",
  });
  expect(discounts.redeem(roomy, orderId, 500, later)).toBe(false);
  expect(discounts.redeem(roomy, orderId, 500, ADA, later)).toBe(false);
  expect(used(roomy)).toBe(0);
  // A use given back is a row of its own, and the counter follows it.
  discounts.release(once, orderId, 500);
  discounts.release(once, orderId, 500, ADA);
  expect(used(once)).toBe(0);
  expect(rows(once)).toBe(2);
  expect(discounts.withUse().find((row) => row.code === "ONE-USE-ONLY")!.given_cents).toBe(0);
@@ -697,10 +703,10 @@
test("a deployment that knows how many proxies are in front says so, and is beli
});
test("a card's holder is told what happened, not what the shop wrote to itself", () => {
  const { card } = giftcards.issue({ cents: 4000, note: "a present" });
  const { card } = giftcards.issue({ cents: 4000, note: "a present", by: ADA });
  const orderId = bareOrder("BZ-CARD-WORDS");
  expect(giftcards.spend(card.id, 1000, "paid on BZ-CARD-WORDS", orderId)).toBe(true);
  giftcards.setActive(card.id, false, "chargeback from the buyer, do not honour");
  expect(giftcards.spend(card.id, 1000, "paid on BZ-CARD-WORDS", ADA, orderId)).toBe(true);
  giftcards.setActive(card.id, false, "chargeback from the buyer, do not honour", ADA);
  const shown = giftcards.publicEntriesOf(card.id);
  expect(shown.map((entry) => entry.what)).toEqual(["Taken off the card", "Spent on an order", "Issued"]);
@@ -727,7 +733,7 @@
const shortEvents = (orderId: number) => orders.eventsOf(orderId).filter((event)
test("a gateway's amount is compared to what the order owes before anything is called paid", () => {
  // Short: the money that moved is written down, and the order is not paid.
  const short = pendingOrder("BZ-SHORT-1", 5000);
  const after = orders.settleFromGateway(short, { gateway: "mock", ref: "ref_short", amount_cents: 4500 });
  const after = orders.settleFromGateway(short, { gateway: "mock", ref: "ref_short", amount_cents: 4500 }, ADA);
  expect(after.status).toBe("pending_payment");
  expect(after.paid_at).toBeNull();
  expect(orders.chargedCents(short.id)).toBe(4500);
@@ -740,25 +746,25 @@
test("a gateway's amount is compared to what the order owes before anything is c
  // Exactly what is owed pays it, and so does more than that.
  const exact = pendingOrder("BZ-EXACT-1", 5000);
  expect(orders.settleFromGateway(exact, { gateway: "mock", ref: "ref_exact", amount_cents: 5000 }).status).toBe("paid");
  expect(orders.settleFromGateway(exact, { gateway: "mock", ref: "ref_exact", amount_cents: 5000 }, ADA).status).toBe("paid");
  expect(orders.shortfall(orders.byNumber("BZ-EXACT-1")!)).toBeNull();
  const over = pendingOrder("BZ-OVER-1", 5000);
  expect(orders.settleFromGateway(over, { gateway: "mock", ref: "ref_over", amount_cents: 5100 }).status).toBe("paid");
  expect(orders.settleFromGateway(over, { gateway: "mock", ref: "ref_over", amount_cents: 5100 }, ADA).status).toBe("paid");
  expect(orders.chargedCents(over.id)).toBe(5100);
  // A gateway that names no amount moved no money we can write a row for, and
  // it says so once however many times the same claim is delivered.
  const nothing = pendingOrder("BZ-NOTHING-1", 5000);
  for (let i = 0; i < 3; i++)
    orders.settleFromGateway(nothing, { gateway: "stripe", ref: "pi_nothing", amount_cents: 0 });
    orders.settleFromGateway(nothing, { gateway: "stripe", ref: "pi_nothing", amount_cents: 0 }, ADA);
  expect(orders.paymentsOf(nothing.id).length).toBe(0);
  expect(shortEvents(nothing.id).length).toBe(1);
  expect(orders.byNumber("BZ-NOTHING-1")!.status).toBe("pending_payment");
  // One key per order: a second arrival is the same charge, not another one.
  const twice = pendingOrder("BZ-TWICE-1", 5000);
  orders.settleFromGateway(twice, { gateway: "mock", ref: "ref_one", amount_cents: 5000 });
  orders.settleFromGateway(twice, { gateway: "mock", ref: "ref_two", amount_cents: 5000 });
  orders.settleFromGateway(twice, { gateway: "mock", ref: "ref_one", amount_cents: 5000 }, ADA);
  orders.settleFromGateway(twice, { gateway: "mock", ref: "ref_two", amount_cents: 5000 }, ADA);
  expect(orders.paymentsOf(twice.id).length).toBe(1);
  expect(orders.eventsOf(twice.id).filter((event) => event.kind === "paid").length).toBe(1);
});
@@ -771,16 +777,16 @@
test("the admin's screen is told about a payment only when the order becomes pai
    // Short. The ledger says awaiting payment, so a live page that said paid
    // would be the admin's screen lying about the money.
    const short = pendingOrder("BZ-SHORT-LIVE", 5000);
    orders.settleFromGateway(short, { gateway: "mock", ref: "ref_short_live", amount_cents: 4500 });
    orders.settleFromGateway(short, { gateway: "mock", ref: "ref_short_live", amount_cents: 4500 }, ADA);
    expect(paidEvents()).toEqual([]);
    // Covered: one event, from the branch that moved the row to paid.
    const full = pendingOrder("BZ-FULL-LIVE", 5000);
    orders.settleFromGateway(full, { gateway: "mock", ref: "ref_full_live", amount_cents: 5000 });
    orders.settleFromGateway(full, { gateway: "mock", ref: "ref_full_live", amount_cents: 5000 }, ADA);
    expect(paidEvents()).toEqual([{ type: "order.paid", data: { id: full.id, number: "BZ-FULL-LIVE", cents: 5000 } }]);
    // The webhook arriving behind the browser is the same charge, not another.
    orders.settleFromGateway(full, { gateway: "mock", ref: "ref_full_again", amount_cents: 5000 });
    orders.settleFromGateway(full, { gateway: "mock", ref: "ref_full_again", amount_cents: 5000 }, ADA);
    expect(paidEvents().length).toBe(1);
  } finally {
    unsubscribe();
@@ -829,3 +835,45 @@
test("the route table knows which paths a GET answers", () => {
  expect(getAnswers("/checkout")).toBe(true);
  expect(getAnswers("/gift-cards")).toBe(true);
});
test("a stock move typed at the terminal names the account the forge put there", () => {
  const before = { ...process.env };
  process.env.FORGE_APP_USER = "bo";
  process.env.FORGE_APP_USER_ID = "u_7";
  process.env.FORGE_APP_USER_ROLE = "admin";
  try {
    const id = variantId("COF-GUJI-250");
    inventory.addStock(id, 3, "a delivery arrived", actors.atDesk());
    const row = inventory.historyOf(id, 1)[0]!;
    expect([row.actor_id, row.actor_name, row.actor_role]).toEqual(["u_7", "bo", "admin"]);
  } finally {
    if (before.FORGE_APP_USER === undefined) delete process.env.FORGE_APP_USER;
    if (before.FORGE_APP_USER_ID === undefined) delete process.env.FORGE_APP_USER_ID;
    if (before.FORGE_APP_USER_ROLE === undefined) delete process.env.FORGE_APP_USER_ROLE;
  }
});
test("the audit timeline is one order of rows, whether it is read whole or paged", () => {
  const name = (entry: { source: string; id: number }): string => `${entry.source}:${entry.id}`;
  const whole = audit.timeline({ limit: 12 }).slice(0, 12).map(name);
  expect(whole.length).toBe(12);
  // The same rows, three at a time, following the cursor each page says.
  const paged: string[] = [];
  let before: ReturnType<typeof audit.readCursor>;
  while (paged.length < 12) {
    const rows = audit.timeline({ limit: 3, before }).slice(0, 3);
    if (rows.length === 0) break;
    for (const row of rows) paged.push(name(row));
    // The cursor goes out through a URL and comes back as text, as it does
    // on the page: what a browser hands back is what is trusted here.
    before = audit.readCursor(audit.cursorOf(rows[rows.length - 1]!));
    expect(before).toBeDefined();
  }
  expect(paged).toEqual(whole);
  expect(new Set(paged).size).toBe(paged.length);
  // A cursor nobody wrote is not a place in the timeline.
  expect(audit.readCursor("' OR 1=1 --")).toBeUndefined();
  expect(audit.readCursor("2026-01-01 00:00:00|9|1")).toBeUndefined();
});
		@@ -40,6 +40,17 @@ admin's three live pages load one small file — see
40	40	changes to what the shop sells and what it charges are a ledger too: a
41	41	price, a slug, a discount code or a tax rate that moves writes a row at
42	42	`/admin/changes` naming who moved it and what it was before.
	43	- The audit trail: every stock movement, payment, refund, order event,
	44	gift-card movement and use of a code names the actor who caused it — the
	45	buyer for a purchase, the admin for an admin's action, `stripe` for a
	46	webhook, `system` for the seed, and the forge's account for anything typed
	47	at the terminal. `/admin/audit` reads those five ledgers as one timeline,
	48	newest first, narrowed to one order by its number and paged with a cursor;
	49	it is an admin's page, and an admin's alone, as is the `audit` tab in the
	50	terminal. For one order it shows the arithmetic rather than a claim:
	51	charges plus the gift card, less refunds and what went back on the card,
	52	against what the order says was paid. Rows written before the actor column
	53	existed say `unknown`, which is the truth about them.
43	54	- Simulated unless you configure it: the payment. With no Stripe keys the
44	55	store uses a mock gateway — a page labelled as a mock, with Approve and
45	56	Decline buttons, that moves no money.
		@@ -487,10 +498,10 @@ is written to the same database, and — because an event is a row in it — a
487	498	stock move or a refund made here reaches an admin's open `/admin` over the
488	499	live stream within about a second, not on that page's next load. `1`–`7`
489	500	switch between stock, orders, the outbox, discount codes, gift cards, the tax
490		table and the changes an admin made to any of it — everything `/admin`
491		can see — and `j`/`k` move. A tab whose rows are the shop's own business is an
	501	table, the changes an admin made to any of it and the audit trail — everything
	502	`/admin` can see — and `j`/`k` move. A tab whose rows are the shop's own business is an
492	503	admin's to open: a non-admin gets stock, tax and their own orders, the other
493		four are marked with a `·` in the tab bar and answer without leaving the tab
	504	five are marked with a `·` in the tab bar and answer without leaving the tab
494	505	they are on:
495	506
496	507	\| Tab \| Keys \|
		@@ -500,6 +511,7 @@ they are on:
500	511	\| codes \| `n` writes a code (`CODE 20% [min 25] [uses 100] [until 2026-12-31]`), `t` turns one on or off, `c` looks a code up \|
501	512	\| cards \| `i` issues a card (`25 a sorry-for-the-wait card`) and prints its code once, `v` voids or revives one, `c` looks a code up \|
502	513	\| tax \| `e` sets a rate (`COUNTRY / REGION / 8.75 / what to call it`), `d` sets the rate for anywhere the table does not name, `x` removes one \|
	514	\| audit \| reads only: the five money ledgers as one timeline, newest first, the terminal's half of `/admin/audit`. `/` narrows it to one order by its number, and the foot says what that order's rows add up to against what the order says was paid \|
503	515	\| changes \| reads only: the last hundred changes an admin made to the catalog, the codes or the tax table, newest first — the terminal's half of `/admin/changes`. A change made here writes one of these rows too, naming the account the forge put at the keyboard \|
504	516
505	517	`q` leaves. The first line says who the forge named and what they may read;
		@@ -0,0 +1,72 @@
	1	/**
	2	* Who caused a row.
	3	*
	4	* Every ledger in this shop says what happened and why. This is the last
	5	* column: who. A stock correction, a refund, a movement of a gift card's
	6	* balance — each of them was caused by somebody, and an auditor's first
	7	* question about any of them is whose hand it was.
	8	*
	9	* There are five kinds of hand and no more:
	10	*
	11	* - an admin, whom the forge named and `src/who.ts` verified;
	12	* - a shopper, the account an order belongs to;
	13	* - `stripe`, for a row a webhook caused — the gateway told us, nobody asked;
	14	* - `system`, for a seed or a boot-time job, which is nobody in particular;
	15	* - `unknown`, for a row written before this column existed, and for anyone
	16	* the forge did not name.
	17	*
	18	* The actor is never a form field and never a header the caller wrote: the
	19	* caller does not get to sign the trail that is about them. It is also not a
	20	* second place that says who bought an order — `order.buyer_id` is the one
	21	* answer to that, and this says who caused this row.
	22	*/
	23
	24	import { atKeyboard, type Who } from "./who.ts";
	25	import type { Order } from "./db.ts";
	26
	27	export type Role = "admin" \| "user" \| "stripe" \| "system" \| "unknown";
	28	export type Actor = { id: string; name: string; role: Role };
	29
	30	/** Nobody the forge named, and the rows written before there was a column. */
	31	export const UNKNOWN: Actor = { id: "", name: "unknown", role: "unknown" };
	32
	33	/** The app itself: a seed, or a job that runs because the process started. */
	34	export const SYSTEM: Actor = { id: "", name: "system", role: "system" };
	35
	36	/** The gateway, when it is the gateway that told us rather than a person. */
	37	export const STRIPE: Actor = { id: "", name: "stripe", role: "stripe" };
	38
	39	/** Whoever the forge signed in, as an actor. Anonymous is nobody. */
	40	export const of = (who: Who): Actor =>
	41	who.role === "anon" ? UNKNOWN : { id: who.id, name: who.name, role: who.role };
	42
	43	/**
	44	* Who is at the keyboard of the app's terminal. There are no headers on an
	45	* ssh session; the forge names the person in the environment before it starts
	46	* us, which is the same trust as the socket itself.
	47	*/
	48	export const atDesk = (): Actor => of(atKeyboard());
	49
	50	/** The account an order belongs to. A guest order from before accounts is nobody's. */
	51	export const buyerOf = (order: Pick<Order, "buyer_id" \| "buyer_name">): Actor =>
	52	order.buyer_id === "" ? UNKNOWN : { id: order.buyer_id, name: order.buyer_name, role: "user" };
	53
	54	/**
	55	* Who is paying: whoever the forge has signed in, or — for a shopper holding
	56	* nothing but an order's access token — the account the order belongs to.
	57	*/
	58	export const paying = (who: Who, order: Pick<Order, "buyer_id" \| "buyer_name">): Actor =>
	59	who.role === "anon" ? buyerOf(order) : of(who);
	60
	61	/** How long a name or an id is allowed to be in a row: enough, and no more. */
	62	const CAP = 64;
	63
	64	/**
	65	* The three columns a ledger row keeps, clipped to what the columns hold.
	66	* Spread into the parameters of an INSERT, in the order id, name, role.
	67	*/
	68	export const cells = (by: Actor): [string, string, string] => [
	69	by.id.slice(0, CAP),
	70	(by.name \|\| "unknown").slice(0, CAP),
	71	by.role,
	72	];
		@@ -7,6 +7,8 @@
7	7	* saying who asked and why.
8	8	*/
9	9
	10	import * as actors from "./actor.ts";
	11	import * as audit from "./audit.ts";
10	12	import * as catalog from "./catalog.ts";
11	13	import * as changes from "./changes.ts";
12	14	import * as discounts from "./discounts.ts";
		@@ -67,7 +69,7 @@ const guard = (ctx: Ctx): Response \| null =>
67	69	* src/who.ts, and it is the only source there is: a form field or a header
68	70	* that named someone else would be the caller signing their own trail.
69	71	*/
70		const actor = (ctx: Ctx): changes.Actor => changes.actorOf(ctx.who);
	72	const actor = (ctx: Ctx): actors.Actor => actors.of(ctx.who);
71	73
72	74	/** A rate as the tax table says it. */
73	75	const percent = (bp: number): string => `${(bp / 100).toFixed(2)}%`;
		@@ -78,6 +80,42 @@ export function changeList(ctx: Ctx): Response {
78	80	return render(ctx, { title: "Changes", admin: true }, pages.changes(changes.recent(100)));
79	81	}
80	82
	83	/**
	84	* The whole money trail on one page: the five ledgers merged, newest first,
	85	* narrowed to one order by its number and paged with a cursor. The number is
	86	* looked up before anything is read, so what reaches the query is an id; the
	87	* cursor is parsed to a stamp and two numbers or thrown away.
	88	*/
	89	export function auditList(ctx: Ctx): Response {
	90	const blocked = guard(ctx);
	91	if (blocked) return blocked;
	92	const query = (ctx.url.searchParams.get("q") ?? "").slice(0, 20).trim().toUpperCase();
	93	const order = query === "" ? null : orders.byNumber(query);
	94	const before = audit.readCursor(ctx.url.searchParams.get("before") ?? "");
	95	const found =
	96	query !== "" && !order ? [] : audit.timeline({ orderId: order?.id, before, limit: AUDIT_PAGE });
	97	const rows = found.slice(0, AUDIT_PAGE);
	98	const last = rows[rows.length - 1];
	99	const older =
	100	found.length > AUDIT_PAGE && last
	101	? `/admin/audit?q=${encodeURIComponent(query)}&before=${encodeURIComponent(audit.cursorOf(last))}`
	102	: null;
	103	return render(
	104	ctx,
	105	{ title: "Audit", admin: true },
	106	pages.audit(rows, {
	107	query,
	108	order,
	109	balance: order ? audit.balanceOf(order) : null,
	110	shop: audit.shopBalance(),
	111	older,
	112	}),
	113	);
	114	}
	115
	116	/** How much of the timeline one page shows. */
	117	const AUDIT_PAGE = 60;
	118
81	119	// --- the door ---------------------------------------------------------------
82	120
83	121	export function dashboard(ctx: Ctx): Response {
		@@ -245,7 +283,7 @@ export function variantCreate(ctx: Ctx): Response {
245	283	// Opening stock is not a field of the trail: it moves through the stock
246	284	// ledger, which already says who and why.
247	285	db.transaction(() => {
248		const id = catalog.createVariant({ product_id: found.id, sku, name, price_cents: price, stock });
	286	const id = catalog.createVariant({ product_id: found.id, sku, name, price_cents: price, stock, by: actor(ctx) });
249	287	changes.changed(actor(ctx), "variant", id, {}, { sku, name, price: formatCents(price) });
250	288	})();
251	289	return redirect(`/admin/products/${found.id}?m=variant-added`);
		@@ -306,8 +344,8 @@ export function inventoryMove(ctx: Ctx): Response {
306	344	const reason = field(ctx.form, "reason", 120);
307	345	const variant = variantId === undefined ? null : catalog.variantById(variantId);
308	346	if (!variant \|\| delta === undefined \|\| delta === 0 \|\| reason === "") return redirect("/admin/inventory?m=bad-delta");
309		if (delta > 0) inventory.addStock(variant.id, delta, reason);
310		else inventory.setStock(variant.id, Math.max(0, variant.stock + delta), reason);
	347	if (delta > 0) inventory.addStock(variant.id, delta, reason, actor(ctx));
	348	else inventory.setStock(variant.id, Math.max(0, variant.stock + delta), reason, actor(ctx));
311	349	return redirect("/admin/inventory?m=stocked");
312	350	}
313	351
		@@ -365,14 +403,22 @@ export async function orderRefund(ctx: Ctx): Promise<Response> {
365	403	if (order.gateway === "stripe" && order.payment_ref?.startsWith("pi_")) {
366	404	const result = await gateway.refundCharge(order.payment_ref, amount, key);
367	405	if (!result.ok) {
368		orders.note(order.id, "refund-failed", result.error);
	406	orders.note(order.id, "refund-failed", actor(ctx), result.error);
369	407	return redirect(`/admin/orders/${order.number}?m=refund-failed`);
370	408	}
371	409	gatewayRef = result.value.id;
372	410	}
373		const done = orders.refund({ order, amount_cents: amount, reason, restock, gateway_ref: gatewayRef, idempotencyKey: key });
	411	const done = orders.refund({
	412	order,
	413	amount_cents: amount,
	414	reason,
	415	restock,
	416	gateway_ref: gatewayRef,
	417	idempotencyKey: key,
	418	by: actor(ctx),
	419	});
374	420	if (!done.ok) {
375		orders.note(order.id, "refund-refused", done.error);
	421	orders.note(order.id, "refund-refused", actor(ctx), done.error);
376	422	return redirect(`/admin/orders/${order.number}?m=bad-amount`);
377	423	}
378	424	return redirect(`/admin/orders/${order.number}?m=refunded`);
		@@ -383,7 +429,7 @@ export function orderCancel(ctx: Ctx): Response {
383	429	if (blocked) return blocked;
384	430	const order = orders.byNumber((ctx.params.number ?? "").slice(0, 20));
385	431	if (!order) return notFound(ctx);
386		orders.cancel(order, field(ctx.form, "reason", 200) \|\| "cancelled in admin");
	432	orders.cancel(order, field(ctx.form, "reason", 200) \|\| "cancelled in admin", actor(ctx));
387	433	return redirect(`/admin/orders/${order.number}?m=cancelled`);
388	434	}
389	435
		@@ -501,7 +547,7 @@ export function giftCardIssue(ctx: Ctx): Response {
501	547	if (blocked) return blocked;
502	548	const amount = parseCents(field(ctx.form, "amount", 12));
503	549	if (amount === undefined \|\| amount <= 0) return redirect("/admin/giftcards?m=bad-amount");
504		const issued = giftcards.issue({ cents: amount, note: field(ctx.form, "note", 120), orderId: undefined });
	550	const issued = giftcards.issue({ cents: amount, note: field(ctx.form, "note", 120), by: actor(ctx) });
505	551	return giftCardList(ctx, issued.code);
506	552	}
507	553
		@@ -514,7 +560,7 @@ export function giftCardAdjust(ctx: Ctx): Response {
514	560	const reason = field(ctx.form, "reason", 120) \|\| "adjusted in admin";
515	561	const asked = field(ctx.form, "void", 1);
516	562	if (asked !== "") {
517		giftcards.setActive(card.id, asked === "0", reason);
	563	giftcards.setActive(card.id, asked === "0", reason, actor(ctx));
518	564	return redirect("/admin/giftcards?m=saved");
519	565	}
520	566	const raw = field(ctx.form, "amount", 12).replace(/^\+/, "");
		@@ -522,8 +568,8 @@ export function giftCardAdjust(ctx: Ctx): Response {
522	568	const cents = parseCents(down ? raw.slice(1) : raw);
523	569	if (cents === undefined \|\| cents === 0) return redirect("/admin/giftcards?m=bad-amount");
524	570	const moved = down
525		? giftcards.spend(card.id, cents, reason)
526		: giftcards.credit(card.id, cents, reason, undefined, `admin:${crypto.randomUUID()}`);
	571	? giftcards.spend(card.id, cents, reason, actor(ctx))
	572	: giftcards.credit(card.id, cents, reason, actor(ctx), undefined, `admin:${crypto.randomUUID()}`);
527	573	return redirect(`/admin/giftcards?m=${moved ? "saved" : "bad-amount"}`);
528	574	}
529	575
		@@ -0,0 +1,273 @@
	1	/**
	2	* The money trail, as one timeline.
	3	*
	4	* Five tables say what this shop did with money and goods: `stock_entry`,
	5	* `payment`, `order_event`, `gift_card_entry` and `discount_redemption`. Each
	6	* is authoritative about its own thing and each is read on its own page. This
	7	* module reads all five at once, newest first, so that an auditor's question —
	8	* what happened, in what order, and who did it — has one answer on one page.
	9	*
	10	* It is a bounded read per table and a merge in memory, never five scans: each
	11	* table is ordered by an index on (at DESC, id DESC) and asked for one page's
	12	* worth, so the work is the same whether the shop has a hundred rows or a
	13	* million. Paging is a cursor rather than an offset, for the same reason — and
	14	* because rows arriving while somebody reads must not shift the page under
	15	* them. The cursor is (when, which table, which row), which is exactly the
	16	* ordering, so it is unambiguous even when a second holds a dozen rows.
	17	*
	18	* Nothing here reads a column the order page does not already show: no gift
	19	* card codes (only the last four, as everywhere), no gateway secrets.
	20	*/
	21
	22	import { creditedForOrder } from "./giftcards.ts";
	23	import { db, type Order } from "./db.ts";
	24
	25	/** Which ledger a row came from. */
	26	export type Source = "stock" \| "payment" \| "event" \| "gift_card" \| "discount";
	27
	28	/**
	29	* The tie-break between two rows written in the same second. It is arbitrary
	30	* but fixed: the cursor and the ordering have to agree, or paging would skip.
	31	*/
	32	const RANK: Record<Source, number> = { stock: 0, payment: 1, event: 2, gift_card: 3, discount: 4 };
	33
	34	export type Entry = {
	35	source: Source;
	36	id: number;
	37	at: string;
	38	actor_id: string;
	39	actor_name: string;
	40	actor_role: string;
	41	/** The kind of thing that happened, in one or two words. */
	42	what: string;
	43	/** The row's own words: a reason, a reference, a SKU. */
	44	detail: string;
	45	order_id: number \| null;
	46	order_number: string \| null;
	47	/** Money as the shop's balance felt it: positive in, negative out, null for goods. */
	48	cents: number \| null;
	49	};
	50
	51	/** Where a page of the timeline stops: the ordering, written down. */
	52	export type Cursor = { at: string; rank: number; id: number };
	53
	54	export const PAGE = 100;
	55
	56	export const cursorOf = (entry: Entry): string => `${entry.at}\|${RANK[entry.source]}\|${entry.id}`;
	57
	58	/**
	59	* A cursor as it came back from a URL. A stamp, a rank and an id, or nothing:
	60	* whatever else was typed there is not a place in this timeline.
	61	*/
	62	export function readCursor(raw: string): Cursor \| undefined {
	63	const fields = /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\\|([0-4])\\|(\d{1,15})$/.exec(raw.slice(0, 40));
	64	if (!fields) return undefined;
	65	return { at: fields[1]!, rank: Number(fields[2]), id: Number(fields[3]) };
	66	}
	67
	68	type Raw = {
	69	id: number;
	70	at: string;
	71	actor_id: string;
	72	actor_name: string;
	73	actor_role: string;
	74	order_id: number \| null;
	75	order_number: string \| null;
	76	a: string;
	77	b: string;
	78	n: number;
	79	};
	80
	81	/**
	82	* The five reads. Each selects the same shape — when, who, which order, and
	83	* three loose columns the mapping below turns into words — and each is ordered
	84	* by the index its table has for exactly this. `$where` is the only thing that
	85	* varies, and it is built below from an id and a cursor, never from text.
	86	*/
	87	type Read = { alias: string; stamp: string; sql: (where: string) => string };
	88
	89	const READS: Record<Source, Read> = {
	90	stock: {
	91	alias: "s",
	92	stamp: "at",
	93	sql: (where) => `
	94	SELECT s.id, s.at, s.actor_id, s.actor_name, s.actor_role, s.order_id,
	95	(SELECT number FROM "order" o WHERE o.id = s.order_id) AS order_number,
	96	(SELECT sku FROM variant v WHERE v.id = s.variant_id) AS a, s.reason AS b, s.delta AS n
	97	FROM stock_entry s WHERE ${where} ORDER BY s.at DESC, s.id DESC LIMIT $limit`,
	98	},
	99	payment: {
	100	alias: "p",
	101	stamp: "created_at",
	102	sql: (where) => `
	103	SELECT p.id, p.created_at AS at, p.actor_id, p.actor_name, p.actor_role, p.order_id,
	104	(SELECT number FROM "order" o WHERE o.id = p.order_id) AS order_number,
	105	p.kind AS a, p.gateway \|\| CASE WHEN p.gateway_ref = '' THEN '' ELSE ' ' \|\| p.gateway_ref END AS b,
	106	p.amount_cents AS n
	107	FROM payment p WHERE ${where} ORDER BY p.created_at DESC, p.id DESC LIMIT $limit`,
	108	},
	109	event: {
	110	alias: "e",
	111	stamp: "at",
	112	sql: (where) => `
	113	SELECT e.id, e.at, e.actor_id, e.actor_name, e.actor_role, e.order_id,
	114	(SELECT number FROM "order" o WHERE o.id = e.order_id) AS order_number,
	115	e.kind AS a, e.detail AS b, 0 AS n
	116	FROM order_event e WHERE ${where} ORDER BY e.at DESC, e.id DESC LIMIT $limit`,
	117	},
	118	gift_card: {
	119	alias: "g",
	120	stamp: "at",
	121	sql: (where) => `
	122	SELECT g.id, g.at, g.actor_id, g.actor_name, g.actor_role, g.order_id,
	123	(SELECT number FROM "order" o WHERE o.id = g.order_id) AS order_number,
	124	(SELECT last4 FROM gift_card c WHERE c.id = g.gift_card_id) AS a, g.reason AS b, g.delta AS n
	125	FROM gift_card_entry g WHERE ${where} ORDER BY g.at DESC, g.id DESC LIMIT $limit`,
	126	},
	127	discount: {
	128	alias: "r",
	129	stamp: "at",
	130	sql: (where) => `
	131	SELECT r.id, r.at, r.actor_id, r.actor_name, r.actor_role, r.order_id,
	132	(SELECT number FROM "order" o WHERE o.id = r.order_id) AS order_number,
	133	r.kind AS a, (SELECT code FROM discount d WHERE d.id = r.discount_id) AS b, r.amount_cents AS n
	134	FROM discount_redemption r WHERE ${where} ORDER BY r.at DESC, r.id DESC LIMIT $limit`,
	135	},
	136	};
	137
	138	/**
	139	* One table's page, as raw rows. Both conditions are built here and never from
	140	* anything a caller typed: the order is an id looked up first, and the cursor
	141	* is a stamp and two numbers. The table's own rank against the cursor's is
	142	* decided in this process, so the statement takes the same parameters however
	143	* the two compare.
	144	*/
	145	function page(source: Source, options: { orderId?: number; before?: Cursor; limit: number }): Raw[] {
	146	const { alias, stamp, sql } = READS[source];
	147	const when = `${alias}.${stamp}`;
	148	const where = [
	149	options.orderId === undefined ? "" : `${alias}.order_id = $order`,
	150	options.before === undefined
	151	? ""
	152	: `(${when} < $at OR (${when} = $at AND ($below = 1 OR ($equal = 1 AND ${alias}.id < $id))))`,
	153	].filter((part) => part !== "");
	154	return db.query<Raw, any>(sql(where.length === 0 ? "1 = 1" : where.join(" AND "))).all({
	155	...(options.orderId === undefined ? {} : { $order: options.orderId }),
	156	...(options.before === undefined
	157	? {}
	158	: {
	159	$at: options.before.at,
	160	$below: RANK[source] < options.before.rank ? 1 : 0,
	161	$equal: RANK[source] === options.before.rank ? 1 : 0,
	162	$id: options.before.id,
	163	}),
	164	$limit: options.limit,
	165	});
	166	}
	167
	168	const sign = (value: number, negative: boolean): number => (negative ? -value : value);
	169
	170	/** A raw row as the timeline says it: source by source, in the shop's words. */
	171	function read(source: Source, row: Raw): Entry {
	172	const common = {
	173	source,
	174	id: row.id,
	175	at: row.at,
	176	actor_id: row.actor_id,
	177	actor_name: row.actor_name,
	178	actor_role: row.actor_role,
	179	order_id: row.order_id,
	180	order_number: row.order_number,
	181	};
	182	if (source === "stock")
	183	return { ...common, what: "stock", detail: `${row.a} ${row.n > 0 ? "+" : ""}${row.n} — ${row.b}`, cents: null };
	184	if (source === "payment")
	185	return { ...common, what: row.a, detail: row.b, cents: sign(row.n, row.a === "refund") };
	186	if (source === "event") return { ...common, what: row.a, detail: row.b, cents: null };
	187	if (source === "gift_card")
	188	return { ...common, what: "gift card", detail: `····${row.a} — ${row.b}`, cents: row.n };
	189	return { ...common, what: row.a, detail: row.b ?? "", cents: sign(row.n, row.a === "redeemed") };
	190	}
	191
	192	/**
	193	* The timeline, newest first. Five short reads, merged and cut to the limit:
	194	* the merge is over at most five pages' worth of rows, and the ordering is the
	195	* one the cursor speaks. One row more than the limit comes back when there is
	196	* one, so the page can say whether there is another without counting anything.
	197	*/
	198	export function timeline(options: { orderId?: number; before?: Cursor; limit?: number } = {}): Entry[] {
	199	const limit = Math.max(1, Math.min(PAGE, Math.trunc(options.limit ?? PAGE) \|\| PAGE));
	200	const asked = { orderId: options.orderId, before: options.before, limit: limit + 1 };
	201	const all: Entry[] = [];
	202	for (const source of Object.keys(READS) as Source[])
	203	for (const row of page(source, asked)) all.push(read(source, row));
	204	all.sort(
	205	(one, two) =>
	206	(one.at < two.at ? 1 : one.at > two.at ? -1 : 0) \|\|
	207	RANK[two.source] - RANK[one.source] \|\|
	208	two.id - one.id,
	209	);
	210	return all.slice(0, limit + 1);
	211	}
	212
	213	/**
	214	* What an order's ledgers add up to, beside what the order itself says was
	215	* paid. Every figure is a sum of rows anyone can check on this page; the
	216	* order's own claim is the one thing that is not, which is the point of
	217	* holding them up against each other.
	218	*/
	219	export type Balance = {
	220	charged_cents: number;
	221	refunded_cents: number;
	222	gift_card_cents: number;
	223	gift_card_back_cents: number;
	224	/** Charges and gift card, less refunds and what went back on the card. */
	225	held_cents: number;
	226	/** What the order row says has been paid and not given back. */
	227	says_cents: number;
	228	agrees: boolean;
	229	};
	230
	231	const PAID = ["paid", "partially_refunded", "refunded"];
	232
	233	const sumPayments = (orderId: number, kind: "charge" \| "refund"): number =>
	234	db
	235	.query<{ total: number }, [number, string]>(
	236	`SELECT COALESCE(SUM(amount_cents), 0) AS total FROM payment
	237	WHERE order_id = ?1 AND kind = ?2 AND status = 'succeeded'`,
	238	)
	239	.get(orderId, kind)!.total;
	240
	241	export function balanceOf(order: Order): Balance {
	242	const charged = sumPayments(order.id, "charge");
	243	const refunded = sumPayments(order.id, "refund");
	244	const spent = db
	245	.query<{ total: number }, [number]>(
	246	"SELECT COALESCE(-SUM(delta), 0) AS total FROM gift_card_entry WHERE order_id = ?1 AND delta < 0",
	247	)
	248	.get(order.id)!.total;
	249	const back = creditedForOrder(order.id);
	250	const held = charged + spent - refunded - back;
	251	const says = PAID.includes(order.status) ? order.total_cents - (refunded + back) : 0;
	252	return {
	253	charged_cents: charged,
	254	refunded_cents: refunded,
	255	gift_card_cents: spent,
	256	gift_card_back_cents: back,
	257	held_cents: held,
	258	says_cents: says,
	259	agrees: held === says,
	260	};
	261	}
	262
	263	/** The same sum over the whole shop: every charge, less every refund. */
	264	export const shopBalance = (): { charged_cents: number; refunded_cents: number; held_cents: number } => {
	265	const row = db
	266	.query<{ charged: number; refunded: number }, []>(
	267	`SELECT
	268	(SELECT COALESCE(SUM(amount_cents), 0) FROM payment WHERE kind = 'charge' AND status = 'succeeded') AS charged,
	269	(SELECT COALESCE(SUM(amount_cents), 0) FROM payment WHERE kind = 'refund' AND status = 'succeeded') AS refunded`,
	270	)
	271	.get()!;
	272	return { charged_cents: row.charged, refunded_cents: row.refunded, held_cents: row.charged - row.refunded };
	273	};
		@@ -4,6 +4,7 @@
4	4	* carts, orders or money beyond the integer cents it stores.
5	5	*/
6	6
	7	import { SYSTEM, type Actor } from "./actor.ts";
7	8	import { db, type Category, type Product, type Variant } from "./db.ts";
8	9	import { addStock } from "./inventory.ts";
9	10
		@@ -170,13 +171,18 @@ export function updateProduct(
170	171	});
171	172	}
172	173
173		/** A new variant starts at zero stock; stock only ever moves through the ledger. */
	174	/**
	175	* A new variant starts at zero stock; stock only ever moves through the
	176	* ledger, so opening stock is a row like any other and names whoever opened it.
	177	*/
174	178	export function createVariant(input: {
175	179	product_id: number;
176	180	sku: string;
177	181	name: string;
178	182	price_cents: number;
179	183	stock: number;
	184	/** Who is adding it: an admin, or the seed that fills an empty shop. */
	185	by: Actor;
180	186	/** Non-zero makes this variant a gift card of that face value. */
181	187	gift_card_cents?: number;
182	188	}): number {
		@@ -194,7 +200,7 @@ export function createVariant(input: {
194	200	$price_cents: input.price_cents,
195	201	$gift_card_cents: input.gift_card_cents ?? 0,
196	202	});
197		if (input.stock > 0) addStock(row!.id, input.stock, "opening stock");
	203	if (input.stock > 0) addStock(row!.id, input.stock, "opening stock", input.by);
198	204	return row!.id;
199	205	}
200	206
		@@ -238,7 +244,7 @@ export function seedGiftCards(): void {
238	244	["GFT-CARD-50", "$50", 5000],
239	245	["GFT-CARD-100", "$100", 10000],
240	246	] as [string, string, number][])
241		createVariant({ product_id: productId, sku, name, price_cents: cents, stock: 1000, gift_card_cents: cents });
	247	createVariant({ product_id: productId, sku, name, price_cents: cents, stock: 1000, gift_card_cents: cents, by: SYSTEM });
242	248	})();
243	249	}
244	250
		@@ -343,7 +349,7 @@ export function seed(): void {
343	349	active: true,
344	350	});
345	351	for (const [sku, name, price_cents, stock] of product.variants) {
346		createVariant({ product_id: productId, sku, name, price_cents, stock });
	352	createVariant({ product_id: productId, sku, name, price_cents, stock, by: SYSTEM });
347	353	}
348	354	}
349	355	}
		@@ -11,7 +11,8 @@
11	11	* The actor is whoever the forge named: `ctx.who` on the web, the account the
12	12	* forge put in the environment at the terminal. It is never a form field and
13	13	* never a header the caller wrote — the caller does not get to sign the trail
14		* that is about them.
	14	* that is about them. `src/actor.ts` is where an actor comes from, here and
	15	* in every other ledger; this table keeps the id and the name of one.
15	16	*
16	17	* Nothing spendable is recorded. A discount code is printed on a poster; a
17	18	* gift card's code is bearer money and its balance has a ledger of its own,
		@@ -19,10 +20,9 @@
19	20	*/
20	21
21	22	import { db, type AdminChange } from "./db.ts";
22		import { atKeyboard, type Who } from "./who.ts";
	23	import type { Actor } from "./actor.ts";
23	24
24	25	export type Change = AdminChange;
25		export type Actor = { id: string; name: string };
26	26	export type Field = { field: string; before: string; after: string };
27	27
28	28	/** A value as an audit row says it: plain data in, one short string out. */
		@@ -58,17 +58,6 @@ export const flat = (value: Value): string =>
58	58	/** A value as a row says it: flat, and short enough to be a row. */
59	59	export const say = (value: Value): string => clip(flat(value));
60	60
61		/** Who the forge says is asking, as an actor. Anonymous cannot be an admin. */
62		export const actorOf = (who: Who): Actor =>
63		who.role === "anon" ? { id: "", name: "unknown" } : { id: who.id, name: who.name };
64
65		/**
66		* Who is at the keyboard of the app's terminal. There are no headers on an
67		* ssh session; the forge names the person in the environment before it starts
68		* us, which is the same trust as the socket itself.
69		*/
70		export const atDesk = (): Actor => actorOf(atKeyboard());
71
72	61	/**
73	62	* The fields of two snapshots that differ. A form submitted with nothing
74	63	* changed produces an empty list, and an empty list writes nothing.
		@@ -276,8 +276,32 @@ function migrate(handle: Database): void {
276	276	addColumn(handle, "order", "buyer_id", "TEXT NOT NULL DEFAULT ''");
277	277	addColumn(handle, "order", "buyer_name", "TEXT NOT NULL DEFAULT ''");
278	278	handle.exec('CREATE INDEX IF NOT EXISTS order_buyer ON "order"(buyer_id, id DESC)');
	279
	280	// Who caused the row. The ledgers already said what happened and why; these
	281	// three columns say whose hand it was — see src/actor.ts for the five kinds
	282	// of hand there are. The rows written before the column tell the truth about
	283	// themselves: no id, and a name and a role of "unknown", because nobody
	284	// wrote down who they were and this is not the place to guess.
	285	for (const table of ["stock_entry", "payment", "order_event", "gift_card_entry", "discount_redemption"]) {
	286	addColumn(handle, table, "actor_id", "TEXT NOT NULL DEFAULT ''");
	287	addColumn(handle, table, "actor_name", "TEXT NOT NULL DEFAULT 'unknown'");
	288	addColumn(handle, table, "actor_role", "TEXT NOT NULL DEFAULT 'unknown'");
	289	}
	290	// /admin/audit reads those five newest-first and merges them. Each ordering
	291	// is an index, so the timeline is five short reads however many rows there
	292	// are — never five scans.
	293	handle.exec(`
	294	CREATE INDEX IF NOT EXISTS stock_entry_at ON stock_entry(at DESC, id DESC);
	295	CREATE INDEX IF NOT EXISTS payment_at ON payment(created_at DESC, id DESC);
	296	CREATE INDEX IF NOT EXISTS order_event_at ON order_event(at DESC, id DESC);
	297	CREATE INDEX IF NOT EXISTS gift_card_entry_at ON gift_card_entry(at DESC, id DESC);
	298	CREATE INDEX IF NOT EXISTS discount_redemption_at ON discount_redemption(at DESC, id DESC);
	299	`);
279	300	}
280	301
	302	/** The three columns every ledger row carries about who caused it. */
	303	export type ActorColumns = { actor_id: string; actor_name: string; actor_role: string };
	304
281	305	/**
282	306	* Open the database kept in a directory: the directory is made if it is not
283	307	* there, the file is opened, the pragmas are set, the schema is created and
		@@ -430,7 +454,7 @@ export type TaxRate = {
430	454	label: string;
431	455	active: number;
432	456	};
433		export type Payment = {
	457	export type Payment = ActorColumns & {
434	458	id: number;
435	459	order_id: number;
436	460	kind: "charge" \| "refund";
		@@ -21,6 +21,7 @@
21	21	* it is a function from `Who` to rows, so the rule is tested without a pty.
22	22	*/
23	23
	24	import * as actors from "./actor.ts";
24	25	import * as changes from "./changes.ts";
25	26	import * as discounts from "./discounts.ts";
26	27	import * as giftcards from "./giftcards.ts";
		@@ -41,7 +42,7 @@ const percent = (bp: number): string => `${(bp / 100).toFixed(2)}%`;
41	42	* the same row. The actor is the account the forge named at the keyboard —
42	43	* the environment it started us with, which is the same trust as the socket.
43	44	*/
44		export const TABS = ["stock", "orders", "outbox", "codes", "cards", "tax", "changes"] as const;
	45	export const TABS = ["stock", "orders", "outbox", "codes", "cards", "tax", "changes", "audit"] as const;
45	46	export type Tab = (typeof TABS)[number];
46	47
47	48	/**
		@@ -112,6 +113,12 @@ const DESK: Record<Tab, { read: "anyone" \| "own" \| "admin"; keys: Offer[] }> = {
112	113	// Who changed a price, a code or a rate is the shop's own business, and it
113	114	// names people: the same gate the orders and the cards are behind.
114	115	changes: { read: "admin", keys: [] },
	116	// The five money ledgers as one timeline — the same rows /admin/audit shows,
	117	// and the same gate: it names people, and it says what every order took.
	118	audit: {
	119	read: "admin",
	120	keys: [{ key: "/", label: "/ one order", press: "admin" }],
	121	},
115	122	};
116	123
117	124	/**
		@@ -218,7 +225,7 @@ export function newDiscount(line: string): Done {
218	225	expires_at: expires,
219	226	});
220	227	changes.changed(
221		changes.atDesk(),
	228	actors.atDesk(),
222	229	"discount",
223	230	made,
224	231	{},
		@@ -250,7 +257,7 @@ export function toggleDiscount(id: number): Done {
250	257	if (!found) return no("No code selected.");
251	258	db.transaction(() => {
252	259	discounts.setActive(found.id, found.active !== 1);
253		changes.changed(changes.atDesk(), "discount", found.id, { active: found.active === 1 }, { active: found.active !== 1 });
	260	changes.changed(actors.atDesk(), "discount", found.id, { active: found.active === 1 }, { active: found.active !== 1 });
254	261	})();
255	262	return yes(`${found.code} is now ${found.active === 1 ? "off" : "on"}.`);
256	263	}
		@@ -260,7 +267,11 @@ export function issueCard(line: string): Done {
260	267	const parts = words(line);
261	268	const cents = parseCents(parts[0] ?? "");
262	269	if (cents === undefined \|\| cents <= 0) return no("A card is worth an amount of money, like 25 or 25.00.");
263		const issued = giftcards.issue({ cents, note: parts.slice(1).join(" ").slice(0, 120) \|\| "issued at the terminal" });
	270	const issued = giftcards.issue({
	271	cents,
	272	note: parts.slice(1).join(" ").slice(0, 120) \|\| "issued at the terminal",
	273	by: actors.atDesk(),
	274	});
264	275	return yes(`${issued.code} — ${formatCents(cents)}. This is the only copy of the code.`);
265	276	}
266	277
		@@ -268,7 +279,7 @@ export function toggleCard(id: number, reason: string): Done {
268	279	const card = giftcards.byId(id);
269	280	if (!card) return no("No card selected.");
270	281	const reviving = card.active !== 1;
271		giftcards.setActive(card.id, reviving, reason.trim() \|\| "voided at the terminal");
	282	giftcards.setActive(card.id, reviving, reason.trim() \|\| "voided at the terminal", actors.atDesk());
272	283	return yes(
273	284	reviving
274	285	? `····${card.last4} can be used again; it holds ${formatCents(giftcards.byId(card.id)!.balance_cents)}.`
		@@ -316,7 +327,7 @@ export function setRate(line: string): Done {
316	327	db.transaction(() => {
317	328	const id = tax.upsertRate({ country, region, rate_bp: points, label, active: true });
318	329	changes.changed(
319		changes.atDesk(),
	330	actors.atDesk(),
320	331	"tax_rate",
321	332	id,
322	333	existing ? { rate: percent(existing.rate_bp), label: existing.label, active: existing.active === 1 } : {},
		@@ -332,7 +343,7 @@ export function setDefaultRate(text: string): Done {
332	343	const was = tax.defaultRateBp();
333	344	db.transaction(() => {
334	345	tax.setDefaultRateBp(points);
335		changes.changed(changes.atDesk(), "tax_default", 0, { rate: percent(was) }, { rate: percent(points) });
	346	changes.changed(actors.atDesk(), "tax_default", 0, { rate: percent(was) }, { rate: percent(points) });
336	347	})();
337	348	return yes(`Anywhere the table does not name is taxed at ${(points / 100).toFixed(2)}%.`);
338	349	}
		@@ -343,7 +354,7 @@ export function removeRate(id: number, confirmation: string): Done {
343	354	if (!/^y(es)?$/i.test(confirmation.trim())) return no(`${rate.country} ${rate.region} kept.`);
344	355	db.transaction(() => {
345	356	tax.removeRate(rate.id);
346		changes.record(changes.atDesk(), "tax_rate", rate.id, [
	357	changes.record(actors.atDesk(), "tax_rate", rate.id, [
347	358	{
348	359	field: "removed",
349	360	before: `${rate.country}${rate.region ? ` ${rate.region}` : ""} ${percent(rate.rate_bp)} ${rate.label}`,
		@@ -11,6 +11,7 @@
11	11	* A discount never applies to a gift card: money is not bought at a discount.
12	12	*/
13	13
	14	import { cells, type Actor } from "./actor.ts";
14	15	import { db, type Discount } from "./db.ts";
15	16	import { formatCents } from "./money.ts";
16	17
		@@ -106,7 +107,13 @@ export function evaluate(code: string, base_cents: number, now = new Date()): Ch
106	107	* said the same thing a moment earlier, but only this decides, so a code that
107	108	* expired or was switched off in between is not taken anyway.
108	109	*/
109		export function redeem(discountId: number, orderId: number, amount_cents: number, now = new Date()): boolean {
	110	export function redeem(
	111	discountId: number,
	112	orderId: number,
	113	amount_cents: number,
	114	by: Actor,
	115	now = new Date(),
	116	): boolean {
110	117	const changes = db
111	118	.query(
112	119	`UPDATE discount SET used_count = used_count + 1
		@@ -116,18 +123,20 @@ export function redeem(discountId: number, orderId: number, amount_cents: number
116	123	.run(discountId, stampOf(now)).changes;
117	124	if (changes !== 1) return false;
118	125	db.query(
119		"INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents) VALUES (?1, ?2, 'redeemed', ?3)",
120		).run(discountId, orderId, amount_cents);
	126	`INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents, actor_id, actor_name, actor_role)
	127	VALUES (?1, ?2, 'redeemed', ?3, ?4, ?5, ?6)`,
	128	).run(discountId, orderId, amount_cents, ...cells(by));
121	129	return true;
122	130	}
123	131
124	132	/** An order that never happened gives its use back, and says so in a row. */
125		export function release(discountId: number, orderId: number, amount_cents: number): void {
	133	export function release(discountId: number, orderId: number, amount_cents: number, by: Actor): void {
126	134	db.transaction(() => {
127	135	db.query("UPDATE discount SET used_count = MAX(0, used_count - 1) WHERE id = ?1").run(discountId);
128	136	db.query(
129		"INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents) VALUES (?1, ?2, 'released', ?3)",
130		).run(discountId, orderId, amount_cents);
	137	`INSERT INTO discount_redemption (discount_id, order_id, kind, amount_cents, actor_id, actor_name, actor_role)
	138	VALUES (?1, ?2, 'released', ?3, ?4, ?5, ?6)`,
	139	).run(discountId, orderId, amount_cents, ...cells(by));
131	140	})();
132	141	}
133	142
		@@ -12,7 +12,8 @@
12	12	* so two checkouts racing for the last $5 cannot both win.
13	13	*/
14	14
15		import { dataDir, db, type GiftCard } from "./db.ts";
	15	import { cells, type Actor } from "./actor.ts";
	16	import { dataDir, db, type ActorColumns, type GiftCard } from "./db.ts";
16	17	import { hmac, loadSecret } from "./sign.ts";
17	18	import type { Order, OrderItem } from "./db.ts";
18	19
		@@ -21,7 +22,7 @@ const secret = loadSecret(dataDir);
21	22	/** No I, O, 0 or 1: a code is read aloud and typed by hand. */
22	23	const ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
23	24
24		export type Entry = {
	25	export type Entry = ActorColumns & {
25	26	id: number;
26	27	gift_card_id: number;
27	28	delta: number;
		@@ -112,7 +113,7 @@ export type Issued = { card: GiftCard; code: string };
112	113	* Make a card. The plain code is returned once, to be printed on a receipt or
113	114	* shown to the admin who asked for it, and then it exists nowhere else.
114	115	*/
115		export function issue(input: { cents: number; note: string; orderId?: number }): Issued {
	116	export function issue(input: { cents: number; note: string; by: Actor; orderId?: number }): Issued {
116	117	const code = freshCode();
117	118	const card = db.transaction(() => {
118	119	const row = db
		@@ -127,7 +128,7 @@ export function issue(input: { cents: number; note: string; orderId?: number }):
127	128	$note: input.note,
128	129	$order: input.orderId ?? null,
129	130	})!;
130		credit(row.id, input.cents, input.orderId ? "issued with an order" : "issued", input.orderId);
	131	credit(row.id, input.cents, input.orderId ? "issued with an order" : "issued", input.by, input.orderId);
131	132	return byId(row.id)!;
132	133	})();
133	134	return { card, code };
		@@ -142,6 +143,7 @@ export function credit(
142	143	giftCardId: number,
143	144	cents: number,
144	145	reason: string,
	146	by: Actor,
145	147	orderId?: number,
146	148	idempotencyKey?: string,
147	149	): boolean {
		@@ -149,10 +151,11 @@ export function credit(
149	151	return db.transaction(() => {
150	152	const inserted = db
151	153	.query(
152		`INSERT OR IGNORE INTO gift_card_entry (gift_card_id, delta, reason, order_id, idempotency_key)
153		VALUES (?1, ?2, ?3, ?4, ?5)`,
	154	`INSERT OR IGNORE INTO gift_card_entry (gift_card_id, delta, reason, order_id, idempotency_key,
	155	actor_id, actor_name, actor_role)
	156	VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)`,
154	157	)
155		.run(giftCardId, cents, reason, orderId ?? null, idempotencyKey ?? null).changes;
	158	.run(giftCardId, cents, reason, orderId ?? null, idempotencyKey ?? null, ...cells(by)).changes;
156	159	if (inserted !== 1) return false;
157	160	db.query("UPDATE gift_card SET balance_cents = balance_cents + ?2 WHERE id = ?1").run(giftCardId, cents);
158	161	return true;
		@@ -163,35 +166,32 @@ export function credit(
163	166	* Take money off a card. False and nothing written when the balance is not
164	167	* there or the card is void; the caller turns that into a refusal.
165	168	*/
166		export function spend(giftCardId: number, cents: number, reason: string, orderId?: number): boolean {
	169	export function spend(giftCardId: number, cents: number, reason: string, by: Actor, orderId?: number): boolean {
167	170	if (cents <= 0) return true;
168	171	return db.transaction(() => {
169	172	const changes = db
170	173	.query("UPDATE gift_card SET balance_cents = balance_cents - ?2 WHERE id = ?1 AND active = 1 AND balance_cents >= ?2")
171	174	.run(giftCardId, cents).changes;
172	175	if (changes !== 1) return false;
173		db.query("INSERT INTO gift_card_entry (gift_card_id, delta, reason, order_id) VALUES (?1, ?2, ?3, ?4)").run(
174		giftCardId,
175		-cents,
176		reason,
177		orderId ?? null,
178		);
	176	db.query(
	177	`INSERT INTO gift_card_entry (gift_card_id, delta, reason, order_id, actor_id, actor_name, actor_role)
	178	VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)`,
	179	).run(giftCardId, -cents, reason, orderId ?? null, ...cells(by));
179	180	return true;
180	181	})();
181	182	}
182	183
183	184	/** Void a card by writing its balance away, or bring it back to life. */
184		export function setActive(giftCardId: number, active: boolean, reason: string): void {
	185	export function setActive(giftCardId: number, active: boolean, reason: string, by: Actor): void {
185	186	const card = byId(giftCardId);
186	187	if (!card) return;
187	188	db.transaction(() => {
188	189	if (!active && card.balance_cents > 0) {
189	190	db.query("UPDATE gift_card SET balance_cents = 0 WHERE id = ?1").run(giftCardId);
190		db.query("INSERT INTO gift_card_entry (gift_card_id, delta, reason) VALUES (?1, ?2, ?3)").run(
191		giftCardId,
192		-card.balance_cents,
193		reason \|\| "voided",
194		);
	191	db.query(
	192	`INSERT INTO gift_card_entry (gift_card_id, delta, reason, actor_id, actor_name, actor_role)
	193	VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
	194	).run(giftCardId, -card.balance_cents, reason \|\| "voided", ...cells(by));
195	195	}
196	196	db.query("UPDATE gift_card SET active = ?2 WHERE id = ?1").run(giftCardId, active ? 1 : 0);
197	197	})();
		@@ -202,7 +202,7 @@ export function setActive(giftCardId: number, active: boolean, reason: string):
202	202	* quantity three issues three cards, each with its own code, each worth what
203	203	* was paid for it. Idempotent — an order that already issued issues nothing.
204	204	*/
205		export function issueForOrder(order: Order, items: OrderItem[]): Issued[] {
	205	export function issueForOrder(order: Order, items: OrderItem[], by: Actor): Issued[] {
206	206	const lines = items.filter((item) => item.gift_card_cents > 0);
207	207	if (lines.length === 0) return [];
208	208	const already = db
		@@ -212,7 +212,7 @@ export function issueForOrder(order: Order, items: OrderItem[]): Issued[] {
212	212	const issued: Issued[] = [];
213	213	for (const line of lines)
214	214	for (let n = 0; n < line.quantity; n++)
215		issued.push(issue({ cents: line.gift_card_cents, note: `bought on ${order.number}`, orderId: order.id }));
	215	issued.push(issue({ cents: line.gift_card_cents, note: `bought on ${order.number}`, by, orderId: order.id }));
216	216	return issued;
217	217	}
218	218