castle-web-sdk 0.4.46 → 0.4.48

package/dist/server/storage.js

@@ -91,17 +91,20 @@ export function createServerStorage(platformHandle) {
             }
             return createScope(call, "USER", userId, saveApi);
         },
+        town(userId) {
+            return createTownStorage(call, userId);
+        },
         board(name) {
             return createBoard(call, name);
         },
         async playthrough(userId) {
             const subject = assertUserId(userId, "session.storage.playthrough");
             const opened = await call("playthroughOpen", { subject });
-            return createPlaythrough(call, subject, assertGeneration(opened?.generation));
+            return createPlaythrough(call, subject, assertGeneration(opened?.generation), optionalResetGeneration(opened?.resetGeneration));
         },
     };
 }
-function createPlaythrough(call, subject, generation) {
+function createPlaythrough(call, subject, generation, resetGeneration) {
     const characters = Object.freeze({
         async send(input) {
             const characterId = assertNarrativeId(input?.characterId, "characterId");
@@ -217,6 +220,7 @@ function createPlaythrough(call, subject, generation) {
     });
     return Object.freeze({
         generation,
+        ...(resetGeneration === undefined ? {} : { resetGeneration }),
         characters,
         async get(keys) {
             const entries = await call("playthroughGet", { subject, generation, keys: assertKeys(keys, "session.storage.playthrough.get") });
@@ -239,10 +243,53 @@ function createPlaythrough(call, subject, generation) {
                 generation,
                 operationId: assertOperationId(operationId),
             });
-            return createPlaythrough(call, subject, assertGeneration(reset?.generation));
+            return createPlaythrough(call, subject, assertGeneration(reset?.generation), resetGeneration);
         },
     });
 }
+/** 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),
@@ -371,6 +418,13 @@ function assertGeneration(value) {
     }
     return value;
 }
+function optionalResetGeneration(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (Number.isSafeInteger(value) && value >= 1 && value <= MAX_GENERATION)
+        return value;
+    throw storageError("CAULDRON_STORAGE_INVALID_RESPONSE", "The platform returned an invalid progress reset generation.", "session.storage.playthrough");
+}
 function assertOperationId(value) {
     if (typeof value !== "string" ||
         value.length === 0 ||

package/dist/server/wrapper.d.ts

@@ -1,4 +1,4 @@
-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";
@@ -7,9 +7,9 @@ export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, Pla
 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 type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveConditionalCheck, SaveConditionalWriteInput, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRecentOperationsInput, SaveRecentOperationsPage, 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;
@@ -268,11 +268,41 @@ 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[];
+    /** Private host-brokered transcript metadata, not player-selected. */
+    hubTextArchive?: {
+        npcId: string;
+        conversationId?: string;
+        input: string;
+    };
+}
+/** 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;
@@ -284,6 +314,13 @@ export interface MultiplayerServerCallbacks {
     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;
     /**

package/dist/server/wrapper.js

@@ -1,3 +1,4 @@
+import { CastleError } from "../errors";
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
 import { encodeStorageValue, storageError } from "../storageJson";
 import { createServerStorage } from "./storage";
@@ -69,18 +70,15 @@ async function bootSession(platformHandle, callbacks) {
                     players: Object.freeze(request.audience.players.map((player) => Object.freeze(joinedPlayer(player.playerId, player)))),
                     characterIds: Object.freeze([...request.audience.characterIds]),
                 }),
-                async send() {
+                async send(options) {
                     if (settled)
                         throw new TypeError("This shared character request is already settled.");
                     settled = true;
-                    let rawReceipt;
-                    try {
-                        rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
-                    }
-                    catch (error) {
+                    const rawReceipt = await sendWorldCharacterTurn(platformHandle, request.grantId, options)
+                        .catch((error) => {
                         brokerFailure.rejection = { error };
                         throw error;
-                    }
+                    });
                     return parseWorldCharacterAdmission(rawReceipt, request.operationId);
                 },
                 reject(code) {
@@ -103,6 +101,7 @@ async function bootSession(platformHandle, callbacks) {
             }
         });
     }
+    listenForWorldCharacterTools(platformHandle, callbacks, session);
     if (callbacks.onWorldCharacterCommand &&
         hasWorldCharacterPlatform(platformHandle, "worldCharacterCommand")) {
         platformHandle.on("worldCharacterCommand", async (raw) => {
@@ -1081,12 +1080,13 @@ function assertRuntimeCharacterCapabilities(value) {
     }
     return Object.freeze({ actionIds: Object.freeze([...normalized].sort()) });
 }
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
 function assertRuntimeCharacterText(value, field, maxCharacters, maxBytes) {
     if (typeof value !== "string" ||
         value.length === 0 ||
         value.length > maxCharacters ||
         value.includes("\0") ||
-        /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value) ||
+        LONE_SURROGATE.test(value) ||
         new TextEncoder().encode(value).byteLength > maxBytes) {
         throw new TypeError(`session.world.characters.create: ${field} must be valid non-empty text of at most ${maxCharacters} characters.`);
     }
@@ -1190,6 +1190,87 @@ function assertPlatformWorldCharacterRead(value) {
     }
     return value;
 }
+// Tools ride only to a host that can answer them (an older host refuses a send
+// carrying anything beyond the grant); otherwise this is exactly the tool-less send.
+function sendWorldCharacterTurn(platformHandle, grantId, options) {
+    const tools = options?.tools;
+    if (options?.hubTextArchive !== undefined) {
+        if (platformHandle.hubTextArchiveEnabled !== true)
+            return Promise.reject(new CastleError({ code: 'CAULDRON_HUB_UNAVAILABLE', message: 'This host cannot archive NPC transcripts.', operation: 'worldCharacter.send' }));
+        return platformHandle.worldCharacterSend(grantId, Array.isArray(tools) && typeof platformHandle.worldCharacterToolResult === "function" ? tools : undefined, options.hubTextArchive);
+    }
+    return Array.isArray(tools) && tools.length > 0 &&
+        typeof platformHandle.worldCharacterToolResult === "function"
+        ? platformHandle.worldCharacterSend(grantId, tools)
+        : platformHandle.worldCharacterSend(grantId);
+}
+// Only a handler on a host that answers place tools listens; without one the
+// host times the lookup out and the character answers without it.
+function listenForWorldCharacterTools(platformHandle, callbacks, session) {
+    const handler = callbacks.onWorldCharacterTool;
+    const answer = platformHandle.worldCharacterToolResult?.bind(platformHandle);
+    if (!handler || !answer)
+        return;
+    try {
+        platformHandle.on("worldCharacterTool", async (raw) => {
+            const call = platformWorldCharacterTool(raw);
+            if (!call)
+                return;
+            const result = await worldCharacterToolResult(handler, call.request, session);
+            try {
+                await answer(call.requestId, result);
+            }
+            catch {
+                // The host has stopped waiting (or refused); the character answers without it.
+            }
+        });
+    }
+    catch {
+        // Older shims may reject event names they do not recognize.
+    }
+}
+const MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES = 1024;
+const WORLD_CHARACTER_TOOL_TOO_LARGE = '{"error":"result too large"}';
+const WORLD_CHARACTER_TOOL_FAILED = '{"error":"tool failed"}';
+function platformWorldCharacterTool(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.requestId !== "string" ||
+        typeof value.operationId !== "string" ||
+        typeof value.characterId !== "string" ||
+        typeof value.playerId !== "string" ||
+        typeof value.name !== "string" ||
+        !value.input ||
+        typeof value.input !== "object" ||
+        Array.isArray(value.input)) {
+        return null;
+    }
+    return {
+        requestId: value.requestId,
+        request: Object.freeze({
+            operationId: value.operationId,
+            characterId: value.characterId,
+            playerId: value.playerId,
+            name: value.name,
+            input: deepFreezeJsonObject(value.input),
+        }),
+    };
+}
+async function worldCharacterToolResult(handler, request, session) {
+    let result;
+    try {
+        const value = await handler(request, session);
+        result = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    catch {
+        return WORLD_CHARACTER_TOOL_FAILED;
+    }
+    if (typeof result !== "string")
+        return WORLD_CHARACTER_TOOL_FAILED;
+    return new TextEncoder().encode(result).byteLength > MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES
+        ? WORLD_CHARACTER_TOOL_TOO_LARGE
+        : result;
+}
 function hasWorldCharacterPlatform(platformHandle, operation) {
     return (typeof platformHandle[operation] === "function" &&
         typeof platformHandle.worldCharacterReject === "function");
@@ -1344,10 +1425,11 @@ function joinedPlayer(connId, identity) {
         delete player.hiddenUserIds;
         // A/B arms arrive beside the player; one a host put on it stays off it too.
         delete player.experimentVariants;
+        Object.defineProperty(player, "under13", { value: identity.under13 === true, enumerable: false });
         return player;
     }
     const legacy = connId;
-    return {
+    const player = {
         playerId: legacy.playerId,
         userId: legacy.userId,
         username: legacy.username,
@@ -1355,6 +1437,8 @@ function joinedPlayer(connId, identity) {
         participantId: legacy.scopedUserId ?? legacy.userId,
         ...(legacy.scopedUserId ? { scopedUserId: legacy.scopedUserId } : {}),
     };
+    Object.defineProperty(player, "under13", { value: legacy.under13 === true, enumerable: false });
+    return player;
 }
 function parseHandleMessage(text) {
     if (typeof text !== "string")

package/dist/social.d.ts

@@ -0,0 +1,9 @@
+import type { SocialFriend, SocialPresence } from './commands';
+export type { SocialFriend, SocialPresence } from './commands';
+export interface CastleSocialApi {
+    /** The signed-in player's mutual Castle follows, at most 20. */
+    friends(): Promise<SocialFriend[]>;
+    /** Mutual friends playing this deck now. Poll to refresh; v1 has no event. */
+    presence(): Promise<SocialPresence[]>;
+}
+export declare const Social: CastleSocialApi;

package/dist/social.js

@@ -0,0 +1,5 @@
+import { hostRequest } from './transport';
+export const Social = {
+    friends: () => hostRequest('social.friends', {}),
+    presence: () => hostRequest('social.presence', {}),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.46",
+  "version": "0.4.48",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"