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

package/lib/build/endpoints.d.ts

@@ -0,0 +1,421 @@
+import { type MutationOutcome } from '../ui/mutation-outcome.js';
+import type { Participant, SignatureCallbacks, TeamInfo } from './callbacks.js';
+import type { ContextDeletePath } from './context-merge.js';
+import type { EndpointActionType, EndpointDefinition } from './resource-schema.js';
+import type { LogicMeta, SessionMode, ViewerRole } from './signatures.js';
+import type { TimerState } from './timer.js';
+/**
+ * Host-issued identity of the caller invoking an endpoint. Every field is set
+ * by the host from session bookkeeping — iframe-supplied values are never part
+ * of the trust chain.
+ */
+export interface EndpointCaller {
+    /**
+     * Session this call belongs to. Absent on a call from the scenario editor,
+     * which edits a scenario rather than a session and runs with none (§6.5).
+     */
+    sessionId?: string;
+    /**
+     * The caller's own team: present for a participant or an observer, absent
+     * for a facilitator, an author or an external caller, who are on no team.
+     *
+     * Not the team the call acts on. That is `team`, set on every team-scoped
+     * call whoever makes it, so a facilitator's call to a team-scoped endpoint
+     * has `team` and no `caller.teamId`, and a participant's has both, equal.
+     */
+    teamId?: string;
+    /** Participant identifier, when the caller is a participant. */
+    playerId?: string;
+    /** Who is calling: see {@link EndpointCallerRole}. */
+    role: EndpointCallerRole;
+    /**
+     * Identifier of the user interface that invoked the endpoint. Absent when
+     * no surface made the call, as for an `external` caller.
+     */
+    userInterfaceIdentifier?: string;
+    /**
+     * Who is behind an `external` call, as the host authenticated them: an AI
+     * agent, an API key, an integration. Absent on every other role, and on
+     * an external call from a host that cannot say.
+     *
+     * The role alone says only that the caller is outside the game, which is
+     * too little for an endpoint that should answer one agent differently from
+     * another, or for anyone reading back afterwards who changed what.
+     */
+    principal?: EndpointPrincipal;
+}
+/**
+ * Who is calling an endpoint (§6.12).
+ *
+ * - `participant`: a participant's game or waiting room UI.
+ * - `observer`: a game UI rendered for an observer (§13.3).
+ * - `facilitator`: the session UI, the setup UI, the CLI, or any other
+ *   system-trusted path inside a session.
+ * - `author`: the scenario editor, used by someone creating a scenario, who
+ *   need not be a facilitator and has no session.
+ * - `external`: a caller outside the game, such as a facilitator's AI agent or
+ *   a platform API, which only an endpoint whose `visibility` is `external`
+ *   receives.
+ */
+export type EndpointCallerRole = ViewerRole | 'facilitator' | 'author' | 'external';
+/** The host's account of who made an `external` call (§6.12). */
+export interface EndpointPrincipal {
+    /** What kind of caller this is, e.g. `agent`, `apiKey`, `integration`. */
+    kind: string;
+    /** Stable for that caller across calls. Opaque: the host's, not the game's. */
+    id: string;
+    /** A display name, where the host has one. */
+    name?: string;
+}
+/**
+ * One team's values, for a session-scoped endpoint (§6.12).
+ *
+ * A session-scoped call acts on the whole session, so it has no board of its
+ * own and a `team`, `team-readable` or `private` declaration has no single copy
+ * to resolve against. Those arrive here instead, one entry per team.
+ */
+export interface EndpointTeamEntry<TContext> extends TeamInfo {
+    /** Exactly this endpoint's non-shared declarations, for this team. */
+    context: TContext;
+}
+/**
+ * Where the session stands when an endpoint is called (§6.12).
+ *
+ * An endpoint runs between ticks rather than as part of one, so it has no
+ * `RunMeta` and nothing else tells it what round it is, whether the waiting
+ * room is open or whether the game has finished. A caller outside the game,
+ * an agent most of all, commonly asks exactly that before it acts.
+ */
+export interface EndpointSession {
+    mode: SessionMode;
+    /**
+     * Ticks the session has completed: the shared clock, or in independent
+     * mode the furthest any team has reached. Each team's own is on its entry.
+     */
+    completedTicks: number;
+    /** The game's tick limit, or null when completion is not a tick count. */
+    maxTicks: number | null;
+    waitingRoomOpen: boolean;
+    /** True only once every team is complete. */
+    complete: boolean;
+    /** Every team, in stable-index order. Status only: no context. */
+    teams: EndpointTeamStatus[];
+}
+/** One team's standing, for {@link EndpointSession}. */
+export interface EndpointTeamStatus extends TeamInfo {
+    /** Ticks this team has completed. Equal to the session's outside independent mode. */
+    completedTicks: number;
+    complete: boolean;
+    /** The automatic timer this team runs on, or null when there is none. */
+    timer: TimerState | null;
+    /**
+     * The team's participants. Present only when the endpoint declares
+     * `roster: true`: the list grows with the cohort, and most endpoints do not
+     * need it.
+     */
+    participants?: Participant[];
+}
+/**
+ * A session action an endpoint returns for the runtime to carry out (§6.12).
+ *
+ * Each is an operation a facilitator's session surface can already perform,
+ * and the runtime holds it to the same rules: a tick past the limit is refused
+ * here exactly as it is from the console. Returned rather than called, so a
+ * handler stays a function of its arguments and nothing happens until the
+ * whole result has been checked.
+ *
+ * `teamId` defaults to the call's own team on a team-scoped endpoint. On a
+ * session-scoped one an omitted `teamId` means the whole session where the
+ * action has a session-wide form (`tick`, the timer actions) and is refused
+ * where it has none (`renameTeam`).
+ */
+export type EndpointAction = {
+    type: 'tick';
+    teamId?: string;
+} | {
+    type: 'setWaitingRoom';
+    open: boolean;
+} | {
+    type: 'pauseTimer';
+    teamId?: string;
+} | {
+    type: 'resumeTimer';
+    teamId?: string;
+} | {
+    type: 'extendTick';
+    byMs: number;
+    teamId?: string;
+} | {
+    type: 'renameTeam';
+    name: string;
+    teamId?: string;
+} | {
+    type: 'moveParticipant';
+    participantId: string;
+    teamId: string;
+} | {
+    type: 'addTeam';
+    name?: string;
+} | {
+    type: 'setLocale';
+    locale: string;
+};
+/** What an endpoint call acts on (§6.12). Absent in a bundle means `team`. */
+export type EndpointScope = NonNullable<EndpointDefinition['scope']>;
+/** The arguments every endpoint receives, whatever its scope. */
+export interface EndpointBaseArgs<TRequest, TContext, TCallbacks = SignatureCallbacks, TSettings = Record<string, never>> {
+    /** Request payload, validated against the endpoint's `requestSchema`. */
+    request: TRequest;
+    /** Scoped snapshot of the capabilities listed in the endpoint's `reads`. */
+    context: TContext;
+    /** Guarded subset of runtime callbacks for the endpoint's declared `uses`. */
+    callbacks: TCallbacks;
+    /** Host-issued identity of the caller invoking this endpoint. */
+    caller: EndpointCaller;
+    /**
+     * The settings resources this endpoint declared in `settings`, keyed by
+     * identifier (§8). Read-only.
+     */
+    settings: TSettings;
+    /**
+     * The facts true of the whole run: its locale, its seed, whether it is the
+     * game being played or a walkthrough beside it, and when this call started
+     * (`now`, the same for `Plan` and `Respond`).
+     *
+     * An endpoint is invoked by a surface rather than as part of a tick, so
+     * this is {@link LogicMeta} rather than the `RunMeta` an engine receives.
+     */
+    meta: LogicMeta;
+    /**
+     * The participants this call covers, taken as the call is made (§6.12):
+     * the addressed team's on a team-scoped endpoint, every participant in the
+     * session on a session-scoped one. Read-only, and a copy per call.
+     * `Respond` reads the roster again once the effects land, as it does
+     * `context` and `session`.
+     *
+     * Always present, unlike `session.teams[].participants`, which `roster:
+     * true` adds so a team-scoped endpoint can see other teams' rosters.
+     */
+    participants: readonly Readonly<Participant>[];
+    /** Where the session stands as the call is made. */
+    session: EndpointSession;
+}
+/** What a team-scoped endpoint receives beyond the base arguments. */
+export interface TeamEndpointArgs {
+    /**
+     * The team whose board `context` was read from. The runtime sets it on
+     * every team-scoped call, whoever made it.
+     *
+     * Separate from `caller`, which says who is calling: a facilitator's agent
+     * or the CLI calls on a team's behalf without being on it, so it has no
+     * `caller.teamId`. Carries the index and display name an endpoint needs to
+     * answer in words, having no other route to a team's name.
+     */
+    team: TeamInfo;
+}
+/** What a session-scoped endpoint receives beyond the base arguments. */
+export interface SessionEndpointArgs<TTeamContext> {
+    /**
+     * Every team's values, when the endpoint declared at least one non-shared
+     * capability (§6.12). Stable-index order.
+     *
+     * Absent when every declaration is shared: a shared capability holds one
+     * value for the session, so it arrives on `context` where a single value is
+     * the right shape.
+     */
+    teams?: EndpointTeamEntry<TTeamContext>[];
+}
+/**
+ * Argument shape passed to an endpoint handler. The handler's input is the
+ * entire surface: nothing else leaks in — no headers, no cookies, no fetch.
+ *
+ * `TScope` picks the half that differs: a team-scoped handler is always told
+ * its `team`, and a session-scoped one may receive `teams`. Neither is typed on
+ * the other, so reaching for the wrong one fails to compile rather than reading
+ * `undefined` at run time.
+ */
+export type EndpointHandlerArgs<TRequest, TContext, TCallbacks = SignatureCallbacks, TTeamContext = never, TScope extends EndpointScope = 'team', TSettings = Record<string, never>> = EndpointBaseArgs<TRequest, TContext, TCallbacks, TSettings> & (TScope extends 'session' ? SessionEndpointArgs<TTeamContext> : TeamEndpointArgs);
+/**
+ * Function signature for an endpoint that declares no `writes`. The runtime
+ * never persists anything on its behalf: the returned value is validated
+ * against the endpoint's `responseSchema` and surfaced to the caller as-is.
+ */
+export type EndpointHandler<TRequest = unknown, TResponse = unknown, TContext = unknown, TCallbacks = SignatureCallbacks, TTeamContext = never, TScope extends EndpointScope = 'team', TSettings = Record<string, never>> = (args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>) => Promise<TResponse>;
+/**
+ * What an endpoint that declares `writes` returns: the response its caller
+ * receives, and the state it changes.
+ *
+ * The two are separate because they are held to different contracts. `response`
+ * is validated against the endpoint's `responseSchema`; `capabilities` is held to
+ * its declared `writes`, and a capability outside that set is a fault rather
+ * than a silent no-op.
+ */
+export interface EndpointWriteResult<TResponse, TWrites> {
+    /** Validated against the endpoint's `responseSchema`, then returned as-is. */
+    response: TResponse;
+    /** The capabilities this call changes. Merged into the board on return. */
+    capabilities: TWrites;
+    /**
+     * Paths to remove once `capabilities` has merged, each under a capability
+     * in `writes`, with the same rules as a UI's `deletes`.
+     */
+    deletes?: ContextDeletePath[];
+}
+/**
+ * Function signature for an endpoint that declares `writes`.
+ *
+ * Unlike a participant's own write, an endpoint's is not put to the game's
+ * validators: they exist so a game can refuse a context update a participant
+ * submitted directly, and an endpoint is the game's own code, which checks its
+ * own writes. The pairing is deliberate — a validator can refuse a change
+ * outright while a strict endpoint remains the one sanctioned way to make it.
+ */
+export type WritingEndpointHandler<TRequest = unknown, TResponse = unknown, TWrites = unknown, TContext = unknown, TCallbacks = SignatureCallbacks, TTeamContext = never, TScope extends EndpointScope = 'team', TSettings = Record<string, never>> = (args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>) => Promise<EndpointWriteResult<TResponse, TWrites>>;
+/**
+ * What an endpoint that declares `actions`, or a session-scoped endpoint that
+ * writes team capabilities, returns (§6.12).
+ *
+ * Every part beside `response` is optional, and the runtime applies what is
+ * there in one step, in this order: `capabilities` and its `deletes`, then
+ * `teams`, then `actions`. So an endpoint can set a price and then tick on it,
+ * and nothing else lands in between.
+ */
+export interface EndpointResult<TResponse, TWrites = never, TAction extends EndpointAction = never, TTeamWrites = never> {
+    /** Validated against the endpoint's `responseSchema`, then returned as-is. */
+    response: TResponse;
+    /**
+     * A team-scoped endpoint's change to its board, or a session-scoped
+     * endpoint's change to the shared store.
+     */
+    capabilities?: TWrites;
+    /**
+     * Paths to remove from the same board once `capabilities` has merged, each
+     * under a capability in `writes` (a shared one, for a session-scoped
+     * endpoint). Same rules as a UI's `deletes`.
+     */
+    deletes?: ContextDeletePath[];
+    /**
+     * A session-scoped endpoint's change to individual teams' boards, keyed by
+     * team id. Each is held to the endpoint's non-shared `writes`, and every
+     * one lands, or none does.
+     */
+    teams?: Record<string, TTeamWrites>;
+    /** Session actions to carry out after the writes. Only declared ones. */
+    actions?: TAction[];
+}
+/**
+ * Function signature for an endpoint that returns an {@link EndpointResult}:
+ * one that declares `actions`, or a session-scoped one that writes team
+ * capabilities.
+ */
+export type EffectfulEndpointHandler<TRequest = unknown, TResponse = unknown, TContext = unknown, TCallbacks = SignatureCallbacks, TTeamContext = never, TScope extends EndpointScope = 'team', TSettings = Record<string, never>, TWrites = never, TAction extends EndpointAction = never, TTeamWrites = never> = (args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>) => Promise<EndpointResult<TResponse, TWrites, TAction, TTeamWrites>>;
+/**
+ * What `Plan` returns, for an endpoint that answers in two phases: its effects
+ * alone (§6.12). The response is `Respond`'s to write, once they have landed.
+ */
+export type EndpointPlan<TWrites = never, TAction extends EndpointAction = never, TTeamWrites = never> = Omit<EndpointResult<never, TWrites, TAction, TTeamWrites>, 'response'>;
+/** What one of `Plan`'s actions came to, for `Respond` (§6.12). */
+export interface EndpointOutcome {
+    type: EndpointActionType;
+    /** The tick a `tick` action committed. */
+    committedAtTick?: number;
+}
+/**
+ * `Plan`: the first phase of an endpoint that answers in two. It decides what
+ * happens and returns no response; `Respond` writes that once the effects have
+ * landed. An endpoint that answers in one exports `Handle` instead.
+ */
+export type EndpointPlanner<TRequest = unknown, TContext = unknown, TCallbacks = SignatureCallbacks, TTeamContext = never, TScope extends EndpointScope = 'team', TSettings = Record<string, never>, TWrites = never, TAction extends EndpointAction = never, TTeamWrites = never> = (args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>) => Promise<EndpointPlan<TWrites, TAction, TTeamWrites>>;
+/**
+ * `Respond`: the second phase, called once `Plan`'s effects have landed. It
+ * receives every argument `Plan` did, read afresh, plus what `Plan` returned
+ * and what each action came to. Its return is the response, validated against
+ * `responseSchema`. It changes nothing.
+ *
+ * `context`, `teams` and `session` are read after the effects, so an endpoint
+ * that ticked sees the round it started rather than the one before.
+ */
+export type EndpointResponder<TRequest = unknown, TResponse = unknown, TContext = unknown, TCallbacks = SignatureCallbacks, TTeamContext = never, TScope extends EndpointScope = 'team', TSettings = Record<string, never>, TWrites = never, TAction extends EndpointAction = never, TTeamWrites = never> = (args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings> & {
+    /** What `Plan` returned. */
+    plan: EndpointPlan<TWrites, TAction, TTeamWrites>;
+    /** One entry per action in `plan.actions`, in order. */
+    outcomes: EndpointOutcome[];
+}) => Promise<TResponse>;
+/**
+ * One effect of an endpoint's result, in the order the runtime applies them
+ * (§6.12): the endpoint's own `capabilities`, then each team's patch under
+ * `teams`, then each action by its position in `actions`.
+ */
+export type EffectStep = {
+    kind: 'capabilities';
+} | {
+    kind: 'teams';
+    teamId: string;
+} | {
+    kind: 'action';
+    index: number;
+    type: EndpointActionType;
+};
+/**
+ * Why an endpoint call failed (§6.12).
+ *
+ * Every {@link MutationOutcome} kind, for a refusal the call shares with any
+ * other operation (`denied` for an allowlist, visibility or team refusal,
+ * `conflict` for a result a tick overtook, and an applied step's own outcome,
+ * such as `tick-failed`), plus three that only an endpoint can produce:
+ *
+ * - `invalid-request` - the request failed `requestSchema`, or a file field
+ *   could not be resolved. The handler did not run.
+ * - `handler-error` - `Handle`, `Plan` or `Respond` threw, or ran past the
+ *   execution bound.
+ * - `invalid-response` - what the handler returned broke its declaration: the
+ *   response failed `responseSchema`, or the result named a write, a team or
+ *   an action the endpoint does not declare, or had the wrong shape.
+ */
+export type EndpointFailureOutcome = MutationOutcome | {
+    kind: 'invalid-request';
+    message: string;
+} | {
+    kind: 'handler-error';
+    message: string;
+} | {
+    kind: 'invalid-response';
+    message: string;
+};
+/**
+ * A failed endpoint call (§6.12), itemised so a caller can tell 'nothing
+ * happened' from 'the writes landed, then an action failed'.
+ */
+export interface EndpointFailure {
+    outcome: EndpointFailureOutcome;
+    /**
+     * The effect steps that committed before the failure, in order. Empty
+     * when nothing changed. Non-empty means the session moved: those steps
+     * stay applied, and the response was not delivered.
+     */
+    applied: EffectStep[];
+    /** The step that failed, when the failure was applying one. */
+    failedStep?: EffectStep;
+}
+/** How an endpoint call settled: its response, or an {@link EndpointFailure}. */
+export type EndpointCallResult = {
+    ok: true;
+    response: unknown;
+} | ({
+    ok: false;
+} & EndpointFailure);
+/**
+ * Error a surface's endpoint call (`callbacks.endpoints.<id>(request)`)
+ * rejects with. Inspect {@link outcome} (or the shorthand {@link kind}) for
+ * why, and {@link applied} for what had already changed.
+ */
+export declare class EndpointError extends Error {
+    readonly outcome: EndpointFailureOutcome;
+    readonly applied: EffectStep[];
+    readonly failedStep?: EffectStep;
+    constructor(failure: EndpointFailure);
+    /** Shorthand for `outcome.kind`. */
+    get kind(): EndpointFailureOutcome['kind'];
+    /** The failure as plain data, as it travels on the wire. */
+    get failure(): EndpointFailure;
+}

package/lib/build/endpoints.js

@@ -0,0 +1,46 @@
+import { describeMutationOutcome } from '../ui/mutation-outcome.js';
+const actionsMatchSchema = true;
+void actionsMatchSchema;
+function describeEndpointFailure(outcome) {
+    switch (outcome.kind) {
+        case 'invalid-request':
+        case 'handler-error':
+        case 'invalid-response':
+            return outcome.message;
+        default:
+            return describeMutationOutcome(outcome);
+    }
+}
+/**
+ * Error a surface's endpoint call (`callbacks.endpoints.<id>(request)`)
+ * rejects with. Inspect {@link outcome} (or the shorthand {@link kind}) for
+ * why, and {@link applied} for what had already changed.
+ */
+export class EndpointError extends Error {
+    outcome;
+    applied;
+    failedStep;
+    constructor(failure) {
+        super(describeEndpointFailure(failure.outcome));
+        this.name = 'EndpointError';
+        this.outcome = failure.outcome;
+        this.applied = failure.applied;
+        if (failure.failedStep)
+            this.failedStep = failure.failedStep;
+        // Restore the prototype chain so `instanceof` works after transpilation
+        // to ES5-targeted output.
+        Object.setPrototypeOf(this, EndpointError.prototype);
+    }
+    /** Shorthand for `outcome.kind`. */
+    get kind() {
+        return this.outcome.kind;
+    }
+    /** The failure as plain data, as it travels on the wire. */
+    get failure() {
+        return {
+            outcome: this.outcome,
+            applied: this.applied,
+            ...(this.failedStep ? { failedStep: this.failedStep } : {}),
+        };
+    }
+}

package/lib/build/hooks.d.ts

@@ -0,0 +1,74 @@
+import { Participant, SignatureCallbacks } from './callbacks.js';
+import { HookSignal } from './resource-schema.js';
+import { LogicMeta, LogicResult } from './signatures.js';
+/**
+ * The live, identifiable subject of a participant lifecycle hook — the same
+ * record every surface sees, not a reduced view of it. Defined in
+ * `./callbacks.ts`; re-exported here because hooks are where most consumers
+ * meet it.
+ */
+export type { Participant };
+/**
+ * Maps each hook signal to its payload shape. Adding a new signal extends this
+ * map; the {@link HookFunction} type then surfaces the new payload fields
+ * automatically.
+ */
+export interface HookPayloadMap {
+    participantJoin: {
+        participant: Participant;
+    };
+    participantMove: {
+        participant: Participant;
+        fromTeamId: string;
+        toTeamId: string;
+        /**
+         * Which team's context this invocation owns. The signal is dispatched
+         * once per affected team, and `participant.teamId` is post-change on
+         * both, so it cannot distinguish them.
+         */
+        phase: 'departure' | 'arrival';
+    };
+}
+/**
+ * Payload for a hook subscribed to signal `S`. Defaults to the union across
+ * all signals so callers that haven't pinned a signal still get a valid type.
+ */
+export type HookPayload<S extends HookSignal = HookSignal> = HookPayloadMap[S];
+/**
+ * Argument shape passed to a hook function. The signal-specific payload fields
+ * are spread alongside `context`, `settings`, and `callbacks` so consumers can
+ * destructure them directly (e.g. `({ context, participant }) => ...`).
+ */
+export type HookFunctionArgs<S extends HookSignal, TContext, TSettings, TCallbacks = SignatureCallbacks> = HookPayload<S> & {
+    context: TContext;
+    /**
+     * The settings resources this resource declared in `settings`, keyed by
+     * identifier: resolved from their defaults, the active scenario and the
+     * session's overrides, and fixed when play starts (§8). Read-only.
+     */
+    settings: TSettings;
+    callbacks: TCallbacks;
+    /**
+     * The facts true of the whole run: its locale, its seed, whether it is the
+     * game being played or a walkthrough beside it, and when this dispatch
+     * started (`now`).
+     *
+     * A hook fires outside the tick loop, so this is {@link LogicMeta} rather
+     * than the `RunMeta` an engine receives: there is no tick being executed.
+     */
+    meta: LogicMeta;
+    /**
+     * The roster after the lifecycle change this hook reports, taken when the
+     * dispatch started (§14.3): the participants on the team whose context
+     * this call owns for a `participantJoin`, and every participant in the
+     * session for a `participantMove`, so a departure and an arrival read the
+     * same list. Read-only, and a copy per call.
+     */
+    participants: readonly Readonly<Participant>[];
+};
+/**
+ * Function signature for a hook. Returns its writes under `capabilities`, the
+ * same shape an engine returns: hooks fire after the runtime applies the
+ * lifecycle change, then the runtime merges and persists what they return.
+ */
+export type HookFunction<S extends HookSignal = HookSignal, TContext = unknown, TSettings = unknown, TCallbacks = SignatureCallbacks> = (args: HookFunctionArgs<S, TContext, TSettings, TCallbacks>) => Promise<LogicResult<TContext>>;

package/lib/build/hooks.js

@@ -0,0 +1 @@
+export {};

package/lib/build/index.d.ts

@@ -0,0 +1,18 @@
+export type { RunKind, LogicMeta, RunMeta, TeamRunMeta, LogicFunctionArgs, InitializationFunction, RunFunction, StepFunction, TickControllerResult, TickControllerFunctionArgs, GetTickControllerFunction, AggregateFunctionTeam, AggregateFunctionShared, RunAggregateFunctionArgs, RunAggregateResult, RunAggregateFunction, InitAggregateFunction, LogicResult, EngineResult, RunResult, RunAggregateTickResult, EngineFunctionArgs, } from './signatures.js';
+export type { ApiUse, EndpointActionType, HookSignal, Schema, PackageDefinition, EngineDefinition, CapabilityDefinition, SettingsDefinition, SetupDefinition, ScenarioEditorDefinition, ScenarioDefinition, UserInterfaceDefinition, GameDefinition, GameSettings, GameSettingConstraint, GameSettingsConstraints, SessionUserInterfaceDefinition, SDKSessionUserInterface, WaitingRoomUserInterfaceDefinition, SDKWaitingRoomUserInterface, PresentationDefinition, SDKPresentation, FacilitatorGuideDefinition, SDKFacilitatorGuide, TickControllerDefinition, ResolvedPackageManifest, HookDefinition, ValidatorDefinition, ValidatorGate, EndpointDefinition, LogicLayout, SDKPackage, SDKEngine, SDKCapability, SDKSettings, SDKScenario, SDKUserInterface, SDKSetup, SDKScenarioEditor, SDKGame, PackageManifest, SDKTickController, SDKHook, SDKValidator, SDKEndpoint, GlobalSettings, } from './resource-schema.js';
+export { getText } from './llm.js';
+export type { ContentBlock, LLMMessage, JSONSchema, LLMTier, LLMTool, LLMGenerateOptions, LLMStopReason, LLMUsage, LLMResponse, LLMGenerateFunction, } from './llm.js';
+export { UndeclaredApiUseError } from './callbacks.js';
+export type { ReadAssetResponse, TeamInfo, TeamStateEntry, PastStateEntry, PastStateQuery, ThemePreference, HostOverlay, SignatureCallbacks, UngatedSignatureCallbacks, LogicCallbacks, UserInterfaceCallbacks, WaitingRoomUserInterfaceCallbacks, SessionUserInterfaceCallbacks, SettingsEditorCallbacks, } from './callbacks.js';
+export type { ExtractTextResponse, ExtractTextFunction } from './document.js';
+export type { GenerateSpeechVoice, GenerateSpeechFormat, GenerateSpeechRequest, GenerateSpeechResponse, GenerateSpeechFunction, } from './speech.js';
+export { nextDailyAt, nextWeeklyAt, nextDailyFromSchedule, scheduledTick, intervalTick, } from './scheduling.js';
+export type { ScheduleOptions } from './scheduling.js';
+export type { TimerState } from './timer.js';
+export { deriveSeed, seededRandom } from './seed.js';
+export type { ContextDeletePath, ContextUpdate } from './context-merge.js';
+export type { Participant, HookPayloadMap, HookPayload, HookFunctionArgs, HookFunction, } from './hooks.js';
+export type { ValidationResult, ValidatorActor, ValidatorFunctionArgs, ValidatorFunction, RequestTickFunctionArgs, RequestTickFunction, ValidationRejection, } from './validators.js';
+export type { EffectfulEndpointHandler, EffectStep, EndpointAction, EndpointBaseArgs, EndpointCaller, EndpointCallerRole, EndpointCallResult, EndpointFailure, EndpointFailureOutcome, EndpointPrincipal, EndpointResult, EndpointSession, EndpointTeamStatus, EndpointHandlerArgs, EndpointOutcome, EndpointPlan, EndpointPlanner, EndpointResponder, EndpointScope, EndpointTeamEntry, EndpointHandler, EndpointWriteResult, SessionEndpointArgs, TeamEndpointArgs, WritingEndpointHandler, } from './endpoints.js';
+export { EndpointError } from './endpoints.js';
+export { encodeUtf8, decodeUtf8 } from './encoding.js';

package/lib/build/index.js

@@ -0,0 +1,16 @@
+// Public API surface for @seriousgaming/sdk.
+//
+// Every export here is explicit so the published surface is reviewable and a
+// rename/removal in the generated schema (see ./resource-schema.js) fails the
+// build rather than silently changing public types with no semver signal.
+// Runtime plumbing (the `uses` guard, the context merge and projection, the
+// tick-result check, the manifest version) is not here: it lives in
+// @seriousgaming/sdk-tools/runtime, and the modules the
+// SDK's own builders and UI wrappers still need are private to this package.
+// See public-api.test.ts for the snapshot.
+export { getText } from './llm.js';
+export { UndeclaredApiUseError } from './callbacks.js';
+export { nextDailyAt, nextWeeklyAt, nextDailyFromSchedule, scheduledTick, intervalTick, } from './scheduling.js';
+export { deriveSeed, seededRandom } from './seed.js';
+export { EndpointError } from './endpoints.js';
+export { encodeUtf8, decodeUtf8 } from './encoding.js';