@krtuworks/sdk 0.0.0-stage → 1.0.0

package/dist/bugs.js

@@ -0,0 +1,276 @@
+import { KrtuworksError, isKrtuworksError } from './errors.js';
+import { uuidV4 } from './ids.js';
+/** The fixed categories: the same menu in every app. */
+export const BUG_CATEGORIES = ['CRASH', 'GAMEPLAY', 'GRAPHICS', 'AUDIO', 'PERFORMANCE', 'CONTROLS', 'TEXT', 'OTHER'];
+const MAX_DESCRIPTION = 4000;
+const MAX_SCREENSHOT = 5 * 1024 * 1024;
+const MAX_WAITING = 20;
+const RING_EVENTS = 50;
+const EVENT_CHARS = 1800;
+/** The server takes at most 100 KB of events; the SDK's own part stays under it so it never costs the player's report. */
+const EVENTS_CHARS = 90_000;
+const LOG_CHARS = 32_768;
+const LOG_LINE = 1000;
+const RETRY_MS = 60_000;
+/** The report can never be taken as it is: dropped rather than sent forever. */
+const REPORT_REFUSED = new Set([400, 413]);
+const REPORT_REFUSED_CODES = new Set(['report_id_reused']);
+/** The screenshot can never be taken (too late, too big, not a picture, the report gone); `screenshot_exists` is done. */
+const SCREENSHOT_REFUSED = new Set([400, 404, 409, 411, 413, 415]);
+const TOLD_KEPT = 200;
+/** The picture's type from its first bytes (what the server takes). */
+export function screenshotType(bytes) {
+    if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47)
+        return 'image/png';
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'image/jpeg';
+    const ascii = (from, to) => String.fromCharCode(...bytes.subarray(from, to));
+    if (bytes.length >= 12 && ascii(0, 4) === 'RIFF' && ascii(8, 12) === 'WEBP')
+        return 'image/webp';
+    return null;
+}
+function refused(message) {
+    return new KrtuworksError('invalid_request', message, 400);
+}
+/**
+ * The body the server takes for a report: the player's words and what the SDK knows of the moment (the
+ * platform, build, device, language, level, place, frame rate, the last events and log lines).
+ * Checked here so a report that can never be taken is refused at once instead of waiting in the queue.
+ */
+export function reportBody(input, context) {
+    if (!BUG_CATEGORIES.includes(input.category))
+        throw refused(`category is one of ${BUG_CATEGORIES.join(', ')}`);
+    const description = typeof input.description === 'string' ? input.description.trim() : '';
+    if (!description || description.length > MAX_DESCRIPTION)
+        throw refused(`description is what the player wrote, 1-${MAX_DESCRIPTION} characters`);
+    // The level the SDK saw is cut to fit; one the game names must fit.
+    const level = input.level ?? (context.level ? context.level.slice(0, 200) : null);
+    if (level !== null && (typeof level !== 'string' || !level.trim() || level.length > 200))
+        throw refused('level is 1-200 characters');
+    const fps = input.fps ?? context.fps;
+    if (fps !== null && (typeof fps !== 'number' || !Number.isFinite(fps) || fps < 0 || fps > 1000))
+        throw refused('fps is a number from 0 to 1000');
+    const position = input.position;
+    if (position && (typeof position.area !== 'string' || !position.area || position.area.length > 100 || !Number.isFinite(position.x) || !Number.isFinite(position.y))) {
+        throw refused('position is {area, x, y, z?}');
+    }
+    let events = context.events;
+    while (events.length && JSON.stringify(events).length > EVENTS_CHARS)
+        events = events.slice(1);
+    const device = context.opts.device ? Object.fromEntries(Object.entries(context.opts.device).filter(([, v]) => v !== undefined && v !== null)) : null;
+    return {
+        reportId: context.reportId,
+        category: input.category,
+        description,
+        platform: context.opts.platform,
+        build: context.opts.build,
+        ...(device && Object.keys(device).length ? { device } : {}),
+        ...(context.opts.locale ? { locale: context.opts.locale } : {}),
+        ...(level ? { level: level.trim() } : {}),
+        ...(position ? { position: { area: position.area, x: position.x, y: position.y, ...(position.z !== undefined ? { z: position.z } : {}) } } : {}),
+        ...(fps !== null ? { fps: Math.round(fps * 10) / 10 } : {}),
+        ...(events.length ? { events } : {}),
+        ...(context.log ? { log: context.log } : {}),
+    };
+}
+/**
+ * The reports a player told about since the last check: the first check of a player on this device
+ * tells nothing (it only learns what was already fixed); a report made here starts the record empty,
+ * so its fix is told even when another device saw it first.
+ */
+export function newlyFixed(reports, state) {
+    const fixedIds = reports.filter((r) => r.status === 'RESOLVED').map((r) => r.id);
+    if (!state)
+        return { fixed: [], state: { told: fixedIds.slice(0, TOLD_KEPT) } };
+    const told = new Set(state.told);
+    const fixed = reports.filter((r) => r.status === 'RESOLVED' && !told.has(r.id));
+    return { fixed, state: { told: [...new Set([...fixedIds, ...state.told])].slice(0, TOLD_KEPT) } };
+}
+/**
+ * Bug reports from inside the app: a report is kept on the device first and
+ * sent when it can be (offline, before the player exists, after a merge), its screenshot right after
+ * it. The server takes a reportId once; the body is frozen when the report is made, so sending it again
+ * after a lost answer gets the same report. The last events and log lines are kept in memory only.
+ */
+export class BugReports {
+    opts;
+    store;
+    api;
+    owner;
+    subject;
+    events = [];
+    logLines = [];
+    logChars = 0;
+    lastFps = null;
+    /** Reports that wait before their next try (in memory: a new launch tries them all again). */
+    waitUntil = new Map();
+    fixedListeners = new Set();
+    constructor(opts, store, api, owner, subject) {
+        this.opts = opts;
+        this.store = store;
+        this.api = api;
+        this.owner = owner;
+        this.subject = subject;
+    }
+    prefix(owner) {
+        return `krtu:${this.opts.clientId}:bugs:${owner}:`;
+    }
+    fixedKey(subject) {
+        return `krtu:${this.opts.clientId}:bugsFixed:${subject}`;
+    }
+    /** An event the SDK kept, for the next report's "last events". */
+    noteEvent(event) {
+        const entry = { type: event.type, at: event.createdAt, ...(event.position ? { position: event.position } : {}) };
+        if (event.data && JSON.stringify(event.data).length <= EVENT_CHARS)
+            entry.data = event.data;
+        this.events.push(entry);
+        if (this.events.length > RING_EVENTS)
+            this.events.shift();
+        const fps = event.type === 'performance' ? event.data?.fps : undefined;
+        if (typeof fps === 'number' && Number.isFinite(fps))
+            this.lastFps = fps;
+    }
+    /** A line for the next report's log (the app's own, and the errors the SDK told). */
+    log(message) {
+        const line = `${new Date().toISOString()} ${String(message).slice(0, LOG_LINE)}`;
+        this.logLines.push(line);
+        this.logChars += line.length + 1;
+        while (this.logChars > LOG_CHARS && this.logLines.length)
+            this.logChars -= this.logLines.shift().length + 1;
+    }
+    async report(input, level) {
+        const owner = this.owner();
+        if ((await this.store.keys(this.prefix(owner))).length >= MAX_WAITING) {
+            throw new KrtuworksError('too_many_reports', `At most ${MAX_WAITING} bug reports wait on this device; they are sent when the app is online.`, 429);
+        }
+        let screenshot = null;
+        if (input.screenshot !== undefined) {
+            const raw = input.screenshot instanceof Uint8Array ? input.screenshot : new Uint8Array(input.screenshot instanceof ArrayBuffer ? input.screenshot : await input.screenshot.arrayBuffer());
+            const type = screenshotType(raw);
+            if (!type)
+                throw refused('The screenshot is a PNG, JPEG or WebP picture');
+            if (raw.length > MAX_SCREENSHOT)
+                throw refused('The screenshot is at most 5 MB');
+            screenshot = { bytes: raw.slice(), type };
+        }
+        const reportId = uuidV4();
+        const body = reportBody(input, { reportId, opts: this.opts, level, fps: this.lastFps, events: [...this.events], log: this.logLines.join('\n') });
+        const waiting = { reportId, madeAt: Date.now(), body, screenshot, bugId: null };
+        await this.store.set(`${this.prefix(owner)}${reportId}`, waiting);
+        const subject = this.subject();
+        if (subject && !(await this.store.get(this.fixedKey(subject))))
+            await this.store.set(this.fixedKey(subject), { told: [] });
+        return { reportId };
+    }
+    /** Reports (with their screenshots) that wait on this device for the player, or for the first player. */
+    async waiting() {
+        return (await this.store.keys(this.prefix(this.owner()))).length;
+    }
+    /** Hands one owner's waiting reports to another (the anonymous queue to the first player, a confirmed merge). */
+    async move(from, to) {
+        if (from === to)
+            return;
+        for (const key of await this.store.keys(this.prefix(from))) {
+            const w = await this.store.get(key);
+            if (w)
+                await this.store.set(`${this.prefix(to)}${w.reportId}`, w);
+            await this.store.delete(key);
+        }
+    }
+    async flush(now = Date.now()) {
+        const result = { sent: 0, dropped: [] };
+        const subject = this.subject();
+        if (!subject)
+            return result;
+        const keys = await this.store.keys(this.prefix(subject));
+        const queue = (await Promise.all(keys.map(async (k) => ({ key: k, w: await this.store.get(k) }))))
+            .filter((e) => !!e.w)
+            .sort((a, b) => a.w.madeAt - b.w.madeAt);
+        for (const { key, w } of queue) {
+            if ((this.waitUntil.get(w.reportId) ?? 0) > now)
+                continue;
+            try {
+                if (!w.bugId) {
+                    const answer = await this.api.player('/v1/me/bug-reports', { method: 'POST', json: w.body });
+                    const bugId = answer.json?.report?.id;
+                    if (typeof bugId !== 'string')
+                        throw new KrtuworksError('invalid_answer', 'The server answered without the report.');
+                    w.bugId = bugId;
+                    if (w.screenshot)
+                        await this.store.set(key, w);
+                }
+                if (w.screenshot) {
+                    try {
+                        await this.api.player(`/v1/me/bug-reports/${encodeURIComponent(w.bugId)}/screenshot`, {
+                            method: 'PUT',
+                            body: w.screenshot.bytes,
+                            headers: { 'content-type': w.screenshot.type },
+                        });
+                    }
+                    catch (err) {
+                        // The report is in: a screenshot it already has is done, one refused for good is let go.
+                        if (!isKrtuworksError(err) || !SCREENSHOT_REFUSED.has(err.status))
+                            throw err;
+                        if (err.code !== 'screenshot_exists')
+                            result.dropped.push({ reportId: w.reportId, code: err.code, screenshotOnly: true });
+                    }
+                }
+                await this.store.delete(key);
+                this.waitUntil.delete(w.reportId);
+                result.sent += 1;
+            }
+            catch (err) {
+                const e = isKrtuworksError(err) ? err : new KrtuworksError('network_error', String(err));
+                if (!w.bugId && (REPORT_REFUSED.has(e.status) || REPORT_REFUSED_CODES.has(e.code))) {
+                    await this.store.delete(key);
+                    result.dropped.push({ reportId: w.reportId, code: e.code, screenshotOnly: false });
+                    continue;
+                }
+                // Anything else (no answer, a busy or closed server, a player in a merge, a ban, the module
+                // off for now) keeps the report for later.
+                if (e.code !== 'context_changed')
+                    this.waitUntil.set(w.reportId, now + (e.retryAfter !== null ? e.retryAfter * 1000 : RETRY_MS));
+                return { ...result, stoppedBy: e.code };
+            }
+        }
+        return result;
+    }
+    /** The player's reports in this app and environment, newest first; fixes not told yet are told. */
+    async mine() {
+        const subject = this.subject();
+        const answer = await this.api.player('/v1/me/bug-reports');
+        const reports = (answer.json?.reports ?? []);
+        if (subject)
+            await this.tellFixed(subject, reports);
+        return reports;
+    }
+    /** At a player's arrival: only when this device keeps a record for them (they reported here, or the app read their reports). */
+    async checkFixed() {
+        const subject = this.subject();
+        if (subject && (await this.store.get(this.fixedKey(subject))))
+            await this.mine();
+    }
+    async tellFixed(subject, reports) {
+        const { fixed, state } = newlyFixed(reports, await this.store.get(this.fixedKey(subject)));
+        // A fix counts as told only when the game listens; otherwise it waits for the next look.
+        const untold = new Set(this.fixedListeners.size ? [] : fixed.map((r) => r.id));
+        await this.store.set(this.fixedKey(subject), { told: state.told.filter((id) => !untold.has(id)) });
+        for (const report of fixed) {
+            for (const listener of this.fixedListeners) {
+                try {
+                    listener(report);
+                }
+                catch {
+                    // the app's listener
+                }
+            }
+        }
+    }
+    onFixed(listener) {
+        this.fixedListeners.add(listener);
+        return () => this.fixedListeners.delete(listener);
+    }
+    resetBackoff() {
+        this.waitUntil.clear();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,390 @@
+import { type AvatarReportReason } from './avatarReports.js';
+import { type BugFlushResult, type BugReportInput, type BugReportView } from './bugs.js';
+import { type AppType, type KrtuworksOptions, type Module, type ResolvedOptions } from './config.js';
+import { type EventPosition, type FlushResult } from './events.js';
+import type { Family, FamilyData } from './families.js';
+import { Files } from './files.js';
+import { type IdentityChange, type Player } from './identity.js';
+import { type Entitlement } from './entitlements.js';
+import { type PresenceResult } from './presence.js';
+import { type LevelRef } from './progression.js';
+import { ProgressQueue, type SortOrder, type StatKind, type UploadMethod } from './progress.js';
+import { RemoteConfig, type Switch } from './remoteConfig.js';
+export interface TrackOptions {
+    position?: EventPosition;
+    /** The version of the app's own schema (or of its extension of a family). */
+    schemaVersion?: number;
+}
+export interface Gate {
+    maintenance: {
+        enabled: boolean;
+        message: string | null;
+    } | null;
+    /** The owner's minimum version is newer than this build: the player must update from the store. */
+    updateRequired: boolean;
+    switchedOff: Switch | null;
+}
+export interface ProgressView {
+    locale: string | null;
+    stats: Array<{
+        key: string;
+        name: string;
+        description: string | null;
+        kind: StatKind;
+        valueType: string;
+        value: number | null;
+        updatedAt: string | null;
+        /** The stat on each platform (a Steam stat's API name); the native SDKs mirror it there. */
+        platformIds: Record<string, string>;
+    }>;
+    achievements: Array<{
+        key: string;
+        id: string;
+        name: string | null;
+        description: string | null;
+        hidden: boolean;
+        retired: boolean;
+        unlocked: boolean;
+        unlockedAt: string | null;
+        platformIds: Record<string, string>;
+        iconUrl: string | null;
+        lockedIconUrl: string | null;
+    }>;
+}
+export type LeaderboardDisplay = 'NUMERIC' | 'TIME_SECONDS' | 'TIME_MILLISECONDS';
+/** One of the app's leaderboards with the player's own score and rank (`rank`, `score`, `details` are null while the player is not on it). */
+export interface LeaderboardView {
+    key: string;
+    name: string;
+    description: string | null;
+    sortOrder: SortOrder;
+    display: LeaderboardDisplay;
+    /** Present when the server tells it: the SDK folds waiting scores only for a board whose method it knows. */
+    uploadMethod?: UploadMethod;
+    importFromPlatform: boolean;
+    /** The board on each platform (Steam's leaderboard name). */
+    platformIds: Record<string, string>;
+    score: number | null;
+    /** Base64 of the bytes submitted with the score. */
+    details: string | null;
+    /** Competition rank: equal scores share one. */
+    rank: number | null;
+    /** Rows on the board. */
+    entries: number;
+}
+export interface LeaderboardsView {
+    locale: string | null;
+    leaderboards: LeaderboardView[];
+}
+export interface LeaderboardEntry {
+    rank: number;
+    /** The id the app knows the player by (pairwise). */
+    subject: string | null;
+    /** The player's Krtuworks username; null when there is none or it could not be read (show "Player"). */
+    name: string | null;
+    score: number;
+    /** Base64 of the bytes submitted with the score. */
+    details: string | null;
+    updatedAt: string;
+    /** The row is the signed-in player's. */
+    you: boolean;
+}
+export interface LeaderboardEntriesView {
+    key: string;
+    scope: 'global' | 'around';
+    sortOrder: SortOrder;
+    display: LeaderboardDisplay;
+    total: number;
+    entries: LeaderboardEntry[];
+}
+export interface LeaderboardEntriesOptions {
+    /** `global` reads from `offset`; `around` centres the window on the player (default `global`). */
+    scope?: 'global' | 'around';
+    /** 1-100 (server default 25). */
+    limit?: number;
+    /** Global scope only. */
+    offset?: number;
+}
+/** Why the SDK suggests a guest links a Krtuworks ID now. */
+export type LinkReminderReason = 'first_achievement' | 'first_save' | 'play_time';
+export interface MergeSettled {
+    previousSubject: string;
+    /** Saves the merged account left waiting on this device: the player chooses (files.adoptWaiting / discardWaiting). */
+    waitingSaves: Array<{
+        uploadId: string;
+        slot: string;
+        savedAt: number;
+    }>;
+}
+export interface SendResult {
+    progress: Awaited<ReturnType<ProgressQueue['flush']>>;
+    bugs: BugFlushResult;
+    events: FlushResult;
+}
+/**
+ * The Krtuworks SDK for web games and apps. One instance per app and environment:
+ *
+ *   const krtu = await Krtuworks.initialize({ config, environment: 'LIVE', platform: 'WEB', build: '1.0.0' });
+ *   await krtu.signInAsGuest({ birthDate: '2001-04-02', acceptedTerms: CURRENT_TERMS });
+ *   krtu.track('screen_view', { screen: 'menu' });
+ *   await krtu.incrementStat('coins', 5);
+ */
+export declare class Krtuworks {
+    readonly options: ResolvedOptions;
+    readonly config: RemoteConfig;
+    readonly files: Files;
+    private readonly store;
+    private readonly clock;
+    private readonly identity;
+    private readonly api;
+    private readonly events;
+    private readonly progress;
+    private readonly sessions;
+    private readonly levels;
+    private readonly bugs;
+    private readonly presence;
+    private readonly licences;
+    private readonly fetchFn;
+    private optedOut;
+    private experiments;
+    private flushTimer;
+    private configTimer;
+    private readonly mergeListeners;
+    private readonly reminderListeners;
+    private countedActive;
+    private sessionOwner;
+    private readonly detach;
+    private settling;
+    private constructor();
+    /** Makes the SDK ready: the player and the remote config this device kept, then the server in the background. */
+    static initialize(options: KrtuworksOptions): Promise<Krtuworks>;
+    get player(): Player | null;
+    /** GAME, MOBILE_APP, WEB_APP or DESKTOP_APP, from krtuworks-config.json. */
+    get appType(): AppType;
+    onIdentityChange(listener: (change: IdentityChange) => void): () => void;
+    /** Called when a merged account's waiting queues moved to the signed-in player (after the server confirmed). */
+    onMergeSettled(listener: (merge: MergeSettled) => void): () => void;
+    /** Plays as a guest on this device; a new guest needs the age screen's answers. */
+    signInAsGuest(input?: {
+        birthDate?: string;
+        acceptedTerms?: string;
+    }): Promise<Player>;
+    /** The Krtuworks ID sign-in address (a guest playing here is carried along unless `carryGuest: false`). */
+    signInUrl(options?: {
+        redirectUri?: string;
+        carryGuest?: boolean;
+    }): Promise<string>;
+    /** In a browser: goes to the sign-in page. */
+    signIn(options?: {
+        redirectUri?: string;
+        carryGuest?: boolean;
+    }): Promise<void>;
+    /** Finishes the sign-in on the page the player came back to (`location.href` by default). */
+    completeSignIn(callbackUrl?: string | URL): Promise<Player>;
+    signOut(): Promise<void>;
+    private identityChanged;
+    /**
+     * What follows a player's arrival: the anonymous queues go to the first player; a merged account's
+     * waiting queues move here once the server confirms the merge; the
+     * session opens; unfinished saves are finished; the queues are sent. Without a player, a guest the
+     * server could not make on an earlier launch is tried again.
+     */
+    private settle;
+    private settleMerges;
+    /**
+     * Records an event (a family or the app's own type). Nothing is made when its module is off, the
+     * owner switched this build's telemetry off, or the player turned statistics off. Returns whether
+     * the event was kept.
+     */
+    track<F extends Family>(type: F, data: FamilyData[F], options?: TrackOptions): boolean;
+    track(type: string, data?: Record<string, unknown>, options?: TrackOptions): boolean;
+    private telemetryAllowed;
+    /** Levels: the SDK adds the attempt, its times and deaths. Levels and deaths are for games only (nothing happens in an app). */
+    readonly level: {
+        start: (level: LevelRef) => Promise<void>;
+        complete: (score?: number) => void;
+        fail: (score?: number) => void;
+        quit: () => void;
+        checkpoint: (name: string) => void;
+        restart: () => Promise<void>;
+    };
+    /** A death, counted toward the level in play and told with its place. Games only: false in an app. */
+    death(cause: string, extra?: {
+        enemy?: string;
+        position?: EventPosition;
+    }): boolean;
+    /** An error the game caught, as the errors family tells it. */
+    error(err: unknown, extra?: {
+        kind?: FamilyData['error']['kind'];
+        fingerprint?: string;
+        handled?: boolean;
+    }): boolean;
+    /**
+     * A bug report from the player (the categories are a fixed menu). The SDK adds the platform, build,
+     * device, language, level in play, frame rate, the last 50 events and the log lines. The report is
+     * kept on this device first and sent when it can be, its screenshot right after it; a player sends at
+     * most 5 an hour and 20 a day in an app (more wait with `too_many_reports`). Refused at once when the
+     * owner turned bug reports off (`module_disabled`) or the input can never be taken (`invalid_request`).
+     */
+    reportBug(input: BugReportInput): Promise<{
+        reportId: string;
+    }>;
+    /** A line for the bug reports' log (kept in memory, the last 32 KB; sent only inside a report the player makes). */
+    log(message: string): void;
+    /** The player's bug reports in this app, newest first, with their status and the build a fix shipped in. */
+    myBugReports(): Promise<BugReportView[]>;
+    /**
+     * Called for each of the player's reports that was fixed since the app last looked (at a player's
+     * arrival, and on myBugReports): the game may tell the player "fixed in <fixedIn>".
+     */
+    onBugFixed(listener: (report: BugReportView) => void): () => void;
+    /**
+     * Reports another player's profile picture: `subject` is the id your app knows them by (another
+     * player of this app, e.g. from your game server), the reason one of AVATAR_REPORT_REASONS, an
+     * optional note of at most 300 characters. Krtuworks reviews it; the reporter is never told an
+     * outcome. Once per player and picture (again answers `already: true`), at most 10 a day
+     * (`too_many_reports`). Needs a connection: nothing waits on this device.
+     */
+    reportAvatar(subject: string, reason: AvatarReportReason, note?: string): Promise<{
+        already: boolean;
+    }>;
+    /** The player's statistics choice in this app (on by default). Off: no event is made or kept. */
+    getTelemetryOptOut(): Promise<boolean>;
+    setTelemetryOptOut(optedOut: boolean): Promise<void>;
+    private optOutKey;
+    private readOptOut;
+    /** Adds to a SUM stat. Kept on the device until the server has it; never lost, never counted twice. */
+    incrementStat(key: string, by?: number): Promise<void>;
+    /** Reports a value to a MAX, MIN or LATEST stat. */
+    setStat(key: string, value: number): Promise<void>;
+    /**
+     * Submits the player's score to a leaderboard (a whole number below 10^15; `details` 1-64 bytes the game
+     * keeps with it). Kept on the device until the server has it, like a stat; the server decides what the
+     * board keeps (KEEP_BEST or FORCE_UPDATE) and mirrors to the platform itself.
+     */
+    submitScore(key: string, value: number, options?: {
+        details?: Uint8Array;
+    }): Promise<void>;
+    unlockAchievement(key: string): Promise<void>;
+    /** The app's stats and achievements with the player's values (names in the SDK's locale where the app has them). */
+    getProgress(): Promise<ProgressView>;
+    /** The app's leaderboards with the player's own score and rank (names in the SDK's locale where the app has them). */
+    getLeaderboards(options?: {
+        locale?: string;
+    }): Promise<LeaderboardsView>;
+    /** A leaderboard's rows in its order: from `offset`, or the window around the player. */
+    getLeaderboardEntries(key: string, options?: LeaderboardEntriesOptions): Promise<LeaderboardEntriesView>;
+    /**
+     * Lines achievements up with a platform's: unlocks here what the platform has, answers what to unlock
+     * there (`toPlatform`) and what support took back here that the platform still has (`toClear`). The open
+     * session goes with it: the server mirrors only with the platform account the session proved (Steam:
+     * required, `409 platform_link_mismatch {state}` when that account is not mirrored for this player).
+     */
+    syncPlatformAchievements(unlocked: string[]): Promise<{
+        unlockedHere: string[];
+        toPlatform: string[];
+        toClear: string[];
+    }>;
+    /** Progress the server refused for good (a retired stat, a wrong value): for the game's own diagnostics. */
+    get progressRefusals(): import("./progress.js").ProgressRefusal[];
+    /** Only a Steam game has licences the server reads from the platform today; a launch asks for them once the player is here. */
+    private refreshLicences;
+    /**
+     * The player's licences as the server last said them (kept on this device, so the last answer of an
+     * earlier launch is here when the server cannot be reached): the game (`sku` base) first, then the
+     * DLCs. `checked` marks what the server confirmed with the platform in this launch. Empty for an app
+     * that is not a game.
+     */
+    entitlements(): Entitlement[];
+    /** Asks the server for the stored licences now (`GET /v1/me/entitlements`) and keeps the answer. Throws when the server cannot be reached. */
+    refreshEntitlements(): Promise<Entitlement[]>;
+    /**
+     * Whether the player owns the DLC with this product key: what the server confirmed with the platform
+     * in this launch; else the last answer the server gave (a browser has no platform client of its own
+     * to ask). False for an unknown key and for an app that is not a game.
+     */
+    ownsDlc(key: string): boolean;
+    private presenceOn;
+    private refreshPresence;
+    /**
+     * Shows what the player is doing (a state the owner declared on the console, with its parameters).
+     * Never throws for the reasons in the result. A browser has no platform presence to write, so a call
+     * that passes every rule answers `no_platform`. `LEVEL` and `SESSION_MINUTES` fill themselves when
+     * the state declares them and the call does not give them.
+     */
+    setPresence(key: string, params?: Record<string, string | number>): Promise<PresenceResult>;
+    /** Takes the shown presence away. A browser shows none, so there is nothing to clear. */
+    clearPresence(): void;
+    /** Tells the platform the player's party (`null` leaves it). A browser has no platform presence, so this does nothing. */
+    setPresenceGroup(_groupId: string | null, _size?: number): void;
+    /** Whether the player shows their presence; null until the server has said (or when the module is off). */
+    presenceVisible(): boolean | null;
+    /** The player's choice to show their presence. Throws `module_disabled` when the owner turned presence off. */
+    setPresenceVisible(visible: boolean): Promise<void>;
+    refreshConfig(): Promise<void>;
+    /** The owner's gates for this build: maintenance, a newer minimum version, a switch. */
+    gate(): Gate;
+    /** The modules the owner left on (all of them until the config says otherwise; in an app the game-only ones are off). */
+    modules(): Record<Module, boolean>;
+    /** The player's A/B groups; their values take over the config's (`value`). */
+    refreshExperiments(): Promise<Array<{
+        key: string;
+        configKey: string;
+        group: string;
+        value: unknown;
+    }>>;
+    /** A remote config value, the player's A/B group's when one varies it. */
+    value<T = unknown>(key: string, fallback?: T): T | undefined;
+    getStatus(): Promise<Record<string, unknown>>;
+    getProfile(): Promise<{
+        fields: Record<string, string | number | boolean>;
+        updatedAt: string | null;
+    }>;
+    /** Writes the named fields of the player's card (null clears one). */
+    updateProfile(fields: Record<string, string | number | boolean | null>): Promise<{
+        fields: Record<string, string | number | boolean>;
+        updatedAt: string | null;
+    }>;
+    private guestCall;
+    /** Asks to delete this guest account (90 days; signing in as the guest is then only for cancelling or the data copy). */
+    requestGuestDeletion(): Promise<{
+        deletionDate: string;
+    }>;
+    cancelGuestDeletion(): Promise<{
+        status: string;
+    }>;
+    /** The guest's data copy: asks for a new one with `request`; a ready copy comes with a 15-minute download address. */
+    guestDataExport(options?: {
+        request?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Called at the moments a guest has something to lose (the first achievement, the first save, a while
+     * of play) when the app's `linkReminder` setting says it is time: the game shows its own prompt and,
+     * if the player agrees, calls `signIn()`. Remote config `linkReminder`: `{ enabled, afterMinutes, everyDays }`
+     * (default on, 30 minutes, every 3 days).
+     */
+    onLinkReminder(listener: (reason: LinkReminderReason) => void): () => void;
+    private remindLinking;
+    private flushSoon;
+    private scheduleFlush;
+    private flushing;
+    /**
+     * Sends what waits: progress first (it must not wait behind telemetry), then bug reports, then events.
+     * One send at a time: a call made while one runs gets that one's result.
+     */
+    flush(): Promise<SendResult>;
+    private send;
+    /** @internal The validator's round: a session opened, kept alive once and ended, every step answered. */
+    sessionRound(): Promise<void>;
+    /** What waits on this device for the signed-in player (or the anonymous queue). */
+    waiting(): Promise<{
+        events: number;
+        progress: number;
+        bugReports: number;
+    }>;
+    private watchPage;
+    /** Waits for the work that follows a player's arrival (tests, or a game that wants to know it is done). */
+    ready(): Promise<void>;
+    /** Stops the SDK: the level in play ends as a quit, the session ends, what waits is written to the store. */
+    shutdown(): Promise<void>;
+}