@pithy-sh/matchmaking 0.1.0

package/src/data/friend.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/** The state of a friend edge. */
+export const FriendStatus = z
+  .enum(["pending", "accepted"])
+  .describe("A friend edge's state: a request awaiting acceptance, or a mutual connection.");
+export type FriendStatus = z.infer<typeof FriendStatus>;
+
+/**
+ * One edge of the symmetric friend graph — the row in `pithy_matchmaking_friends`. A pair is stored once,
+ * canonicalized so `userA < userB`; `requestedBy` records who initiated a pending request (the other
+ * accepts). Either party can remove an accepted edge. The unique `(userA, userB)` index makes the pairing
+ * idempotent.
+ */
+export const Friendship = z
+  .object({
+    id: z.number().int().describe("Autoincrement PK. Internal only."),
+    userA: z.string().describe("The lexicographically smaller user id of the pair (canonical ordering)."),
+    userB: z.string().describe("The lexicographically larger user id of the pair (canonical ordering)."),
+    status: FriendStatus.describe("Whether the edge is a pending request or an accepted friendship."),
+    requestedBy: z.string().describe("Which of the two users sent the request — the other one accepts it."),
+    createdAt: SQLiteDate.describe("When the request was sent."),
+    updatedAt: SQLiteDate.describe("When the edge last changed (e.g. on acceptance)."),
+  })
+  .describe("One symmetric friend edge between two users.");
+export type Friendship = z.output<typeof Friendship>;
+export type FriendshipRow = z.input<typeof Friendship>;

package/src/data/invite.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/** The lifecycle of a direct invite. */
+export const InviteStatus = z
+  .enum(["pending", "accepted", "declined"])
+  .describe("A direct invite's state: awaiting a response, accepted (a session was minted), or declined.");
+export type InviteStatus = z.infer<typeof InviteStatus>;
+
+/**
+ * A direct invite — one player asks another (by email or screen name, resolved to a user id) to play. The
+ * row in `pithy_matchmaking_invites`. The id is a UUID (externally referenced in URLs), not an
+ * autoincrement, to prevent enumeration.
+ */
+export const Invite = z
+  .object({
+    id: z.string().describe("The invite's UUID — the externally-referenced id."),
+    gameKey: z.string().describe("The matchmaking game this invite is for."),
+    inviterId: z.string().describe("The authenticated user who sent the invite."),
+    inviteeId: z.string().describe("The resolved user the invite was sent to."),
+    status: InviteStatus.describe("The invite's current state."),
+    sessionId: z
+      .string()
+      .nullable()
+      .describe("The multiplayer session id minted on accept, or null while pending/declined."),
+    createdAt: SQLiteDate.describe("When the invite was sent."),
+    respondedAt: SQLiteDate.nullable().describe("When the invitee accepted or declined, or null while pending."),
+  })
+  .describe("One direct invite from one player to another.");
+export type Invite = z.output<typeof Invite>;
+export type InviteRow = z.input<typeof Invite>;

package/src/data/tables.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { Friendship } from "./friend";
+import { Invite } from "./invite";
+
+/**
+ * The matchmaking capability's D1 tables: `pithy_matchmaking_invites` (direct invites) and
+ * `pithy_matchmaking_friends` (the friend graph). Room codes live in KV, not D1. Table names are
+ * camelCase constants; core's `createDatabase` installs the mandatory `CamelCasePlugin`.
+ */
+
+export const MATCHMAKING_INVITES_TABLE = "pithyMatchmakingInvites";
+export const MATCHMAKING_FRIENDS_TABLE = "pithyMatchmakingFriends";
+
+export function matchmakingTables(): Record<string, z.ZodObject> {
+  return {
+    [MATCHMAKING_INVITES_TABLE]: Invite,
+    [MATCHMAKING_FRIENDS_TABLE]: Friendship,
+  };
+}
+
+type MatchmakingTables = {
+  [MATCHMAKING_INVITES_TABLE]: typeof Invite;
+  [MATCHMAKING_FRIENDS_TABLE]: typeof Friendship;
+};
+export type MatchmakingDatabase = Kysely<DatabaseSchema<MatchmakingTables>>;
+
+export function matchmakingDatabase(d1: D1Database): MatchmakingDatabase {
+  return createDatabase(d1, {
+    [MATCHMAKING_INVITES_TABLE]: Invite,
+    [MATCHMAKING_FRIENDS_TABLE]: Friendship,
+  }) as unknown as MatchmakingDatabase;
+}

package/src/error/errors.ts

@@ -0,0 +1,165 @@
+// 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/matchmaking` throw sugar. The `matchmaking/*` codes live in core's closed `KitErrorPayload`
+ * union; these subclasses set one of those members — the leaderboard/multiplayer pattern. Runtime code
+ * throws one of these, never a plain `new Error`.
+ */
+interface MatchmakingErrorArgs {
+  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 MatchmakingRoomNotFoundError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/room_not_found",
+        status: 404,
+        message: args.message ?? "That room does not exist.",
+        action: args.action ?? "Ask the host for a fresh code — it may have expired or been used up.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingRoomFullError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/room_full",
+        status: 409,
+        message: args.message ?? "That room code is used up.",
+        action: args.action ?? "Ask the host to open a new room.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingInvalidCodeError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/invalid_code",
+        status: 400,
+        message: args.message ?? "That is not a valid room code.",
+        action: args.action ?? "Enter the code exactly as shared, e.g. WXYZ-1234.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingInviteNotFoundError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/invite_not_found",
+        status: 404,
+        message: args.message ?? "That invite does not exist.",
+        action: args.action ?? "It may have been accepted, declined, or expired.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingInviteForbiddenError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/invite_forbidden",
+        status: 403,
+        message: args.message ?? "This invite is not yours to act on.",
+        action: args.action ?? "Only the inviter or the invitee may act on an invite.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingUserNotFoundError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/user_not_found",
+        status: 404,
+        message: args.message ?? "No single user matches that invite.",
+        action: args.action ?? "Invite by email for a unique identity — a display name may be ambiguous.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingAlreadyFriendsError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/already_friends",
+        status: 409,
+        message: args.message ?? "You are already connected, or a request is already pending.",
+        action: args.action ?? "Wait for the pending request, or you are already friends.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingFriendRequestNotFoundError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/friend_request_not_found",
+        status: 404,
+        message: args.message ?? "There is no pending friend request to act on.",
+        action: args.action ?? "The request may have been withdrawn or already answered.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MatchmakingNotQueuedError extends PithyError {
+  constructor(args: MatchmakingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "matchmaking/not_queued",
+        status: 404,
+        message: args.message ?? "You are not in this queue.",
+        action: args.action ?? "Enqueue before checking your status or leaving.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/friends/store.ts

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { FriendStatus } from "../data/friend";
+import { Friendship } from "../data/friend";
+import { MATCHMAKING_FRIENDS_TABLE, type MatchmakingDatabase } from "../data/tables";
+import { MatchmakingAlreadyFriendsError, MatchmakingFriendRequestNotFoundError } from "../error/errors";
+
+/**
+ * The friend graph — a symmetric connection formed by mutual accept. A player sends a request; the
+ * recipient accepts (forming the edge) or declines (dropping it); either party can later remove an
+ * accepted edge. Pairs are canonicalized (`userA < userB`) so a connection is one row regardless of who
+ * asked. See {@link friendStore}.
+ */
+
+/** One friend edge from a given user's perspective. */
+export interface FriendSummary {
+  /** The other user in the edge. */
+  userId: string;
+  /** Whether the edge is a pending request or an accepted friendship. */
+  status: FriendStatus;
+  /** For a pending edge: `outgoing` (this user asked) or `incoming` (the other asked). `mutual` once accepted. */
+  direction: "incoming" | "outgoing" | "mutual";
+  /** When the edge was last updated. */
+  since: Date;
+}
+
+export interface FriendStore {
+  /** Send a friend request from `from` to `to`. Throws `matchmaking/already_friends` if an edge exists. */
+  request(from: string, to: string, at: Date): Promise<void>;
+  /** `userId` accepts a pending request from `other`. Throws `matchmaking/friend_request_not_found` if none. */
+  accept(userId: string, other: string, at: Date): Promise<void>;
+  /** `userId` declines/withdraws a pending edge with `other` (drops the row). */
+  decline(userId: string, other: string): Promise<void>;
+  /** `userId` removes an accepted friendship with `other`. */
+  remove(userId: string, other: string): Promise<void>;
+  /** Every edge touching `userId`, from their perspective. */
+  list(userId: string): Promise<FriendSummary[]>;
+  /** Whether `a` and `b` are accepted friends. */
+  areFriends(a: string, b: string): Promise<boolean>;
+}
+
+/** Order a pair so the row is stored once regardless of who asked: `userA` is the lexicographically smaller id. */
+function canonical(x: string, y: string): { userA: string; userB: string } {
+  return x < y ? { userA: x, userB: y } : { userA: y, userB: x };
+}
+
+export function friendStore(db: MatchmakingDatabase): FriendStore {
+  const findPair = (userA: string, userB: string) =>
+    db
+      .selectFrom(MATCHMAKING_FRIENDS_TABLE)
+      .selectAll()
+      .where("userA", "=", userA)
+      .where("userB", "=", userB)
+      .executeTakeFirst();
+
+  return {
+    async request(from, to, at) {
+      if (from === to) {
+        throw new ValidationError({
+          message: "You cannot send a friend request to yourself.",
+          detail: `request called with from === to (${from}).`,
+        });
+      }
+      const { userA, userB } = canonical(from, to);
+      const existing = await findPair(userA, userB);
+      if (existing) {
+        throw new MatchmakingAlreadyFriendsError({
+          detail: `A friend edge already exists for (${userA}, ${userB}) with status ${String((existing as { status: unknown }).status)}.`,
+        });
+      }
+      const record = {
+        userA,
+        userB,
+        status: "pending" as const,
+        requestedBy: from,
+        createdAt: Friendship.shape.createdAt.encode(at),
+        updatedAt: Friendship.shape.updatedAt.encode(at),
+      };
+      await db
+        .insertInto(MATCHMAKING_FRIENDS_TABLE)
+        // biome-ignore lint/suspicious/noExplicitAny: the record is the schema's `z.input` side; `id` is an autoincrement rowid SQLite assigns.
+        .values(record as any)
+        .execute();
+    },
+
+    async accept(userId, other, at) {
+      const { userA, userB } = canonical(userId, other);
+      const row = await findPair(userA, userB);
+      const parsed = row ? Friendship.parse(row) : undefined;
+      if (parsed?.status !== "pending" || parsed.requestedBy !== other) {
+        throw new MatchmakingFriendRequestNotFoundError({
+          detail: `No pending request from ${other} to ${userId} to accept.`,
+        });
+      }
+      await db
+        .updateTable(MATCHMAKING_FRIENDS_TABLE)
+        .set({ status: "accepted", updatedAt: Friendship.shape.updatedAt.encode(at) })
+        .where("userA", "=", userA)
+        .where("userB", "=", userB)
+        .execute();
+    },
+
+    async decline(userId, other) {
+      const { userA, userB } = canonical(userId, other);
+      await db
+        .deleteFrom(MATCHMAKING_FRIENDS_TABLE)
+        .where("userA", "=", userA)
+        .where("userB", "=", userB)
+        .where("status", "=", "pending")
+        .execute();
+    },
+
+    async remove(userId, other) {
+      const { userA, userB } = canonical(userId, other);
+      await db.deleteFrom(MATCHMAKING_FRIENDS_TABLE).where("userA", "=", userA).where("userB", "=", userB).execute();
+    },
+
+    async list(userId) {
+      const rows = await db
+        .selectFrom(MATCHMAKING_FRIENDS_TABLE)
+        .selectAll()
+        .where((eb) => eb.or([eb("userA", "=", userId), eb("userB", "=", userId)]))
+        .execute();
+      return rows.map((row) => {
+        const edge = Friendship.parse(row);
+        const otherId = edge.userA === userId ? edge.userB : edge.userA;
+        const direction = edge.status === "accepted" ? "mutual" : edge.requestedBy === userId ? "outgoing" : "incoming";
+        return { userId: otherId, status: edge.status, direction, since: edge.updatedAt };
+      });
+    },
+
+    async areFriends(a, b) {
+      const { userA, userB } = canonical(a, b);
+      const row = await db
+        .selectFrom(MATCHMAKING_FRIENDS_TABLE)
+        .select("id")
+        .where("userA", "=", userA)
+        .where("userB", "=", userB)
+        .where("status", "=", "accepted")
+        .executeTakeFirst();
+      return row !== undefined;
+    },
+  };
+}

package/src/http/guard.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * Route guard over the `AuthContext` seam. Copied — not imported from `@pithy-sh/auth` — so matchmaking
+ * keeps `dependsOn` empty: without auth installed, `c.var.auth` is null and every guarded route is denied
+ * rather than open (the leaderboard/multiplayer pattern). Membership everywhere binds to
+ * `c.var.auth.userId`, never a client-supplied id.
+ */
+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();
+  };
+}