castle-web-sdk 0.4.45 → 0.4.47

package/dist/server/hub.js

@@ -0,0 +1,195 @@
+import { CastleError } from "../errors";
+const DOOR_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
+export function hubArrival(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const { fromDeckId, doorId } = raw;
+    if (typeof fromDeckId !== "string" || fromDeckId.length === 0 || fromDeckId.length > 64) {
+        return null;
+    }
+    return Object.freeze({
+        fromDeckId,
+        doorId: typeof doorId === "string" && DOOR_ID.test(doorId) ? doorId : null,
+    });
+}
+// The co-present users a block hides from a joining hub player, as the host
+// sends them on the join (`player.hiddenUserIds`): decimal user ids, or null
+// when there are none or the list is malformed.
+const HIDDEN_USER_ID = /^\d{1,20}$/;
+const HIDDEN_USER_IDS_MAX = 1000;
+export function recordHiddenUserIds(hidden, playerId, raw) {
+    const ids = hubHiddenUserIds(raw);
+    if (ids) {
+        hidden.set(playerId, ids);
+    }
+    else {
+        hidden.delete(playerId);
+    }
+}
+function hubHiddenUserIds(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const list = raw.hiddenUserIds;
+    if (!Array.isArray(list) || list.length === 0)
+        return null;
+    const ids = new Set();
+    for (const id of list.slice(0, HIDDEN_USER_IDS_MAX)) {
+        if (typeof id === "string" && HIDDEN_USER_ID.test(id))
+            ids.add(id);
+    }
+    return ids.size > 0 ? ids : null;
+}
+function unavailable(op, what) {
+    return new CastleError({
+        code: "CAULDRON_HUB_UNAVAILABLE",
+        message: `This host's runtime cannot ${what}.`,
+        operation: `session.hub.${op}`,
+    });
+}
+export function createServerHub(platformHandle, arrivals, hiddenPair = () => false) {
+    const pinned = platformHandle.hub;
+    if (!pinned ||
+        typeof platformHandle.hubResult !== "function" ||
+        typeof platformHandle.hubPadUpdate !== "function" ||
+        typeof platformHandle.hubResultsRead !== "function") {
+        return null;
+    }
+    const call = async (op, args) => {
+        const raw = await platformHandle[op](JSON.stringify(args));
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new CastleError({
+                code: "CAULDRON_HUB_INVALID_RESPONSE",
+                message: `The platform returned an invalid ${op} response.`,
+                operation: `session.hub.${op}`,
+            });
+        }
+        return parsed;
+    };
+    return Object.freeze({
+        place: typeof pinned.place === "string" ? pinned.place : null,
+        title: typeof pinned.title === "string" ? pinned.title : null,
+        result: pinned.result ?? null,
+        ...(typeof pinned.owner === "string" && pinned.owner.length > 0 ? { owner: pinned.owner } : {}),
+        arrival(playerId) {
+            return arrivals.get(playerId) ?? null;
+        },
+        hiddenPair(playerIdA, playerIdB) {
+            return hiddenPair(playerIdA, playerIdB);
+        },
+        async friendsAmong(playerId, userIds) {
+            const json = JSON.stringify({ playerId, userIds: [...userIds] });
+            const raw = typeof platformHandle.hubFriendsAmong === "function"
+                ? await platformHandle.hubFriendsAmong(json)
+                : await platformHandle.storage?.("hubFriendsAmong", json);
+            const answer = JSON.parse(raw ?? "null");
+            return Array.isArray(answer?.userIds) ? answer.userIds : [];
+        },
+        async relationsAmong(playerId, userIds) {
+            const asked = new Set(userIds);
+            const json = JSON.stringify({ playerId, userIds: [...userIds] });
+            let raw;
+            if (typeof platformHandle.hubFriendsAmong === "function") {
+                raw = await platformHandle.hubFriendsAmong(json);
+            }
+            else {
+                raw = await platformHandle.storage?.("hubFriendsAmong", json);
+            }
+            const answer = JSON.parse(raw ?? "null");
+            const list = (value) => Array.isArray(value)
+                ? value.filter((id) => typeof id === "string" && asked.has(id))
+                : [];
+            return {
+                friends: list(answer?.userIds),
+                follows: list(answer?.follows),
+                followedBy: list(answer?.followedBy),
+            };
+        },
+        async reportResult(playerId, result) {
+            const { place, outcome, score, stats } = result ?? {};
+            return (await call("hubResult", {
+                playerId,
+                ...(place === undefined ? {} : { place }),
+                outcome,
+                ...(score === undefined || score === null ? {} : { score }),
+                ...(stats === undefined ? {} : { stats }),
+            }));
+        },
+        async updatePad(input) {
+            return (await call("hubPadUpdate", {
+                doorId: input?.doorId,
+                padId: input?.padId,
+                memberUserIds: [...(input?.memberUserIds ?? [])],
+                ...(input?.fire === true ? { fire: true } : {}),
+            }));
+        },
+        async readResults(input = {}) {
+            const read = await call("hubResultsRead", {
+                ...(input.userIds ? { userIds: [...input.userIds] } : {}),
+                ...(input.doorIds ? { doorIds: [...input.doorIds] } : {}),
+            });
+            return {
+                players: (read.players ?? {}),
+                boards: (read.boards ?? {}),
+            };
+        },
+        async wear(playerId, wearable) {
+            if (typeof platformHandle.hubWear !== "function") {
+                throw new CastleError({
+                    code: "CAULDRON_HUB_UNAVAILABLE",
+                    message: "This host's runtime cannot change wearables.",
+                    operation: "session.hub.hubWear",
+                });
+            }
+            const receipt = await call("hubWear", {
+                playerId,
+                wearable: wearable === null || wearable === undefined
+                    ? null
+                    : { kind: wearable.kind, color: wearable.color, rarity: wearable.rarity },
+            });
+            return {
+                wearable: (receipt.wearable ?? null),
+            };
+        },
+        async unlock(playerId, itemId) {
+            if (typeof platformHandle.hubUnlock !== "function") {
+                throw unavailable("hubUnlock", "give earned items");
+            }
+            const receipt = await call("hubUnlock", { playerId, itemId });
+            return {
+                unlocked: true,
+                isNew: receipt.isNew === true,
+                earned: (receipt.earned ?? null),
+            };
+        },
+        async wearEarned(playerId, earned) {
+            if (typeof platformHandle.hubWearEarned !== "function") {
+                throw unavailable("hubWearEarned", "choose earned items");
+            }
+            const receipt = await call("hubWearEarned", {
+                playerId,
+                earned: earned === null || earned === undefined
+                    ? null
+                    : { deckId: earned.deckId, id: earned.id },
+            });
+            return {
+                earned: (receipt.earned ?? null),
+            };
+        },
+        async readUnlocks(userIds) {
+            if (typeof platformHandle.hubUnlocksRead !== "function") {
+                throw unavailable("hubUnlocksRead", "read earned items");
+            }
+            const read = await call("hubUnlocksRead", { userIds: [...(userIds ?? [])] });
+            return {
+                players: (read.players ?? {}),
+            };
+        },
+    });
+}

package/dist/server/platformHandle.d.ts

@@ -1,4 +1,5 @@
 import type { Json } from "../types";
+import type { MultiplayerWorldCharacterCommand } from "../multiplayer";
 export type MultiplayerSessionMode = "named" | "party" | "public";
 export interface PlayerIdentity {
     userId: string;
@@ -13,6 +14,16 @@ export interface PlatformSessionConfig {
     readonly tickRate: number;
     readonly maxPlayers: number;
     readonly world?: PlatformWorldSnapshot;
+    /**
+     * True when the host brokers a hub place's shared characters into this
+     * session without a world (a layer of the place). Absent on hosts that do not.
+     */
+    readonly placeCharacters?: boolean;
+    /**
+     * The place this session was started for, stamped by a host that placed it
+     * through a door (the hub's door table). Absent on hosts that do not.
+     */
+    readonly place?: string;
 }
 export interface PlatformWorldCheckpoint {
     version: number;
@@ -21,6 +32,11 @@ export interface PlatformWorldCheckpoint {
 export interface PlatformWorldSnapshot {
     revision: string;
     checkpoint: PlatformWorldCheckpoint | null;
+    /** Selected destination timing policy, stamped by hosts that support catch-up. */
+    worldTime?: PlatformWorldTimeConfig;
+}
+export interface PlatformWorldTimeConfig {
+    advance: "wallClock";
 }
 export interface PlatformHandle {
     send(connId: string, text: string): void;
@@ -28,7 +44,7 @@ export interface PlatformHandle {
     sendBinary?(connId: string, bytes: Uint8Array | ArrayBuffer): void;
     broadcastBinary?(bytes: Uint8Array | ArrayBuffer): void;
     disconnect(connId: string, code: string | number): void;
-    on(event: "join", callback: (connId: string, player: PlayerIdentity) => unknown): void;
+    on(event: "join", callback: (connId: string, player: PlayerIdentity, arrival?: PlatformHubArrival, experimentVariants?: Record<string, string>) => unknown): void;
     on(event: "leave", callback: (connId: string) => unknown): void;
     on(event: "message", callback: (connId: string, text: string) => unknown): void;
     on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
@@ -37,6 +53,7 @@ export interface PlatformHandle {
     on(event: "worldCharacterTurn", callback: (request: PlatformWorldCharacterTurn) => unknown): void;
     on(event: "worldCharacterCommand", callback: (request: PlatformWorldCharacterCommand) => unknown): void;
     on(event: "worldCharacterRead", callback: (request: PlatformWorldCharacterRead) => unknown): void;
+    on(event: "worldCharacterTool", callback: (request: PlatformWorldCharacterTool) => unknown): void;
     /**
      * Deck storage. Strings in and strings out, like the rest of this handle, so a
      * runtime other than the Node shim can implement it without knowing what storage is.
@@ -52,14 +69,60 @@ export interface PlatformHandle {
     /** Persistent-world checkpoint broker. The host stamps the hidden world binding. */
     worldCheckpointRead?(): Promise<string>;
     worldCheckpointCommit?(argsJson: string): Promise<string>;
-    worldCharacterSend?(grantId: string): Promise<string>;
+    /** `tools` is the turn's place tools, passed only when non-empty. */
+    worldCharacterSend?(grantId: string, tools?: readonly PlatformPlaceTool[]): Promise<string>;
     worldCharacterCommand?(grantId: string): Promise<string>;
     worldCharacterRead?(grantId: string): Promise<string>;
     worldCharacterRuntimeCreate?(argsJson: string): Promise<string>;
     worldCharacterRuntimeList?(): Promise<string>;
     worldCharacterReject?(grantId: string, code?: string): void;
+    /**
+     * Answers a `worldCharacterTool` event with at most 1 KiB of UTF-8. Present only
+     * when the host serves place tools, which is also what lets a send declare them.
+     */
+    worldCharacterToolResult?(requestId: string, result: string): Promise<string>;
+    /**
+     * The hub place this session runs, as ghost pinned it from the published
+     * castle.json `hub` block. Present only when the host services the hub ops
+     * below, so a deck without a hub block never sees any of them.
+     */
+    readonly hub?: Readonly<PlatformHubPlace>;
+    hubResult?(argsJson: string): Promise<string>;
+    hubPadUpdate?(argsJson: string): Promise<string>;
+    hubResultsRead?(argsJson: string): Promise<string>;
+    /** Friends among candidates (hub contract v1.36); older images use storage. */
+    hubFriendsAmong?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than wearables (contract v1.4). */
+    hubWear?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than earned items (contract v1.53). */
+    hubUnlock?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than earned items (contract v1.53). */
+    hubWearEarned?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than earned items (contract v1.53). */
+    hubUnlocksRead?(argsJson: string): Promise<string>;
     readonly config: PlatformSessionConfig;
 }
+export interface PlatformHubResultShape {
+    outcomes: ("win" | "lose" | "draw")[];
+    score: {
+        unit: "ms" | "s" | "points";
+        better: "higher" | "lower";
+        min: number;
+        max: number;
+    } | null;
+    stats: Record<string, "number" | "string">;
+}
+export interface PlatformHubPlace {
+    owner?: string;
+    place?: string;
+    title?: string | null;
+    result?: PlatformHubResultShape | null;
+}
+/** Where a player came in, when ghost placed them through a hub door. Ghost's word, not a client's. */
+export interface PlatformHubArrival {
+    fromDeckId: string;
+    doorId?: string;
+}
 export interface PlatformWorldCharacterCommand {
     grantId: string;
     requestId: string;
@@ -67,7 +130,7 @@ export interface PlatformWorldCharacterCommand {
     speaker: PlayerIdentity & {
         playerId: string;
     };
-    command: unknown;
+    command: MultiplayerWorldCharacterCommand;
 }
 export interface PlatformWorldCharacterRead {
     grantId: string;
@@ -77,6 +140,20 @@ export interface PlatformWorldCharacterRead {
     };
     query: unknown;
 }
+/** A lookup a place declares for one character turn. */
+export interface PlatformPlaceTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export interface PlatformWorldCharacterTool {
+    requestId: string;
+    operationId: string;
+    characterId: string;
+    playerId: string;
+    name: string;
+    input: Record<string, unknown>;
+}
 export interface PlatformWorldCharacterTurn {
     grantId: string;
     requestId: string;

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,13 +16,19 @@ 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>;
     increment(key: string, delta?: number): Promise<number>;
     list<T extends Json = Json>(options?: ServerStorageListOptions): Promise<ServerStorageListPage<T>>;
 }
+export interface ServerTownStorage {
+    get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
+    set(values: Record<string, Json>): Promise<void>;
+    remove(keys: string[]): Promise<void>;
+    increment(key: string, delta?: number): Promise<number>;
+}
 export interface ServerStorageBoardScore {
     subject: string;
     score: number;
@@ -95,6 +102,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 +249,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,11 +264,18 @@ 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. */
     user(userId: string): ServerStorageScope;
+    /**
+     * The door deck's source town's deck-scope rows, for one player in this session.
+     * Only a door deck's server may call it; a town gets CAULDRON_HUB_NO_TOWN.
+     * In an owner house, only the owner's rows are accessible. Quota counts against
+     * the town. Each key must be tokens|spent|own|hat|chirp, then userId, as its first two segments.
+     */
+    town(userId: string): ServerTownStorage;
     board(name: string): ServerStorageBoard;
     /** Opens one player's experimental, generation-bound game namespace. */
     playthrough(userId: string): Promise<ServerPlaythrough>;

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,15 @@ 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);
+        },
+        town(userId) {
+            return createTownStorage(call, userId);
         },
         board(name) {
             return createBoard(call, name);
@@ -224,8 +246,52 @@ function createPlaythrough(call, subject, generation) {
         },
     });
 }
-function createScope(call, scope, subject) {
+/** The town's per-player namespaces a door deck may reach; ghost holds the same list. */
+const TOWN_PLAYER_NAMESPACES = ["tokens", "spent", "own", "hat", "chirp"];
+function createTownStorage(call, subject) {
+    const args = { scope: "DECK", subject, place: "town" };
+    // Validate in the async verbs, so a bad subject poisons the handle without
+    // throwing when the author creates it. Validate every key before any chunk lands.
+    const keysFor = (keys, operation) => {
+        assertUserId(subject, operation);
+        const checked = assertKeys(keys, operation);
+        for (const key of checked) {
+            const segments = key.split(":");
+            if (!TOWN_PLAYER_NAMESPACES.includes(segments[0]) || segments[1] !== subject) {
+                throw storageError("CAULDRON_STORAGE_INVALID_ARGUMENT", `Town storage key ${JSON.stringify(key)} must be ${TOWN_PLAYER_NAMESPACES.join("|")}:${subject}[:...].`, operation);
+            }
+        }
+        return checked;
+    };
+    return {
+        async get(keys) {
+            const entries = [];
+            for (const chunk of chunked(keysFor(keys, "session.storage.town.get"), MAX_KEYS_PER_CALL)) {
+                entries.push(...await call("get", { ...args, keys: chunk }));
+            }
+            return decodeEntries(entries, "session.storage.town.get");
+        },
+        async set(values) {
+            keysFor(Object.keys(values), "session.storage.town.set");
+            const entries = encodeEntries(values, "session.storage.town.set");
+            for (const chunk of batched(entries, "session.storage.town.set")) {
+                await call("set", { ...args, entries: chunk });
+            }
+        },
+        async remove(keys) {
+            for (const chunk of chunked(keysFor(keys, "session.storage.town.remove"), MAX_KEYS_PER_CALL)) {
+                await call("delete", { ...args, keys: chunk });
+            }
+        },
+        async increment(key, delta = 1) {
+            keysFor([key], "session.storage.town.increment");
+            return Number(await call("increment", { ...args, key, delta }));
+        },
+    };
+}
+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.