@seekprotocol/game 0.1.0 → 0.1.1

package/README.md

@@ -3,19 +3,16 @@
 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.
+A minigame in a quest is a web page that the Seek app shows. The bridge tells
+the app when the game is ready and how it ended.
 
 ```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-game.js` is the same bridge as one file, for a game without a bundler.
 
-Seek Protocol: https://www.seekprotocol.ai/en
+- Store Connect: https://storeconnect.seekprotocol.ai
+- 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

@@ -1,26 +1,6 @@
-/**
- * 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';
+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);
@@ -31,7 +11,6 @@ interface MessageEventLike {
     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;
@@ -42,47 +21,34 @@ export interface WindowLike {
         postMessage(message: string): void;
     };
     document?: {
-        addEventListener(type: 'message', fn: Listener): void;
-        removeEventListener(type: 'message', fn: Listener): void;
+        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>>;
+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;
@@ -92,24 +58,13 @@ export interface Bridge {
         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

@@ -1,34 +1,20 @@
-/**
- * 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';
+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;
@@ -44,14 +30,11 @@ export interface ErrorInput {
     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. */
+    log(level: LogLevel, message: string, data?: unknown, source?: "log" | "console"): boolean;
     end(reason: EndReason): Promise<void>;
     flush(final?: boolean): Promise<void>;
-    /** For tests and the docs: what the collector counted. */
     stats(): {
         sent: number;
         dropped: number;
@@ -62,6 +45,5 @@ export interface Collector {
     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

@@ -1,64 +1,57 @@
-/**
- * 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 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 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 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 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. */
+    kind: "error";
     at: number;
     source: ErrorSource;
     message: string;
@@ -66,96 +59,82 @@ export interface ErrorEntry {
     file?: string;
     line?: number;
     col?: number;
-    /** How many identical errors this entry stands for. */
     count?: number;
 }
 export interface LogEntry {
-    kind: 'log';
+    kind: "log";
     at: number;
     level: LogLevel;
     message: string;
     data?: unknown;
-    /** `console` when captured from console.*, else the game called log(). */
-    source?: 'log' | 'console';
+    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';
+    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';
+    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];
+    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';
+    kind: "end";
     at: number;
     reason: EndReason;
 }
-/** Only a host may send these, with a host token. */
 export interface HostEntry {
-    kind: 'host';
+    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. */
+    device: "phone" | "tablet" | "desktop" | "unknown";
+    os: "ios" | "android" | "web" | "unknown";
     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 const DEVICE_CLASSES: readonly LaunchContext["device"][];
+export declare const OS_NAMES: readonly LaunchContext["os"][];
 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;
@@ -163,49 +142,27 @@ export interface StackFrame {
     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';
+    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;
@@ -214,20 +171,11 @@ export interface WatchdogOptions {
     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. */
+    fail(event: "render_gone" | "load_failed", detail?: string): void;
     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

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