hyperchess-store 0.1.0

package/dist/adapters/supabase.js

@@ -0,0 +1,328 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-store
+// File: packages/store/src/adapters/supabase.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { GameNotFoundError } from '../types/game-record';
+/**
+ * Supabase adapter - PostgreSQL + Realtime + Auth
+ * Requires: npm install @supabase/supabase-js
+ *
+ * Features:
+ * - Realtime subscriptions via postgres_changes
+ * - Row Level Security aware (games scoped to authenticated user)
+ * - Range-based pagination
+ *
+ * Schema assumption: a `public.games` table exposed through PostgREST with
+ * columns `id` (primary key), `hpgn`, `hfen`, `players`, `metadata`, `result`,
+ * `user_id`, `synced`, `created_at`, `updated_at`. `players` and `metadata` are
+ * sent as objects and read back as objects, so those columns must be `json`/
+ * `jsonb` — the opposite of the raw Postgres adapter, which round-trips them as
+ * JSON strings.
+ *
+ * Because every call goes through PostgREST, Row Level Security applies: what a
+ * query returns depends on the key the client was built with. Under RLS a
+ * "missing" row and a forbidden one are indistinguishable, so
+ * {@link GameNotFoundError} can also mean "not visible to you". Realtime
+ * subscriptions likewise require the `games` table to be in the realtime
+ * publication.
+ *
+ * Errors from the client are surfaced as plain `Error`s carrying the PostgREST
+ * message rather than being swallowed — only `isHealthy()` degrades quietly.
+ */
+export class SupabaseGameStore {
+    /**
+     * Create the underlying Supabase client.
+     *
+     * The key determines the store's effective permissions: an anon key leaves RLS
+     * in force (games scoped to the signed-in user), a service-role key bypasses
+     * it entirely and must never reach a browser.
+     *
+     * @param supabaseUrl - Project URL, e.g. `https://<ref>.supabase.co`.
+     * @param supabaseKey - Anon or service-role API key.
+     * @throws Error if the optional `@supabase/supabase-js` package is not
+     *   installed.
+     */
+    constructor(supabaseUrl, supabaseKey) {
+        this.channels = new Map();
+        try {
+            const { createClient } = require('@supabase/supabase-js');
+            this.client = createClient(supabaseUrl, supabaseKey);
+        }
+        catch (error) {
+            throw new Error('Supabase adapter requires "@supabase/supabase-js" package: npm install @supabase/supabase-js');
+        }
+    }
+    /**
+     * Upsert a game, conflicting on `id`, and read the stored row back.
+     *
+     * `updated_at` is always stamped with the current time; `created_at` falls
+     * back to now only when the record carries none, which means re-saving a
+     * record whose `createdAt` was dropped will rewrite the creation time.
+     *
+     * @param game - Record to persist; a missing `id` is generated locally.
+     * @returns The id reported by the returned row.
+     * @throws Error carrying the PostgREST message if the upsert is rejected —
+     *   including RLS denials.
+     */
+    async saveGame(game) {
+        const id = game.id || this.generateId();
+        const now = new Date().toISOString();
+        const { data, error } = await this.client
+            .from('games')
+            .upsert({
+            id,
+            hpgn: game.hpgn,
+            hfen: game.hfen,
+            players: game.players ?? null,
+            metadata: game.metadata ?? null,
+            result: game.result ?? null,
+            user_id: game.userId ?? null,
+            synced: game.synced ?? true,
+            created_at: game.createdAt || now,
+            updated_at: now,
+        }, { onConflict: 'id' })
+            .select()
+            .single();
+        if (error) {
+            throw new Error(`Supabase saveGame failed: ${error.message}`);
+        }
+        return data.id;
+    }
+    /**
+     * Fetch one row by id.
+     *
+     * Uses `maybeSingle()` so an absent row comes back as `null` data rather than
+     * a PostgREST error, letting the missing case be reported as a typed
+     * {@link GameNotFoundError}.
+     *
+     * @param id - Game id.
+     * @returns The row in {@link GameRecord} shape.
+     * @throws {@link GameNotFoundError} if no row is visible under `id`.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    async loadGame(id) {
+        const { data, error } = await this.client.from('games').select('*').eq('id', id).maybeSingle();
+        if (error) {
+            throw new Error(`Supabase loadGame failed: ${error.message}`);
+        }
+        if (!data) {
+            throw new GameNotFoundError(id);
+        }
+        return this.rowToRecord(data);
+    }
+    /**
+     * Delete a row, using the returned representation to prove it existed.
+     *
+     * The trailing `.select()` is what makes the not-found case detectable: a
+     * `DELETE` matching nothing is not an error to PostgREST, it simply returns an
+     * empty set.
+     *
+     * @param id - Game id.
+     * @throws {@link GameNotFoundError} if no row was deleted.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    async deleteGame(id) {
+        const { data, error } = await this.client.from('games').delete().eq('id', id).select();
+        if (error) {
+            throw new Error(`Supabase deleteGame failed: ${error.message}`);
+        }
+        if (!data || data.length === 0) {
+            throw new GameNotFoundError(id);
+        }
+    }
+    /**
+     * List games using PostgREST filters and range-based pagination.
+     *
+     * `range()` bounds are inclusive, so a page is expressed as
+     * `[offset, offset + limit - 1]`. An `offset` given without a `limit` falls
+     * back to a fixed 1000-row window, since PostgREST needs an upper bound.
+     *
+     * @param options - `userId`/`result` equality filters, `sort` direction
+     *   (default descending by `created_at`), `limit` and `offset`.
+     * @returns Matching rows in the requested order.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    async listGames(options) {
+        let q = this.client.from('games').select('*');
+        if (options?.userId)
+            q = q.eq('user_id', options.userId);
+        if (options?.result)
+            q = q.eq('result', options.result);
+        q = q.order('created_at', { ascending: options?.sort === 'asc' });
+        if (options?.limit !== undefined) {
+            const from = options?.offset ?? 0;
+            q = q.range(from, from + options.limit - 1);
+        }
+        else if (options?.offset) {
+            q = q.range(options.offset, options.offset + 999);
+        }
+        const { data, error } = await q;
+        if (error) {
+            throw new Error(`Supabase listGames failed: ${error.message}`);
+        }
+        return (data ?? []).map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Count matching rows without transferring them.
+     *
+     * `head: true` issues a `HEAD` request so only the count header comes back;
+     * `count: 'exact'` is accurate but does a full scan on large tables.
+     *
+     * @param options - Only `userId` and `result` are honoured.
+     * @returns Total number of matching rows, or 0 if the count header is absent.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    async countGames(options) {
+        let q = this.client.from('games').select('*', { count: 'exact', head: true });
+        if (options?.userId)
+            q = q.eq('user_id', options.userId);
+        if (options?.result)
+            q = q.eq('result', options.result);
+        const { count, error } = await q;
+        if (error) {
+            throw new Error(`Supabase countGames failed: ${error.message}`);
+        }
+        return count ?? 0;
+    }
+    /**
+     * Subscribe to a game over a Realtime `postgres_changes` channel.
+     *
+     * Listens for `UPDATE` events only — inserts and deletes are not delivered, so
+     * watching an id before it exists yields nothing until the first update after
+     * creation. Each id gets its own channel, tracked so `clear()` can tear them
+     * all down.
+     *
+     * @param id - Game id to observe.
+     * @param callback - Receives the new row from the change payload.
+     * @returns Unsubscribe handle that removes the channel.
+     */
+    watch(id, callback) {
+        const channelName = `games:${id}`;
+        const channel = this.client
+            .channel(channelName)
+            .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'games', filter: `id=eq.${id}` }, (payload) => callback(this.rowToRecord(payload.new)))
+            .subscribe();
+        this.channels.set(channelName, channel);
+        return () => {
+            this.client.removeChannel(channel);
+            this.channels.delete(channelName);
+        };
+    }
+    /**
+     * Probe with a bounded head request against the `games` table.
+     *
+     * Verifies both reachability and that the table is readable under the current
+     * key and RLS policy.
+     *
+     * @returns `false` instead of throwing on any error.
+     */
+    async isHealthy() {
+        try {
+            const { error } = await this.client.from('games').select('id', { head: true, count: 'exact' }).limit(1);
+            return !error;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read every visible row, newest first.
+     *
+     * No range is applied, so the result is still subject to the project's
+     * PostgREST `max-rows` setting — on a large table this may silently return a
+     * truncated backup.
+     *
+     * @returns All games visible to the current key.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    async exportAll() {
+        const { data, error } = await this.client.from('games').select('*').order('created_at', { ascending: false });
+        if (error) {
+            throw new Error(`Supabase exportAll failed: ${error.message}`);
+        }
+        return (data ?? []).map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Upsert a batch of games with one request per record.
+     *
+     * Sequential and non-transactional; a record rejected by RLS or a constraint
+     * is logged and skipped, so a partial import is possible.
+     *
+     * @param games - Records to import.
+     * @returns How many were saved successfully.
+     */
+    async importGames(games) {
+        let count = 0;
+        for (const game of games) {
+            try {
+                await this.saveGame(game);
+                count++;
+            }
+            catch (error) {
+                console.warn(`Failed to import game ${game.id}:`, error);
+            }
+        }
+        return count;
+    }
+    /**
+     * Delete every visible row and close all Realtime channels.
+     *
+     * The `neq('id', '')` predicate exists because PostgREST refuses an unfiltered
+     * `DELETE` as a footgun guard; matching "id is not the empty string" selects
+     * everything while satisfying that requirement. RLS still applies, so this
+     * clears only what the current key can see.
+     *
+     * @returns Number of rows deleted.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    async clear() {
+        const { data, error } = await this.client.from('games').delete().neq('id', '').select();
+        if (error) {
+            throw new Error(`Supabase clear failed: ${error.message}`);
+        }
+        this.channels.forEach((channel) => this.client.removeChannel(channel));
+        this.channels.clear();
+        return data?.length ?? 0;
+    }
+    /**
+     * Map a snake_case PostgREST row to a {@link GameRecord}. The JSON columns
+     * arrive already deserialised, so only the key renaming and `null`-to-
+     * `undefined` normalisation is needed.
+     */
+    rowToRecord(row) {
+        return {
+            id: row.id,
+            hpgn: row.hpgn,
+            hfen: row.hfen,
+            players: row.players ?? undefined,
+            metadata: row.metadata ?? undefined,
+            result: row.result ?? undefined,
+            userId: row.user_id ?? undefined,
+            synced: row.synced ?? undefined,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+    generateId() {
+        return `game_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    // Row Level Security - games scoped to user
+    /**
+     * Resolve the id of the currently signed-in Supabase user.
+     *
+     * Useful for stamping `GameRecord.userId` so saved games line up with the
+     * `user_id` an RLS policy filters on.
+     *
+     * @returns The auth user id, or `null` when nobody is signed in or the lookup
+     *   fails — the two cases are not distinguished.
+     */
+    async getAuthenticatedUser() {
+        const { data, error } = await this.client.auth.getUser();
+        if (error || !data?.user) {
+            return null;
+        }
+        return data.user.id;
+    }
+}
+//# sourceMappingURL=supabase.js.map

package/dist/adapters/supabase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supabase.js","sourceRoot":"","sources":["../../src/adapters/supabase.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Persistence layer for HyperChess games.
+ *
+ * Every adapter implements the same {@link GameStore} contract over a different
+ * backend, so an application can swap storage without touching game logic. The
+ * database-backed adapters (`postgres`, `sqlite`, `firebase`, `supabase`) load
+ * their driver lazily via `require()` and throw from their constructor if the
+ * driver is absent — this keeps all four out of the dependency graph of a
+ * consumer that only uses one of them.
+ *
+ * @packageDocumentation
+ */
+export type { GameStore } from './types/game-store';
+export { isStoreOnline, syncStores } from './types/game-store';
+export type { GameRecord, GameQueryOptions, Unsubscribe } from './types/game-record';
+export { GameNotFoundError, ValidationError, SyncError } from './types/game-record';
+export { MemoryGameStore } from './adapters/memory';
+export { PostgresGameStore } from './adapters/postgres';
+export { SqliteGameStore } from './adapters/sqlite';
+export { FirebaseGameStore } from './adapters/firebase';
+export { SupabaseGameStore } from './adapters/supabase';
+export { MemoryGameStore as default } from './adapters/memory';
+//# 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":"AAMA;;;;;;;;;;;GAWG;AAGH,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGpF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,eAAe,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-store
+// File: packages/store/src/index.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+export { isStoreOnline, syncStores } from './types/game-store';
+export { GameNotFoundError, ValidationError, SyncError } from './types/game-record';
+// Export adapters
+export { MemoryGameStore } from './adapters/memory';
+export { PostgresGameStore } from './adapters/postgres';
+export { SqliteGameStore } from './adapters/sqlite';
+export { FirebaseGameStore } from './adapters/firebase';
+export { SupabaseGameStore } from './adapters/supabase';
+// Default export is memory store for development
+export { MemoryGameStore as default } from './adapters/memory';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,qCAAqC;AACrC,oCAAoC;AACpC,iBAAiB;AACjB,+CAA+C;AAiB/C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEpF,kBAAkB;AAClB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,iDAAiD;AACjD,OAAO,EAAE,eAAe,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/game-record.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A complete game record (HPGN + metadata).
+ *
+ * This is the single wire/storage shape shared by every adapter. Adapters that
+ * persist to a relational backend flatten `players`/`metadata` into JSON columns
+ * and rename `userId` to `user_id`; consumers always see this camelCase form.
+ */
+export interface GameRecord {
+    /** Unique game identifier */
+    id: string;
+    /** Game in HPGN format */
+    hpgn: string;
+    /** Starting position (HFEN) */
+    hfen: string;
+    /** Player names */
+    players?: {
+        white?: string;
+        black?: string;
+    };
+    /** Game metadata */
+    metadata?: {
+        event?: string;
+        site?: string;
+        date?: string;
+        round?: string;
+        whiteElo?: number;
+        blackElo?: number;
+        timeControl?: string;
+    };
+    /** Game result (1-0, 0-1, 1/2-1/2, *) */
+    result?: '1-0' | '0-1' | '1/2-1/2' | '*';
+    /** User/owner ID (for multi-user systems) */
+    userId?: string;
+    /** When created (ISO 8601) */
+    createdAt?: string;
+    /** When last modified (ISO 8601) */
+    updatedAt?: string;
+    /** Whether synced to cloud (for offline systems) */
+    synced?: boolean;
+}
+/**
+ * Query options for listing games.
+ *
+ * Filters are combined with AND. All fields are optional; an empty object means
+ * "every game, newest first" for the backend-query adapters and "every game,
+ * oldest first" for {@link GameRecord} sorting done in memory.
+ */
+export interface GameQueryOptions {
+    /** Filter by user ID */
+    userId?: string;
+    /** Filter by result */
+    result?: '1-0' | '0-1' | '1/2-1/2' | '*';
+    /** Maximum results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Sort order (asc/desc by date) */
+    sort?: 'asc' | 'desc';
+}
+/**
+ * Teardown handle returned by `GameStore.watch()`. Calling it detaches the
+ * callback and, once the last callback for an id is gone, releases whatever
+ * backend resource backed the subscription (poll timer, channel, snapshot).
+ */
+export type Unsubscribe = () => void;
+/**
+ * Thrown when a game id does not resolve to a stored record.
+ *
+ * Raised by `loadGame()` and `deleteGame()` on every adapter, so callers can
+ * distinguish "absent" from a genuine backend failure.
+ *
+ * @param id - The game id that could not be resolved; embedded in the message.
+ */
+export declare class GameNotFoundError extends Error {
+    constructor(id: string);
+}
+/**
+ * Thrown when a {@link GameRecord} fails structural validation before it is
+ * handed to a backend.
+ *
+ * @param message - Description of which field or invariant was violated.
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when replication between two stores cannot complete — for example an
+ * offline SQLite store failing to flush its sync queue upstream.
+ *
+ * @param message - Description of what failed to sync and why.
+ */
+export declare class SyncError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=game-record.d.ts.map

package/dist/types/game-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-record.d.ts","sourceRoot":"","sources":["../../src/types/game-record.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IAEX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IAEb,mBAAmB;IACnB,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,oBAAoB;IACpB,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF,yCAAyC;IACzC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,GAAG,CAAC;IAEzC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uBAAuB;IACvB,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,GAAG,CAAC;IAEzC,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,oCAAoC;IACpC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,EAAE,EAAE,MAAM;CAIvB;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/types/game-record.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-store
+// File: packages/store/src/types/game-record.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+/**
+ * Thrown when a game id does not resolve to a stored record.
+ *
+ * Raised by `loadGame()` and `deleteGame()` on every adapter, so callers can
+ * distinguish "absent" from a genuine backend failure.
+ *
+ * @param id - The game id that could not be resolved; embedded in the message.
+ */
+export class GameNotFoundError extends Error {
+    constructor(id) {
+        super(`Game not found: ${id}`);
+        this.name = 'GameNotFoundError';
+    }
+}
+/**
+ * Thrown when a {@link GameRecord} fails structural validation before it is
+ * handed to a backend.
+ *
+ * @param message - Description of which field or invariant was violated.
+ */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Thrown when replication between two stores cannot complete — for example an
+ * offline SQLite store failing to flush its sync queue upstream.
+ *
+ * @param message - Description of what failed to sync and why.
+ */
+export class SyncError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SyncError';
+    }
+}
+//# sourceMappingURL=game-record.js.map

package/dist/types/game-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-record.js","sourceRoot":"","sources":["../../src/types/game-record.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,qCAAqC;AACrC,gDAAgD;AAChD,iBAAiB;AACjB,+CAA+C;AAmF/C;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,EAAU;QACpB,KAAK,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/types/game-store.d.ts

@@ -0,0 +1,99 @@
+import { GameRecord, GameQueryOptions, Unsubscribe } from './game-record';
+/**
+ * Universal game storage interface
+ * Implementations: PostgreSQL, SQLite, Firebase, Supabase, Memory
+ *
+ * All methods are async for compatibility with remote backends
+ */
+export interface GameStore {
+    /**
+     * Save a new game or update existing
+     * @param game Game record to save
+     * @returns ID of saved game (auto-generated if not provided)
+     */
+    saveGame(game: GameRecord): Promise<string>;
+    /**
+     * Load a game by ID
+     * @param id Game ID
+     * @returns Game record or throws GameNotFoundError
+     */
+    loadGame(id: string): Promise<GameRecord>;
+    /**
+     * Delete a game
+     * @param id Game ID
+     */
+    deleteGame(id: string): Promise<void>;
+    /**
+     * List games (optionally filtered)
+     * @param options Query options
+     * @returns Array of game records
+     */
+    listGames(options?: GameQueryOptions): Promise<GameRecord[]>;
+    /**
+     * Count games (optionally filtered)
+     * @param options Query options (omit limit/offset for count)
+     * @returns Total count
+     */
+    countGames(options?: GameQueryOptions): Promise<number>;
+    /**
+     * Watch a game for real-time updates
+     * @param id Game ID
+     * @param callback Called when game changes
+     * @returns Unsubscribe function
+     */
+    watch(id: string, callback: (game: GameRecord) => void): Unsubscribe;
+    /**
+     * Health check - verify backend is accessible
+     * @returns true if backend is operational
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Export all games (useful for backups)
+     * @returns Array of all games
+     */
+    exportAll?(): Promise<GameRecord[]>;
+    /**
+     * Import games from backup
+     * @param games Array of games to import
+     * @returns Number of imported games
+     */
+    importGames?(games: GameRecord[]): Promise<number>;
+    /**
+     * Clear all games (dangerous!)
+     * @returns Number of games deleted
+     */
+    clear?(): Promise<number>;
+}
+/**
+ * Check if a game store is reachable, without letting a backend failure escape.
+ *
+ * Wraps `isHealthy()` so that a driver-level throw (connection refused, expired
+ * credentials) reads as "offline" rather than crashing the caller — the intended
+ * use is an availability probe on a sync path, not error reporting.
+ *
+ * @param store - Store to probe.
+ * @returns `true` only if `isHealthy()` resolved `true`; `false` if it resolved
+ *   `false` or threw.
+ */
+export declare function isStoreOnline(store: GameStore): Promise<boolean>;
+/**
+ * Copy games from one store into another, one record at a time.
+ *
+ * Best-effort and non-transactional: a game that fails to save is logged and
+ * skipped so a single bad record cannot abort the whole sync, which matters when
+ * draining an offline queue on reconnect. Records are not deleted from the
+ * source, so this is a copy rather than a move.
+ *
+ * @param fromStore - Source of truth to read from.
+ * @param toStore - Destination the games are written into.
+ * @param options - `userId` restricts the copy to one owner's games;
+ *   `overwrite` deletes the destination record first so the source version wins
+ *   outright instead of being merged by the destination's upsert semantics.
+ * @returns How many games were saved successfully — may be fewer than the number
+ *   read from the source.
+ */
+export declare function syncStores(fromStore: GameStore, toStore: GameStore, options?: {
+    userId?: string;
+    overwrite?: boolean;
+}): Promise<number>;
+//# sourceMappingURL=game-store.d.ts.map

package/dist/types/game-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-store.d.ts","sourceRoot":"","sources":["../../src/types/game-store.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE1C;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;;;OAIG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAE7D;;;;OAIG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,WAAW,CAAC;IAErE;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9B;;;OAGG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEpC;;;;OAIG;IACH,WAAW,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnD;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAMtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GACjD,OAAO,CAAC,MAAM,CAAC,CA0BjB"}