@krtuworks/sdk 0.0.0-stage → 1.0.0

package/dist/events.js

@@ -0,0 +1,304 @@
+import { KrtuworksError, isKrtuworksError } from './errors.js';
+import { uuidV7 } from './ids.js';
+import { withLock } from './locks.js';
+export const ANON = 'anon';
+const MAX_EVENTS = 50_000;
+const MAX_BYTES = 20 * 1024 * 1024;
+const MAX_AGE_MS = 30 * 86_400_000;
+const BATCH_EVENTS = 500;
+/** The server reads at most 256 KB as sent; batches are built well under it and halved when gzip still overshoots. */
+const SENT_LIMIT = 250 * 1024;
+const RAW_LIMIT_GZIP = 1_500_000;
+const encoder = new TextEncoder();
+const sizeOf = (e) => encoder.encode(JSON.stringify(e)).length;
+async function gzip(text) {
+    if (typeof CompressionStream === 'undefined')
+        return null;
+    const stream = new Blob([text]).stream().pipeThrough(new CompressionStream('gzip'));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+/**
+ * Telemetry events: every event is made with its id and
+ * bound to the player it is about (`anon` before any account; that queue goes to the first player).
+ * Queued events are written to the store before they are sent; a batch is frozen before its first send
+ * and sent again unchanged after a failure; each event's answer is read on its own: accepted, duplicate
+ * and rejected leave the queue, retry goes back with its id into a new batch.
+ */
+export class EventQueue {
+    ctx;
+    buffer = [];
+    persistTimer = null;
+    notBefore = 0;
+    backoffMs = 0;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    key(owner) {
+        return `krtu:${this.ctx.opts.clientId}:events:${owner}`;
+    }
+    lock(owner) {
+        return `krtu:${this.ctx.opts.clientId}:events:${owner}`;
+    }
+    async load(owner) {
+        return (await this.ctx.store.get(this.key(owner))) ?? { pending: [], batch: null, dropped: 0, reported: 0 };
+    }
+    async save(owner, state) {
+        if (!state.pending.length && !state.batch && state.dropped === state.reported)
+            await this.ctx.store.delete(this.key(owner));
+        else
+            await this.ctx.store.set(this.key(owner), state);
+    }
+    /** Makes an event now, for whoever plays now. Kept in memory for a moment, then written to the store. */
+    add(event) {
+        const made = {
+            id: uuidV7(),
+            createdAt: new Date().toISOString(),
+            launchId: this.ctx.clock.launchId,
+            monotonicMs: this.ctx.clock.monotonicMs(),
+            ...(this.ctx.clock.serverOffsetMs !== null ? { serverOffsetMs: Math.round(this.ctx.clock.serverOffsetMs) } : {}),
+            ...event,
+        };
+        this.buffer.push({ owner: this.ctx.subject() ?? ANON, event: made });
+        this.persistTimer ??= setTimeout(() => {
+            this.persistTimer = null;
+            void this.persist().catch(() => undefined);
+        }, 1000);
+        return made;
+    }
+    /** Writes the events made since the last write; drops the oldest when the queue is full or too old. */
+    async persist() {
+        if (this.persistTimer) {
+            clearTimeout(this.persistTimer);
+            this.persistTimer = null;
+        }
+        const taken = this.buffer;
+        this.buffer = [];
+        const byOwner = new Map();
+        for (const { owner, event } of taken)
+            byOwner.set(owner, [...(byOwner.get(owner) ?? []), event]);
+        for (const [owner, events] of byOwner) {
+            await withLock(this.lock(owner), async () => {
+                const state = await this.load(owner);
+                state.pending.push(...events);
+                this.trim(state);
+                await this.save(owner, state);
+            });
+        }
+    }
+    trim(state) {
+        const oldest = Date.now() - MAX_AGE_MS;
+        const before = state.pending.length;
+        state.pending = state.pending.filter((e) => Date.parse(e.createdAt) >= oldest);
+        let bytes = state.pending.reduce((n, e) => n + sizeOf(e), 0) + (state.batch?.events.reduce((n, e) => n + sizeOf(e), 0) ?? 0);
+        let count = state.pending.length + (state.batch?.events.length ?? 0);
+        let cut = 0;
+        while (state.pending.length > cut && (count > MAX_EVENTS || bytes > MAX_BYTES)) {
+            bytes -= sizeOf(state.pending[cut]);
+            count -= 1;
+            cut += 1;
+        }
+        state.pending = state.pending.slice(cut);
+        state.dropped += before - state.pending.length;
+    }
+    /** Events waiting for `owner` (written and not yet written). */
+    async size(owner) {
+        const state = await this.load(owner);
+        return state.pending.length + (state.batch?.events.length ?? 0) + this.buffer.filter((b) => b.owner === owner).length;
+    }
+    /**
+     * Moves `from`'s queue to `to`: the events made before any account go to the first player; a merged
+     * account's go to the one it went into (the server counts each event once by its id, and a batch it
+     * took under the old account answers the same under the new one).
+     */
+    async move(from, to) {
+        await this.persist();
+        const [first, second] = from < to ? [from, to] : [to, from];
+        await withLock(this.lock(first), () => withLock(this.lock(second), async () => {
+            const source = await this.load(from);
+            if (!source.pending.length && !source.batch && source.dropped === source.reported)
+                return;
+            const target = await this.load(to);
+            if (source.batch) {
+                if (target.batch)
+                    target.pending.unshift(...source.batch.events);
+                else
+                    target.batch = source.batch;
+            }
+            target.pending.push(...source.pending);
+            target.dropped += source.dropped - source.reported;
+            this.trim(target);
+            await this.save(to, target);
+            await this.ctx.store.delete(this.key(from));
+        }));
+    }
+    freeze(state, limit) {
+        if (!state.pending.length)
+            return null;
+        const gzipOk = typeof CompressionStream !== 'undefined';
+        const raw = gzipOk ? RAW_LIMIT_GZIP : SENT_LIMIT;
+        const events = [];
+        let bytes = 0;
+        for (const e of state.pending) {
+            const size = sizeOf(e) + 1;
+            if (events.length >= limit || (events.length > 0 && bytes + size > raw))
+                break;
+            events.push(e);
+            bytes += size;
+        }
+        state.pending = state.pending.slice(events.length);
+        return { batchId: uuidV7(), platform: this.ctx.opts.platform, build: this.ctx.opts.build, events };
+    }
+    /** The dropped-events count, said once as an SDK error event (if the app keeps errors). */
+    droppedNotice(state, errorsOn) {
+        const unsaid = state.dropped - state.reported;
+        if (unsaid <= 0)
+            return null;
+        state.reported = state.dropped;
+        if (!errorsOn)
+            return null;
+        return {
+            id: uuidV7(),
+            type: 'error',
+            createdAt: new Date().toISOString(),
+            launchId: this.ctx.clock.launchId,
+            monotonicMs: this.ctx.clock.monotonicMs(),
+            data: { kind: 'other', message: `${unsaid} events were dropped on this device: the queue was full or too old`, fingerprint: 'sdk.events_dropped', handled: true },
+        };
+    }
+    /**
+     * Sends the signed-in player's queue, batch by batch, until it is empty or a send fails (the frozen
+     * batch then waits, unchanged, for the next flush).
+     */
+    async flush(options = { errorsOn: true }) {
+        await this.persist();
+        const owner = this.ctx.subject();
+        const result = { sent: 0, rejected: [], stoppedBy: null };
+        if (!owner)
+            return { ...result, stoppedBy: 'signed_out' };
+        if (Date.now() < this.notBefore)
+            return { ...result, stoppedBy: 'waiting' };
+        let limit = BATCH_EVENTS;
+        for (let round = 0; round < (options.maxBatches ?? 20); round += 1) {
+            const batch = await withLock(this.lock(owner), async () => {
+                const state = await this.load(owner);
+                if (!state.batch) {
+                    const notice = this.droppedNotice(state, options.errorsOn);
+                    if (notice)
+                        state.pending.push(notice);
+                    state.batch = this.freeze(state, limit);
+                }
+                await this.save(owner, state);
+                return state.batch;
+            });
+            if (!batch)
+                return result;
+            const outcome = await this.sendBatch(owner, batch, result);
+            if (outcome === 'split') {
+                limit = Math.max(1, Math.floor(batch.events.length / 2));
+                continue;
+            }
+            if (outcome !== 'done') {
+                result.stoppedBy = outcome;
+                return result;
+            }
+            limit = BATCH_EVENTS;
+        }
+        return result;
+    }
+    async sendBatch(owner, batch, result) {
+        const text = JSON.stringify({
+            batchId: batch.batchId,
+            platform: batch.platform,
+            build: batch.build,
+            sentAt: new Date().toISOString(),
+            launchId: this.ctx.clock.launchId,
+            monotonicMs: this.ctx.clock.monotonicMs(),
+            events: batch.events,
+        });
+        const zipped = await gzip(text);
+        const body = zipped ?? encoder.encode(text);
+        if (body.length > 256 * 1024 && batch.events.length > 1) {
+            await this.unfreeze(owner, batch);
+            return 'split';
+        }
+        let answer;
+        try {
+            answer = await this.ctx.api.player('/v1/events', {
+                method: 'POST',
+                body: body,
+                headers: { 'content-type': 'application/json', ...(zipped ? { 'content-encoding': 'gzip' } : {}) },
+            });
+        }
+        catch (err) {
+            return this.failed(owner, batch, err);
+        }
+        this.backoffMs = 0;
+        const json = answer.json ?? {};
+        const retryIds = new Set((json.retry ?? []).map((r) => r.id));
+        const rejected = json.rejected ?? [];
+        await withLock(this.lock(owner), async () => {
+            const state = await this.load(owner);
+            if (state.batch?.batchId !== batch.batchId)
+                return;
+            state.pending.unshift(...batch.events.filter((e) => retryIds.has(e.id)));
+            state.batch = null;
+            await this.save(owner, state);
+        });
+        result.sent += batch.events.length - retryIds.size - rejected.length;
+        result.rejected.push(...rejected.map((r) => ({ id: r.id, code: r.code })));
+        if (retryIds.size) {
+            // `retry` is for now (the app's events of the day, a build cap): wait before the next batch.
+            this.notBefore = Date.now() + 60_000;
+            return 'retry';
+        }
+        return 'done';
+    }
+    /** A batch never taken by the server goes back to the front of the queue (only before any answer said otherwise). */
+    async unfreeze(owner, batch) {
+        await withLock(this.lock(owner), async () => {
+            const state = await this.load(owner);
+            if (state.batch?.batchId !== batch.batchId)
+                return;
+            state.pending.unshift(...batch.events);
+            state.batch = null;
+            await this.save(owner, state);
+        });
+    }
+    async failed(owner, batch, err) {
+        if (!isKrtuworksError(err))
+            throw err;
+        if (err.code === 'payload_too_large' && batch.events.length > 1) {
+            await this.unfreeze(owner, batch);
+            return 'split';
+        }
+        if (err.code === 'batch_id_reused') {
+            // The id was spent on other events (a store restored from another device): same events, new id.
+            await this.unfreeze(owner, batch);
+            return 'done';
+        }
+        if (err.status === 400 || err.status === 413) {
+            // The batch itself can never be taken: drop it rather than block every later event.
+            await withLock(this.lock(owner), async () => {
+                const state = await this.load(owner);
+                if (state.batch?.batchId !== batch.batchId)
+                    return;
+                state.dropped += batch.events.length;
+                state.batch = null;
+                await this.save(owner, state);
+            });
+            return err.code;
+        }
+        this.backoff(err);
+        return err.code;
+    }
+    backoff(err) {
+        this.backoffMs = Math.min(300_000, Math.max(5_000, this.backoffMs * 2));
+        const wait = err.retryAfter !== null ? err.retryAfter * 1000 : this.backoffMs;
+        this.notBefore = Date.now() + wait;
+    }
+    /** Lets the next flush try at once (back online, or the player changed). */
+    resetBackoff() {
+        this.notBefore = 0;
+        this.backoffMs = 0;
+    }
+}

package/dist/families.d.ts

@@ -0,0 +1,94 @@
+/** Where in the game something happened (death, damage, economy, items, performance, errors). */
+export interface Place {
+    world?: string;
+    level?: string;
+}
+/**
+ * The ready-made event families and their fields, as the server checks them. An app adds
+ * its own fields to a family through an extension schema (`ext`) and makes its own event types.
+ */
+export interface FamilyData {
+    screen_view: {
+        screen: string;
+        previous?: string;
+    };
+    button: {
+        name: string;
+        screen?: string;
+    };
+    tutorial: {
+        tutorial: string;
+        step: number;
+        action: 'start' | 'complete' | 'skip';
+    };
+    progression: {
+        action: 'start' | 'complete' | 'fail' | 'quit' | 'checkpoint' | 'restart';
+        level: string;
+        world?: string;
+        part?: string;
+        checkpoint?: string;
+        attempt?: number;
+        seconds?: number;
+        activeSeconds?: number;
+        deaths?: number;
+        score?: number;
+    };
+    death: Place & {
+        cause: string;
+        enemy?: string;
+    };
+    damage: Place & {
+        amount: number;
+        source?: string;
+    };
+    economy: Place & {
+        direction: 'earn' | 'spend';
+        currency: string;
+        amount: number;
+        source?: string;
+        sink?: string;
+        item?: string;
+    };
+    balance: {
+        currency: string;
+        amount: number;
+    };
+    item: Place & {
+        action: 'pickup' | 'use' | 'equip' | 'unequip' | 'drop' | 'craft' | 'buy' | 'sell';
+        item: string;
+        count?: number;
+    };
+    interaction: Place & {
+        kind: 'dialog' | 'puzzle' | 'secret' | 'hint' | 'npc' | 'other';
+        name: string;
+        choice?: string;
+        outcome?: string;
+    };
+    performance: Place & {
+        fps?: number;
+        fpsLow1?: number;
+        frameMs?: number;
+        loadMs?: number;
+        loadKind?: 'startup' | 'level' | 'other';
+        memoryMb?: number;
+        batteryPct?: number;
+        thermal?: 'nominal' | 'fair' | 'serious' | 'critical';
+        latencyMs?: number;
+    };
+    settings: {
+        graphicsPreset?: string;
+        resolution?: string;
+        language?: string;
+        subtitles?: boolean;
+        subtitleLanguage?: string;
+        difficulty?: string;
+        inputDevice?: 'keyboard_mouse' | 'gamepad' | 'touch' | 'other';
+    };
+    error: Place & {
+        kind: 'exception' | 'crash' | 'assert' | 'other';
+        message?: string;
+        fingerprint?: string;
+        handled?: boolean;
+    };
+}
+export type Family = keyof FamilyData;

package/dist/families.js

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

package/dist/files.d.ts

@@ -0,0 +1,108 @@
+import type { Api } from './api.js';
+import type { ResolvedOptions } from './config.js';
+import type { KrtuStore } from './store.js';
+export interface FileVersion {
+    id: string;
+    slot: string;
+    device: string | null;
+    generation: number;
+    sizeBytes: number;
+    sha256: string;
+    platform: string | null;
+    build: string | null;
+    savedAt: string;
+    fromMerge: boolean;
+}
+export interface SlotView {
+    key: string;
+    kind: 'SAVE' | 'PROFILE' | 'SETTINGS' | 'DEVICE_SETTINGS';
+    name: string;
+    retired: boolean;
+    file: FileVersion | null;
+    /** After a merge: the other account's version, waiting for the player's choice. */
+    conflict: FileVersion | null;
+    devices: FileVersion[];
+}
+export interface FileRead {
+    bytes: Uint8Array;
+    /** A save of this slot started on this device while the read ran: the read is older than what the player has here. */
+    newerLocalSave: boolean;
+    /** The version read (null when it is a similar device's file: a starting point, not this device's). */
+    version: {
+        id: string;
+        generation: number;
+        sha256: string;
+        savedAt: string;
+    } | null;
+    similarDevice: boolean;
+}
+export interface SaveOptions {
+    /** The version this one replaces (its id, the ETag of a read), or null for an empty slot. SETTINGS-like slots need neither. */
+    base?: string | null;
+    /** DEVICE_SETTINGS: this device's id and description (`os`, `gpu`, `ramMb`, `screenWidth`, `screenHeight`). */
+    device?: string;
+    deviceInfo?: Record<string, string | number>;
+}
+/**
+ * The player's files in the app's slots: a save is
+ * written to the store first, sent with its upload id as the Idempotency-Key and asked about until it
+ * is final; a conflict comes back with the slot's current version for the game's choice screen.
+ */
+export declare class Files {
+    private readonly opts;
+    private readonly api;
+    private readonly store;
+    private readonly subject;
+    private readonly generation;
+    /** Told after every save the server activated (the client's link reminder counts the first one). */
+    private readonly onSaved;
+    /** Per slot (and device), bumped by every save started here: a read compares it before and after. */
+    private readonly revisions;
+    constructor(opts: ResolvedOptions, api: Api, store: KrtuStore, subject: () => string | null, generation: () => number, 
+    /** Told after every save the server activated (the client's link reminder counts the first one). */
+    onSaved?: () => void);
+    private revisionKey;
+    private path;
+    private uploadKey;
+    list(): Promise<{
+        slots: SlotView[];
+        limits: Record<string, number>;
+    }>;
+    /** A slot's current version; null when `ifNoneMatch` (a version id held) is still current. */
+    read(slot: string, options?: {
+        device?: string;
+        deviceInfo?: Record<string, string | number>;
+        ifNoneMatch?: string;
+    }): Promise<FileRead | null>;
+    /**
+     * Saves a new version of `slot`. Resolves with the new version once the server activated it; rejects
+     * with `file_conflict` (`details.current`: the version now in the slot) when another one came first.
+     */
+    save(slot: string, data: Uint8Array, options?: SaveOptions): Promise<FileVersion>;
+    private send;
+    /** Reads an upload's state (200 again or 202) until it is final. */
+    private settle;
+    private done;
+    /** Saves left unfinished by an earlier launch (an answer lost, a 202): finishes the signed-in player's. */
+    resume(): Promise<Array<{
+        uploadId: string;
+        slot: string;
+        outcome: 'saved' | 'refused' | 'waiting';
+        code?: string;
+    }>>;
+    /** Saves of another player waiting on this device (a merged account's): the game asks the player what to keep. */
+    waitingFor(owner: string): Promise<Array<{
+        uploadId: string;
+        slot: string;
+        savedAt: number;
+    }>>;
+    /**
+     * A save another player left waiting (a merged account's) that the player chose to keep:
+     * saved now as this player's, over `base` (the slot's version the player saw), with a new upload id.
+     */
+    adoptWaiting(uploadId: string, base: string | null): Promise<FileVersion>;
+    /** A waiting save the player chose not to keep. */
+    discardWaiting(uploadId: string): Promise<void>;
+    /** After a merge: keep `keep` (the slot's version or the merged one) over `current` (the one the player saw). */
+    resolve(slot: string, keep: string, current: string): Promise<FileVersion>;
+}