@krtuworks/sdk 0.0.0-stage → 1.0.0

package/dist/files.js

@@ -0,0 +1,215 @@
+import { KrtuworksError, isKrtuworksError } from './errors.js';
+import { sha256Hex, uuidV4 } from './ids.js';
+const POLL_LIMIT_MS = 60_000;
+/**
+ * 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 class Files {
+    opts;
+    api;
+    store;
+    subject;
+    generation;
+    onSaved;
+    /** Per slot (and device), bumped by every save started here: a read compares it before and after. */
+    revisions = new Map();
+    constructor(opts, api, store, subject, generation, 
+    /** Told after every save the server activated (the client's link reminder counts the first one). */
+    onSaved = () => undefined) {
+        this.opts = opts;
+        this.api = api;
+        this.store = store;
+        this.subject = subject;
+        this.generation = generation;
+        this.onSaved = onSaved;
+    }
+    revisionKey(slot, device) {
+        return `${slot}\u0000${device ?? ''}`;
+    }
+    path(slot) {
+        const base = `/v1/apps/${encodeURIComponent(this.opts.slug)}/files`;
+        return slot === undefined ? base : `${base}/${encodeURIComponent(slot)}`;
+    }
+    uploadKey(uploadId) {
+        return `krtu:${this.opts.clientId}:upload:${uploadId}`;
+    }
+    async list() {
+        const answer = await this.api.player(this.path());
+        return answer.json;
+    }
+    /** A slot's current version; null when `ifNoneMatch` (a version id held) is still current. */
+    async read(slot, options = {}) {
+        const revisionKey = this.revisionKey(slot, options.device);
+        const revision = this.revisions.get(revisionKey) ?? 0;
+        const answer = await this.api.player(this.path(slot), {
+            query: { device: options.device, platform: this.opts.platform, ...options.deviceInfo },
+            headers: options.ifNoneMatch ? { 'if-none-match': options.ifNoneMatch } : {},
+            bytes: true,
+            accept: [304],
+        });
+        if (answer.status === 304)
+            return null;
+        const etag = answer.headers.get('etag');
+        const similar = answer.headers.get('x-krtu-similar-device') === 'true';
+        return {
+            bytes: answer.bytes ?? new Uint8Array(),
+            newerLocalSave: (this.revisions.get(revisionKey) ?? 0) !== revision,
+            similarDevice: similar,
+            version: etag
+                ? {
+                    id: etag.replace(/^W\//, '').replace(/"/g, ''),
+                    generation: Number(answer.headers.get('x-krtu-generation') ?? 0),
+                    sha256: answer.headers.get('x-krtu-sha256') ?? '',
+                    savedAt: answer.headers.get('x-krtu-saved-at') ?? '',
+                }
+                : 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.
+     */
+    async save(slot, data, options = {}) {
+        const owner = this.subject();
+        if (!owner)
+            throw new KrtuworksError('signed_out', 'No player is signed in.');
+        const revisionKey = this.revisionKey(slot, options.device);
+        this.revisions.set(revisionKey, (this.revisions.get(revisionKey) ?? 0) + 1);
+        const upload = {
+            uploadId: uuidV4(),
+            owner,
+            slot,
+            device: options.device ?? null,
+            base: options.base ?? null,
+            conditional: options.base !== undefined,
+            sha256: await sha256Hex(data),
+            bytes: data,
+            deviceInfo: options.deviceInfo ?? null,
+            savedAt: Date.now(),
+        };
+        await this.store.set(this.uploadKey(upload.uploadId), upload);
+        return this.send(upload);
+    }
+    async send(upload) {
+        const headers = { 'idempotency-key': upload.uploadId, 'content-type': 'application/octet-stream' };
+        if (upload.conditional) {
+            if (upload.base)
+                headers['if-match'] = upload.base;
+            else
+                headers['if-none-match'] = '*';
+        }
+        let answer;
+        try {
+            answer = await this.api.player(this.path(upload.slot), {
+                method: 'PUT',
+                query: { platform: this.opts.platform, build: this.opts.build, device: upload.device ?? undefined, ...(upload.deviceInfo ?? {}) },
+                headers,
+                body: upload.bytes,
+                accept: [202],
+            });
+        }
+        catch (err) {
+            if (isKrtuworksError(err) && !err.retryable)
+                await this.store.delete(this.uploadKey(upload.uploadId));
+            throw err;
+        }
+        if (answer.status === 201)
+            return this.done(upload, answer.json?.file ?? null);
+        return this.settle(upload, answer.json);
+    }
+    /** Reads an upload's state (200 again or 202) until it is final. */
+    async settle(upload, state) {
+        const started = Date.now();
+        const generation = this.generation();
+        let wait = 1000;
+        let current = state;
+        for (;;) {
+            const status = current?.status;
+            if (status === 'ACTIVATED')
+                return this.done(upload, null, current?.file);
+            if (status === 'REJECTED') {
+                await this.store.delete(this.uploadKey(upload.uploadId));
+                throw new KrtuworksError(String(current?.code ?? 'write_failed'), 'The save was refused.', 409, null, { upload: current });
+            }
+            if (Date.now() - started > POLL_LIMIT_MS) {
+                throw new KrtuworksError('upload_pending', 'The save is still being written; it is finished on a later launch.', 202, null, { uploadId: upload.uploadId });
+            }
+            await new Promise((r) => setTimeout(r, wait));
+            wait = Math.min(8000, wait * 2);
+            // Another player now: this upload is asked about with its own player's token on a later sign-in.
+            if (this.generation() !== generation)
+                throw new KrtuworksError('context_changed', 'The player changed while the save was being written; it is finished when that player signs in again.');
+            const answer = await this.api.player(`${this.path(upload.slot)}/uploads/${upload.uploadId}`);
+            current = answer.json;
+        }
+    }
+    async done(upload, file, ref) {
+        await this.store.delete(this.uploadKey(upload.uploadId));
+        this.onSaved();
+        if (file)
+            return file;
+        // An answer replayed from the upload's record names the version; read the slot for the whole of it.
+        const list = await this.list();
+        const slot = list.slots.find((s) => s.key === upload.slot);
+        const versions = [slot?.file, ...(slot?.devices ?? [])].filter((v) => !!v);
+        const found = versions.find((v) => v.id === ref?.id) ?? versions[0];
+        if (!found)
+            throw new KrtuworksError('file_not_found', 'The saved version is no longer the slot\'s.', 404);
+        return found;
+    }
+    /** Saves left unfinished by an earlier launch (an answer lost, a 202): finishes the signed-in player's. */
+    async resume() {
+        const owner = this.subject();
+        const out = [];
+        if (!owner)
+            return out;
+        for (const key of await this.store.keys(`krtu:${this.opts.clientId}:upload:`)) {
+            const upload = await this.store.get(key);
+            if (!upload || upload.owner !== owner)
+                continue;
+            try {
+                // Sent again with the same id and bytes: the server answers what the first one did.
+                await this.send(upload);
+                out.push({ uploadId: upload.uploadId, slot: upload.slot, outcome: 'saved' });
+            }
+            catch (err) {
+                const code = isKrtuworksError(err) ? err.code : 'error';
+                out.push({ uploadId: upload.uploadId, slot: upload.slot, outcome: code === 'upload_pending' || (isKrtuworksError(err) && err.retryable) ? 'waiting' : 'refused', code });
+            }
+        }
+        return out;
+    }
+    /** Saves of another player waiting on this device (a merged account's): the game asks the player what to keep. */
+    async waitingFor(owner) {
+        const out = [];
+        for (const key of await this.store.keys(`krtu:${this.opts.clientId}:upload:`)) {
+            const upload = await this.store.get(key);
+            if (upload?.owner === owner)
+                out.push({ uploadId: upload.uploadId, slot: upload.slot, savedAt: upload.savedAt });
+        }
+        return out;
+    }
+    /**
+     * 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.
+     */
+    async adoptWaiting(uploadId, base) {
+        const waiting = await this.store.get(this.uploadKey(uploadId));
+        if (!waiting)
+            throw new KrtuworksError('upload_not_found', 'No such waiting save on this device.', 404);
+        const saved = await this.save(waiting.slot, waiting.bytes, { base, device: waiting.device ?? undefined, deviceInfo: waiting.deviceInfo ?? undefined });
+        await this.store.delete(this.uploadKey(uploadId));
+        return saved;
+    }
+    /** A waiting save the player chose not to keep. */
+    async discardWaiting(uploadId) {
+        await this.store.delete(this.uploadKey(uploadId));
+    }
+    /** After a merge: keep `keep` (the slot's version or the merged one) over `current` (the one the player saw). */
+    async resolve(slot, keep, current) {
+        const answer = await this.api.player(`${this.path(slot)}/resolve`, { method: 'POST', json: { keep, current } });
+        return answer.json?.file;
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,129 @@
+import type { Clock } from './clock.js';
+import { type ResolvedOptions } from './config.js';
+import { type ProofPurpose } from './deviceKey.js';
+import type { KrtuStore } from './store.js';
+export type PlayerKind = 'guest' | 'account';
+export interface Player {
+    kind: PlayerKind;
+    /** The id this app knows the player by: the same on every device, never the Krtuworks ID itself. */
+    subject: string;
+    username: string | null;
+    picture: string | null;
+}
+interface IdentityMeta {
+    /** Bumped by every sign-in the player starts and every sign-out. */
+    epoch: number;
+    /** Players whose waiting queues move to the signed-in one once the server confirms a merge. */
+    waitingOwners: string[];
+    /** The age screen's answers for a guest not made yet: tried again on every launch. */
+    guestRequest: {
+        birthDate: string;
+        acceptedTerms: string;
+    } | null;
+}
+export type IdentityChange = {
+    type: 'signed_in';
+    player: Player;
+    promoted: boolean;
+} | {
+    type: 'guest';
+    player: Player;
+    created: boolean;
+} | {
+    type: 'signed_out';
+    reason: string;
+} | {
+    type: 'merged';
+    previousSubject: string;
+    mergedInto: string | null;
+} | {
+    type: 'deletion_pending';
+} | {
+    type: 'sanctioned';
+    reason: string | null;
+};
+export interface IdentityContext {
+    opts: ResolvedOptions;
+    store: KrtuStore;
+    fetch: typeof fetch;
+    clock: Clock;
+}
+export declare const DEVICE_KEY_GRANT = "urn:krtuworks:params:oauth:grant-type:device-key";
+/** `terms_required` names the documents in its text: `Accept the current terms: TERMS:v2 PRIVACY:v1.` */
+export declare function termsIn(text: string): string | null;
+/**
+ * Who plays: the tokens, the device's guest key, and every way a player arrives or leaves. One token
+ * chain per sign-in client; every write of it happens under one lock (Web Locks across tabs), and a
+ * refresh writes its answer only over the refresh token it spent.
+ */
+export declare class Identity {
+    private readonly ctx;
+    private tokens;
+    private refreshing;
+    private readonly listeners;
+    /** Bumped whenever the signed-in player changes; an answer made for another one is dropped. */
+    generation: number;
+    constructor(ctx: IdentityContext);
+    private key;
+    private get lockName();
+    private get issuer();
+    load(): Promise<Player | null>;
+    get player(): Player | null;
+    onChange(listener: (change: IdentityChange) => void): () => void;
+    private emit;
+    meta(): Promise<IdentityMeta>;
+    private saveMeta;
+    /** The owners whose queues wait for a merge check, with the one to drop once it is answered. */
+    waitingOwners(): Promise<string[]>;
+    /** The merge of `subject` is settled: it no longer waits, and its guest key (retired by the server) goes. */
+    forgetWaitingOwner(subject: string): Promise<void>;
+    /** Writes who is signed in (or nobody); a different player bumps the generation. */
+    private adopt;
+    /**
+     * A valid access token, refreshed first when it is about to expire (or `force`: the server said it was).
+     * One refresh at a time in this tab (single flight) and across tabs (the lock).
+     */
+    accessToken(force?: boolean): Promise<string>;
+    private token;
+    private tokensFrom;
+    private refresh;
+    /** A refresh the server refused, read by what it says; under the identity lock. */
+    private refused;
+    private markMergedLocked;
+    /** The server said the player's account went into another one (401 account_merged). */
+    markMerged(previousSubject: string, mergedInto: string | null): Promise<never>;
+    private challenge;
+    private proofWith;
+    /** A proof by this device's guest key for one of the guest's own calls (deletion, data copy). */
+    guestProof(purpose: ProofPurpose): Promise<string>;
+    /** The device-key grant; the caller holds the identity lock. */
+    private deviceKeyGrant;
+    /** A guest whose refresh token is gone signs in again with its key; under the identity lock. */
+    private guestAgain;
+    /**
+     * Plays as a guest: the device's key, made now if there is none. A new guest needs the age screen's
+     * answers (13 or older, the current terms); they are kept and tried again on later launches when the
+     * server could not make the guest now. A sign-in the player starts meanwhile wins: this
+     * guest is then not used.
+     */
+    signInAsGuest(input?: {
+        birthDate?: string;
+        acceptedTerms?: string;
+    }): Promise<Player>;
+    /**
+     * The address to send the player to. A guest playing on this device is carried along (`krtu_guest`):
+     * a new Krtuworks ID made there IS this guest, and signing in to an existing one folds the guest into
+     * it. Starting a sign-in bumps the epoch, so a guest still being made in the background is not used.
+     */
+    beginSignIn(options?: {
+        redirectUri?: string;
+        carryGuest?: boolean;
+    }): Promise<string>;
+    /** Finishes a sign-in from the address the player came back to. */
+    completeSignIn(callbackUrl: string | URL): Promise<Player>;
+    /** OIDC Core 3.1.3.7 for a token straight from the token endpoint over TLS: issuer, audience, nonce, time. */
+    private checkIdToken;
+    /** Forgets the player on this device (a guest's key stays: signing in as the guest again reaches it). */
+    signOut(): Promise<void>;
+}
+export {};