@krtuworks/sdk 0.0.0-stage → 1.0.1

package/dist/remoteConfig.d.ts

@@ -0,0 +1,48 @@
+import type { Api } from './api.js';
+import { type Module, type ResolvedOptions } from './config.js';
+import type { KrtuStore } from './store.js';
+export interface Switch {
+    build: string;
+    mode: 'TELEMETRY' | 'ALL';
+    message: string;
+}
+export interface RemoteConfigValue {
+    appId: string;
+    environment: string;
+    platform: string | null;
+    version: string;
+    config: Record<string, unknown> & {
+        maintenance?: {
+            enabled: boolean;
+            message?: string | null;
+        };
+        minVersion?: string | null;
+        modules?: Partial<Record<Module, boolean>>;
+    };
+    switches: Switch[];
+    serverTime: string;
+}
+/**
+ * The app's remote config, read without a sign-in and revalidated with its ETag. The
+ * last good copy is kept in the store, so an offline launch starts with what the owner set last.
+ */
+export declare class RemoteConfig {
+    private readonly opts;
+    private readonly api;
+    private readonly store;
+    private stored;
+    constructor(opts: ResolvedOptions, api: Api, store: KrtuStore);
+    private get key();
+    load(): Promise<RemoteConfigValue | null>;
+    get value(): RemoteConfigValue | null;
+    /** Asks the server; `false` when nothing changed. Throws when it cannot (the kept copy stays). */
+    refresh(): Promise<boolean>;
+    /** A module the owner switched off makes nothing; a switch never set is on. An app that is not a game has no game-only modules. */
+    moduleOn(module: Module): boolean;
+    modules(): Record<Module, boolean>;
+    /** The owner's switch that rules this build, ALL over TELEMETRY. */
+    switchForBuild(): Switch | null;
+    get<T = unknown>(key: string, fallback?: T): T | undefined;
+}
+/** True when `build` is older than `minVersion` (dotted numbers; a build's `+meta` is ignored). */
+export declare function olderThan(build: string, minVersion: string): boolean;

package/dist/remoteConfig.js

@@ -0,0 +1,70 @@
+import { GAME_MODULES, MODULES } from './config.js';
+/**
+ * The app's remote config, read without a sign-in and revalidated with its ETag. The
+ * last good copy is kept in the store, so an offline launch starts with what the owner set last.
+ */
+export class RemoteConfig {
+    opts;
+    api;
+    store;
+    stored = null;
+    constructor(opts, api, store) {
+        this.opts = opts;
+        this.api = api;
+        this.store = store;
+    }
+    get key() {
+        return `krtu:${this.opts.clientId}:config:${this.opts.platform}`;
+    }
+    async load() {
+        this.stored = (await this.store.get(this.key)) ?? null;
+        return this.value;
+    }
+    get value() {
+        return this.stored?.value ?? null;
+    }
+    /** Asks the server; `false` when nothing changed. Throws when it cannot (the kept copy stays). */
+    async refresh() {
+        const answer = await this.api.open(`/v1/apps/${encodeURIComponent(this.opts.slug)}/config`, {
+            // The build rides in the query (no header: a browser's read stays a simple GET) and counts for its release report.
+            query: { environment: this.opts.environment, platform: this.opts.platform, build: this.opts.build },
+            headers: this.stored?.etag ? { 'if-none-match': this.stored.etag } : {},
+            accept: [304],
+        });
+        if (answer.status === 304)
+            return false;
+        this.stored = { etag: answer.headers.get('etag'), value: answer.json };
+        await this.store.set(this.key, this.stored);
+        return true;
+    }
+    /** A module the owner switched off makes nothing; a switch never set is on. An app that is not a game has no game-only modules. */
+    moduleOn(module) {
+        if (!this.opts.game && GAME_MODULES.includes(module))
+            return false;
+        return this.value?.config.modules?.[module] !== false;
+    }
+    modules() {
+        return Object.fromEntries(MODULES.map((m) => [m, this.moduleOn(m)]));
+    }
+    /** The owner's switch that rules this build, ALL over TELEMETRY. */
+    switchForBuild() {
+        const mine = (this.value?.switches ?? []).filter((s) => s.build === '*' || s.build === this.opts.build);
+        return mine.find((s) => s.mode === 'ALL') ?? mine.find((s) => s.mode === 'TELEMETRY') ?? null;
+    }
+    get(key, fallback) {
+        const config = this.value?.config;
+        return config && Object.prototype.hasOwnProperty.call(config, key) ? config[key] : fallback;
+    }
+}
+/** True when `build` is older than `minVersion` (dotted numbers; a build's `+meta` is ignored). */
+export function olderThan(build, minVersion) {
+    const parts = (v) => v.split('+')[0].split(/[.-]/).map((p) => Number.parseInt(p, 10) || 0);
+    const a = parts(build);
+    const b = parts(minVersion);
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const d = (a[i] ?? 0) - (b[i] ?? 0);
+        if (d !== 0)
+            return d < 0;
+    }
+    return false;
+}

package/dist/sessions.d.ts

@@ -0,0 +1,45 @@
+import type { Api } from './api.js';
+import type { ResolvedOptions } from './config.js';
+export interface SessionInfo {
+    id: string;
+    /** The player the session is for. */
+    owner: string;
+    startedAt: string;
+}
+/**
+ * The play session: opened once per launch and player, kept alive every
+ * `heartbeatSeconds` with the time actually in use (foreground only), ended when the app goes away.
+ * An open whose answer was lost is sent again with the same `clientSessionId` and gets the same session.
+ */
+export declare class SessionKeeper {
+    private readonly opts;
+    private readonly api;
+    private readonly subject;
+    /** Told the licence list of a session answer (only an open that sent a platform proof gets one). */
+    private readonly onEntitlements;
+    private current;
+    private clientSessionId;
+    private timer;
+    private heartbeatSeconds;
+    private activeMs;
+    private activeSince;
+    private opening;
+    constructor(opts: ResolvedOptions, api: Api, subject: () => string | null, 
+    /** Told the licence list of a session answer (only an open that sent a platform proof gets one). */
+    onEntitlements?: (items: unknown) => Promise<void>);
+    get session(): SessionInfo | null;
+    /** Seconds in use in this launch (foreground only). */
+    activeSeconds(): number;
+    setForeground(foreground: boolean): void;
+    /** Opens the player's session if there is none (one at a time). */
+    open(): Promise<SessionInfo | null>;
+    private doOpen;
+    private schedule;
+    heartbeat(): Promise<void>;
+    /** One whole session where every step must answer: open, a heartbeat, end (the validator's round). */
+    round(): Promise<void>;
+    /** Ends the session (on pagehide the request outlives the page). */
+    end(): Promise<void>;
+    /** Forgets the session without telling the server (the player changed: it times out there). */
+    close(): void;
+}

package/dist/sessions.js

@@ -0,0 +1,157 @@
+import { KrtuworksError, isKrtuworksError } from './errors.js';
+import { uuidV4 } from './ids.js';
+/**
+ * The play session: opened once per launch and player, kept alive every
+ * `heartbeatSeconds` with the time actually in use (foreground only), ended when the app goes away.
+ * An open whose answer was lost is sent again with the same `clientSessionId` and gets the same session.
+ */
+export class SessionKeeper {
+    opts;
+    api;
+    subject;
+    onEntitlements;
+    current = null;
+    clientSessionId = null;
+    timer = null;
+    heartbeatSeconds = 60;
+    activeMs = 0;
+    activeSince = performance.now();
+    opening = null;
+    constructor(opts, api, subject, 
+    /** Told the licence list of a session answer (only an open that sent a platform proof gets one). */
+    onEntitlements = async () => undefined) {
+        this.opts = opts;
+        this.api = api;
+        this.subject = subject;
+        this.onEntitlements = onEntitlements;
+    }
+    get session() {
+        const owner = this.subject();
+        return this.current && this.current.owner === owner ? this.current : null;
+    }
+    /** Seconds in use in this launch (foreground only). */
+    activeSeconds() {
+        const live = this.activeSince !== null ? performance.now() - this.activeSince : 0;
+        return Math.floor((this.activeMs + live) / 1000);
+    }
+    setForeground(foreground) {
+        if (foreground && this.activeSince === null)
+            this.activeSince = performance.now();
+        if (!foreground && this.activeSince !== null) {
+            this.activeMs += performance.now() - this.activeSince;
+            this.activeSince = null;
+        }
+    }
+    /** Opens the player's session if there is none (one at a time). */
+    async open() {
+        if (this.session)
+            return this.session;
+        this.opening ??= this.doOpen().finally(() => {
+            this.opening = null;
+        });
+        return this.opening;
+    }
+    async doOpen() {
+        const owner = this.subject();
+        if (!owner)
+            return null;
+        if (this.current && this.current.owner !== owner)
+            this.close();
+        this.clientSessionId ??= uuidV4();
+        const device = this.opts.device ?? undefined;
+        const answer = await this.api.player('/v1/sessions', {
+            method: 'POST',
+            json: {
+                clientSessionId: this.clientSessionId,
+                platform: this.opts.platform,
+                build: this.opts.build,
+                ...(device ? { device } : {}),
+                ...(this.opts.locale ? { locale: this.opts.locale } : {}),
+            },
+        });
+        const session = answer.json?.session;
+        if (!session || this.subject() !== owner)
+            return null;
+        this.current = { id: session.id, owner, startedAt: session.startedAt };
+        await this.onEntitlements(answer.json?.entitlements).catch(() => undefined);
+        if (typeof answer.json?.heartbeatSeconds === 'number')
+            this.heartbeatSeconds = answer.json.heartbeatSeconds;
+        this.schedule();
+        return this.current;
+    }
+    schedule() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => void this.heartbeat().catch(() => undefined), this.heartbeatSeconds * 1000);
+        this.timer.unref?.();
+    }
+    async heartbeat() {
+        const session = this.session;
+        if (!session)
+            return;
+        try {
+            const answer = await this.api.player(`/v1/sessions/${session.id}/heartbeat`, {
+                method: 'POST',
+                json: { activeSeconds: this.activeSeconds(), foreground: this.activeSince !== null },
+            });
+            const next = answer.json?.nextHeartbeatSeconds;
+            if (typeof next === 'number' && next > 0)
+                this.heartbeatSeconds = next;
+        }
+        catch (err) {
+            if (isKrtuworksError(err) && (err.code === 'session_ended' || err.code === 'session_not_found')) {
+                // The server closed it (30 minutes without a heartbeat): a new one, with a new id.
+                this.current = null;
+                this.clientSessionId = null;
+                await this.open().catch(() => undefined);
+                return;
+            }
+        }
+        finally {
+            if (this.current)
+                this.schedule();
+        }
+    }
+    /** One whole session where every step must answer: open, a heartbeat, end (the validator's round). */
+    async round() {
+        const session = await this.open();
+        if (!session)
+            throw new KrtuworksError('signed_out', 'No player is signed in.');
+        let failure = null;
+        try {
+            await this.api.player(`/v1/sessions/${session.id}/heartbeat`, {
+                method: 'POST',
+                json: { activeSeconds: this.activeSeconds(), foreground: this.activeSince !== null },
+            });
+        }
+        catch (err) {
+            failure = err;
+        }
+        this.close();
+        // The session is ended even when its heartbeat failed, so the round leaves nothing open.
+        const ended = this.api.player(`/v1/sessions/${session.id}/end`, { method: 'POST', json: { activeSeconds: this.activeSeconds() } });
+        if (failure) {
+            await ended.catch(() => undefined);
+            throw failure;
+        }
+        await ended;
+    }
+    /** Ends the session (on pagehide the request outlives the page). */
+    async end() {
+        const session = this.session;
+        this.close();
+        if (!session)
+            return;
+        await this.api
+            .player(`/v1/sessions/${session.id}/end`, { method: 'POST', json: { activeSeconds: this.activeSeconds() }, keepalive: true })
+            .catch(() => undefined);
+    }
+    /** Forgets the session without telling the server (the player changed: it times out there). */
+    close() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.current = null;
+        this.clientSessionId = null;
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where the SDK keeps what must outlive the page: tokens, the device key, queued events, progress and
+ * uploads. Values are structured-cloneable (plain objects, Uint8Array, CryptoKey): the device's private
+ * key is a non-extractable CryptoKey and is only ever stored as one, never as bytes.
+ */
+export interface KrtuStore {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Every key that starts with `prefix`. */
+    keys(prefix: string): Promise<string[]>;
+}
+/** Kept in this process only (tests, servers, a page that must remember nothing). */
+export declare function memoryStore(): KrtuStore;
+/** The browser's IndexedDB: one object store, survives reloads, shared by the origin's tabs. */
+export declare function indexedDbStore(name?: string): KrtuStore;
+/** IndexedDB where there is one, otherwise this process's memory. */
+export declare function defaultStore(): KrtuStore;

package/dist/store.js

@@ -0,0 +1,57 @@
+/** Kept in this process only (tests, servers, a page that must remember nothing). */
+export function memoryStore() {
+    const data = new Map();
+    return {
+        async get(key) {
+            return data.has(key) ? structuredClone(data.get(key)) : undefined;
+        },
+        async set(key, value) {
+            data.set(key, structuredClone(value));
+        },
+        async delete(key) {
+            data.delete(key);
+        },
+        async keys(prefix) {
+            return [...data.keys()].filter((k) => k.startsWith(prefix));
+        },
+    };
+}
+function request(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+/** The browser's IndexedDB: one object store, survives reloads, shared by the origin's tabs. */
+export function indexedDbStore(name = 'krtuworks-sdk') {
+    let db = null;
+    const open = () => {
+        db ??= new Promise((resolve, reject) => {
+            const req = indexedDB.open(name, 1);
+            req.onupgradeneeded = () => req.result.createObjectStore('kv');
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+        return db;
+    };
+    const tx = async (mode) => (await open()).transaction('kv', mode).objectStore('kv');
+    return {
+        async get(key) {
+            return (await request((await tx('readonly')).get(key)));
+        },
+        async set(key, value) {
+            await request((await tx('readwrite')).put(value, key));
+        },
+        async delete(key) {
+            await request((await tx('readwrite')).delete(key));
+        },
+        async keys(prefix) {
+            const range = IDBKeyRange.bound(prefix, `${prefix}￿`);
+            return (await request((await tx('readonly')).getAllKeys(range))).map(String);
+        },
+    };
+}
+/** IndexedDB where there is one, otherwise this process's memory. */
+export function defaultStore() {
+    return typeof indexedDB === 'undefined' ? memoryStore() : indexedDbStore();
+}

package/dist/transport.d.ts

@@ -0,0 +1,30 @@
+import type { Clock } from './clock.js';
+import { KrtuworksError } from './errors.js';
+export interface Answer {
+    status: number;
+    headers: Headers;
+    /** Parsed JSON, or null for an empty or non-JSON body. */
+    json: Record<string, unknown> | null;
+    /** The raw body, when asked for (file reads). */
+    bytes: Uint8Array | null;
+}
+export interface SendInit {
+    method: string;
+    headers?: Record<string, string>;
+    body?: BodyInit | null;
+    /** Read the body as bytes instead of JSON. */
+    bytes?: boolean;
+    /** Let the request outlive the page (the end of a session on pagehide). */
+    keepalive?: boolean;
+}
+/**
+ * The error an answer carries. The server and the /v1/guest calls answer `{ error: { code, message }, ...more }`;
+ * the token endpoint and the device-key challenge answer OAuth's `{ error, error_description, ...more }`.
+ */
+export declare function errorOf(answer: Answer): KrtuworksError;
+export declare function send(fetchFn: typeof fetch, clock: Clock, url: string, init: SendInit): Promise<Answer>;
+/** A form body: the token endpoint wants one, and a browser sends it without a preflight. */
+export declare function form(fields: Record<string, string | undefined | null>): {
+    body: URLSearchParams;
+    headers: Record<string, string>;
+};

package/dist/transport.js

@@ -0,0 +1,73 @@
+import { KrtuworksError } from './errors.js';
+function retryAfterOf(headers, json) {
+    const fromBody = json?.retryAfter;
+    if (typeof fromBody === 'number' && Number.isFinite(fromBody))
+        return fromBody;
+    const header = headers.get('retry-after');
+    if (!header)
+        return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return seconds;
+    const at = Date.parse(header);
+    return Number.isFinite(at) ? Math.max(0, Math.ceil((at - Date.now()) / 1000)) : null;
+}
+/**
+ * The error an answer carries. The server and the /v1/guest calls answer `{ error: { code, message }, ...more }`;
+ * the token endpoint and the device-key challenge answer OAuth's `{ error, error_description, ...more }`.
+ */
+export function errorOf(answer) {
+    const json = answer.json ?? {};
+    const { error, error_description: description, ...rest } = json;
+    let code = `http_${answer.status}`;
+    let message = `The server answered ${answer.status}.`;
+    if (error && typeof error === 'object') {
+        const e = error;
+        if (typeof e.code === 'string')
+            code = e.code;
+        if (typeof e.message === 'string')
+            message = e.message;
+    }
+    else if (typeof error === 'string') {
+        code = error;
+        if (typeof description === 'string')
+            message = description;
+        rest.description = description;
+    }
+    return new KrtuworksError(code, message, answer.status, retryAfterOf(answer.headers, answer.json), rest);
+}
+export async function send(fetchFn, clock, url, init) {
+    let res;
+    try {
+        res = await fetchFn(url, { method: init.method, headers: init.headers, body: init.body ?? undefined, keepalive: init.keepalive });
+    }
+    catch (err) {
+        throw new KrtuworksError('network_error', `No answer from ${new URL(url).host}: ${err?.message ?? String(err)}`);
+    }
+    clock.noteServerTime(res.headers.get('date'));
+    let json = null;
+    let bytes = null;
+    const type = res.headers.get('content-type') ?? '';
+    try {
+        if (init.bytes && res.ok)
+            bytes = new Uint8Array(await res.arrayBuffer());
+        else if (type.includes('json'))
+            json = (await res.json());
+        else
+            await res.arrayBuffer();
+    }
+    catch (err) {
+        throw new KrtuworksError('network_error', `The answer from ${new URL(url).host} was cut: ${err?.message ?? String(err)}`, res.status);
+    }
+    if (json && typeof json.serverTime === 'string')
+        clock.noteServerTime(json.serverTime);
+    return { status: res.status, headers: res.headers, json, bytes };
+}
+/** A form body: the token endpoint wants one, and a browser sends it without a preflight. */
+export function form(fields) {
+    const body = new URLSearchParams();
+    for (const [k, v] of Object.entries(fields))
+        if (v !== undefined && v !== null)
+            body.set(k, v);
+    return { body, headers: { 'content-type': 'application/x-www-form-urlencoded' } };
+}

package/dist/validator.d.ts

@@ -0,0 +1,43 @@
+import { type KrtuworksAppConfig, type KrtuworksOptions } from './config.js';
+/**
+ * The Krtuworks validator: one call checks the app's setup on this
+ * machine, then runs a TEST round against the servers the way the build's release report counts it
+ * (the server's release report): a guest signs in, a session opens, sends a heartbeat and ends, an
+ * event batch, a save written and read back, a progress operation, a test bug report, the remote config
+ * read. Every call names the build, so this run is what turns its report green on the partner console.
+ *
+ * The run uses the SDK's own store (the default one unless `store` names another): on this machine the
+ * same TEST guest comes back run after run (new guests are limited per address and day). A new guest is
+ * an adult that accepts the current terms (`birthDate`, `acceptedTerms` change that). The save goes to the
+ * app's first save slot in TEST (`saveSlot` names another) as a new version; older ones stay in its history.
+ * A run right after another waits out the slot's write limit (one write per 10 seconds) and saves again.
+ */
+export type ValidationStatus = 'PASSED' | 'FAILED' | 'SKIPPED';
+export interface ValidationCheck {
+    key: string;
+    title: string;
+    status: ValidationStatus;
+    /** Why it failed or was skipped. */
+    detail: string | null;
+}
+export interface ValidationReport {
+    /** No check failed. */
+    ok: boolean;
+    build: string;
+    checks: ValidationCheck[];
+}
+export interface ValidateOptions extends Omit<KrtuworksOptions, 'environment' | 'sessions'> {
+    /** The slot to write and read back; default: the app's first save slot in TEST. */
+    saveSlot?: string;
+    /** A new TEST guest's date of birth (default 2000-01-01) and the terms it accepts (default the current ones). */
+    birthDate?: string;
+    acceptedTerms?: string;
+}
+/** What is wrong with krtuworks-config.json for this kind of client, if anything. */
+export declare function configProblems(config: KrtuworksAppConfig | null | undefined, clientKind: 'web' | 'native'): string[];
+/** What is wrong with the platform and, for a web page, the sign-in return address, if anything. */
+export declare function platformProblems(platform: unknown, clientKind: 'web' | 'native', redirectUri: string | undefined): string[];
+/** A send's verdict: sent, or left this device with no refusal; otherwise why it was not. */
+export declare const sentOrWhy: (sent: number, waiting: number, stoppedBy: string | null | undefined) => string | null;
+/** Checks this app's setup and runs a TEST round against the servers; never throws. */
+export declare function validate(options: ValidateOptions): Promise<ValidationReport>;