@pithy-sh/matchmaking 0.1.0

package/src/http/routes.ts

@@ -0,0 +1,301 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, DurableObjectNamespace, KVNamespace } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { InternalError, NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import { createRoom, joinRoom, normalizeCode } from "../code/room";
+import { type MatchmakingConfig, type MatchmakingGame, resolveGame } from "../config/config";
+import type { Invite } from "../data/invite";
+import { matchmakingDatabase } from "../data/tables";
+import { MatchmakingInviteForbiddenError, MatchmakingInviteNotFoundError } from "../error/errors";
+import { friendStore } from "../friends/store";
+import { resolveInvitee } from "../invite/resolve";
+import { type InviteStore, inviteStore } from "../invite/store";
+import type { MatchmakingPresence } from "../presence/durableObject";
+import { PRESENCE_USER_HEADER, type PresenceEvent } from "../presence/protocol";
+import type { MatchmakingQueue } from "../queue/durableObject";
+import { readSkill } from "../queue/skill";
+import { callRpc } from "../rpc";
+import { type SessionNamespace, sessionMinter } from "../session/minter";
+import { requireAuth } from "./guard";
+import { FriendParams, GameParams, InviteBody, InviteParams, RoomCodeParams } from "./schemas";
+
+/**
+ * The matchmaking HTTP surface. Every route is `requireAuth()`-gated (no public surface) and binds to
+ * `c.var.auth.userId`. Verification strategy: `bearer | session` throughout; the room-code join route may
+ * additionally stack a Turnstile humanity check when the adopter opts in (abuse flag).
+ *
+ * Every route also declares what it accepts on its route line, with `zValidator(target, Schema,
+ * validationHook)` from `./schemas` — always after the guards, so an unauthenticated caller still gets a
+ * 401 rather than a 400. A route that reads no request body declares no `json` validator.
+ *
+ * Rooms · POST /games/:game/rooms (param GameParams) · POST /rooms/:code/join (param RoomCodeParams)
+ * Invites · POST /games/:game/invites (param GameParams, json InviteBody) · GET /invites ·
+ *           POST /invites/:id/accept (param InviteParams) · POST /invites/:id/decline (param InviteParams)
+ * Friends · GET /friends · POST /friends/:userId/request · POST /friends/:userId/accept ·
+ *           POST /friends/:userId/decline · DELETE /friends/:userId — each param FriendParams
+ * Queue · POST /games/:game/queue · GET /games/:game/queue · DELETE /games/:game/queue — each param GameParams
+ * Presence · GET /presence (WebSocket; the raw request is forwarded to the Durable Object, body untouched)
+ */
+export interface MatchmakingRoutesOptions {
+  config: MatchmakingConfig;
+  basePath?: string;
+}
+
+export function registerMatchmakingRoutes(options: MatchmakingRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/matchmaking";
+  const { config } = options;
+
+  return (app) => {
+    // --- Rooms ---
+    app.post(`${base}/games/:game/rooms`, requireAuth(), zValidator("param", GameParams, validationHook), async (c) => {
+      const game = resolveMatchmakingGame(config, c.req.valid("param").game);
+      const result = await createRoom(kvOf(c), game, minterOf(c), userId(c), new Date());
+      return c.json(result, 201);
+    });
+
+    app.post(
+      `${base}/rooms/:code/join`,
+      requireAuth(),
+      zValidator("param", RoomCodeParams, validationHook),
+      async (c) => {
+        // The param schema is a length bound; `normalizeCode` still owns the code's real shape.
+        const code = normalizeCode(c.req.valid("param").code);
+        const result = await joinRoom(kvOf(c), minterOf(c), code, userId(c), new Date());
+        return c.json(result, 200);
+      },
+    );
+
+    // --- Invites ---
+    app.post(
+      `${base}/games/:game/invites`,
+      requireAuth(),
+      zValidator("param", GameParams, validationHook),
+      zValidator("json", InviteBody, validationHook),
+      async (c) => {
+        const game = resolveMatchmakingGame(config, c.req.valid("param").game);
+        // A direct invite seats exactly two players (inviter + invitee). A game that needs a larger roster
+        // cannot be filled this way — use a room code or the open queue — so reject it with a clear error
+        // rather than mint a session that can never start. Hand-thrown, not Zod: the roster is config, not
+        // request shape, so no body schema can express it.
+        if (game.players !== 2) {
+          throw new ValidationError({
+            message: "Direct invites are for two-player games.",
+            action: "Use a room code or the open queue for games with more than two players.",
+            detail: `Game "${game.key}" needs ${game.players} players; a direct invite seats only two.`,
+          });
+        }
+        const inviteeId = await resolveInvitee(dbBinding(c), c.req.valid("json"));
+        const invite = await inviteStore(matchmakingDatabase(dbBinding(c))).create({
+          id: crypto.randomUUID(),
+          gameKey: game.key,
+          inviterId: userId(c),
+          inviteeId,
+          at: new Date(),
+        });
+        await notify(c, inviteeId, { type: "invite", inviteId: invite.id, gameKey: game.key, from: userId(c) });
+        return c.json(invite, 201);
+      },
+    );
+
+    app.get(`${base}/invites`, requireAuth(), async (c) => {
+      const invites = await inviteStore(matchmakingDatabase(dbBinding(c))).pendingFor(userId(c));
+      return c.json({ invites });
+    });
+
+    app.post(
+      `${base}/invites/:id/accept`,
+      requireAuth(),
+      zValidator("param", InviteParams, validationHook),
+      async (c) => {
+        const store = inviteStore(matchmakingDatabase(dbBinding(c)));
+        const invite = await requireInvitee(c, store, c.req.valid("param").id);
+        const game = resolveMatchmakingGame(config, invite.gameKey);
+        const sessionId = await minterOf(c).mint(game.snapshot, game.players, [invite.inviterId, invite.inviteeId]);
+        const accepted = await store.accept(invite.id, sessionId, new Date());
+        await notify(c, invite.inviterId, { type: "match_found", sessionId, gameKey: game.key });
+        return c.json(accepted, 200);
+      },
+    );
+
+    app.post(
+      `${base}/invites/:id/decline`,
+      requireAuth(),
+      zValidator("param", InviteParams, validationHook),
+      async (c) => {
+        const store = inviteStore(matchmakingDatabase(dbBinding(c)));
+        const invite = await requireInvitee(c, store, c.req.valid("param").id);
+        return c.json(await store.decline(invite.id, new Date()), 200);
+      },
+    );
+
+    // --- Friends ---
+    if (config.friends) {
+      app.get(`${base}/friends`, requireAuth(), async (c) => {
+        const friends = await friendStore(matchmakingDatabase(dbBinding(c))).list(userId(c));
+        return c.json({ friends });
+      });
+
+      app.post(
+        `${base}/friends/:userId/request`,
+        requireAuth(),
+        zValidator("param", FriendParams, validationHook),
+        async (c) => {
+          const other = c.req.valid("param").userId;
+          await friendStore(matchmakingDatabase(dbBinding(c))).request(userId(c), other, new Date());
+          await notify(c, other, { type: "friend_request", from: userId(c) });
+          return c.body(null, 204);
+        },
+      );
+
+      app.post(
+        `${base}/friends/:userId/accept`,
+        requireAuth(),
+        zValidator("param", FriendParams, validationHook),
+        async (c) => {
+          await friendStore(matchmakingDatabase(dbBinding(c))).accept(
+            userId(c),
+            c.req.valid("param").userId,
+            new Date(),
+          );
+          return c.body(null, 204);
+        },
+      );
+
+      app.post(
+        `${base}/friends/:userId/decline`,
+        requireAuth(),
+        zValidator("param", FriendParams, validationHook),
+        async (c) => {
+          await friendStore(matchmakingDatabase(dbBinding(c))).decline(userId(c), c.req.valid("param").userId);
+          return c.body(null, 204);
+        },
+      );
+
+      app.delete(
+        `${base}/friends/:userId`,
+        requireAuth(),
+        zValidator("param", FriendParams, validationHook),
+        async (c) => {
+          await friendStore(matchmakingDatabase(dbBinding(c))).remove(userId(c), c.req.valid("param").userId);
+          return c.body(null, 204);
+        },
+      );
+    }
+
+    // --- Open queue ---
+    app.post(`${base}/games/:game/queue`, requireAuth(), zValidator("param", GameParams, validationHook), async (c) => {
+      const game = resolveMatchmakingGame(config, c.req.valid("param").game);
+      const skill = game.skillPool ? await readSkill(dbBinding(c), game.skillPool, userId(c)) : null;
+      const status = await callRpc(() =>
+        queueStub(c, game.key).enqueue({
+          userId: userId(c),
+          skill,
+          region: region(c),
+          gameKey: game.key,
+          players: game.players,
+          settings: game.queue,
+          snapshot: game.snapshot,
+        }),
+      );
+      return c.json(status, 200);
+    });
+
+    app.get(`${base}/games/:game/queue`, requireAuth(), zValidator("param", GameParams, validationHook), async (c) => {
+      const game = resolveMatchmakingGame(config, c.req.valid("param").game);
+      return c.json(await callRpc(() => queueStub(c, game.key).status(userId(c))), 200);
+    });
+
+    app.delete(
+      `${base}/games/:game/queue`,
+      requireAuth(),
+      zValidator("param", GameParams, validationHook),
+      async (c) => {
+        const game = resolveMatchmakingGame(config, c.req.valid("param").game);
+        await callRpc(() => queueStub(c, game.key).leave(userId(c)));
+        return c.body(null, 204);
+      },
+    );
+
+    // --- Presence (WebSocket) ---
+    app.get(`${base}/presence`, requireAuth(), async (c) => {
+      const request = new Request(c.req.url, c.req.raw);
+      request.headers.set(PRESENCE_USER_HEADER, userId(c));
+      return presenceStub(c).fetch(request);
+    });
+  };
+}
+
+// --- helpers ---
+
+function resolveMatchmakingGame(config: MatchmakingConfig, key: string): MatchmakingGame {
+  const game = resolveGame(config, key);
+  if (!game) {
+    throw new NotFoundError({
+      message: "That game does not exist.",
+      action: "Check the game key against the `games` list in pithy.config.ts.",
+      detail: `No matchmaking game "${key}" is configured.`,
+    });
+  }
+  return game;
+}
+
+async function requireInvitee(c: Context<PithyHonoEnv>, store: InviteStore, id: string): Promise<Invite> {
+  const invite = await store.get(id);
+  if (!invite) throw new MatchmakingInviteNotFoundError({ detail: `No invite "${id}".` });
+  if (invite.inviteeId !== userId(c)) {
+    throw new MatchmakingInviteForbiddenError({ detail: "Only the invitee may respond." });
+  }
+  return invite;
+}
+
+async function notify(c: Context<PithyHonoEnv>, target: string, event: PresenceEvent): Promise<void> {
+  try {
+    await presenceStub(c).notify(target, event);
+  } catch {
+    // Best-effort: a notification never fails the action that triggered it.
+  }
+}
+
+function userId(c: Context<PithyHonoEnv>): string {
+  const auth = c.var.auth;
+  if (!auth) throw new InternalError({ detail: "requireAuth() must run before a handler reads the user id." });
+  return auth.userId;
+}
+
+function dbBinding(c: Context<PithyHonoEnv>): D1Database {
+  const db = c.env.DB as D1Database | undefined;
+  if (!db) throw new InternalError({ detail: "The matchmaking routes require a `DB` D1 binding." });
+  return db;
+}
+
+function kvOf(c: Context<PithyHonoEnv>): KVNamespace {
+  const kv = c.env.MATCHMAKING as KVNamespace | undefined;
+  if (!kv) throw new InternalError({ detail: "The matchmaking routes require a `MATCHMAKING` KV binding." });
+  return kv;
+}
+
+function minterOf(c: Context<PithyHonoEnv>) {
+  return sessionMinter(c.env.SESSIONS as SessionNamespace | undefined);
+}
+
+function queueStub(c: Context<PithyHonoEnv>, gameKey: string) {
+  const ns = c.env.QUEUE as DurableObjectNamespace<MatchmakingQueue> | undefined;
+  if (!ns) throw new InternalError({ detail: "The matchmaking routes require a `QUEUE` Durable Object binding." });
+  return ns.get(ns.idFromName(gameKey));
+}
+
+function presenceStub(c: Context<PithyHonoEnv>) {
+  const ns = c.env.PRESENCE as DurableObjectNamespace<MatchmakingPresence> | undefined;
+  if (!ns) throw new InternalError({ detail: "The matchmaking routes require a `PRESENCE` Durable Object binding." });
+  return ns.get(ns.idFromName("presence"));
+}
+
+function region(c: Context<PithyHonoEnv>): string {
+  const cf = (c.req.raw as { cf?: { country?: string; colo?: string } }).cf;
+  return cf?.country ?? cf?.colo ?? "unknown";
+}

package/src/http/schemas.ts

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * What the matchmaking routes accept. Every schema here is named on a route line via
+ * `zValidator(target, Schema, validationHook)`, so reading `routes.ts` tells you the shape of a request
+ * without opening a handler.
+ *
+ * Path params are **shape** checks, not existence checks. A game key, a room code, an invite id and a
+ * user id are all bounded here so an unbounded string never reaches a store or a KV key; whether the
+ * value *resolves* stays with the code that owns that answer — `resolveMatchmakingGame` still raises its
+ * 404 for an unconfigured game, `normalizeCode` still raises `matchmaking/invalid_code` for a code that
+ * is the wrong shape, and the invite store still raises `matchmaking/invite_not_found`. Building a param
+ * schema out of the configured game keys would move a 404 to a 400 and leak the config to the caller.
+ */
+
+/** A game key on the path. Shape only — `resolveMatchmakingGame` owns the 404 for an unconfigured key. */
+export const GameParams = z
+  .object({
+    game: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe("The matchmaking game key from the path, resolved against the configured `games` list."),
+  })
+  .describe("The path params of a per-game route: which game the caller is addressing.");
+export type GameParams = z.infer<typeof GameParams>;
+
+/**
+ * A room code on the path. Deliberately tolerant: `normalizeCode` uppercases, strips whitespace, and
+ * accepts the dashless `WXYZ1234` as well as the canonical `WXYZ-1234`, so this is a length sanity bound
+ * only. `normalizeCode` still runs and still throws `matchmaking/invalid_code` for a genuinely bad code.
+ */
+export const RoomCodeParams = z
+  .object({
+    code: z.string().min(1).max(32).describe("The shareable room code from the path, before normalization."),
+  })
+  .describe("The path params of the room-code join route.");
+export type RoomCodeParams = z.infer<typeof RoomCodeParams>;
+
+/** An invite id on the path. Invite ids are minted with `crypto.randomUUID()`, so the shape is a UUID. */
+export const InviteParams = z
+  .object({
+    id: z.uuid().describe("The invite's UUID from the path — the externally-referenced invite id."),
+  })
+  .describe("The path params of an invite accept/decline route.");
+export type InviteParams = z.infer<typeof InviteParams>;
+
+/** The other user on a friend route. Auth user ids are opaque text, so this is a length bound only. */
+export const FriendParams = z
+  .object({
+    userId: z.string().min(1).max(255).describe("The other user in the friendship, as an auth user id."),
+  })
+  .describe("The path params of a friend-graph route: whom the friendship is with.");
+export type FriendParams = z.infer<typeof FriendParams>;
+
+/**
+ * Whom to invite. `resolveInvitee` re-checks the same exclusive-or for direct, non-HTTP callers — this
+ * schema is the HTTP boundary's copy of that rule, and answers a 400 instead of the resolver's 404.
+ */
+export const InviteBody = z
+  .object({
+    email: z.string().email().optional().describe("The invitee's email — the reliable, unique identity key."),
+    name: z.string().min(1).optional().describe("The invitee's screen name — best-effort, may be ambiguous."),
+  })
+  .refine((b) => (b.email ? 1 : 0) + (b.name ? 1 : 0) === 1, {
+    message: "Provide exactly one of `email` or `name`.",
+  })
+  .describe("Whom to invite: an email or a screen name.");
+export type InviteBody = z.infer<typeof InviteBody>;

package/src/index.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add matchmaking` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory and its config/options types. Every other module is imported by deep
+ * path; this is the documented contract, not a barrel.
+ *
+ * **The two Durable Objects are deliberately not here.** `MatchmakingQueue` and `MatchmakingPresence`
+ * import `cloudflare:workers`, which resolves in workerd and nowhere else, and this module is what an
+ * adopter's `pithy.config.ts` imports — a file every Node-side CLI command loads. Re-exporting the classes
+ * from here put both Durable Object chains on that path, so `pithy upgrade`, `pithy migrate`, and
+ * `pithy deploy` would have died with "Could not load pithy.config.ts" for any project composing
+ * matchmaking (#180, the defect `@pithy-sh/multiplayer` shipped as #172). The factory and the Durable
+ * Objects are two things with two runtimes, and this entry point carries only the first.
+ *
+ * The adopter's worker still exports the classes, from their own modules:
+ *
+ * ```ts
+ * export { MatchmakingQueue } from "@pithy-sh/matchmaking/src/queue/durableObject";
+ * export { MatchmakingPresence } from "@pithy-sh/matchmaking/src/presence/durableObject";
+ * ```
+ *
+ * — which is what wrangler's `class_name` resolves against, for the `QUEUE` and `PRESENCE` bindings
+ * `matchmaking()` declares. The CLI writes the bindings and the class migration tags for you.
+ */
+
+export {
+  isMatchmakingCapability,
+  MATCHMAKING_MIGRATION_ORDER,
+  type MatchmakingCapability,
+  type MatchmakingOptions,
+  matchmaking,
+} from "./capability";
+export {
+  MatchmakingConfig,
+  type MatchmakingConfigInput,
+  MatchmakingGame,
+  MatchmakingQueueSettings,
+  MatchmakingRoomCodes,
+  MatchmakingSnapshot,
+  resolveGame,
+} from "./config/config";
+export { FriendStatus, Friendship } from "./data/friend";
+export { Invite, InviteStatus } from "./data/invite";

package/src/invite/resolve.ts

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { MatchmakingUserNotFoundError } from "../error/errors";
+
+/**
+ * Resolve an invite target — an email or a screen name — to a single authenticated user id, via the
+ * optional `@pithy-sh/auth` seam (dynamic-imported, like multiplayer → leaderboard). Email is the reliable
+ * key (unique on the user table); a display name is best-effort and may be ambiguous. Auth exposes no
+ * unique screen name, so a name that matches zero or many users throws `matchmaking/user_not_found` —
+ * invite by email for certainty. If `@pithy-sh/auth` is not installed, resolution is impossible.
+ */
+
+/** How an invitee is addressed — exactly one of these. */
+export interface InviteTarget {
+  email?: string;
+  name?: string;
+}
+
+export async function resolveInvitee(db: D1Database, target: InviteTarget): Promise<string> {
+  const byEmail = typeof target.email === "string" && target.email.length > 0;
+  const byName = typeof target.name === "string" && target.name.length > 0;
+  if (byEmail === byName) {
+    throw new MatchmakingUserNotFoundError({
+      detail: "Provide exactly one of email or name to resolve an invitee.",
+    });
+  }
+
+  let authDatabase: typeof import("@pithy-sh/auth/src/data/tables").authDatabase;
+  let User: typeof import("@pithy-sh/auth/src/data/betterAuth").User;
+  try {
+    ({ authDatabase } = await import("@pithy-sh/auth/src/data/tables"));
+    ({ User } = await import("@pithy-sh/auth/src/data/betterAuth"));
+  } catch (cause) {
+    throw new MatchmakingUserNotFoundError(
+      { detail: "@pithy-sh/auth is required to resolve an invitee by email or name." },
+      { cause },
+    );
+  }
+
+  const auth = authDatabase(db);
+
+  if (byEmail) {
+    const row = await auth
+      .selectFrom("pithyAuthUsers")
+      // Normalized, so an invite typed `Ada@Example.com` finds the account that signed in as
+      // `ada@example.com`. Both sides of every address comparison in the kit go through this rule.
+      .where("email", "=", normalizeAddress(target.email as string))
+      .selectAll()
+      .executeTakeFirst();
+    if (!row) {
+      throw new MatchmakingUserNotFoundError({ detail: `No user with email ${target.email}.` });
+    }
+    return User.parse(row).id;
+  }
+
+  // Names are non-unique: zero or many matches is unresolvable.
+  const rows = await auth
+    .selectFrom("pithyAuthUsers")
+    .where("name", "=", target.name as string)
+    .selectAll()
+    .execute();
+  if (rows.length !== 1) {
+    throw new MatchmakingUserNotFoundError({
+      detail: `Name ${target.name} matched ${rows.length} users; invite by email for a unique identity.`,
+    });
+  }
+  return User.parse(rows[0]).id;
+}

package/src/invite/store.ts

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Invite } from "../data/invite";
+import { MATCHMAKING_INVITES_TABLE, type MatchmakingDatabase } from "../data/tables";
+import { MatchmakingInviteNotFoundError } from "../error/errors";
+
+/**
+ * The direct-invite store — one player's pending asks to another. Create a pending invite; the invitee
+ * accepts (a session is minted and recorded) or declines. See {@link inviteStore}.
+ *
+ * Round-trip rule (CLAUDE.md §Data layer): read rows with `Invite.parse` (decode), write with
+ * `Invite.encode` (encode). No raw epoch numbers below.
+ */
+
+/** What creating an invite needs. */
+export interface CreateInviteInput {
+  id: string;
+  gameKey: string;
+  inviterId: string;
+  inviteeId: string;
+  at: Date;
+}
+
+export interface InviteStore {
+  /** Persist a new pending invite. */
+  create(input: CreateInviteInput): Promise<Invite>;
+  /** Fetch an invite by id, or undefined. */
+  get(id: string): Promise<Invite | undefined>;
+  /** Mark an invite accepted and record the minted session id. Throws `matchmaking/invite_not_found`. */
+  accept(id: string, sessionId: string, at: Date): Promise<Invite>;
+  /** Mark an invite declined. Throws `matchmaking/invite_not_found`. */
+  decline(id: string, at: Date): Promise<Invite>;
+  /** Every pending invite addressed to `userId`. */
+  pendingFor(userId: string): Promise<Invite[]>;
+}
+
+export function inviteStore(db: MatchmakingDatabase): InviteStore {
+  const get = async (id: string): Promise<Invite | undefined> => {
+    const row = await db.selectFrom(MATCHMAKING_INVITES_TABLE).where("id", "=", id).selectAll().executeTakeFirst();
+    return row ? Invite.parse(row) : undefined;
+  };
+
+  const loadOrThrow = async (id: string): Promise<Invite> => {
+    const invite = await get(id);
+    if (!invite) {
+      throw new MatchmakingInviteNotFoundError({ detail: `No invite with id ${id}.` });
+    }
+    return invite;
+  };
+
+  return {
+    async create(input: CreateInviteInput): Promise<Invite> {
+      const invite: Invite = {
+        id: input.id,
+        gameKey: input.gameKey,
+        inviterId: input.inviterId,
+        inviteeId: input.inviteeId,
+        status: "pending",
+        sessionId: null,
+        createdAt: input.at,
+        respondedAt: null,
+      };
+      await db.insertInto(MATCHMAKING_INVITES_TABLE).values(Invite.encode(invite)).execute();
+      return invite;
+    },
+
+    get,
+
+    async accept(id: string, sessionId: string, at: Date): Promise<Invite> {
+      const invite = await loadOrThrow(id);
+      const updated: Invite = { ...invite, status: "accepted", sessionId, respondedAt: at };
+      const record = Invite.encode(updated);
+      await db
+        .updateTable(MATCHMAKING_INVITES_TABLE)
+        .set({ status: record.status, sessionId: record.sessionId, respondedAt: record.respondedAt })
+        .where("id", "=", id)
+        .execute();
+      return updated;
+    },
+
+    async decline(id: string, at: Date): Promise<Invite> {
+      const invite = await loadOrThrow(id);
+      const updated: Invite = { ...invite, status: "declined", respondedAt: at };
+      const record = Invite.encode(updated);
+      await db
+        .updateTable(MATCHMAKING_INVITES_TABLE)
+        .set({ status: record.status, respondedAt: record.respondedAt })
+        .where("id", "=", id)
+        .execute();
+      return updated;
+    },
+
+    async pendingFor(userId: string): Promise<Invite[]> {
+      const rows = await db
+        .selectFrom(MATCHMAKING_INVITES_TABLE)
+        .where("inviteeId", "=", userId)
+        .where("status", "=", "pending")
+        .orderBy("createdAt", "desc")
+        .selectAll()
+        .execute();
+      return rows.map((row) => Invite.parse(row));
+    },
+  };
+}

package/src/kv/rooms.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { KVNamespace } from "@cloudflare/workers-types";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+import { TypedKv } from "@pithy-sh/core/src/kv/kv";
+import { z } from "zod";
+
+/**
+ * A room — a short, shareable join code pointing at an already-minted multiplayer session. Stored in KV
+ * (namespace `MATCHMAKING`) under `matchmaking:<code>`, with a TTL so it expires, and a `usesRemaining`
+ * counter so it is limited-use. Zod-validated on every read and write.
+ */
+export const Room = z
+  .object({
+    code: z.string().describe("The room's shareable code, e.g. WXYZ-1234."),
+    gameKey: z.string().describe("The matchmaking game the room is for."),
+    hostId: z.string().describe("The authenticated user who opened the room (the session's creator)."),
+    sessionId: z.string().describe("The multiplayer session id the room's code joins players into."),
+    usesRemaining: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe("How many redemptions the code has left before it is spent."),
+    createdAt: JsonDate.describe("When the room was opened."),
+    expiresAt: JsonDate.describe(
+      "When the code expires — used to recompute the KV TTL on each redemption without resetting the window.",
+    ),
+  })
+  .describe("A room-code entry: a limited-use, short-lived pointer to a multiplayer session.");
+export type Room = z.output<typeof Room>;
+
+/** The KV key for a room — its code. Physical key: `matchmaking:<code>`. */
+export const RoomKey = z.object({ code: z.string().describe("The room code (the key).") }).describe("Room KV key.");
+
+/** The fixed KV namespace prefix for room entries. */
+export const ROOM_PREFIX = "matchmaking";
+
+/** A typed, Zod-validated KV view of the room store over the `MATCHMAKING` namespace. */
+export function roomStore(namespace: KVNamespace, ttlSeconds: number): TypedKv<typeof Room, typeof RoomKey> {
+  return new TypedKv(namespace, { prefix: ROOM_PREFIX, key: RoomKey, value: Room, ttlSeconds });
+}