castle-web-sdk 0.4.45 → 0.4.46

package/dist/server/storage.d.ts

@@ -1,6 +1,7 @@
 import type { Json } from "../types";
 import type { CharacterHistory, CharacterOperation } from "../commands";
 import type { PlatformHandle } from "./platformHandle";
+import { type SaveApi, type SaveBucketApi } from "../save";
 export interface ServerStorageListOptions {
     prefix?: string;
     limit?: number;
@@ -15,7 +16,7 @@ export interface ServerStorageListPage<T extends Json = Json> {
     /** Null means there is nothing left. A short page alone does not mean that. */
     cursor: string | null;
 }
-export interface ServerStorageScope {
+export interface ServerStorageScope extends SaveBucketApi {
     get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
     set(values: Record<string, Json>): Promise<void>;
     remove(keys: string[]): Promise<void>;
@@ -95,6 +96,59 @@ export interface DeliverCharacterKnowledgeInput {
     claimIds: string[];
     source: CharacterKnowledgeSource;
 }
+/**
+ * A character acting on its own after a command woke it (autonomous character
+ * actions, bundles with `characterActions`). `declined` covers choosing
+ * nothing, too little confidence for its temperament, and an action no longer
+ * eligible when it committed; `failed` is a decision-model error.
+ */
+export type CharacterActionNotice = {
+    characterId: string;
+    /** `id` is the event occurrence, routine, or promise id. */
+    trigger: {
+        type: "witnessed" | "routine" | "promise_due";
+        id: string;
+    };
+    outcome: "acted" | "declined" | "failed";
+    /** When acted. */
+    actionId?: string;
+    /** When acted with a parameterized action's variant. */
+    variantId?: string;
+    /** The action's world event, when it has one. */
+    eventOccurrenceId?: string;
+    /** The decision model's probability for its choice. */
+    probability?: number;
+};
+export type CharacterGameStateResult = {
+    revision: number;
+    state: {
+        [key: string]: string | number | boolean;
+    };
+    promiseOutcomes: Array<{
+        id: string;
+        status: "fulfilled" | "broken";
+        due: number;
+        resolvedAtGameTime: number;
+    }>;
+    /** At most 8, omitted when no character acted, declined, or failed. */
+    characterActions?: CharacterActionNotice[];
+};
+export type CharacterGameStateOperation = Omit<CharacterOperation, "result"> & {
+    result: CharacterGameStateResult | null;
+};
+export type CharacterKnowledgeDeliveryResult = {
+    deliveryId: string;
+    recipientCharacterId: string;
+    eventOccurrenceId: string;
+    claimIds: string[];
+    source: CharacterKnowledgeSource;
+    deliveredAt: string;
+    /** At most 8, omitted when no character acted, declined, or failed. */
+    characterActions?: CharacterActionNotice[];
+};
+export type CharacterKnowledgeDeliveryOperation = Omit<CharacterOperation, "result"> & {
+    result: CharacterKnowledgeDeliveryResult | null;
+};
 export interface CompleteCharacterBeatInput {
     operationId: string;
     characterId: string;
@@ -189,10 +243,10 @@ export interface ServerPlaythroughCharacters {
     /** Queues a funded turn whose admitted listeners are fixed at enqueue time. */
     send(input: SendCharacterInput): Promise<CharacterOperation>;
     recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
-    setGameState(input: SetCharacterGameStateInput): Promise<CharacterOperation>;
+    setGameState(input: SetCharacterGameStateInput): Promise<CharacterGameStateOperation>;
     shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
     inspect(): Promise<Json>;
-    deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterOperation>;
+    deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterKnowledgeDeliveryOperation>;
     completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
     evaluateInformation(input: EvaluateCharacterInformationInput): Promise<CharacterInformationEvaluationOperation>;
     evaluateBeats(input: EvaluateCharacterBeatsInput): Promise<CharacterBeatEvaluationOperation>;
@@ -204,7 +258,7 @@ export interface ServerCharacterHistoryOptions {
     limit?: number;
     cursor?: string | null;
 }
-export interface ServerStorage {
+export interface ServerStorage extends SaveApi {
     /** Shared by everyone playing the deck, and owned by this server. */
     readonly deck: ServerStorageScope;
     /** One player's public data. Readable by anyone; writable by them or by this server. */

package/dist/server/storage.js

@@ -1,5 +1,6 @@
 import { chunked } from "../chunk";
 import { decodeStorageValue, encodeStorageValue, storageError, } from "../storageJson";
+import { createSaveApi, createSaveBucket, preflightSaveRequest, SaveError, } from "../save";
 // Deck storage for an author's session server.
 //
 // The same store the deck's clients use, reached over the platform channel instead of
@@ -56,8 +57,26 @@ export function createServerStorage(platformHandle) {
         const result = await platformHandle.storage(op, JSON.stringify(args));
         return JSON.parse(result);
     };
+    // The host forwards these args to the platform's storage route unchanged,
+    // which takes a save's request as `input` and a lookup as `operationId`.
+    const saveApi = createSaveApi(async (verb, input) => {
+        if (typeof platformHandle.storage !== "function" ||
+            platformHandle.storageEnabled === false) {
+            throw new SaveError({
+                code: "CAULDRON_STORAGE_UNAVAILABLE",
+                message: "Storage is not available to this session.",
+                operationId: input.operationId,
+                retryable: false,
+                committed: false,
+            });
+        }
+        const args = verb === "operation" ? input : { input };
+        preflightSaveRequest(verb, args, MAX_REQUEST_BYTES);
+        return call(verb, args);
+    }, true);
     return {
-        deck: createScope(call, "DECK", null),
+        ...saveApi,
+        deck: createScope(call, "DECK", null, saveApi),
         user(userId) {
             // A bad id poisons the scope rather than throwing here, so the failure arrives
             // the same way every other failure does -- as a rejection the author can await.
@@ -65,12 +84,12 @@ export function createServerStorage(platformHandle) {
             // resolved by the platform to the deck's creator, quietly writing the wrong
             // player's bucket, so nothing is sent either.
             if (typeof userId !== "string" || userId.length === 0) {
-                return createScope(rejectMissingSubject, "USER", null);
+                return createScope(rejectMissingSubject, "USER", null, saveApi);
             }
             if (utf8Length(userId) > MAX_SUBJECT_BYTES) {
-                return createScope(rejectOversizeSubject, "USER", null);
+                return createScope(rejectOversizeSubject, "USER", userId, saveApi);
             }
-            return createScope(call, "USER", userId);
+            return createScope(call, "USER", userId, saveApi);
         },
         board(name) {
             return createBoard(call, name);
@@ -224,8 +243,9 @@ function createPlaythrough(call, subject, generation) {
         },
     });
 }
-function createScope(call, scope, subject) {
+function createScope(call, scope, subject, saveApi) {
     return {
+        ...createSaveBucket(saveApi, scope === "DECK" ? "deck" : "user", subject ?? undefined),
         async get(keys) {
             // A bare array, not a wrapper: the platform hands back exactly what the
             // storage verb returns, and `get` returns its entries directly.

package/dist/server/wrapper.d.ts

@@ -1,8 +1,15 @@
 import type { MultiplayerSessionMode, PlatformHandle, 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, 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, } 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;
@@ -194,7 +276,8 @@ export interface MultiplayerWorldCharacterTurn {
 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;