@pithy-sh/matchmaking 0.1.0

package/src/session/minter.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { MatchmakingSnapshot } from "../config/config";
+
+/**
+ * The session-minter seam — matchmaking's one dependency on `@pithy-sh/multiplayer`, kept at arm's
+ * length. Every pairing path (room code, invite accept, an open-queue match) ends by minting a
+ * multiplayer session and seating its roster; this is the single place that does it.
+ *
+ * The default implementation talks to the `SESSIONS` Durable Object namespace binding directly — the
+ * create-then-join dance multiplayer's own routes use (`newUniqueId` → `get` → `create(snapshot, host)`
+ * → `join(player)`). It is typed against a minimal local RPC shape, so matchmaking never imports
+ * multiplayer. Tests inject a fake minter. Matchmaking's output is always a session id.
+ */
+export interface SessionMinter {
+  /** Mint a session for a game from its snapshot, seat the roster (first id is the creator), return its id. */
+  mint(snapshot: MatchmakingSnapshot, players: number, roster: readonly string[]): Promise<string>;
+  /** Seat one more player into an already-minted session (the room-code path: host mints, others join). */
+  join(sessionId: string, userId: string): Promise<void>;
+}
+
+/** The minimal RPC surface the multiplayer session DO exposes — declared locally to avoid a hard dep. */
+interface SessionStub {
+  create(snapshot: unknown, creatorUserId: string): Promise<{ sessionId: string }>;
+  join(userId: string): Promise<{ sessionId: string }>;
+}
+
+/** A DO namespace typed to the minimal session stub — what `env.SESSIONS` provides at runtime. */
+export interface SessionNamespace {
+  newUniqueId(): { toString(): string };
+  idFromString(hex: string): unknown;
+  get(id: unknown): SessionStub;
+}
+
+/**
+ * The default minter over a `SESSIONS` DO namespace binding. Builds a multiplayer `GameSnapshot` from the
+ * matchmaking snapshot (roster size included), creates the session with the first player as creator, and
+ * joins the rest.
+ */
+export function sessionMinter(sessions: SessionNamespace | undefined): SessionMinter {
+  return {
+    async mint(snapshot, players, roster) {
+      if (!sessions) {
+        throw new InternalError({
+          detail: "Minting a session requires the SESSIONS Durable Object binding (install @pithy-sh/multiplayer).",
+        });
+      }
+      const [creator, ...rest] = roster;
+      if (creator === undefined) {
+        throw new InternalError({ detail: "Cannot mint a session for an empty roster." });
+      }
+      const gameSnapshot = {
+        kind: snapshot.kind,
+        mode: snapshot.mode,
+        players,
+        turnTimeoutMs: snapshot.turnTimeoutMs,
+        leaderboard: null,
+        rules: snapshot.rules,
+      };
+      const id = sessions.newUniqueId();
+      const view = await sessions.get(id).create(gameSnapshot, creator);
+      for (const player of rest) {
+        await sessions.get(sessions.idFromString(view.sessionId)).join(player);
+      }
+      return view.sessionId;
+    },
+
+    async join(sessionId, userId) {
+      if (!sessions) {
+        throw new InternalError({
+          detail: "Joining a session requires the SESSIONS Durable Object binding (install @pithy-sh/multiplayer).",
+        });
+      }
+      await sessions.get(sessions.idFromString(sessionId)).join(userId);
+    },
+  };
+}

package/src/testWorker.ts

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// The Miniflare `main` for `*.workers.test.ts`: it exists only to register the Durable Object classes so
+// the test bindings (`QUEUE`, `PRESENCE`) resolve. Its fetch is inert.
+
+export { MatchmakingPresence } from "./presence/durableObject";
+export { MatchmakingQueue } from "./queue/durableObject";
+
+export default {
+  fetch(): Response {
+    return new Response("matchmaking test worker", { status: 200 });
+  },
+};

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/matchmaking knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/matchmaking";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";