castle-web-sdk 0.4.45 → 0.4.47

package/dist/server/wrapper.d.ts

@@ -1,8 +1,15 @@
-import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
+import type { MultiplayerSessionMode, PlatformHandle, PlatformPlaceTool, PlayerIdentity } from "./platformHandle";
 import type { Json } from "../types";
+import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue } from "../multiplayer";
 import { type ServerStorage } from "./storage";
-export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlayerIdentity, } from "./platformHandle";
-export type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
+import { type MultiplayerHubArrival, type MultiplayerServerHub } from "./hub";
+export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlatformWorldTimeConfig, PlayerIdentity, } from "./platformHandle";
+export { createSaveCoordinator } from "../saveCoordinator";
+export type { CoordinatedChange, CoordinatedSave, SaveCoordinator, SaveStatus, } from "../saveCoordinator";
+export { SaveError } from "../save";
+export type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRevision, SaveRows, SaveScope, SaveSelection, SaveSnapshot, SaveTarget, SaveTransactionInput, SaveWriter, } from "../save";
+export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerHubEarnedClass, MultiplayerHubEarnedItem, MultiplayerHubHomeClass, MultiplayerHubHomeItem, MultiplayerHubUnlockReceipt, MultiplayerHubUnlocksRead, MultiplayerHubWearEarnedReceipt, MultiplayerServerHub, } from "./hub";
+export type { CharacterActionNotice, CharacterGameStateOperation, CharacterGameStateResult, CharacterKnowledgeDeliveryOperation, CharacterKnowledgeDeliveryResult, CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, ServerTownStorage, } from "./storage";
 export interface MultiplayerServerPlayer extends PlayerIdentity {
     playerId: string;
     readonly participantId: string;
@@ -15,6 +22,12 @@ export interface MultiplayerServerSession {
     readonly sessionId: string;
     readonly deckId: string;
     readonly mode: MultiplayerSessionMode;
+    /**
+     * The place the host started this session for (a hub door's destination, or
+     * the hub place ghost pinned the session to), or null when the host stamped
+     * none. Never set from a client.
+     */
+    readonly place: string | null;
     /**
      * Deck storage that outlives the session. Nothing else here does: a session ends
      * when its last player leaves and its memory goes with it.
@@ -22,6 +35,27 @@ export interface MultiplayerServerSession {
     readonly storage: ServerStorage;
     /** A durable checkpoint for an opted-in persistent destination. */
     readonly world: MultiplayerServerWorld | null;
+    /**
+     * The shared characters this session can address: `session.world.characters`
+     * in a shared-character world (the same object), or a hub place's characters
+     * on one of its layers, where `session.world` stays null. Null everywhere else.
+     */
+    readonly characters: MultiplayerServerWorldCharacters | null;
+    /**
+     * The hub place this session runs (castle.json `hub`, as ghost pinned it):
+     * results, pads and arrivals. Null for a deck without a hub block and on hosts
+     * without hub support.
+     */
+    readonly hub: MultiplayerServerHub | null;
+    /**
+     * The variant a connected player has in the A/B experiment `name`, or null
+     * when they are in no such experiment (or have left). Castle's server
+     * resolved it and the host delivered it with the join, so it is the same arm
+     * the player's page reads and nothing a client sent.
+     */
+    experiment(player: MultiplayerServerPlayer | string, name: string): string | null;
+    /** Every experiment a connected player is in, `{ name: variant }`. */
+    experiments(player: MultiplayerServerPlayer | string): Record<string, string>;
     /** Sends bytes as a binary message and all other payloads as JSON. */
     send(playerId: string, data: unknown): void;
     /** Broadcasts bytes as a binary message and all other payloads as JSON. */
@@ -53,10 +87,26 @@ export interface MultiplayerServerWorld {
     read(): Promise<MultiplayerWorldSnapshot>;
     /** Commits exactly against expectedRevision; conflicts never partially write. */
     commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
+    catchUp(options: MultiplayerWorldCatchUpOptions): Promise<MultiplayerWorldCatchUpResult>;
     readonly journal: MultiplayerServerWorldJournal;
     readonly participants: MultiplayerServerWorldParticipants;
+    readonly notifications: MultiplayerServerWorldNotifications;
     readonly characters: MultiplayerServerWorldCharacters;
 }
+export interface MultiplayerWorldCatchUpOptions {
+    key?: string;
+    maxElapsedMs?: number;
+    apply(input: {
+        elapsedMs: number;
+        now: number;
+        checkpoint: MultiplayerWorldCheckpoint | null;
+    }): MultiplayerWorldCheckpoint | Promise<MultiplayerWorldCheckpoint>;
+}
+export interface MultiplayerWorldCatchUpResult {
+    applied: boolean;
+    elapsedMs: number;
+    revision: string;
+}
 export interface MultiplayerWorldJournalAppendInput {
     operationId: string;
     entries: readonly MultiplayerWorldJournalAppendEntry[];
@@ -112,6 +162,31 @@ export interface MultiplayerWorldParticipantsReadResult {
 export interface MultiplayerServerWorldParticipants {
     read(options?: MultiplayerWorldParticipantsReadOptions): Promise<MultiplayerWorldParticipantsReadResult>;
 }
+export interface MultiplayerWorldNotificationNotifyInput {
+    key: string;
+    participantIds: readonly string[];
+    templateId: string;
+    slots?: Readonly<Record<string, string>>;
+    at?: string;
+    expiresAt?: string;
+}
+export interface MultiplayerWorldNotificationNotifyResult {
+    key: string;
+    accepted: number;
+    skipped: number;
+    limited: number;
+}
+export interface MultiplayerWorldNotificationCancelInput {
+    key: string;
+    participantIds?: readonly string[];
+}
+export interface MultiplayerWorldNotificationCancelResult {
+    cancelled: number;
+}
+export interface MultiplayerServerWorldNotifications {
+    notify(input: MultiplayerWorldNotificationNotifyInput): Promise<MultiplayerWorldNotificationNotifyResult>;
+    cancel(input: MultiplayerWorldNotificationCancelInput): Promise<MultiplayerWorldNotificationCancelResult>;
+}
 export interface MultiplayerServerWorldCharacters {
     create(input: MultiplayerWorldRuntimeCharacterCreateInput): Promise<MultiplayerWorldRuntimeCharacterCreateReceipt>;
     list(): Promise<MultiplayerWorldCharacterList>;
@@ -155,14 +230,21 @@ export interface MultiplayerWorldRuntimeCharacterCreateReceipt {
 export interface MultiplayerWorldCharacterList {
     characters: readonly MultiplayerWorldCharacterSummary[];
 }
-export interface MultiplayerWorldCharacterCommandRequest {
+interface MultiplayerWorldCharacterCommandRequestFor<Command extends MultiplayerWorldCharacterCommand> {
+    /** Command discriminator mirrored at the request level for TypeScript narrowing. */
+    readonly type: Command["type"];
     readonly requestId: string;
     readonly operationId: string;
     readonly speaker: MultiplayerServerPlayer;
-    readonly command: Readonly<Record<string, unknown>>;
-    apply(): Promise<unknown>;
+    readonly command: Readonly<Command>;
+    apply(): Promise<MultiplayerWorldCharacterCommandResult<MultiplayerWorldCharacterCommandResultValue<Command>>>;
     reject(code?: string): void;
 }
+export type MultiplayerWorldCharacterCommandRequest = {
+    [Type in MultiplayerWorldCharacterCommand["type"]]: MultiplayerWorldCharacterCommandRequestFor<Extract<MultiplayerWorldCharacterCommand, {
+        type: Type;
+    }>>;
+}[MultiplayerWorldCharacterCommand["type"]];
 export interface MultiplayerWorldCharacterReadRequest {
     readonly requestId: string;
     readonly speaker: MultiplayerServerPlayer;
@@ -186,21 +268,53 @@ export interface MultiplayerWorldCharacterTurn {
         readonly players: readonly MultiplayerServerPlayer[];
         readonly characterIds: readonly string[];
     };
-    /** Durably admits the exact host-authorized request. No arguments can broaden it. */
-    send(): Promise<MultiplayerWorldCharacterAdmission>;
+    /**
+     * Durably admits the exact host-authorized request. No arguments can broaden it:
+     * `tools` only declares lookups the character may make of this place during the
+     * turn (answered by `onWorldCharacterTool`), and is dropped on a host that does
+     * not serve place tools.
+     */
+    send(options?: MultiplayerWorldCharacterSendOptions): Promise<MultiplayerWorldCharacterAdmission>;
     /** Explicitly rejects the request before admission. */
     reject(code?: string): void;
 }
+/**
+ * A lookup a place offers its character for one turn. The host drops an invalid
+ * list whole (the turn proceeds without tools): at most 8, a unique `name` matching
+ * `^[A-Za-z][A-Za-z0-9_]{0,31}$` other than `perform_action` or `capture_claim`,
+ * a 1..300 character `description`, and a JSON-object `input_schema` of at most
+ * 1 KiB, with the whole list at most 6 KiB.
+ */
+export type MultiplayerPlaceTool = PlatformPlaceTool;
+export interface MultiplayerWorldCharacterSendOptions {
+    tools?: readonly MultiplayerPlaceTool[];
+}
+/** One place-tool use by a character during a turn this place admitted. */
+export interface MultiplayerWorldCharacterToolRequest {
+    readonly operationId: string;
+    readonly characterId: string;
+    readonly playerId: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
 type CallbackResult = unknown;
 export interface MultiplayerServerCallbacks {
     onStart?: (session: MultiplayerServerSession) => CallbackResult;
-    onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
+    /** `arrival` is set when ghost placed the player through a hub door. */
+    onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, arrival: MultiplayerHubArrival | null) => CallbackResult;
     onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
     /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
     onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
     onWorldCharacterTurn?: (session: MultiplayerServerSession, turn: MultiplayerWorldCharacterTurn) => CallbackResult;
     onWorldCharacterCommand?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterCommandRequest) => CallbackResult;
     onWorldCharacterRead?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterReadRequest) => CallbackResult;
+    /**
+     * Answers a place-tool use declared through `turn.send({ tools })`. Return a
+     * string or a JSON value (stringified); a result over 1 KiB becomes
+     * `{"error":"result too large"}` and a throw `{"error":"tool failed"}`. The host
+     * waits 1.5 s, then the character answers without it.
+     */
+    onWorldCharacterTool?: (request: MultiplayerWorldCharacterToolRequest, session: MultiplayerServerSession) => unknown;
     onTick?: (session: MultiplayerServerSession) => CallbackResult;
     onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
     /**