@table-games-engine/nakama-adapter 0.0.0-stage → 0.1.0

package/dist/match-handler.d.ts

@@ -0,0 +1,76 @@
+import type { ActionHandler, EngineAdapter, GameId, GameManifest, GamePlugin, MatchId, MatchState, StateBasedActionChecker, StateTransition, WinConditionChecker } from '@table-games-engine/core';
+import type { SnapshotPolicy } from '@table-games-engine/persistence';
+import type { GameRegistry } from './registry.js';
+import type { IdempotencyCache } from './idempotency.js';
+import type { NkMatchHandler, NkPresence } from './types.js';
+import { type TimeoutOptions } from './timeouts.js';
+import { type NakamaPlatformPlugin } from './plugins.js';
+export type MatchStatus = 'lobby' | 'active' | 'paused' | 'finished';
+/**
+ * Internal envelope Nakama threads through the loop. Every field is plain
+ * JSON-serialisable (the `manifest` and `handlers` references are recovered
+ * via the registry on every loop, so storing them here is a convenience for
+ * tests; in production they are recovered from the registry on each tick).
+ */
+export interface NkMatchInternalState {
+    readonly matchId: MatchId;
+    readonly gameId: GameId;
+    engineState: MatchState;
+    readonly manifest: GameManifest;
+    readonly handlers: Readonly<Record<string, ActionHandler>>;
+    readonly stateBasedActions?: StateBasedActionChecker;
+    readonly winChecker?: WinConditionChecker;
+    readonly legalMoves?: GamePlugin['legalMoves'];
+    presences: Record<string, NkPresence>;
+    status: MatchStatus;
+    /** Wall-clock ms when the current priority holder took priority. Used by `checkTimeouts`. */
+    priorityHeldSince: number | null;
+    /** Last priority holder we observed; used to detect transitions. */
+    lastPriorityHolder: string | null;
+}
+export interface CreateMatchHandlerOptions {
+    /** Source of truth for `gameId -> manifest/handlers/setup`. */
+    readonly registry: GameRegistry;
+    /** Per-match idempotency cache. */
+    readonly idempotencyCache: IdempotencyCache;
+    /**
+     * Optional default match-id factory. If `params.matchId` is not supplied to
+     * `matchInit`, the handler uses this. Defaults to a deterministic
+     * `match-<now>` (the harness controls `now`, so tests stay deterministic).
+     */
+    readonly matchIdFactory?: (now: number) => string;
+    /**
+     * Optional clock for timeout calculations + idempotency stamping.
+     * Defaults to `Date.now`.
+     */
+    readonly now?: () => number;
+    /** Optional timeout configuration; if omitted, timeouts are disabled. */
+    readonly timeout?: TimeoutOptions;
+    /** Optional override of the default tick rate (`1`). */
+    readonly tickRate?: number;
+    /**
+     * Optional persistence backend. When supplied the handler appends every
+     * engine transition's events and snapshots per `policy`.
+     */
+    readonly adapter?: EngineAdapter;
+    /**
+     * Optional snapshot cadence; ignored when `adapter` is undefined.
+     * Defaults to `everyNTransitions(50)` per the M2 plan.
+     */
+    readonly policy?: SnapshotPolicy;
+    /**
+     * Optional ownership lease holder. When present and `adapter` is also
+     * present the handler acquires a lease at `matchInit` and releases at
+     * `matchTerminate`.
+     */
+    readonly ownerNode?: string;
+    /** Lease duration in seconds. Defaults to 60. */
+    readonly leaseSeconds?: number;
+    /**
+     * Optional platform plugins. Each lifecycle hook fires fire-and-forget;
+     * plugin failures never crash the match.
+     */
+    readonly plugins?: ReadonlyArray<NakamaPlatformPlugin>;
+}
+export declare function createMatchHandler(options: CreateMatchHandlerOptions): NkMatchHandler<NkMatchInternalState>;
+export type { StateTransition };

package/dist/persistence-bridge.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Persistence bridge for the Nakama match handler.
+ *
+ * The Nakama match loop is a synchronous tick loop driven by Nakama's runtime.
+ * Adapter writes are async (`Promise<void>`). The bridge exists to:
+ *
+ *   1. Hide the (manifest, handlers, adapter, snapshot policy) bookkeeping
+ *      so the match handler does not have to repeat it for every transition.
+ *   2. Translate `engine` results into `(events appended, snapshot maybe)`
+ *      pairs.
+ *
+ * We deliberately do NOT use `@table-games-engine/persistence`'s
+ * `createPersistedEngine` here: that wrapper owns its own `Engine`
+ * synchronously across calls, while the Nakama match handler rebuilds an
+ * `Engine` per loop tick from a serialised state envelope (`engineState`).
+ * The bridge mirrors `createPersistedEngine`'s persistence-side state
+ * machine (transition counters, snapshot cadence) but takes the post-call
+ * `MatchState` from the caller rather than holding an engine instance.
+ *
+ * # Failure semantics
+ *
+ * If `appendEvents` or `persistSnapshot` rejects, the bridge re-throws so
+ * the match handler can decide what to do (today: bubble up to the
+ * `matchLoop` caller via `nk.logger.error` and let Nakama observe the
+ * error). The in-memory engine state has already been advanced; rolling it
+ * back is the host runtime's responsibility (e.g. terminate + replay).
+ */
+import type { EngineAdapter, MatchId, MatchState, StateTransition } from '@table-games-engine/core';
+import { type SnapshotPolicy } from '@table-games-engine/persistence';
+/**
+ * Persistence-side state machine that mirrors the `createPersistedEngine`
+ * counters but without owning an `Engine`.
+ *
+ * Construct via {@link createPersistenceBridge}, call
+ * {@link PersistenceBridge.persistInitialSnapshot} once at `matchInit`, and
+ * call {@link PersistenceBridge.persistTransition} after every successful
+ * engine transition.
+ */
+export interface PersistenceBridge {
+    /** The match this bridge is bound to. */
+    readonly matchId: MatchId;
+    /** The adapter the bridge writes against. */
+    readonly adapter: EngineAdapter;
+    /**
+     * Persist the initial state as snapshot v0 (or whatever
+     * `state.version` is). Idempotent against the adapter — the
+     * underlying adapter is required to tolerate repeated snapshots at
+     * the same `(matchId, version)` when the checksum matches.
+     */
+    persistInitialSnapshot(state: MatchState): Promise<void>;
+    /**
+     * Append a single transition's events and conditionally snapshot per
+     * the configured policy. The post-transition `MatchState` is required
+     * because the snapshot policy operates on it.
+     *
+     * Re-throws adapter errors verbatim.
+     */
+    persistTransition(transition: StateTransition, postState: MatchState): Promise<void>;
+    /**
+     * Force a snapshot at the current state, bypassing the policy. Useful
+     * for "snapshot before terminate" or test determinism.
+     */
+    forceSnapshot(state: MatchState): Promise<void>;
+}
+export interface CreatePersistenceBridgeArgs {
+    readonly adapter: EngineAdapter;
+    readonly matchId: MatchId;
+    /** Snapshot cadence; defaults to `everyNTransitions(50)` per M2 plan. */
+    readonly policy?: SnapshotPolicy;
+}
+/**
+ * Build a {@link PersistenceBridge} bound to `(adapter, matchId, policy)`.
+ *
+ * The bridge is stateful only in the persistence-side counters
+ * (`transitionsSince`, `lastSnapshotTick`, `lastVersionPersisted`) — the
+ * engine state itself is owned by the caller (the match handler).
+ */
+export declare function createPersistenceBridge(args: CreatePersistenceBridgeArgs): PersistenceBridge;

package/dist/plugins.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Platform plugin contract for the Nakama match handler.
+ *
+ * Platform plugins are the side-channel hook surface for things that should
+ * NOT live inside the deterministic engine: analytics, leaderboards, audit
+ * logging, push notifications, anti-cheat sampling, achievements, etc.
+ *
+ * # Invocation contract
+ *
+ *   - Plugins are invoked **fire-and-forget** from inside the match handler.
+ *   - The match handler does NOT await plugin promises before returning
+ *     control to Nakama's runtime. A slow plugin must never stall the
+ *     game loop.
+ *   - Plugin rejections are **caught and logged** via `nk.logger.error`.
+ *     A failing plugin is never propagated up — games continue.
+ *   - Multiple plugins can be registered; they are invoked in registration
+ *     order, but their promises run in parallel (no sequencing).
+ *
+ * # Hook coverage
+ *
+ * Each callback is optional. Plugins implement only the hooks they care
+ * about. Coverage:
+ *
+ *   - `onMatchCreated`     fires inside `matchInit`.
+ *   - `onMatchStarted`     fires when status transitions `lobby -> active`.
+ *   - `onPlayerJoined`     fires for each presence in `matchJoin`.
+ *   - `onPlayerLeft`       fires for each presence in `matchLeave`.
+ *   - `onPlayerAction`     fires after each successful player-driven
+ *                          transition (only for player actions, not for
+ *                          stack resolution / triggers).
+ *   - `onStateTransition`  fires after EVERY successful engine transition
+ *                          (player action, stack drain, triggers, timeouts).
+ *   - `onMatchEnded`       fires when the engine reports `ended: true`.
+ */
+import type { ActionInput, GameId, GameResult, MatchId, MatchState, StateTransition } from '@table-games-engine/core';
+import type { NkLogger, NkPresence } from './types.js';
+/**
+ * Common context every plugin callback receives. Pure data — plugins
+ * can capture this freely without retaining live engine references.
+ */
+export interface PluginContext {
+    readonly matchId: MatchId;
+    readonly gameId: GameId;
+    /** Current match state. Plugins MUST treat it as readonly. */
+    readonly state: MatchState;
+    /** Wall-clock ms (host clock or harness clock — plugin should not care). */
+    readonly now: number;
+}
+/**
+ * Optional lifecycle callbacks. Each returns a Promise; rejections are
+ * logged and swallowed by the match handler.
+ */
+export interface NakamaPlatformPlugin {
+    /** Optional human-friendly name surfaced in error logs. */
+    readonly name?: string;
+    onMatchCreated?(ctx: PluginContext): Promise<void>;
+    onMatchStarted?(ctx: PluginContext): Promise<void>;
+    onMatchEnded?(ctx: PluginContext, result: GameResult): Promise<void>;
+    onPlayerJoined?(ctx: PluginContext, presence: NkPresence): Promise<void>;
+    onPlayerLeft?(ctx: PluginContext, presence: NkPresence): Promise<void>;
+    onPlayerAction?(ctx: PluginContext, input: ActionInput, transition: StateTransition): Promise<void>;
+    onStateTransition?(ctx: PluginContext, transition: StateTransition): Promise<void>;
+}
+/**
+ * Invoke a plugin hook fire-and-forget. Errors are caught and logged via
+ * `logger.error`; never propagated to the match loop.
+ *
+ * `hookName` and `pluginName` are interpolated into the error log so
+ * operators can correlate failures.
+ */
+export declare function invokePluginHook(logger: NkLogger, pluginName: string, hookName: string, fn: () => Promise<void> | void): void;
+/**
+ * Iterate plugins and invoke a single hook on each, fire-and-forget.
+ * Plugins that do not implement the hook are skipped.
+ */
+export declare function dispatchPluginHook<H extends keyof NakamaPlatformPlugin>(plugins: ReadonlyArray<NakamaPlatformPlugin> | undefined, logger: NkLogger, hookName: H, invoke: (plugin: NakamaPlatformPlugin) => Promise<void> | void): void;

package/dist/register-plugin.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview GamePlugin → GameRegistry entry. One path for every game,
+ * including generated multi-game init bundles.
+ */
+import { type GamePlugin } from '@table-games-engine/core';
+import type { GameRegistry, RegisteredGame } from './registry.js';
+export declare function registerPlugin(registry: GameRegistry, plugin: GamePlugin): RegisteredGame;

package/dist/registry.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview In-process registry mapping `GameId` to its manifest, action
+ * handlers, optional win-condition checker, and setup function.
+ *
+ * NOTE: `@table-games-engine/core` already exposes a `GameRegistry` *interface*
+ * for plugin-shape registration. This adapter ships its own concrete
+ * registry tuned for the Nakama match handler — it stores the precise
+ * fields `matchInit` will need, keyed by raw `gameId` string for cheap
+ * lookup. We deliberately re-use the term "GameRegistry" but in this
+ * package's namespace.
+ */
+import type { ActionHandler, ActionTypeId, GameId, GameManifest, GamePlugin, JsonObject, MatchId, MatchState, PlayerId, StateBasedActionChecker, WinConditionChecker } from '@table-games-engine/core';
+/**
+ * Setup callback that builds the initial `MatchState` for a new match.
+ *
+ * Implementations are pure (no I/O); they may consult `ctx` for things like
+ * a deterministic clock or RNG seed and `config` for game-instance options.
+ */
+export type GameSetup = (matchId: MatchId, playerIds: ReadonlyArray<PlayerId>, config: JsonObject, ctx: {
+    readonly now: number;
+}) => MatchState;
+/**
+ * Arguments accepted by `GameRegistry.register`.
+ */
+export interface RegisterArgs {
+    readonly gameId: GameId;
+    readonly manifest: GameManifest;
+    readonly handlers: Readonly<Record<ActionTypeId, ActionHandler>>;
+    readonly setup: GameSetup;
+    readonly winChecker?: WinConditionChecker;
+    readonly stateBasedActions?: StateBasedActionChecker;
+    readonly legalMoves?: GamePlugin['legalMoves'];
+}
+/**
+ * The shape returned from `resolve` — a frozen view of what `register` was
+ * called with. Mutations on the returned object do not affect the registry.
+ */
+export interface RegisteredGame {
+    readonly gameId: GameId;
+    readonly manifest: GameManifest;
+    readonly handlers: Readonly<Record<ActionTypeId, ActionHandler>>;
+    readonly setup: GameSetup;
+    readonly winChecker?: WinConditionChecker;
+    readonly stateBasedActions?: StateBasedActionChecker;
+    readonly legalMoves?: GamePlugin['legalMoves'];
+}
+/**
+ * Error thrown when registration is rejected (e.g. duplicate `gameId`).
+ *
+ * We use a plain `Error` subclass — the registry is a synchronous
+ * developer-facing surface and throwing is the most ergonomic signal.
+ */
+export declare class RegistryError extends Error {
+    readonly code: 'duplicate' | 'not-found';
+    constructor(code: 'duplicate' | 'not-found', message: string);
+}
+/**
+ * In-process map-backed game registry. Synchronous; not thread-safe — but
+ * Node's match handler runs single-threaded per match, so callers wire
+ * registration once at module init and resolve at `matchInit`.
+ */
+export declare class GameRegistry {
+    private readonly entries;
+    constructor();
+    /**
+     * Register a game. Throws `RegistryError('duplicate')` if `gameId` is
+     * already registered.
+     */
+    register(args: RegisterArgs): RegisteredGame;
+    /**
+     * Look up a registered game. Returns `null` (not undefined) when not
+     * found, to make call sites read more naturally.
+     */
+    resolve(gameId: GameId): RegisteredGame | null;
+    /**
+     * Remove a game from the registry. Returns `true` if a game was actually
+     * removed; `false` if `gameId` was not registered.
+     */
+    unregister(gameId: GameId): boolean;
+    /** Number of registered games. Mostly useful in tests. */
+    get size(): number;
+    /** List of registered game IDs (snapshot copy). */
+    list(): GameId[];
+}

package/dist/serialization.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview JSON wire-format envelopes for the Nakama adapter.
+ *
+ * The wire format is a strict, discriminated-union JSON envelope keyed by
+ * `kind`. The adapter never throws on bad input: `parseInbound` always
+ * returns a value (using a special `'malformed'` envelope to surface errors
+ * uniformly).
+ *
+ * Inbound envelopes (client -> server):
+ *   - 'action'          a normal action with payload + targets
+ *   - 'pass'            pass priority
+ *   - 'concede'         forfeit the match
+ *   - 'choose-targets'  fill in targets for a pending frame
+ *   - 'order-triggers'  resolve simultaneous-trigger ordering
+ *   - 'admin-pause'     control plane: pause the match
+ *   - 'admin-resume'    control plane: resume the match
+ *
+ * Outbound envelopes (server -> client):
+ *   - 'state'           full filtered `PlayerView` snapshot
+ *   - 'transition'      incremental `StateTransition` delta
+ *   - 'ack'             per-action acknowledgement (carries error if any)
+ *   - 'broadcast'       broadcast event (e.g. PlayerJoined)
+ *   - 'match-ended'     terminal `GameResult` payload
+ *
+ * Note: `clientId` and `stateVersion` are *only* attached to inbound action
+ * envelopes (they're the engine's idempotency + staleness keys). The other
+ * inbound kinds carry only the data the engine needs.
+ */
+import type { ActionInputAction, ActionInputChooseTargets, ActionInputOrderTriggers, GameResult, LegalMove, StateTransition } from '@table-games-engine/core';
+import type { PlayerView } from '@table-games-engine/core';
+/**
+ * Action envelope — the workhorse client message. Carries the full
+ * `ActionInputAction` payload plus the engine's idempotency key
+ * (`clientId`) and the client's last-seen `stateVersion`.
+ */
+export interface InboundAction {
+    readonly kind: 'action';
+    readonly clientId: string;
+    readonly stateVersion: number;
+    readonly action: ActionInputAction;
+}
+/** Pass priority. */
+export interface InboundPass {
+    readonly kind: 'pass';
+    readonly clientId: string;
+    readonly stateVersion: number;
+}
+/** Forfeit the match. */
+export interface InboundConcede {
+    readonly kind: 'concede';
+    readonly clientId: string;
+    readonly stateVersion: number;
+}
+/** Fill in targets for a pending frame. */
+export interface InboundChooseTargets {
+    readonly kind: 'choose-targets';
+    readonly clientId: string;
+    readonly stateVersion: number;
+    readonly action: ActionInputChooseTargets;
+}
+/** Order simultaneous triggers (APNAP). */
+export interface InboundOrderTriggers {
+    readonly kind: 'order-triggers';
+    readonly clientId: string;
+    readonly stateVersion: number;
+    readonly action: ActionInputOrderTriggers;
+}
+/** Admin: pause the match. */
+export interface InboundAdminPause {
+    readonly kind: 'admin-pause';
+    readonly clientId: string;
+    readonly reason?: string;
+}
+/** Admin: resume the match. */
+export interface InboundAdminResume {
+    readonly kind: 'admin-resume';
+    readonly clientId: string;
+}
+/**
+ * Sentinel returned by `parseInbound` when the input could not be parsed
+ * into a valid envelope. Carries a structured reason so the dispatcher
+ * can surface a typed `ack` to the client.
+ */
+export interface InboundMalformed {
+    readonly kind: 'malformed';
+    readonly reason: 'invalid-json' | 'not-object' | 'missing-kind' | 'unknown-kind' | 'invalid-fields';
+    readonly detail?: string;
+}
+export type InboundEnvelope = InboundAction | InboundPass | InboundConcede | InboundChooseTargets | InboundOrderTriggers | InboundAdminPause | InboundAdminResume;
+/** Full per-player filtered snapshot. */
+export interface OutboundState {
+    readonly kind: 'state';
+    readonly view: PlayerView;
+    readonly version: number;
+    readonly legalMoves?: ReadonlyArray<LegalMove>;
+}
+/** Incremental state delta. */
+export interface OutboundTransition {
+    readonly kind: 'transition';
+    readonly delta: StateTransition;
+}
+/** Per-action acknowledgement; idempotency cache replays this verbatim. */
+export interface OutboundAck {
+    readonly kind: 'ack';
+    readonly clientId: string;
+    readonly ok: boolean;
+    readonly error?: {
+        code: string;
+        message: string;
+    };
+}
+/** Broadcast event (e.g. PlayerJoined). */
+export interface OutboundBroadcast {
+    readonly kind: 'broadcast';
+    readonly event: {
+        type: string;
+        [key: string]: unknown;
+    };
+}
+/** Terminal match-ended envelope. */
+export interface OutboundMatchEnded {
+    readonly kind: 'match-ended';
+    readonly result: GameResult;
+}
+export type OutboundEnvelope = OutboundState | OutboundTransition | OutboundAck | OutboundBroadcast | OutboundMatchEnded;
+/**
+ * Parse a JSON string into an `InboundEnvelope`. Never throws; surfaces
+ * parse / shape errors as a typed `InboundMalformed` value.
+ */
+export declare function parseInbound(json: string): InboundEnvelope | InboundMalformed;
+/**
+ * Serialize an outbound envelope to its JSON wire form. Pure function;
+ * never throws (envelopes are typed and assumed valid).
+ */
+export declare function serializeOutbound(env: OutboundEnvelope): string;

package/dist/timeouts.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Action timeout detector.
+ *
+ * If the priority holder has held priority for longer than `timeoutMs` (as
+ * measured by an injected `now` clock), `checkTimeouts` produces a synthetic
+ * `timeout` `ActionInput` the match handler can feed straight into
+ * `engine.applyAction`. The engine treats `timeout` like a concede — the
+ * player is eliminated and turn order advances.
+ *
+ * Pure: no I/O, no clock access, no global state. The match-handler's
+ * matchLoop owns "when did the holder last take priority" tracking and
+ * passes it in via `priorityHeldSince`.
+ */
+import type { ActionInput, MatchState } from '@table-games-engine/core';
+export interface TimeoutOptions {
+    /** Window in milliseconds before a holder times out. */
+    readonly timeoutMs: number;
+}
+/**
+ * Decide whether the current priority holder should be timed out.
+ *
+ * Returns `null` when:
+ *   - there is no priority holder (system is in an automatic phase),
+ *   - the holder has not yet held priority for `timeoutMs`,
+ *   - `priorityHeldSince` is `null` (we haven't observed a holder yet).
+ *
+ * Returns a synthetic `ActionInput` of type `timeout` otherwise. The
+ * `clientId` is derived from the current state version so retries hit the
+ * same idempotency cache key, and the `stateVersion` is the engine's
+ * current version (the engine will reject stale inputs naturally if any
+ * other action squeezed through first).
+ */
+export declare function checkTimeouts(state: MatchState, now: number, timeoutMs: number, priorityHeldSince: number | null): ActionInput | null;

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Minimal `nkruntime`-shaped types for the Nakama adapter.
+ *
+ * The real `nkruntime` types ship with the Nakama TypeScript runtime, but
+ * this package builds standalone — we only need the shapes we actually call,
+ * and we want unit tests to exercise the adapter without a Nakama install.
+ *
+ * Anything in this file is intentionally a structural subset of the real API.
+ * If we later depend on the real `nkruntime`, swap these out for re-exports.
+ */
+/**
+ * Subset of `nkruntime.Logger`.
+ *
+ * Nakama exposes additional levels (`debug`, `fatal`); we only need
+ * info/warn/error for the adapter and harness today.
+ */
+export interface NkLogger {
+    info(format: string, ...args: unknown[]): void;
+    warn(format: string, ...args: unknown[]): void;
+    error(format: string, ...args: unknown[]): void;
+}
+/**
+ * Subset of `nkruntime.Presence` — identifies a connected player session.
+ */
+export interface NkPresence {
+    /** Stable user identifier (Nakama user_id). */
+    readonly userId: string;
+    /** Per-connection session identifier. */
+    readonly sessionId: string;
+    /** Display name; optional. */
+    readonly username?: string;
+    /** Status payload supplied at connect time. */
+    readonly status?: string;
+    /** Node hosting this presence (for cluster routing). Optional. */
+    readonly node?: string;
+}
+/**
+ * Subset of `nkruntime.MatchData` — a single inbound message in the loop.
+ */
+export interface NkMatchData {
+    /** Nakama opcode used to multiplex message kinds. */
+    readonly opCode: number;
+    /** Raw bytes (UTF-8 JSON in this adapter's wire format). */
+    readonly data: Uint8Array;
+    /** The presence that sent the message. */
+    readonly sender: NkPresence;
+    /** Whether the message is reliable. */
+    readonly reliable?: boolean;
+}
+/**
+ * Subset of `nkruntime.MatchDispatcher` used by the adapter to broadcast
+ * messages and request a match termination.
+ */
+export interface NkMatchDispatcher {
+    /**
+     * Send a message to one or more presences. If `presences` is undefined,
+     * Nakama broadcasts to every joined presence.
+     */
+    broadcastMessage(opCode: number, data: string | Uint8Array | null, presences?: NkPresence[] | null, sender?: NkPresence | null, reliable?: boolean): void;
+    /**
+     * Optional: request the match terminate after `graceSeconds`.
+     */
+    matchKick?(presences: NkPresence[]): void;
+}
+/**
+ * Generic match-state container Nakama threads through the loop.
+ * The adapter stores its `MatchHandlerState` here.
+ */
+export interface NkMatchState<T = unknown> {
+    readonly state: T;
+}
+/**
+ * Subset of the Nakama `MatchHandler<T>` shape. Phase A only declares this
+ * interface so callers can name the type — we wire the actual handler in
+ * Phase B.
+ */
+export interface NkMatchHandler<T = unknown> {
+    matchInit(ctx: unknown, logger: NkLogger, nk: unknown, params: {
+        [key: string]: string;
+    }): {
+        state: T;
+        tickRate: number;
+        label: string;
+    };
+    matchJoinAttempt(ctx: unknown, logger: NkLogger, nk: unknown, dispatcher: NkMatchDispatcher, tick: number, state: T, presence: NkPresence, metadata: {
+        [key: string]: unknown;
+    }): {
+        state: T;
+        accept: boolean;
+        rejectMessage?: string;
+    } | null;
+    matchJoin(ctx: unknown, logger: NkLogger, nk: unknown, dispatcher: NkMatchDispatcher, tick: number, state: T, presences: NkPresence[]): {
+        state: T;
+    } | null;
+    matchLeave(ctx: unknown, logger: NkLogger, nk: unknown, dispatcher: NkMatchDispatcher, tick: number, state: T, presences: NkPresence[]): {
+        state: T;
+    } | null;
+    matchLoop(ctx: unknown, logger: NkLogger, nk: unknown, dispatcher: NkMatchDispatcher, tick: number, state: T, messages: NkMatchData[]): {
+        state: T;
+    } | null;
+    matchTerminate(ctx: unknown, logger: NkLogger, nk: unknown, dispatcher: NkMatchDispatcher, tick: number, state: T, graceSeconds: number): {
+        state: T;
+    } | null;
+    matchSignal(ctx: unknown, logger: NkLogger, nk: unknown, dispatcher: NkMatchDispatcher, tick: number, state: T, data: string): {
+        state: T;
+        data?: string;
+    } | null;
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@table-games-engine/nakama-adapter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --format=esm --platform=neutral --packages=external --external:@table-games-engine/* --outfile=dist/index.js && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@table-games-engine/core": "^0.1.0",
+    "@table-games-engine/persistence": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "FSL-1.1-ALv2"
+}