@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/docs/api/sdk-tools-client.md

@@ -0,0 +1,560 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk-tools/client`. Edit those, not this file. -->
+
+# `@seriousgaming/sdk-tools/client`
+
+Programmatic API for testing a game in-process.
+
+`createTestSession` runs the session the dev server runs (hooks, validators,
+endpoints, participants, undo, per-team ticks and timers) with no server
+around it. `startDevServer` runs the server too, isolated from any dev
+server already running for the package, for browser tests and recordings.
+
+@example
+
+```ts
+import { createTestSession } from '@seriousgaming/sdk-tools/client';
+import { fileURLToPath } from 'url';
+
+const session = await createTestSession({
+    packagePath: fileURLToPath(new URL('../..', import.meta.url)),
+});
+
+await session.send({ type: 'tick' });
+```
+
+Every export of `@seriousgaming/sdk-tools/client`, with the declaration it is published with. Anything tagged `@internal` is left out: it ships in the declarations, but is not part of the supported API and may change without a major release. For how the pieces fit together, see the [API reference](./index.md) and the guides it links to.
+
+## Functions
+
+### createStubServices
+
+The stubbed service callbacks: `generateText`, `generateSpeech` and `extractText`. Blob storage stays real, because it is local.
+
+```ts
+function createStubServices(
+    packagePath: string
+): Required<Pick<SignatureCallbacks, 'generateText' | 'generateSpeech' | 'extractText'>>;
+```
+
+### createTestSession
+
+Start a session on a package.
+
+```ts
+function createTestSession<Context = UntypedContext, Shared = UntypedContext>(
+    options: TestSessionOptions
+): Promise<TestSession<Context, Shared>>;
+```
+
+### startDevServer
+
+Start an isolated dev server for the package and resolve once it answers.
+
+```ts
+function startDevServer(options: DevServerOptions): Promise<DevServer>;
+```
+
+### stubGenerateText
+
+What a stubbed `generateText` answers for `request`: `[stub <hash>] <excerpt>`, an eight-digit hex hash of the whole request, then the first 60 characters of its prompt (the `prompt`, or the last `user` message's text) with whitespace collapsed, ending in `...` when it was cut. A request with a `jsonSchema` is answered with JSON that satisfies it.
+
+```ts
+function stubGenerateText(request: LLMGenerateOptions | string): LLMResponse;
+```
+
+## Classes
+
+### FakeClock
+
+A clock a test drives by hand.
+
+```ts
+class FakeClock implements Clock {
+    private current;
+    private nextId;
+    private scheduled;
+    constructor(startAt?: number);
+    now(): number;
+    schedule(fn: () => void, ms: number): Cancellable;
+    get pending(): number;
+    get nextDueAt(): number | null;
+    advance(ms: number): void;
+    set(timestamp: number): void;
+    clear(): void;
+}
+```
+
+## Interfaces
+
+### Clock
+
+```ts
+interface Clock {
+    now(): number;
+    schedule(fn: () => void, ms: number): Cancellable;
+}
+```
+
+### DevServer
+
+```ts
+interface DevServer {
+    url: string;
+    assetUrl: string;
+    stop(): Promise<void>;
+}
+```
+
+### DevServerOptions
+
+```ts
+interface DevServerOptions {
+    packagePath: string;
+    port?: number;
+    teams?: number;
+    participants?: ParticipantCounts;
+    scenarioId?: string | null;
+    locale?: string;
+    clock?: Clock;
+    callbacks?: Partial<SignatureCallbacks>;
+    reinitOnChange?: boolean;
+}
+```
+
+### SetDataOptions
+
+```ts
+interface SetDataOptions {
+    deletes?: DeletePath[];
+    as?: 'participant' | 'system';
+    participantId?: string;
+    ui?: string;
+}
+```
+
+### SetSharedDataOptions
+
+```ts
+interface SetSharedDataOptions {
+    deletes?: DeletePath[];
+    ui?: string;
+}
+```
+
+### SignatureCallbacks
+
+Every callback a runtime may offer logic: the engine, hooks, tick controllers and endpoints.
+
+```ts
+interface SignatureCallbacks {
+    generateText: LLMGenerateFunction;
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    getPastState: <T = Record<string, unknown>>(
+        query: PastStateQuery<T>
+    ) => Promise<PastStateEntry<T>[]>;
+    extractText?: ExtractTextFunction;
+    generateSpeech?: GenerateSpeechFunction;
+    writeBlob?: (
+        data: Uint8Array | ArrayBuffer,
+        options: {
+            name: string;
+            mimeType: string;
+            retention?: 'settings' | 'game';
+        }
+    ) => Promise<string>;
+}
+```
+
+### StateProjection
+
+```ts
+interface StateProjection {
+    projectionVersion: number;
+    game: {
+        identifier: string;
+        name: string;
+        scenarioId: string | null;
+    };
+    session: {
+        completedTicks: number;
+        mode: SessionMode;
+        waitingRoomOpen: boolean;
+        complete: boolean;
+        seed: string;
+        sessionKey: string;
+        locale: string;
+        runKind: RunKind;
+        maxTicks: number | null;
+        teamBounds: {
+            min?: number;
+            max: number;
+        };
+        inSetup: boolean;
+        pending?: PendingChanges;
+    };
+    teams: ProjectedTeam[];
+    shared: Record<string, Record<string, unknown>>;
+    sharedState?: unknown;
+    timer: TimerState | null;
+    settings: ResolvedSettings;
+    settingsWithoutSession: ResolvedSettings;
+    scenarioDrafts?: ScenarioDraft[];
+    faults: ArmedFault[];
+}
+```
+
+### TestSession
+
+A session to test against.
+
+```ts
+interface TestSession<Context = UntypedContext, Shared = UntypedContext> {
+    send(command: MutationCommand): Promise<MutationResult>;
+    send(command: QueryCommand): Promise<QueryResult>;
+    send(command: Command): Promise<MutationResult | QueryResult>;
+    state(): TestSessionState<Context, Shared>;
+    team(index: number): TestSessionTeam<Context>;
+    readonly shared: {
+        readonly context: Shared;
+    };
+    tick(options?: { team?: number }): Promise<MutationResult>;
+    requestTick(
+        team: number,
+        options?: {
+            participantId?: string;
+        }
+    ): Promise<MutationResult>;
+    setData(
+        team: number,
+        patch: ContextPatch<Context>,
+        options?: SetDataOptions
+    ): Promise<MutationResult>;
+    setSharedData(
+        patch: ContextPatch<Shared>,
+        options?: SetSharedDataOptions
+    ): Promise<MutationResult>;
+    settled(): Promise<void>;
+    close(): Promise<void>;
+}
+```
+
+### TestSessionOptions
+
+```ts
+interface TestSessionOptions {
+    packagePath: string;
+    teams?: number;
+    participants?: ParticipantCounts;
+    scenarioId?: string | null;
+    locale?: string;
+    callbacks?: Partial<SignatureCallbacks>;
+    services?: TestServices;
+    clock?: Clock;
+    play?: boolean;
+    platform?: {
+        apiKey?: string;
+        apiHost?: string;
+    };
+}
+```
+
+### TestSessionTeam
+
+One team as `TestSession.state` reports it, its context typed.
+
+```ts
+interface TestSessionTeam<Context = UntypedContext> extends Omit<ProjectedTeam, 'context'> {
+    context: Context;
+}
+```
+
+## Types
+
+### Command
+
+```ts
+type Command = MutationCommand | QueryCommand;
+```
+
+### ContextPatch
+
+A write to some of a context's capabilities, each merged one level deep as a surface's `setData` is: name the variables that change.
+
+```ts
+type ContextPatch<Context> = {
+    [K in keyof Context]?: Partial<Context[K]>;
+};
+```
+
+### DeletePath
+
+A path to remove, as a surface's `deletes` names one.
+
+```ts
+type DeletePath = string | string[];
+```
+
+### MutationCommand
+
+Every state-changing operation. Each one goes through the session's single queue, in submission order.
+
+```ts
+type MutationCommand =
+    | ({
+          type: 'tick';
+      } & TeamScope &
+          Actor)
+    | ({
+          type: 'undo';
+      } & TeamScope)
+    | ({
+          type: 'reset';
+      } & TeamScope)
+    | {
+          type: 'play';
+      }
+    | {
+          type: 'reconfigure';
+      }
+    | {
+          type: 'reinitialise';
+          teams?: number;
+          scenarioId?: string | null;
+          locale?: string;
+          participants?: number | number[];
+      }
+    | ({
+          type: 'updateContext';
+          payload: Record<string, unknown>;
+          deletes?: (string | string[])[];
+          uiIdentifier?: string;
+          sessionUiIdentifier?: string;
+      } & TeamScope &
+          Actor)
+    | {
+          type: 'updateSharedContext';
+          uiIdentifier?: string;
+          endpointIdentifier?: string;
+          payload: Record<string, unknown>;
+          deletes?: (string | string[])[];
+      }
+    | {
+          type: 'updateSettings';
+          uiIdentifier?: string;
+          payload: Record<string, unknown>;
+      }
+    | {
+          type: 'editScenario';
+          scenarioId: string | null;
+      }
+    | {
+          type: 'updateScenarioDraft';
+          uiIdentifier?: string;
+          scenarioId: string | null;
+          payload: Record<string, unknown>;
+      }
+    | {
+          type: 'addTeam';
+          name?: string;
+          participants?: number;
+      }
+    | {
+          type: 'removeTeam';
+          teamIndex: number;
+      }
+    | {
+          type: 'renameTeam';
+          teamId: string;
+          name: string;
+      }
+    | ({
+          type: 'renameOwnTeam';
+          name: string;
+      } & Actor)
+    | {
+          type: 'addParticipant';
+          teamId: string;
+          name?: string;
+      }
+    | {
+          type: 'renameParticipant';
+          participantId: string;
+          name: string;
+      }
+    | {
+          type: 'moveParticipant';
+          participantId: string;
+          teamId: string;
+      }
+    | {
+          type: 'setWaitingRoom';
+          open: boolean;
+      }
+    | {
+          type: 'resetWalkthrough';
+      }
+    | {
+          type: 'selectScenario';
+          scenarioId: string | null;
+      }
+    | {
+          type: 'setLocale';
+          locale: string;
+      }
+    | ({
+          type: 'pauseTimer';
+      } & TeamScope)
+    | ({
+          type: 'resumeTimer';
+      } & TeamScope)
+    | ({
+          type: 'extendTick';
+          byMs: number;
+      } & TeamScope)
+    | {
+          type: 'advanceClock';
+          byMs: number;
+      }
+    | {
+          type: 'armFault';
+          fault: FaultKind;
+          times?: number;
+          reason?: string;
+      }
+    | {
+          type: 'disarmFault';
+          fault: FaultKind;
+      };
+```
+
+### MutationResult
+
+What a mutation settled as.
+
+```ts
+type MutationResult =
+    | {
+          ok: true;
+          committedAtTick?: number;
+      }
+    | {
+          ok: false;
+          outcome: MutationOutcome;
+      };
+```
+
+### ParticipantCounts
+
+How many participants to seed each team with: one count for every team, or one per team in stable index order.
+
+```ts
+type ParticipantCounts = number | number[];
+```
+
+### QueryCommand
+
+Every read. None of these enters the queue: a read is never blocked behind a mutation, so a tick in flight must not delay one.
+
+```ts
+type QueryCommand =
+    | {
+          type: 'getState';
+      }
+    | ({
+          type: 'callEndpoint';
+          endpointIdentifier: string;
+          request: unknown;
+          uiIdentifier?: string;
+          external?: boolean;
+          principal?: {
+              kind: string;
+              id: string;
+              name?: string;
+          };
+          scenarioId?: string | null;
+      } & TeamScope &
+          Actor)
+    | ({
+          type: 'getPastState';
+          query: PastStateQuery;
+          uiIdentifier?: string;
+      } & Actor)
+    | ({
+          type: 'getAllTeamsParticipants';
+          uiIdentifier?: string;
+      } & Actor)
+    | {
+          type: 'getEndpointAudit';
+      }
+    | {
+          type: 'listEndpoints';
+          external?: boolean;
+      };
+```
+
+### QueryResult
+
+What a query answered with.
+
+```ts
+type QueryResult =
+    | {
+          type: 'state';
+          state: StateProjection;
+      }
+    | {
+          type: 'endpoint';
+          response: unknown;
+          blobs?: Record<string, string>;
+      }
+    | {
+          type: 'endpointFailure';
+          failure: EndpointFailure;
+      }
+    | {
+          type: 'pastState';
+          entries: PastStateEntry[];
+      }
+    | {
+          type: 'participants';
+          participants: unknown[];
+      }
+    | {
+          type: 'endpointAudit';
+          entries: EndpointAuditEntry[];
+      }
+    | {
+          type: 'endpoints';
+          endpoints: EndpointListing[];
+      };
+```
+
+### TestServices
+
+Where a test session's service callbacks go (`TestSessionOptions.services`).
+
+```ts
+type TestServices = 'stub' | 'platform';
+```
+
+### TestSessionState
+
+The session's observable state, with each team's context and the shared store typed.
+
+```ts
+type TestSessionState<Context = UntypedContext, Shared = UntypedContext> = Omit<
+    StateProjection,
+    'teams' | 'shared'
+> & {
+    teams: TestSessionTeam<Context>[];
+    shared: Shared;
+};
+```
+
+### UntypedContext
+
+A capability context as the projection carries it, before a game's types narrow it.
+
+```ts
+type UntypedContext = Record<string, Record<string, unknown>>;
+```