@tableverse/contracts 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- `GameSessionContext`, `CurrentUser`, `SessionPlayer` types describing the
+  session payload passed by the shell into the game.
+- `GameFinishedEvent` discriminated union (`GameFinishedWin`,
+  `GameFinishedDraw`, `GameFinishedAborted`) for the `'finished'` CustomEvent.
+- `PlatformBridge` interface and `Window.__PLATFORM__` global augmentation.
+  Subscription methods return an unsubscribe function.
+- `CONTRACT_VERSION` constant kept in sync with `package.json` via
+  `scripts/sync-version.cjs`.
+- ESM build pipeline, ESLint flat config, compile-time type tests,
+  and CI/publish GitHub Actions workflows.

package/README.md

@@ -0,0 +1,92 @@
+# @tableverse/contracts
+
+[English](./README.md) | [Українська](./README.uk.md)
+
+TypeScript contracts shared between the Table Verse shell and games. The package
+contains only **types and constants** — no runtime logic, no DOM access, no
+side effects.
+
+## Install
+
+```bash
+npm install --save-dev @tableverse/contracts
+```
+
+The package is intended as a `devDependency`. Games are shipped as
+self-contained bundles, so consumers should not bundle these types into their
+runtime output.
+
+## Usage
+
+```ts
+import type {
+	GameSessionContext,
+	GameFinishedEvent,
+	PlatformBridge,
+} from '@tableverse/contracts';
+import { CONTRACT_VERSION } from '@tableverse/contracts';
+```
+
+### Custom Element wiring (game side)
+
+```ts
+class MyGame extends HTMLElement {
+	static readonly observedAttributes = ['data-contract-version'];
+
+	set sessionContext(ctx: GameSessionContext) {
+		// store and use ctx
+	}
+
+	private finish(event: GameFinishedEvent) {
+		this.dispatchEvent(new CustomEvent('finished', { detail: event }));
+	}
+}
+
+customElements.define('my-game', MyGame);
+```
+
+The game advertises the contract version it was built against:
+
+```html
+<my-game data-contract-version="0.0.0"></my-game>
+```
+
+### Reading the platform bridge
+
+```ts
+const token = window.__PLATFORM__.getToken();
+
+const unsubscribe = window.__PLATFORM__.onTokenChange((newToken) => {
+	// reconnect with the fresh token
+});
+// later: unsubscribe();
+```
+
+## Exports
+
+| Export                | Kind      | Description                                        |
+| --------------------- | --------- | -------------------------------------------------- |
+| `GameSessionContext`  | interface | Session payload passed by the shell into the game. |
+| `CurrentUser`         | interface | The user playing on this client.                   |
+| `SessionPlayer`       | interface | A single player in the session.                    |
+| `GameFinishedEvent`   | union     | Discriminated union for the `'finished'` event.    |
+| `GameFinishedWin`     | interface | Variant: someone won.                              |
+| `GameFinishedDraw`    | interface | Variant: draw.                                     |
+| `GameFinishedAborted` | interface | Variant: game was aborted.                         |
+| `PlatformBridge`      | interface | `window.__PLATFORM__` shape.                       |
+| `CONTRACT_VERSION`    | constant  | Current contract version (semver string).          |
+
+## Versioning
+
+The package follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** — breaking change in any exported type.
+- **MINOR** — additive change (new optional field, new variant in a union).
+- **PATCH** — documentation, refactor, no public API change.
+
+The shell verifies major-version compatibility against
+`data-contract-version` before mounting a game.
+
+## License
+
+MIT

package/README.uk.md

@@ -0,0 +1,91 @@
+# @tableverse/contracts
+
+[English](./README.md) | [Українська](./README.uk.md)
+
+TypeScript-контракти, спільні між shell-ом Table Verse та іграми. Пакет містить
+**лише типи та константи** — жодної runtime-логіки, доступу до DOM чи
+сайд-ефектів.
+
+## Встановлення
+
+```bash
+npm install --save-dev @tableverse/contracts
+```
+
+Пакет призначений як `devDependency`. Ігри постачаються самодостатніми бандлами,
+тому ці типи не повинні потрапляти в runtime-вивід.
+
+## Використання
+
+```ts
+import type {
+	GameSessionContext,
+	GameFinishedEvent,
+	PlatformBridge,
+} from '@tableverse/contracts';
+import { CONTRACT_VERSION } from '@tableverse/contracts';
+```
+
+### Інтеграція через Custom Element (на боці гри)
+
+```ts
+class MyGame extends HTMLElement {
+	static readonly observedAttributes = ['data-contract-version'];
+
+	set sessionContext(ctx: GameSessionContext) {
+		// зберегти й використати ctx
+	}
+
+	private finish(event: GameFinishedEvent) {
+		this.dispatchEvent(new CustomEvent('finished', { detail: event }));
+	}
+}
+
+customElements.define('my-game', MyGame);
+```
+
+Гра оголошує версію контракту, проти якої її зібрали:
+
+```html
+<my-game data-contract-version="0.0.0"></my-game>
+```
+
+### Робота з platform bridge
+
+```ts
+const token = window.__PLATFORM__.getToken();
+
+const unsubscribe = window.__PLATFORM__.onTokenChange((newToken) => {
+	// перепідключити WebSocket із новим токеном
+});
+// пізніше: unsubscribe();
+```
+
+## Експорти
+
+| Експорт               | Тип       | Опис                                                  |
+| --------------------- | --------- | ----------------------------------------------------- |
+| `GameSessionContext`  | interface | Контекст сесії, який shell передає у гру.             |
+| `CurrentUser`         | interface | Користувач, який грає на цьому клієнті.               |
+| `SessionPlayer`       | interface | Один гравець у сесії.                                 |
+| `GameFinishedEvent`   | union     | Discriminated union для події `'finished'`.           |
+| `GameFinishedWin`     | interface | Варіант: хтось переміг.                               |
+| `GameFinishedDraw`    | interface | Варіант: нічия.                                       |
+| `GameFinishedAborted` | interface | Варіант: гру перервано.                               |
+| `PlatformBridge`      | interface | Форма `window.__PLATFORM__`.                          |
+| `CONTRACT_VERSION`    | constant  | Поточна версія контракту (semver-рядок).              |
+
+## Версіонування
+
+Пакет дотримується [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** — breaking-зміна в будь-якому експортованому типі.
+- **MINOR** — additive-зміна (нове необов'язкове поле, новий варіант у union).
+- **PATCH** — документація, рефакторинг, без зміни публічного API.
+
+Shell перевіряє сумісність за major-версією через атрибут
+`data-contract-version` перед монтуванням гри.
+
+## Ліцензія
+
+MIT

package/dist/events.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Game-finished event the game emits via a CustomEvent named `'finished'`.
+ *
+ * Discriminated union keyed on the `kind` field. Consumers should handle every
+ * variant via an exhaustive switch so that adding a new variant is caught at
+ * compile time.
+ */
+export type GameFinishedEvent = GameFinishedWin | GameFinishedDraw | GameFinishedAborted;
+/**
+ * Game ended with a winner.
+ */
+export interface GameFinishedWin {
+    readonly kind: 'win';
+    /** Identifier of the winning player. */
+    readonly winnerId: string;
+    /** Final scores keyed by player id. */
+    readonly scores: Readonly<Record<string, number>>;
+}
+/**
+ * Game ended in a draw.
+ */
+export interface GameFinishedDraw {
+    readonly kind: 'draw';
+    /** Final scores keyed by player id. */
+    readonly scores: Readonly<Record<string, number>>;
+}
+/**
+ * Game was aborted before reaching a normal terminal state
+ * (e.g. a player left, network failure, server shutdown).
+ */
+export interface GameFinishedAborted {
+    readonly kind: 'aborted';
+    /** Human-readable reason describing why the game was aborted. */
+    readonly reason: string;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAC1B,eAAe,GACf,gBAAgB,GAChB,mBAAmB,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB"}

package/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './session';
+export * from './events';
+export * from './platform-bridge';
+export * from './version';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './session';
+export * from './events';
+export * from './platform-bridge';
+export * from './version';

package/dist/platform-bridge.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Global bridge for cross-cutting platform services (e.g. authentication)
+ * exposed by the shell. Available inside the game via `window.__PLATFORM__`.
+ *
+ * The game does not store the auth token itself. Each request calls
+ * {@link PlatformBridge.getToken} to obtain the freshest value, and subscribes
+ * to {@link PlatformBridge.onTokenChange} for proactive updates.
+ */
+export interface PlatformBridge {
+    /**
+     * Returns the current JWT token. The shell is responsible for refreshing
+     * the token before expiry, so the value returned here is always fresh.
+     */
+    getToken(): string;
+    /**
+     * Subscribes to token updates (e.g. to reconnect a WebSocket with the new
+     * token). Returns an unsubscribe function.
+     */
+    onTokenChange(callback: (newToken: string) => void): () => void;
+    /**
+     * Subscribes to logout events. The game must close its WebSocket and
+     * emit a `leave` event when this fires. Returns an unsubscribe function.
+     */
+    onLogout(callback: () => void): () => void;
+}
+declare global {
+    interface Window {
+        /**
+         * Platform bridge installed by the shell before any game is mounted.
+         * Always present in production; games may assume it is non-null.
+         */
+        readonly __PLATFORM__: PlatformBridge;
+    }
+}
+//# sourceMappingURL=platform-bridge.d.ts.map

package/dist/platform-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-bridge.d.ts","sourceRoot":"","sources":["../src/platform-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC9B;;;OAGG;IACH,QAAQ,IAAI,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEhE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3C;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf;;;WAGG;QACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;KACtC;CACD"}

package/dist/platform-bridge.js

@@ -0,0 +1 @@
+export {};

package/dist/session.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Game session context that the shell passes into the game via the property
+ * setter on its Custom Element. The game uses this object as the single source
+ * of truth about the current session.
+ */
+export interface GameSessionContext {
+    /** Unique session identifier the game uses when calling the Game Server. */
+    readonly sessionId: string;
+    /** WebSocket URL of the Game Server for real-time communication. */
+    readonly serverUrl: string;
+    /** Current user locale (BCP 47 code, e.g. 'uk', 'en'). */
+    readonly locale: string;
+    /** The current user — the one playing on this client. */
+    readonly currentUser: CurrentUser;
+    /** All players in the session, including the current user. */
+    readonly players: ReadonlyArray<SessionPlayer>;
+}
+/**
+ * The current user (the one viewing the game in the browser).
+ */
+export interface CurrentUser {
+    /** Stable user identifier issued by the platform. */
+    readonly id: string;
+    /** Display name shown in the UI. */
+    readonly displayName: string;
+}
+/**
+ * Information about a single player participating in the session.
+ */
+export interface SessionPlayer {
+    /** Stable user identifier issued by the platform. */
+    readonly userId: string;
+    /** Display name shown in the UI. */
+    readonly displayName: string;
+    /** Avatar image URL, or `null` if the player has no avatar. */
+    readonly avatarUrl: string | null;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,oCAAoC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,oCAAoC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC"}

package/dist/session.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Contract version. MUST stay in sync with the `version` field of
+ * `package.json` — this is enforced by `scripts/sync-version.cjs` via the
+ * `npm version` hook.
+ *
+ * The game exports this constant as the `data-contract-version` attribute on
+ * its Custom Element, and the shell verifies major-version compatibility
+ * before mounting the game.
+ */
+export declare const CONTRACT_VERSION = "0.0.1";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,10 @@
+/**
+ * Contract version. MUST stay in sync with the `version` field of
+ * `package.json` — this is enforced by `scripts/sync-version.cjs` via the
+ * `npm version` hook.
+ *
+ * The game exports this constant as the `data-contract-version` attribute on
+ * its Custom Element, and the shell verifies major-version compatibility
+ * before mounting the game.
+ */
+export const CONTRACT_VERSION = '0.0.1';

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@tableverse/contracts",
+	"version": "0.0.1",
+	"description": "TypeScript contracts for the Table Verse game platform",
+	"type": "module",
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md",
+		"README.uk.md",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"lint": "eslint src --ext .ts",
+		"test": "tsc -p tests/tsconfig.json --noEmit",
+		"version": "node scripts/sync-version.cjs && git add src/version.ts",
+		"prepublishOnly": "npm run lint && npm run test && npm run build"
+	},
+	"keywords": [
+		"contracts",
+		"types",
+		"platform",
+		"tableverse"
+	],
+	"author": "Table Verse",
+	"license": "MIT",
+	"devDependencies": {
+		"@types/node": "^25.6.0",
+		"@typescript-eslint/eslint-plugin": "^8.0.0",
+		"@typescript-eslint/parser": "^8.0.0",
+		"eslint": "^10.0.0",
+		"typescript": "^6.0.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/TableVerse/contracts.git"
+	},
+	"engines": {
+		"node": ">=20"
+	}
+}