@seekprotocol/game 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seek Protocol (https://www.seekprotocol.ai/en)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @seekprotocol/game
 
-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.
+The GameKit bridge between a minigame and the Seek app. Made by
+[Seek Protocol](https://www.seekprotocol.ai/en).
+
+A minigame in a quest is a web page that Seek shows inside the app. This bridge
+tells the app when the game is ready, reports the result and sends Seekprotocol
+Vitals (start time, frame rate, errors) so makers see how their game runs on
+real phones.
+
+```js
+import { createBridge } from '@seekprotocol/game';
+```
+
+`seek-game.js` is the same bridge as one file for a game without a bundler.
+The bridge is readable on purpose: it ships inside every game and App Review
+reads it.
+
+Seek Protocol: https://www.seekprotocol.ai/en
+
+Copyright (c) 2026 Seek Protocol. MIT licensed, see `LICENSE.md`: ship the bridge with your game freely.

package/bridge.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The bridge a minigame imports: `ready()`, `launch()`, `finish()`,
+ * `storage` and `track`.
+ *
+ * Two hosts are possible. In the Seek app the game is the top page of a
+ * hardened WebView: the bridge posts to `window.ReactNativeWebView` and the app
+ * answers by dispatching `message` events on the page (no source window). In
+ * Store Connect's simulator the game sits in an iframe: the bridge posts to
+ * its parent, only to the allowed host origins, and accepts answers only from
+ * the parent window at the origin that answered `ready`.
+ *
+ * The bridge never sees who the player is. The launch token names a
+ * pseudonymous `sub`, the run, the seed and the language; it is what the
+ * proxy accepts for storage, track and Vitals, and nothing else.
+ *
+ * Seekprotocol Vitals: once ready, the bridge reports uncaught errors and
+ * unhandled rejections, the game's own `log()` lines (and, if the game opts
+ * in, console output), a heartbeat and the session's end. Everything is
+ * scrubbed, batched and limited first (see `collector.ts` and `diagnostics.ts`).
+ */
+import { type HostEventType, type LaunchInfo, type TrackProps } from './protocol.js';
+import { type CollectorTimers } from './collector.js';
+import { type LogLevel } from './diagnostics.js';
+export declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+interface MessageEventLike {
+    data: unknown;
+    origin: string;
+    source: unknown;
+}
+type Listener = (e: MessageEventLike) => void;
+/** What the bridge needs of `window`; tests pass a fake. Besides `message` it listens for `error`, `unhandledrejection` and `pagehide`. */
+export interface WindowLike {
+    addEventListener(type: string, fn: (e: any) => void): void;
+    removeEventListener(type: string, fn: (e: any) => void): void;
+    parent?: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    } | null;
+    ReactNativeWebView?: {
+        postMessage(message: string): void;
+    };
+    document?: {
+        addEventListener(type: 'message', fn: Listener): void;
+        removeEventListener(type: 'message', fn: Listener): void;
+    };
+}
+export interface BridgeOptions {
+    window?: WindowLike;
+    /** Frame hosts allowed to answer. Default: Store Connect. Add `http://localhost:<port>` for a local simulator. */
+    hostOrigins?: readonly string[];
+    fetch?: typeof fetch;
+    /** How long a request waits for the host, in ms. */
+    timeoutMs?: number;
+    /** Seekprotocol Vitals. On by default; `false` turns off error capture, heartbeats and log(). */
+    vitals?: VitalsOptions | false;
+}
+type ConsoleLike = Partial<Record<'debug' | 'log' | 'info' | 'warn' | 'error', (...args: unknown[]) => void>>;
+export interface VitalsOptions {
+    /** Capture uncaught errors and unhandled promise rejections. Default true. */
+    errors?: boolean;
+    /** Also send console output: true for every level, or a list such as `['warn', 'error']`. Default off. */
+    console?: boolean | readonly LogLevel[];
+    /** Seconds between heartbeats, 5 to 25. Default 10. */
+    heartbeatSeconds?: number;
+    /** Seconds between sends of a non-empty queue. Default 5. */
+    flushSeconds?: number;
+    /** Measure frames per second, jank, the heap and the time to ready(). Default true. */
+    performance?: boolean;
+    /** For tests. */
+    consoleObject?: ConsoleLike;
+    timers?: CollectorTimers;
+    now?: () => number;
+}
+export interface FinishResult {
+    /** Whether the host took the score to Seek. Whether it counts is Seek's decision. */
+    accepted: boolean;
+}
+export interface Bridge {
+    /** The handshake. Resolves with the launch once the host answered. Safe to call twice. */
+    ready(): Promise<LaunchInfo>;
+    /** The run, after `ready()`. */
+    launch(): LaunchInfo;
+    /** Report the run, once. The score is advisory: Seek checks it against the step and the run ticket. */
+    finish(result: {
+        score: number;
+        seconds: number;
+    }): Promise<FinishResult>;
+    storage: {
+        get(key: string): Promise<unknown>;
+        set(key: string, value: unknown): Promise<void>;
+        remove(key: string): Promise<void>;
+    };
+    /** Count an event. Never throws; returns false when the event was dropped. */
+    track(event: string, props?: TrackProps): boolean;
+    /**
+     * A line for Seekprotocol Vitals, shown to you in Store Connect. Never throws;
+     * false when it was dropped (not ready yet beyond 20 lines, over the limits, or Vitals are off).
+     * Do not log personal data: emails, positions, long numbers and tokens are scrubbed, but the rest is kept for 30 days.
+     */
+    log(level: LogLevel, message: string, data?: unknown): boolean;
+    /** End the session cleanly (the player left the game) and send what is left. The bridge keeps working for storage and finish. */
+    exit(): Promise<void>;
+    /** The Vitals session id of this launch, after ready(): search for it in Store Connect's logs. */
+    sessionId(): string | null;
+    /** Host events: the app went to the background (`pause`), came back (`resume`), or is closing the game (`exit`). */
+    on(event: HostEventType, fn: () => void): () => void;
+    /** Stop listening. */
+    close(): void;
+}
+/** Events per launch the bridge sends at most; the proxy counts too. */
+export declare const TRACK_PER_LAUNCH = 200;
+export declare function createBridge(opts?: BridgeOptions): Bridge;
+export {};

package/collector.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The bridge's side of Seekprotocol Vitals: a queue of scrubbed entries that
+ * goes out in small batches, within per-launch limits and a rate limit.
+ *
+ * It knows nothing about windows or transports: the bridge feeds it errors
+ * and logs and gives it a `send` that posts to the proxy or the host.
+ */
+import { type DiagnosticsBatch, type EndReason, type ErrorSource, type LogLevel } from './diagnostics.js';
+export interface CollectorTimers {
+    setInterval(fn: () => void, ms: number): unknown;
+    clearInterval(t: unknown): void;
+}
+export interface CollectorOptions {
+    /** Deliver one batch. `final` is the last one of the session (send it with keepalive). Errors are swallowed. */
+    send: (batch: DiagnosticsBatch, final: boolean) => Promise<unknown> | unknown;
+    /** A heartbeat for the host's hang check, every `heartbeatMs`, and once with `ended` at the end. */
+    beat?: (ended: boolean) => void;
+    /** Exact texts never to send (the launch token). */
+    secrets?: () => readonly string[];
+    now?: () => number;
+    timers?: CollectorTimers;
+    /** How often a non-empty queue is sent. Default 5 s. */
+    flushMs?: number;
+    /** How often a heartbeat goes out. Default 10 s, at least 5 s, at most 25 s (the host's hang limit is 30 s). */
+    heartbeatMs?: number;
+    /** Entries per second on average, and the burst. */
+    rate?: {
+        perSecond: number;
+        burst: number;
+    };
+    /** What each heartbeat carries about how smooth the game runs (perf.ts). */
+    sample?: () => {
+        fps?: number;
+        jank?: number;
+        heap_mb?: number;
+    };
+}
+export interface ErrorInput {
+    source: ErrorSource;
+    message: string;
+    stack?: string;
+    file?: string;
+    line?: number;
+    col?: number;
+}
+export interface Collector {
+    /** The session started (after ready): sends what was buffered before, then runs the timers. `readyMs`: navigation to ready(). */
+    start(session: string, readyMs?: number): void;
+    error(e: ErrorInput): boolean;
+    log(level: LogLevel, message: string, data?: unknown, source?: 'log' | 'console'): boolean;
+    /** End the session once and send what is left. */
+    end(reason: EndReason): Promise<void>;
+    flush(final?: boolean): Promise<void>;
+    /** For tests and the docs: what the collector counted. */
+    stats(): {
+        sent: number;
+        dropped: number;
+        errors: number;
+        logs: number;
+        batches: number;
+    };
+    readonly session: string | null;
+    readonly ended: boolean;
+}
+/** Entries kept before ready(); the rest are dropped and counted. */
+export declare const PRE_READY_ENTRIES = 20;
+export declare function createCollector(opts: CollectorOptions): Collector;

package/diagnostics.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Seekprotocol Vitals: the shapes, limits, scrubbing and grouping of a
+ * minigame's crash and log reports.
+ *
+ * The bridge collects errors, logs, heartbeats and the session's start and
+ * end, scrubs them and sends them in small batches: to the proxy
+ * (`POST /v1/diagnostics`, with the launch token) or, in the simulator, to the
+ * host. A host (the Seek app, the simulator) adds what only it can see: a game
+ * that never became ready, stopped answering, lost its WebView process or did
+ * not load (`HostEvent`). The proxy runs every check here again and scrubs
+ * again: nothing the game sends is trusted.
+ *
+ * No dependencies and no DOM, so the Workers and the hosts import this file too.
+ */
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export declare const isLogLevel: (v: unknown) => v is LogLevel;
+/** What the host reports for a game it runs. Each one ends the session as a crash. */
+export declare const HOST_EVENTS: readonly ["no_ready", "hang", "render_gone", "load_failed"];
+export type HostCrashEvent = (typeof HOST_EVENTS)[number];
+export declare const isHostEvent: (v: unknown) => v is HostCrashEvent;
+/** A host reports `no_ready` when the game has not called ready() this long after it started loading. */
+export declare const HOST_READY_TIMEOUT_MS = 10000;
+/** A host reports `hang` when a ready game sent no heartbeat for this long while in the foreground. */
+export declare const HOST_HANG_MS = 30000;
+export declare const HOST_EVENT_TEXT: Record<HostCrashEvent, string>;
+/** How a session ended. `exit`, `pagehide` and `closed` come from the bridge; the rest from the host. */
+export declare const END_REASONS: readonly ["exit", "pagehide", "closed", "host_exit", "no_ready", "hang", "render_gone", "load_failed"];
+export type EndReason = (typeof END_REASONS)[number];
+/** Where an error came from. `error` and `unhandledrejection` are uncaught and count as crashes. */
+export declare const ERROR_SOURCES: readonly ["error", "unhandledrejection", "console", "manual"];
+export type ErrorSource = (typeof ERROR_SOURCES)[number];
+export declare const isFatalSource: (s: ErrorSource) => s is "error" | "unhandledrejection";
+export declare const DIAG_LIMITS: {
+    /** Characters of a message (log or error). */
+    readonly message: 500;
+    /** Characters of a stack, after scrubbing. */
+    readonly stack: 4000;
+    /** Stack frames kept. */
+    readonly frames: 20;
+    /** Characters of a source file path. */
+    readonly file: 200;
+    /** UTF-8 bytes of a log's data as JSON. */
+    readonly data: 2048;
+    /** Characters of a host event's detail. */
+    readonly detail: 200;
+    /** Entries in one batch. */
+    readonly batchEntries: 50;
+    /** UTF-8 bytes of one batch as JSON (the proxy reads at most 64 KB). */
+    readonly batchBytes: number;
+    /** Error entries per session; the proxy keeps the same limit. */
+    readonly sessionErrors: 100;
+    /** Log entries per session. */
+    readonly sessionLogs: 1000;
+    /** One error entry stands for at most this many identical errors. */
+    readonly repeat: 1000;
+};
+export declare const DIAG_BODY_MAX_BYTES: number;
+export interface ErrorEntry {
+    kind: 'error';
+    /** ms since 1970, the device's clock. The proxy clamps it. */
+    at: number;
+    source: ErrorSource;
+    message: string;
+    stack?: string;
+    file?: string;
+    line?: number;
+    col?: number;
+    /** How many identical errors this entry stands for. */
+    count?: number;
+}
+export interface LogEntry {
+    kind: 'log';
+    at: number;
+    level: LogLevel;
+    message: string;
+    data?: unknown;
+    /** `console` when captured from console.*, else the game called log(). */
+    source?: 'log' | 'console';
+}
+/** A heartbeat, with how the game ran since the last one (perf.ts): frames per second, frames over 50 ms, the JS heap in MB. */
+export interface HeartbeatEntry {
+    kind: 'heartbeat';
+    at: number;
+    fps?: number;
+    jank?: number;
+    heap_mb?: number;
+}
+/** The session's start; `ready_ms` is the time from navigation to ready(). */
+export interface StartEntry {
+    kind: 'start';
+    at: number;
+    ready_ms?: number;
+}
+/** The ranges a measurement must fall in; anything else is left out. */
+export declare const PERF_RANGES: {
+    readonly fps: readonly [0, 240];
+    readonly jank: readonly [0, 100000];
+    readonly heap_mb: readonly [0, 65536];
+    readonly ready_ms: readonly [0, 600000];
+};
+export interface EndEntry {
+    kind: 'end';
+    at: number;
+    reason: EndReason;
+}
+/** Only a host may send these, with a host token. */
+export interface HostEntry {
+    kind: 'host';
+    at: number;
+    event: HostCrashEvent;
+    detail?: string;
+}
+export type DiagnosticEntry = ErrorEntry | LogEntry | HeartbeatEntry | StartEntry | EndEntry | HostEntry;
+/** What the bridge sends, to the proxy or to the host. Who and what game come from the token, never from here. */
+export interface DiagnosticsBatch {
+    /** The session id the bridge derived (`sessionIdOf`); the proxy derives its own and ignores this. */
+    session?: string;
+    /** Batch number within the session, from 1. */
+    seq?: number;
+    entries: DiagnosticEntry[];
+    /** Entries the bridge left out because of its own limits since the last batch. */
+    dropped?: number;
+}
+/**
+ * The launch context a host knows about the device: never free text from the
+ * game. platform-quest signs it into the launch token (`ctx`) from what the
+ * app sent to `run_start`.
+ */
+export interface LaunchContext {
+    device: 'phone' | 'tablet' | 'desktop' | 'unknown';
+    os: 'ios' | 'android' | 'web' | 'unknown';
+    /** `17.4`, `14`: digits and dots only. */
+    os_version?: string;
+    /** The Seek app's version, `3.2.0`, or `simulator`. */
+    app_version?: string;
+}
+export declare const DEVICE_CLASSES: readonly LaunchContext['device'][];
+export declare const OS_NAMES: readonly LaunchContext['os'][];
+/** Why a launch context is not one, or null. */
+export declare function launchContextProblem(c: unknown): string | null;
+/** The context as stored: anything missing or odd becomes `unknown` / null. */
+export declare function normaliseContext(c: unknown): {
+    device: string;
+    os: string;
+    os_version: string | null;
+    app_version: string | null;
+};
+/** A text with emails, tokens, keys, positions, long numbers and URL queries taken out. */
+export declare function scrubText(s: string, extra?: readonly string[]): string;
+/** Plain JSON with every text scrubbed and keys that name personal or secret things emptied. Null when it is not JSON. */
+export declare function scrubData(value: unknown, extra?: readonly string[], depth?: number): unknown;
+/** Data as stored: scrubbed, and replaced by a marker when it is larger than the limit. */
+export declare function boundData(value: unknown, extra?: readonly string[]): unknown;
+/**
+ * A game's own URLs, shortened to their path: `https://<app>.play.seekprotocol.ai/@<hash>/game.js`
+ * becomes `/game.js`, so stacks read well and group across versions.
+ */
+export declare function shortenGameUrls(s: string): string;
+export interface StackFrame {
+    fn: string;
+    file: string;
+    line: number | null;
+    col: number | null;
+}
+/** The frames of a V8, JavaScriptCore or Gecko stack, top first. */
+export declare function parseStack(stack: string | undefined): StackFrame[];
+/**
+ * A message with what changes between occurrences taken out: numbers, quoted
+ * texts, hex ids and placeholders the scrubber left. Two errors that differ
+ * only there are one group.
+ */
+export declare function normaliseMessage(message: string): string;
+/** How many frames name a group. */
+export declare const FINGERPRINT_FRAMES = 3;
+/** The part of a frame that stays the same across builds: the file and the function, or the line when it has no name. */
+export declare const frameKey: (f: StackFrame) => string;
+export declare function sha256HexOf(s: string): Promise<string>;
+/** The text a fingerprint hashes: the kind, the normalised message and the top frames. */
+export declare function fingerprintInput(kind: string, message: string, stack?: string, file?: string, line?: number): string;
+/** A group id: the first 32 hex of SHA-256 over `fingerprintInput`. */
+export declare function fingerprint(kind: string, message: string, stack?: string, file?: string, line?: number): Promise<string>;
+/** The session id of a launch: the same in the bridge, the proxy and Store Connect, and not the run id itself. */
+export declare function sessionIdOf(appId: string, runId: string): Promise<string>;
+export interface ParsedBatch {
+    entries: DiagnosticEntry[];
+    /** What the bridge says it dropped before sending (its own limits). */
+    dropped: number;
+    /** Entries that were not valid and were left out. */
+    invalid: number;
+    /** Host entries in a batch that did not come from a host. */
+    hostOnly: number;
+}
+/**
+ * Check a batch and clean every entry: unknown kinds and broken shapes are
+ * dropped (counted in `invalid`), texts are clipped and scrubbed again, stacks
+ * are shortened. `host` entries are only kept when `from` is `host`.
+ */
+export declare function parseDiagnosticsBatch(body: unknown, opts?: {
+    from: 'game' | 'host';
+    secrets?: readonly string[];
+}): ParsedBatch | null;
+/** One entry, checked, clipped and scrubbed, or null. The bridge runs it before sending, the proxy again on receipt. */
+export declare function cleanDiagnosticEntry(e: unknown, secrets?: readonly string[]): DiagnosticEntry | null;
+/** Whether an entry ends its session as a crash. */
+export declare const isCrashEntry: (e: DiagnosticEntry) => boolean;
+export interface WatchdogOptions {
+    /** Called once with the crash the host saw; the host then sends it (app) or shows it (simulator). */
+    onCrash: (entry: HostEntry) => void;
+    readyTimeoutMs?: number;
+    hangMs?: number;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (t: unknown) => void;
+}
+export interface HostWatchdog {
+    /** The game answered ready. */
+    ready(): void;
+    /** A heartbeat (or any message) arrived from the game. */
+    beat(): void;
+    /** The app went to the background (no hang while paused) or came back. */
+    pause(): void;
+    resume(): void;
+    /** The WebView reported a failure: `render_gone` or `load_failed`. */
+    fail(event: 'render_gone' | 'load_failed', detail?: string): void;
+    /** The game ended cleanly, or the host closed it: stop watching. */
+    stop(): void;
+}
+/**
+ * The timers a host needs for `no_ready` and `hang`. Start it when the game
+ * page starts loading; it reports at most one crash, then stops.
+ */
+export declare function createHostWatchdog(opts: WatchdogOptions): HostWatchdog;

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from './protocol.js';
+export * from './bridge.js';
+export * from './diagnostics.js';
+export * from './collector.js';
+export * from './perf.js';