@pithy-sh/ledger 0.1.0

package/src/data/transaction.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/** What a ledger entry represents. The append-only log records every balance movement by kind. */
+export const TransactionKind = z
+  .enum(["credit", "debit", "hold", "release", "capture", "transfer_in", "transfer_out"])
+  .describe(
+    "The movement this entry records: `credit`/`debit` add or remove funds; `hold`/`release`/`capture` open, cancel, or finalize an escrow; `transfer_in`/`transfer_out` are the two sides of a transfer.",
+  );
+export type TransactionKind = z.infer<typeof TransactionKind>;
+
+/**
+ * One entry in the append-only ledger — the row in `pithy_ledger_transactions`. Never updated or deleted:
+ * the account's materialized balance is the running total, and this log is the auditable history that
+ * explains it.
+ *
+ * `ref` is the caller-supplied idempotency key, unique across the whole ledger. Replaying an operation with
+ * a `ref` that already exists is a no-op — the unique constraint aborts the retry's transaction, so a
+ * payout or a debit applies exactly once however many times it is delivered.
+ */
+export const LedgerTransaction = z
+  .object({
+    id: z.number().int().describe("Autoincrement primary key. Internal only."),
+    ref: z
+      .string()
+      .describe("The caller-supplied idempotency key, unique across the ledger. A replay of the same ref is a no-op."),
+    userId: z.string().describe("The account owner this entry moved funds for."),
+    currency: z.string().describe("The currency code this entry is in."),
+    kind: TransactionKind.describe("What this entry represents."),
+    amount: z
+      .number()
+      .int()
+      .describe("The movement's magnitude in the currency's minor unit — always positive; `kind` gives direction."),
+    relatedRef: z
+      .string()
+      .nullable()
+      .describe(
+        "Links this entry to another: a `release`/`capture` to its `hold`'s ref, or the paired sides of a transfer.",
+      ),
+    memo: z.string().nullable().describe("An optional human-readable note — `blackjack payout`, `daily bonus`."),
+    createdAt: SQLiteDate.describe("When this entry was recorded."),
+  })
+  .describe("One entry in the append-only ledger — the row in `pithy_ledger_transactions`.");
+export type LedgerTransaction = z.output<typeof LedgerTransaction>;
+export type LedgerTransactionRow = z.input<typeof LedgerTransaction>;

package/src/error/errors.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/ledger` throw sugar. The `ledger/*` codes live in core's closed `KitErrorPayload` union
+ * (CLAUDE.md §Errors); these subclasses are the package-local vehicles that set one of those members.
+ * Runtime code in this package throws one of these, never a plain `new Error`.
+ */
+
+interface LedgerErrorArgs {
+  message?: string;
+  action?: string;
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+export class LedgerCurrencyNotFoundError extends PithyError {
+  constructor(args: LedgerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "ledger/currency_not_found",
+        status: 404,
+        message: args.message ?? "That currency does not exist.",
+        action: args.action ?? "Check the currency code against the `currencies` list in pithy.config.ts.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LedgerAccountNotFoundError extends PithyError {
+  constructor(args: LedgerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "ledger/account_not_found",
+        status: 404,
+        message: args.message ?? "You have no account in that currency yet.",
+        action: args.action ?? "Fund the account first — a credit opens it.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LedgerHoldNotFoundError extends PithyError {
+  constructor(args: LedgerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "ledger/hold_not_found",
+        status: 404,
+        message: args.message ?? "That hold does not exist.",
+        action: args.action ?? "Check the hold reference.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LedgerInsufficientFundsError extends PithyError {
+  constructor(args: LedgerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "ledger/insufficient_funds",
+        status: 409,
+        message: args.message ?? "Not enough funds.",
+        action: args.action ?? "Reduce the amount, or top up the balance.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LedgerHoldNotOpenError extends PithyError {
+  constructor(args: LedgerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "ledger/hold_not_open",
+        status: 409,
+        message: args.message ?? "That hold has already been resolved.",
+        action: args.action ?? "A hold can be released or captured once; check its status.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class LedgerInvalidAmountError extends PithyError {
+  constructor(args: LedgerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "ledger/invalid_amount",
+        status: 400,
+        message: args.message ?? "Amount must be a positive whole number.",
+        action:
+          args.action ?? "Amounts are integers in the currency's minor unit — never zero, negative, or fractional.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/http/guards.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { ForbiddenError, UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * The ledger routes' identity gates: the two middlewares this package owns.
+ *
+ * **The scope constants moved to `./scopes`** (#315). A management client reads them to render what a
+ * connection may do, and it reads them in a browser — so they cannot live in a module that imports
+ * Hono middleware and `PithyHonoEnv`. The gates stayed here; the names they demand are next door, and
+ * the routes import both.
+ *
+ * ## `requireAuth` is copied, not imported
+ *
+ * These lines are the same ones `@pithy-sh/payments`, `@pithy-sh/storage`, and `@pithy-sh/media` each
+ * carry, and the duplication is deliberate. Importing the gate from `@pithy-sh/auth` would make auth a
+ * hard dependency, and *a package that imports its authorization from another package fails open when
+ * that package is absent*. Depending on the core `AuthContext` seam instead means `c.var.auth` is simply
+ * `null` with no auth capability composed, and every player route denies. Failing closed is not a side
+ * effect of the copy; it is the reason for it.
+ *
+ * ## The control-plane gate is core's, and the ledger contributes only the scope names
+ *
+ * `requireControlPlane` lives in `@pithy-sh/core/src/controlPlane/http/guard` and the management routes
+ * wear it directly. The ledger verifies nothing itself: a management call arrives as an EdDSA-signed
+ * compact JWS on the `pithy-control-plane` header, and the seam checks the signature against a public
+ * key the **adopter** registered, the connection it addresses, that connection's environment, the
+ * token's lifetime, a digest of the body, and the token's single use.
+ *
+ * **This is not the opposite of the rule above; it is the same rule.** The rule is never to import
+ * authorization from a package that might be absent. `@pithy-sh/auth` is optional, so its gate is
+ * copied. `@pithy-sh/core` is a hard dependency of every capability there is, so importing its gate
+ * cannot leave a deployment without one — and when the *seam* is not composed the imported gate raises
+ * `controlplane/not_connected` rather than passing.
+ *
+ * ## `requireAuth()` never sits on a management route, and `requireAdmin` never replaces the seam
+ *
+ * A management client is not a player: it holds no session, owns no account row, and the seam
+ * deliberately leaves `c.var.auth` null so a control-plane credential cannot satisfy an ordinary
+ * `requireAuth()` anywhere in the tree. So {@link requireAdmin} — which reads `c.var.auth?.scopes` —
+ * can never pass for one, by design. The control-plane scope **replaces** that gate on the management
+ * routes; it does not stack with it. Stacking them would deny every legitimate management call,
+ * permanently, and no credential could fix it.
+ */
+
+/** Require an authenticated caller (the core AuthContext seam). */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}
+
+/**
+ * Require the admin scope for a balance-moving write.
+ *
+ * Reads `c.var.auth`, so it gates the **player-facing** trusted-server routes and nothing else. A
+ * control-plane caller has no `AuthContext` by design and can never satisfy it — see the file comment.
+ */
+export function requireAdmin(scope: string): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth?.scopes.includes(scope)) {
+      throw new ForbiddenError({
+        message: "This session may not move balances.",
+        action: `Retry with a token carrying the ${scope} scope, minted for your trusted server.`,
+        detail: `Ledger writes require the ${scope} scope; this session carries [${c.var.auth?.scopes.join(", ") ?? ""}].`,
+      });
+    }
+    await next();
+  };
+}

package/src/http/responses.ts

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { TransactionKind } from "../data/transaction";
+
+/**
+ * What the ledger's management routes return, as Zod objects a management client can validate against.
+ *
+ * `schemas.ts` bounds what a caller may send; this file states what it gets back. Both halves are
+ * runtime values for the same reason: a management client reading a customer's Worker is crossing a
+ * trust boundary and must validate what comes back, and a TypeScript interface is erased before it
+ * can help — so every client that had only an interface hand-wrote a mirror, and the mirror drifted
+ * the first time a field landed here.
+ *
+ * **No codecs, and no transform anywhere in this file.** These describe JSON on the wire, so parsing
+ * one hands back exactly what went in — which is what lets `responses.test.ts` compare a parsed value
+ * with the projection's output and fail on a field either side forgot.
+ *
+ * The projections live in `view.ts`, which documents *why* each surrogate key is dropped. This file is
+ * the shape; that file is the argument.
+ *
+ * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
+ * version boundary — a management client validates a response with this schema against a customer's
+ * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
+ * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
+ * say*, which is a different fact from `null`.
+ */
+
+/** Where a page resumes, or the end of the list. */
+const NextCursor = z
+  .string()
+  .nullable()
+  .describe("Where the next page resumes. Null at the end of the list. Opaque — pass it back verbatim.");
+
+/** One account, as a management client sees it. */
+export const LedgerAccountView = z
+  .object({
+    userId: z.string().describe("The account owner — the opaque user id the adopter's auth capability issued."),
+    currency: z.string().describe("The currency this balance is in."),
+    balance: z.number().int().describe("Total owned, in the currency's minor unit."),
+    held: z.number().int().describe("The portion reserved by open holds."),
+    available: z
+      .number()
+      .int()
+      .describe("Spendable now (`balance - held`). Computed, so a client never has to know the rule."),
+    createdAt: z.iso.datetime().describe("When the account was opened, ISO-8601."),
+    updatedAt: z.iso.datetime().describe("When the balance last changed, ISO-8601."),
+  })
+  .describe("One account as a management client sees it. Addressed by `(userId, currency)`, never by a surrogate id.");
+export type LedgerAccountView = z.output<typeof LedgerAccountView>;
+
+/** One ledger entry, as a management client sees it. */
+export const LedgerTransactionView = z
+  .object({
+    ref: z
+      .string()
+      .describe("The caller-supplied idempotency key, unique across the ledger — the entry's stable identifier."),
+    kind: TransactionKind.describe("What the movement was."),
+    currency: z.string().describe("The currency the movement was in."),
+    amount: z
+      .number()
+      .int()
+      .describe("The movement's magnitude in the minor unit — always positive; `kind` gives direction."),
+    relatedRef: z
+      .string()
+      .nullable()
+      .describe("The entry this one answers: a hold's ref, or the other side of a transfer. Null when standalone."),
+    memo: z.string().nullable().describe("The adopter's own note on the movement, or null."),
+    createdAt: z.iso.datetime().describe("When the movement was recorded, ISO-8601."),
+  })
+  .describe("One ledger entry as a management client sees it. No surrogate id, and no repeated owner.");
+export type LedgerTransactionView = z.output<typeof LedgerTransactionView>;
+
+/** `GET {base}/admin/accounts`. */
+export const LedgerAccountsResponse = z
+  .object({
+    accounts: z.array(LedgerAccountView).describe("The page, most recently changed first."),
+    nextCursor: NextCursor,
+  })
+  .describe("A page of every account this ledger holds.");
+export type LedgerAccountsResponse = z.output<typeof LedgerAccountsResponse>;
+
+/**
+ * `GET {base}/admin/accounts/:userId`.
+ *
+ * An empty list rather than a 404 for a player who holds nothing: an account is opened by its first
+ * credit, so its absence is not a missing person — and answering 404 would make this surface an
+ * existence oracle for user ids.
+ */
+export const LedgerUserAccountsResponse = z
+  .object({
+    userId: z.string().describe("The player asked after, echoed so a response stands on its own."),
+    accounts: z.array(LedgerAccountView).describe("Every currency this player holds. Empty when they hold none."),
+  })
+  .describe("One player's balances, in every currency they hold.");
+export type LedgerUserAccountsResponse = z.output<typeof LedgerUserAccountsResponse>;
+
+/** `GET {base}/admin/accounts/:userId/:currency/transactions`. */
+export const LedgerTransactionsResponse = z
+  .object({
+    userId: z.string().describe("The account owner, echoed so a response stands on its own."),
+    currency: z.string().describe("The currency, as the configured catalog spells it."),
+    transactions: z.array(LedgerTransactionView).describe("The page, newest first."),
+    nextCursor: NextCursor,
+  })
+  .describe("A page of one account's entry log.");
+export type LedgerTransactionsResponse = z.output<typeof LedgerTransactionsResponse>;