@krtuworks/sdk 0.0.0-stage → 1.0.0

package/AGENTS.md

@@ -0,0 +1,48 @@
+# Krtuworks SDK for JavaScript and TypeScript: instructions for coding agents
+
+`@krtuworks/sdk` connects a web game or app (browser or Node 20+) to Krtuworks: Krtuworks ID sign-in, guests, sessions, events, stats and achievements, cloud files, remote config and A/B tests. It has no dependencies.
+
+## Before you start
+- Check the project folder. A `*.uproject` file means Unreal: use the Krtuworks Unreal plugin. `ProjectSettings/ProjectVersion.txt` means Unity: use `com.krtuworks.sdk`. Only a `package.json` with neither means this package.
+- Get the app's `krtuworks-config.json` from the partner console (the app's Credentials page) or from the Krtuworks MCP tool `get_setup`. Never write it by hand and never guess an id in it. It holds no secret, so it may be committed.
+- In a browser, the app's web client must list the page's origin and the sign-in return address. Krtuworks sets them up on the Credentials page; a sign-in from an origin that is not listed fails.
+
+## Required steps
+1. `npm install @krtuworks/sdk`
+2. Put `krtuworks-config.json` where the app can import it.
+3. Call `Krtuworks.initialize` once, when the app starts, and keep the client it returns:
+   ```ts
+   import { Krtuworks } from '@krtuworks/sdk';
+   import config from './krtuworks-config.json';
+
+   const krtu = await Krtuworks.initialize({ config, environment: 'TEST', platform: 'WEB', build: '1.4.2', redirectUri: 'https://example.com/signed-in' });
+   ```
+   - `environment`: `TEST` while developing, `LIVE` in the released build. Test players and their data never reach LIVE.
+   - `build`: the version label of this build. Give each released build its own label.
+   - `platform`: where the app runs (`WEB`, `WINDOWS`, `MACOS`, `LINUX`, `IOS`, `ANDROID`, `STEAM` …).
+   - `redirectUri` (web): the sign-in return address. It must be one of the web client's registered https return addresses, set on the partner console's Credentials page. `signIn()` throws without it; `signIn({ redirectUri })` can give it later.
+   - Under Node there is no window, so the SDK uses the native client (the config's `clientId`, not `webClientId`) and needs no `redirectUri`. Use `platform: 'WINDOWS'`, `'MACOS'` or `'LINUX'`, not `'WEB'`.
+4. Sign the player in. `await krtu.signInAsGuest({ birthDate: 'YYYY-MM-DD' })` makes a guest account with no sign-in screen: the app's age screen asks the birth date (13 or older) and shows the Krtuworks ID Terms and Privacy Notice, which the player accepts (`acceptedTerms` defaults to `CURRENT_TERMS`). On the next start the same device signs in again with no input. `await krtu.signIn()` opens Krtuworks ID; on the return page call `await krtu.completeSignIn()`. A guest who signs in keeps their progress.
+5. Call `await krtu.shutdown()` when the app closes (Node). In a browser the SDK sends on its own when the page is hidden.
+
+## Rules
+- Events: `krtu.track(type, data)` with a ready-made family (`screen_view`, `economy`, `item`, `performance`, `settings`, `error` …) or a type defined on the console. It returns `false` when nothing was kept (the module is off, statistics are switched off, or the player opted out); that is not an error.
+- Stats and achievements: `incrementStat`, `setStat`, `unlockAchievement`. They are kept on the device until the server has them and are never counted twice: do not add your own retry.
+- Leaderboards: `submitScore(key, value, { details? })` (a whole number below 10^15, details 1 to 64 bytes) is kept on the device like a stat and never lost; the server decides what the board keeps. Read with `getLeaderboards()` (the player's own score and rank per board) and `getLeaderboardEntries(key, { scope: 'global' | 'around', limit, offset })`. Names shown are Krtuworks usernames (`null`: show "Player"). Reads throw `module_disabled` while the leaderboards module is off; scores wait. The SDK never writes scores to a platform; the server mirrors them.
+- Rich presence (games only): `setPresence(key, params?)` answers `{ applied, reason? }` and never throws for those reasons (`not_game`, `module_disabled`, `hidden`, `unknown_state`, `param_missing`, `states_unknown`). The states are declared on the console; `LEVEL` (the open `level.start`) and `SESSION_MINUTES` fill themselves. A browser has no platform presence, so a call that passes every rule answers `no_platform`; `clearPresence()` and `setPresenceGroup()` do nothing there. The player's choice: `presenceVisible()` (cached, `null` until known) and `await setPresenceVisible(bool)`; false makes `setPresence` answer `hidden`.
+- DLC ownership (games only): `ownsDlc(key)` takes the DLC's product key from the console and answers at once with a boolean (`false` for an unknown key). It reads what the server confirmed in this launch, else the last server answer kept on the device, so it works offline after one online launch. `entitlements()` lists the licences (`sku` `base` first, then the DLCs; `status` `ACTIVE`, `REVOKED` or `null`; `checked` is true for what the server confirmed in this launch) and `await refreshEntitlements()` asks the server now. Do not keep your own ownership flags.
+- Levels and deaths (`krtu.level.*`, `death`) are for games only; in an app they do nothing.
+- Cloud files: `krtu.files.save(slot, bytes)` and `krtu.files.read(slot)`. A save conflict (`file_conflict`) carries the current version: let the player choose, do not overwrite.
+- Check `krtu.gate()` at start: it tells about maintenance and a required update.
+- Errors are `KrtuworksError` with a `code`. A network error does not lose data: the SDK keeps what it has and sends it later.
+- Never put a server key or any other Krtuworks secret into app code. This package needs none.
+
+## Verify
+Run the validator against TEST. It checks the config, the build label and the platform, then makes a test round (sign-in, session, event, remote config, cloud save, progress, bug report) with the app's own setup:
+```ts
+import { validate } from '@krtuworks/sdk';
+
+const report = await validate({ config, platform: 'WEB', build: '1.4.2', redirectUri: 'https://example.com/signed-in' });
+console.log(report.ok, report.checks);
+```
+`report.ok` must be `true`. Each check is `PASSED`, `FAILED` (with `detail`) or `SKIPPED` (a module that is off, an app with no save slots or no achievements). A build whose report is not green is not released in LIVE. In a browser (the web client) the validator also needs an https `redirectUri`, one of the web client's registered return addresses.

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `@krtuworks/sdk`. Versions follow semantic versioning; a breaking change is marked **Breaking**.
+
+## Unreleased
+
+First release.
+
+### Added
+- `Krtuworks.initialize` with the app's `krtuworks-config.json`, TEST and LIVE environments, the app's type (`GAME`, `MOBILE_APP`, `WEB_APP`, `DESKTOP_APP`).
+- Guests with a device key (no sign-in screen), Krtuworks ID sign-in in the browser (PKCE), a guest's progress kept when they sign in.
+- Sessions, events (ready-made families and the app's own types), levels and deaths for games.
+- Stats and achievements kept on the device until the server has them, never counted twice; platform achievement sync (with the open session: the server mirrors only with the platform account the session proved).
+- Cloud saves with conflict handling and resumable uploads.
+- Remote config, SDK modules, maintenance and required-update gate, A/B tests, player profile card.
+- Bug reports with a screenshot and the "fixed" notice; profile picture reports.
+- A guest's account deletion, its cancellation and data copy from inside the app.
+- The validator (`validate`) for the release report.
+- Leaderboards (the `leaderboards` module): `submitScore` kept on the device until the server has it (a lost answer goes again with the same op id), `getLeaderboards()` and `getLeaderboardEntries()` (global or around the player).
+- Rich presence (games only): `setPresence`, `clearPresence`, `setPresenceGroup`, `presenceVisible`, `setPresenceVisible` and the `presence` module. The states and the player's choice are kept per player and revalidated with the ETag; a browser has no platform presence, so a valid `setPresence` answers `no_platform`.
+- `getProgress()` stats carry `platformIds` (a stat's name on Steam).
+- DLC ownership: `entitlements()` (the licences the server last said, kept per player and environment on the device), `refreshEntitlements()` (`GET /v1/me/entitlements`) and `ownsDlc(key)`. A browser has no platform client to ask, so it answers with what the server confirmed in this launch, else the last server answer kept from an earlier launch.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+Krtuworks SDK
+Copyright 2026 Krtuworks LLC
+
+This product includes software developed at Krtuworks LLC (https://krtuworks.com).
+"Krtuworks" and the Krtuworks logo are trademarks of Krtuworks LLC; the Apache License does not grant
+permission to use them (section 6).

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# Krtuworks SDK for JavaScript and TypeScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@krtuworks/sdk` connects a web game or app (browser or Node 20+) to Krtuworks: Krtuworks ID sign-in and guests with no sign-in screen, sessions, events and dashboards, stats, achievements and leaderboards, cloud saves, remote config and A/B tests, bug reports and the release report. It has no dependencies.
+
+```sh
+npm install @krtuworks/sdk
+```
+
+```ts
+import { Krtuworks } from '@krtuworks/sdk';
+import config from './krtuworks-config.json';
+
+const krtu = await Krtuworks.initialize({ config, environment: 'TEST', platform: 'WEB', build: '1.0.0', redirectUri: 'https://example.com/signed-in' });
+await krtu.signInAsGuest({ birthDate: '2000-01-31' });
+krtu.track('screen_view', { screen: 'menu' });
+```
+
+Your app's `krtuworks-config.json` comes from the app's Credentials page in the [partner console](https://partner.krtuworks.com).
+
+- Documentation: [partner.krtuworks.com/docs](https://partner.krtuworks.com/docs)
+- Coding agents: [`AGENTS.md`](AGENTS.md)
+- Changes: [`CHANGELOG.md`](CHANGELOG.md)
+- Support: support@krtuworks.com
+
+Licensed under the [Apache License 2.0](LICENSE). The Krtuworks name and logo are not covered by the licence ([`NOTICE`](NOTICE)).

package/dist/api.d.ts

@@ -0,0 +1,34 @@
+import type { Clock } from './clock.js';
+import type { ResolvedOptions } from './config.js';
+import type { Identity } from './identity.js';
+import { type Answer } from './transport.js';
+export interface PlayerCall {
+    method?: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    json?: unknown;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    /** Read the body as bytes (a file). */
+    bytes?: boolean;
+    keepalive?: boolean;
+    /** Statuses that are answers, not failures (304, 202 …); 2xx always are. */
+    accept?: number[];
+}
+/** The player's calls to the server (`/v1`, Bearer + X-Krtu-Build). */
+export declare class Api {
+    private readonly opts;
+    private readonly identity;
+    private readonly fetchFn;
+    private readonly clock;
+    constructor(opts: ResolvedOptions, identity: Identity, fetchFn: typeof fetch, clock: Clock);
+    url(path: string, query?: PlayerCall['query']): string;
+    /** A call without a player (the remote config). */
+    open(path: string, call?: PlayerCall): Promise<Answer>;
+    /**
+     * A player's call. An expired or revoked token is refreshed once and the call made again; a merged
+     * account is reported to the identity; an answer that arrives after the player changed is dropped
+     * (`context_changed`), so it can never land in another player's state.
+     */
+    player(path: string, call?: PlayerCall): Promise<Answer>;
+    private attempt;
+}

package/dist/api.js

@@ -0,0 +1,61 @@
+import { KrtuworksError } from './errors.js';
+import { errorOf, send } from './transport.js';
+/** The player's calls to the server (`/v1`, Bearer + X-Krtu-Build). */
+export class Api {
+    opts;
+    identity;
+    fetchFn;
+    clock;
+    constructor(opts, identity, fetchFn, clock) {
+        this.opts = opts;
+        this.identity = identity;
+        this.fetchFn = fetchFn;
+        this.clock = clock;
+    }
+    url(path, query) {
+        const url = new URL(`${this.opts.devOrigin}${path}`);
+        for (const [k, v] of Object.entries(query ?? {}))
+            if (v !== undefined && v !== null)
+                url.searchParams.set(k, String(v));
+        return url.toString();
+    }
+    /** A call without a player (the remote config). */
+    async open(path, call = {}) {
+        const answer = await send(this.fetchFn, this.clock, this.url(path, call.query), { method: call.method ?? 'GET', headers: { ...call.headers } });
+        if (answer.status >= 400 && !call.accept?.includes(answer.status))
+            throw errorOf(answer);
+        return answer;
+    }
+    /**
+     * A player's call. An expired or revoked token is refreshed once and the call made again; a merged
+     * account is reported to the identity; an answer that arrives after the player changed is dropped
+     * (`context_changed`), so it can never land in another player's state.
+     */
+    async player(path, call = {}) {
+        const generation = this.identity.generation;
+        const subject = this.identity.player?.subject ?? null;
+        let answer = await this.attempt(path, call, false);
+        if (answer.status === 401) {
+            const err = errorOf(answer);
+            if (err.code === 'account_merged' && subject)
+                await this.identity.markMerged(subject, typeof err.details.mergedInto === 'string' ? err.details.mergedInto : null);
+            if (err.code === 'token_expired' || err.code === 'token_revoked' || err.code === 'invalid_token')
+                answer = await this.attempt(path, call, true);
+        }
+        if (this.identity.generation !== generation)
+            throw new KrtuworksError('context_changed', 'The player changed while the call ran; its answer was dropped.');
+        if ((answer.status >= 300 || answer.status < 200) && !call.accept?.includes(answer.status))
+            throw errorOf(answer);
+        return answer;
+    }
+    async attempt(path, call, forceRefresh) {
+        const token = await this.identity.accessToken(forceRefresh);
+        const headers = { authorization: `Bearer ${token}`, 'x-krtu-build': this.opts.build, ...call.headers };
+        let body = call.body;
+        if (call.json !== undefined) {
+            headers['content-type'] = 'application/json';
+            body = JSON.stringify(call.json);
+        }
+        return send(this.fetchFn, this.clock, this.url(path, call.query), { method: call.method ?? 'GET', headers, body, bytes: call.bytes, keepalive: call.keepalive });
+    }
+}

package/dist/avatarReports.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reporting another player's profile picture (POST /v1/players/:subject/avatar-report): a reason from a
+ * fixed list and an optional note. Krtuworks reviews the picture; the player who reports is never told
+ * an outcome. One report per player and picture, at most 10 a day.
+ */
+export declare const AVATAR_REPORT_REASONS: readonly ["SEXUAL", "HATE", "VIOLENCE", "IMPERSONATION", "SPAM", "OTHER"];
+export type AvatarReportReason = (typeof AVATAR_REPORT_REASONS)[number];
+export declare const AVATAR_REPORT_NOTE_MAX = 300;
+export declare function avatarReportBody(subject: string, reason: string, note?: string | null): {
+    path: string;
+    json: {
+        reason: AvatarReportReason;
+        note?: string;
+    };
+};

package/dist/avatarReports.js

@@ -0,0 +1,18 @@
+import { KrtuworksError } from './errors.js';
+/**
+ * Reporting another player's profile picture (POST /v1/players/:subject/avatar-report): a reason from a
+ * fixed list and an optional note. Krtuworks reviews the picture; the player who reports is never told
+ * an outcome. One report per player and picture, at most 10 a day.
+ */
+export const AVATAR_REPORT_REASONS = ['SEXUAL', 'HATE', 'VIOLENCE', 'IMPERSONATION', 'SPAM', 'OTHER'];
+export const AVATAR_REPORT_NOTE_MAX = 300;
+export function avatarReportBody(subject, reason, note) {
+    if (typeof subject !== 'string' || !subject || subject.length > 200)
+        throw new KrtuworksError('invalid_request', 'Name the player by the subject your app knows them by.', 400);
+    if (!AVATAR_REPORT_REASONS.includes(reason))
+        throw new KrtuworksError('invalid_request', `reason is one of ${AVATAR_REPORT_REASONS.join(', ')}.`, 400);
+    const trimmed = typeof note === 'string' ? note.trim() : '';
+    if (trimmed.length > AVATAR_REPORT_NOTE_MAX)
+        throw new KrtuworksError('invalid_request', `A note is at most ${AVATAR_REPORT_NOTE_MAX} characters.`, 400);
+    return { path: `/v1/players/${encodeURIComponent(subject)}/avatar-report`, json: { reason: reason, ...(trimmed ? { note: trimmed } : {}) } };
+}

package/dist/bugs.d.ts

@@ -0,0 +1,114 @@
+import type { Api } from './api.js';
+import type { ResolvedOptions } from './config.js';
+import type { EventPosition, WireEvent } from './events.js';
+import type { KrtuStore } from './store.js';
+/** The fixed categories: the same menu in every app. */
+export declare const BUG_CATEGORIES: readonly ["CRASH", "GAMEPLAY", "GRAPHICS", "AUDIO", "PERFORMANCE", "CONTROLS", "TEXT", "OTHER"];
+export type BugCategory = (typeof BUG_CATEGORIES)[number];
+export interface BugReportInput {
+    category: BugCategory;
+    /** What the player wrote, 1-4000 characters. */
+    description: string;
+    /** A picture of the screen (PNG, JPEG or WebP, at most 5 MB); the player may leave it out. */
+    screenshot?: Uint8Array | ArrayBuffer | Blob;
+    /** Where the player is; the level in play when not given. */
+    level?: string;
+    position?: EventPosition;
+    /** The frame rate now; the last one the performance family told when not given. */
+    fps?: number;
+}
+/** A report as its player sees it: never the notes, the assignee or the labels. */
+export interface BugReportView {
+    id: string;
+    category: BugCategory;
+    description: string | null;
+    platform: string;
+    build: string;
+    createdAt: string;
+    screenshot: boolean;
+    /** NEW, INVESTIGATING, RESOLVED, CANNOT_REPRODUCE or DUPLICATE; a duplicate shows its original's. */
+    status: string;
+    fixedIn: string | null;
+    fixedAt: string | null;
+    duplicate: boolean;
+}
+export interface BugFlushResult {
+    sent: number;
+    /** Reports or screenshots the server refused for good; they are not sent again. */
+    dropped: Array<{
+        reportId: string;
+        code: string;
+        screenshotOnly: boolean;
+    }>;
+    stoppedBy?: string;
+}
+interface FixedState {
+    told: string[];
+}
+/** The picture's type from its first bytes (what the server takes). */
+export declare function screenshotType(bytes: Uint8Array): string | null;
+/**
+ * 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 declare function reportBody(input: BugReportInput, context: {
+    reportId: string;
+    opts: ResolvedOptions;
+    level: string | null;
+    fps: number | null;
+    events: Record<string, unknown>[];
+    log: string;
+}): Record<string, unknown>;
+/**
+ * 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 declare function newlyFixed(reports: BugReportView[], state: FixedState | undefined): {
+    fixed: BugReportView[];
+    state: FixedState;
+};
+/**
+ * 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 declare class BugReports {
+    private readonly opts;
+    private readonly store;
+    private readonly api;
+    private readonly owner;
+    private readonly subject;
+    private readonly events;
+    private logLines;
+    private logChars;
+    private lastFps;
+    /** Reports that wait before their next try (in memory: a new launch tries them all again). */
+    private readonly waitUntil;
+    private readonly fixedListeners;
+    constructor(opts: ResolvedOptions, store: KrtuStore, api: Api, owner: () => string, subject: () => string | null);
+    private prefix;
+    private fixedKey;
+    /** An event the SDK kept, for the next report's "last events". */
+    noteEvent(event: WireEvent): void;
+    /** A line for the next report's log (the app's own, and the errors the SDK told). */
+    log(message: string): void;
+    report(input: BugReportInput, level: string | null): Promise<{
+        reportId: string;
+    }>;
+    /** Reports (with their screenshots) that wait on this device for the player, or for the first player. */
+    waiting(): Promise<number>;
+    /** Hands one owner's waiting reports to another (the anonymous queue to the first player, a confirmed merge). */
+    move(from: string, to: string): Promise<void>;
+    flush(now?: number): Promise<BugFlushResult>;
+    /** The player's reports in this app and environment, newest first; fixes not told yet are told. */
+    mine(): Promise<BugReportView[]>;
+    /** At a player's arrival: only when this device keeps a record for them (they reported here, or the app read their reports). */
+    checkFixed(): Promise<void>;
+    private tellFixed;
+    onFixed(listener: (report: BugReportView) => void): () => void;
+    resetBackoff(): void;
+}
+export {};