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

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Dmitry Kucher
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @table-games-engine/nakama-adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Nakama runtime bindings for `@table-games-engine/core`: wraps the engine (and `@table-games-engine/persistence`) in a Nakama TypeScript-runtime match handler so players can connect over WebSocket and play your game.
+
+Most game authors don't install this directly: it comes with [`@table-games-engine/game-kit`](https://www.npmjs.com/package/@table-games-engine/game-kit), whose `preview` command and the [Logigra](https://logigra.ru) store host your game for you. Install it to run your own Nakama server.
+
+## Install
+
+```sh
+npm install @table-games-engine/nakama-adapter
+```
+
+## What you get
+
+- `createMatchHandler(opts)` returns a Nakama `MatchHandler` implementing `matchInit`, `matchJoinAttempt`, `matchJoin`, `matchLeave`, `matchLoop`, `matchSignal` and `matchTerminate`.
+- `GameRegistry` resolves `gameId` to `{ manifest, handlers, setup }` at `matchInit`, so one runtime can host many games (`registerPlugin` registers a `GamePlugin`).
+- `IdempotencyCache` absorbs client retries.
+- JSON wire format (`parseInbound`, `serializeOutbound`, `OPCODES`), per-player filtered broadcasts (`broadcastViews`), action timeouts (`checkTimeouts`), reconnection-aware joins.
+- Persistence wiring: events are appended per transition and snapshots follow a `SnapshotPolicy`.
+- `NakamaPlatformPlugin` hooks for analytics, audit and similar.
+
+## Wiring into Nakama
+
+```ts
+import { createMatchHandler, registerPlugin, GameRegistry, IdempotencyCache } from '@table-games-engine/nakama-adapter';
+import { SqliteAdapter, everyNTransitions } from '@table-games-engine/persistence';
+
+const registry = new GameRegistry();
+registerPlugin(registry, myGamePlugin);   // a GamePlugin; or registry.register({ gameId, manifest, handlers, setup }) by hand
+
+const handler = createMatchHandler({
+  registry,
+  idempotencyCache: new IdempotencyCache(),
+  adapter: new SqliteAdapter('/data/engine.db'),
+  policy: everyNTransitions(50),
+  ownerNode: 'node-A',
+  leaseSeconds: 60,
+  timeout: { timeoutMs: 30_000 },
+  plugins: [],
+});
+
+function InitModule(_ctx: nkruntime.Context, logger: nkruntime.Logger, _nk: nkruntime.Nakama, initializer: nkruntime.Initializer): void {
+  initializer.registerMatch('tabletop_match', handler);
+}
+```
+
+Create a match from your own server code:
+
+```ts
+nk.matchCreate('tabletop_match', {
+  gameId: 'my-game',
+  playerIds: 'alice,bob',                 // comma-separated; passed to setup()
+  config: JSON.stringify({ /* game options */ }),
+});
+```
+
+The adapter reads no environment variables; plumb configuration into the options yourself.
+
+## Persistence and reconnection
+
+With `adapter` set, `matchInit` stores snapshot v0 (and takes an ownership lease if `ownerNode` is set), each transition appends its events and may snapshot, and `matchTerminate` releases the lease without closing the adapter. When the same user rejoins with a new session, the handler swaps the presence, sends a fresh filtered state to that player only, and keeps the idempotency cache.
+
+## Plugins
+
+```ts
+import type { NakamaPlatformPlugin } from '@table-games-engine/nakama-adapter';
+
+const audit: NakamaPlatformPlugin = {
+  name: 'audit',
+  async onMatchEnded(ctx, result) { /* ... */ },
+};
+```
+
+Hooks: `onMatchCreated`, `onMatchStarted`, `onPlayerJoined`, `onPlayerLeft`, `onPlayerAction`, `onStateTransition`, `onMatchEnded`. All are optional and async. They are fire-and-forget: the match loop never waits for them, and a failing plugin is logged but never crashes the match.
+
+## Licence
+
+FSL-1.1-ALv2 (Functional Source License, converts to Apache-2.0 after two years). See `LICENSE.md` in the package.

package/dist/broadcast.d.ts

@@ -0,0 +1,27 @@
+import type { GameManifest, LegalMove, MatchState, PlayerId } from '@table-games-engine/core';
+import type { NkMatchDispatcher, NkPresence } from './types.js';
+/**
+ * Opcode allocation for the adapter.
+ *
+ *   STATE_UPDATE = 1   per-player full snapshot (`OutboundState`)
+ *   ACK          = 2   per-action acknowledgement (`OutboundAck`)
+ *   BROADCAST    = 3   broadcast events (`OutboundBroadcast`)
+ *   MATCH_ENDED  = 4   terminal `match-ended`
+ *   TRANSITION   = 5   incremental transition deltas (future use)
+ */
+export declare const OPCODES: {
+    readonly STATE_UPDATE: 1;
+    readonly ACK: 2;
+    readonly BROADCAST: 3;
+    readonly MATCH_ENDED: 4;
+    readonly TRANSITION: 5;
+};
+export type Opcode = (typeof OPCODES)[keyof typeof OPCODES];
+/**
+ * Compute and dispatch a filtered `state-update` envelope to each presence.
+ *
+ * Players whose `userId` is not registered as a `PlayerId` in `state.players`
+ * are skipped — they may be observers (Phase B doesn't model them) and we
+ * never broadcast a `PlayerView` for an unknown viewer.
+ */
+export declare function broadcastViews(state: MatchState, manifest: GameManifest, dispatcher: NkMatchDispatcher, presences: ReadonlyArray<NkPresence>, legalMovesFor?: (playerId: PlayerId) => ReadonlyArray<LegalMove>): void;

package/dist/idempotency.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Per-match idempotency cache: when a client retries a message
+ * with the same `clientId`, the adapter should replay the original outbound
+ * response instead of executing the action twice.
+ *
+ * Cache layout:
+ *   matchId -> Map<clientId, { response: OutboundEnvelope; expiresAt }>
+ *
+ * Entries expire after `ttlMs` (default 5 min). The clock is injectable for
+ * deterministic tests. Pruning runs on every `get` / `set` for the affected
+ * match — it stays cheap because each match's map is small (one entry per
+ * recent action) and we only walk one match at a time.
+ */
+import type { OutboundEnvelope } from './serialization.js';
+/** A single cache entry. */
+export interface IdempotencyEntry {
+    readonly response: OutboundEnvelope;
+    readonly expiresAt: number;
+}
+/** Constructor options for `IdempotencyCache`. */
+export interface IdempotencyCacheOptions {
+    /** Entry lifetime in milliseconds. Defaults to 5 minutes. */
+    readonly ttlMs?: number;
+    /** Clock source (ms epoch). Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare class IdempotencyCache {
+    private readonly buckets;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options?: IdempotencyCacheOptions);
+    /**
+     * Look up a cached response. Prunes expired entries for the match as a
+     * side effect, so a stale entry is never returned.
+     */
+    get(matchId: string, clientId: string): OutboundEnvelope | null;
+    /**
+     * Cache `response` under `(matchId, clientId)` with TTL. Replaces any
+     * existing entry for the same key.
+     */
+    set(matchId: string, clientId: string, response: OutboundEnvelope): void;
+    /**
+     * Drop the entire bucket for `matchId`. Use when a match terminates so
+     * we don't hold the response payloads in memory.
+     */
+    clear(matchId: string): void;
+    /**
+     * Walk every bucket and drop expired entries. Empty buckets are removed.
+     */
+    prune(): void;
+    /** Total number of live entries across all buckets. Test-only helper. */
+    get size(): number;
+    private pruneBucket;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Public barrel for `@table-games-engine/nakama-adapter`.
+ *
+ * This package wraps the pure `EngineOperations` from `@table-games-engine/core`
+ * (and the persistence layer from `@table-games-engine/persistence`) behind a
+ * Nakama match handler so that multiple players can connect via WebSocket.
+ */
+export type { NkLogger, NkPresence, NkMatchData, NkMatchDispatcher, NkMatchState, NkMatchHandler, } from './types.js';
+export { parseInbound, serializeOutbound, } from './serialization.js';
+export type { InboundEnvelope, OutboundEnvelope, InboundAction, InboundPass, InboundConcede, InboundChooseTargets, InboundOrderTriggers, InboundAdminPause, InboundAdminResume, InboundMalformed, OutboundState, OutboundTransition, OutboundAck, OutboundBroadcast, OutboundMatchEnded, } from './serialization.js';
+export { GameRegistry, RegistryError } from './registry.js';
+export { registerPlugin } from './register-plugin.js';
+export type { RegisteredGame, RegisterArgs, GameSetup, } from './registry.js';
+export { IdempotencyCache } from './idempotency.js';
+export type { IdempotencyEntry, IdempotencyCacheOptions, } from './idempotency.js';
+export { createMatchHandler } from './match-handler.js';
+export type { MatchStatus, NkMatchInternalState, CreateMatchHandlerOptions, } from './match-handler.js';
+export { broadcastViews, OPCODES } from './broadcast.js';
+export type { Opcode } from './broadcast.js';
+export { checkTimeouts } from './timeouts.js';
+export type { TimeoutOptions } from './timeouts.js';
+export { createPersistenceBridge } from './persistence-bridge.js';
+export type { PersistenceBridge, CreatePersistenceBridgeArgs, } from './persistence-bridge.js';
+export { invokePluginHook, dispatchPluginHook, } from './plugins.js';
+export type { NakamaPlatformPlugin, PluginContext, } from './plugins.js';