castle-web-sdk 0.4.46 → 0.4.48

package/dist/party.js

@@ -0,0 +1,91 @@
+import { CastleError } from './errors';
+import { hostRequest } from './transport';
+export const Party = {
+    current,
+    create,
+    invite,
+    respond,
+    members,
+    leave,
+    messages,
+    say,
+};
+const ID_MAX = 128;
+const CURSOR_MAX = 512;
+const PARTY_USERS_MAX = 32;
+function id(value, field, operation) {
+    return boundedText(value, field, operation, ID_MAX);
+}
+function boundedText(value, field, operation, max) {
+    if (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= max &&
+        !value.includes('\0')) {
+        return value;
+    }
+    throw new CastleError({
+        code: 'INVALID_ARGUMENT',
+        message: `${operation} requires a valid ${field}.`,
+        operation,
+    });
+}
+function ids(value, operation) {
+    if (!Array.isArray(value) || value.length > PARTY_USERS_MAX) {
+        throw new CastleError({
+            code: 'INVALID_ARGUMENT',
+            message: `${operation} requires at most ${PARTY_USERS_MAX} user ids.`,
+            operation,
+        });
+    }
+    return value.map((value) => id(value, 'userId', operation));
+}
+async function current() {
+    return hostRequest('party.current', {});
+}
+async function create(userIds) {
+    return hostRequest('party.create', { userIds: ids(userIds, 'Party.create') });
+}
+async function invite(partyId, userIds) {
+    return hostRequest('party.invite', {
+        partyId: id(partyId, 'partyId', 'Party.invite'),
+        userIds: ids(userIds, 'Party.invite'),
+    });
+}
+async function respond(partyId, accept) {
+    if (typeof accept !== 'boolean') {
+        throw new CastleError({
+            code: 'INVALID_ARGUMENT',
+            message: 'Party.respond requires accept to be a boolean.',
+            operation: 'Party.respond',
+        });
+    }
+    return hostRequest('party.respond', {
+        partyId: id(partyId, 'partyId', 'Party.respond'),
+        accept,
+    });
+}
+async function members(partyId) {
+    return hostRequest('party.members', { partyId: id(partyId, 'partyId', 'Party.members') });
+}
+async function leave(partyId) {
+    return hostRequest('party.leave', { partyId: id(partyId, 'partyId', 'Party.leave') });
+}
+async function messages(partyId, cursor) {
+    const params = {
+        partyId: id(partyId, 'partyId', 'Party.messages'),
+    };
+    if (cursor !== undefined) {
+        params.cursor = boundedText(cursor, 'cursor', 'Party.messages', CURSOR_MAX);
+    }
+    return hostRequest('party.messages', params);
+}
+async function say(partyId, text) {
+    if (typeof text !== 'string' || text.length === 0) {
+        throw new CastleError({
+            code: 'INVALID_ARGUMENT',
+            message: 'Party.say requires text.',
+            operation: 'Party.say',
+        });
+    }
+    return hostRequest('party.say', { partyId: id(partyId, 'partyId', 'Party.say'), text });
+}

package/dist/save.d.ts

@@ -63,6 +63,13 @@ export interface SaveTransactionInput {
     checks?: SaveCheck[];
     changes: SaveChange[];
 }
+export interface SaveConditionalCheck extends Omit<SaveCheck, "expectedRevision"> {
+    /** Null checks absence without creating the target. */
+    expectedRevision: SaveRevision | null;
+}
+export interface SaveConditionalWriteInput extends Omit<SaveTransactionInput, "checks"> {
+    checks?: SaveConditionalCheck[];
+}
 export interface SaveInitial {
     target: SaveTarget;
     rows: SaveRows;
@@ -95,8 +102,24 @@ export type SaveOperation = {
 } | {
     state: "unknown";
 };
-export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation";
+export interface SaveRecentOperationsInput {
+    limit?: number;
+    cursor?: string;
+}
+export interface SaveRecentOperationsPage {
+    operations: {
+        operationId: string;
+        committedAt: string;
+        receipt: SaveReceipt;
+    }[];
+    cursor: string | null;
+}
+export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation" | "conditionalWrite" | "recentOperations";
 export interface SaveApi {
+    /** Gated atomic revision check and write, up to eight targets and two players. */
+    conditionalWrite(input: SaveConditionalWriteInput): Promise<SaveReceipt>;
+    /** Gated caller-scoped receipt discovery after losing local operation IDs. */
+    recentOperations(input?: SaveRecentOperationsInput): Promise<SaveRecentOperationsPage>;
     snapshot(input: {
         targets: SaveReadTarget[];
     }): Promise<SaveSnapshot>;
@@ -156,6 +179,7 @@ export interface SaveErrorEnvelope {
     receipt?: SaveReceipt;
     retryAfterMs?: number;
     target?: SaveTarget;
+    current?: SaveSnapshot;
     [detail: string]: unknown;
 }
 export declare class SaveError extends CastleError {
@@ -165,6 +189,7 @@ export declare class SaveError extends CastleError {
     readonly receipt?: SaveReceipt;
     readonly retryAfterMs?: number;
     readonly target?: SaveTarget;
+    readonly current?: SaveSnapshot;
     constructor(envelope: SaveErrorEnvelope);
 }
 /**

package/dist/save.js

@@ -7,6 +7,7 @@ export class SaveError extends CastleError {
     receipt;
     retryAfterMs;
     target;
+    current;
     constructor(envelope) {
         super({
             code: envelope.code,
@@ -20,6 +21,7 @@ export class SaveError extends CastleError {
         this.receipt = envelope.receipt;
         this.retryAfterMs = envelope.retryAfterMs;
         this.target = envelope.target;
+        this.current = envelope.current;
     }
 }
 /**
@@ -60,7 +62,8 @@ const MAX_SUBJECT_BYTES = 256;
 const MAX_VALUE_BYTES = 256 * 1024;
 const encoder = new TextEncoder();
 const byteLength = (text) => encoder.encode(text).length;
-const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+// Unicode mode consumes valid pairs together; avoid lookbehind for Safari < 16.4.
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
 function invalid(message) {
     throw new SaveError({
         code: "CAULDRON_STORAGE_INVALID_ARGUMENT",
@@ -240,12 +243,14 @@ function encodeChange(change, server) {
         ...(remove === undefined ? {} : { remove }),
     };
 }
-function encodeCheck(check, server) {
+function encodeCheck(check, server, conditional = false) {
     const target = validateSaveTarget(check.target, server);
+    if (conditional && check.expectedRevision === undefined)
+        invalid("Every conditional check needs an expected revision.");
     if (check.expectedRevision === undefined && check.writer === undefined) {
         invalid("A check needs an expected revision or a writer.");
     }
-    if (check.expectedRevision !== undefined) {
+    if (check.expectedRevision !== undefined && !(conditional && check.expectedRevision === null)) {
         checkText(check.expectedRevision, "expected revision");
     }
     if (check.writer !== undefined)
@@ -258,7 +263,7 @@ function encodeCheck(check, server) {
         ...(check.writer === undefined ? {} : { writer: check.writer }),
     };
 }
-function encodeTransaction(input, server) {
+function encodeTransaction(input, server, conditional = false) {
     const changes = checkList(input.changes, "changes").map((change) => encodeChange(change, server));
     const keys = changes.map((change) => saveTargetKey(change.target));
     if (new Set(keys).size !== keys.length) {
@@ -270,7 +275,7 @@ function encodeTransaction(input, server) {
         ...(input.checks === undefined
             ? {}
             : {
-                checks: checkList(input.checks, "checks").map((check) => encodeCheck(check, server)),
+                checks: checkList(input.checks, "checks").map((check) => encodeCheck(check, server, conditional)),
             }),
         changes,
     };
@@ -282,12 +287,26 @@ export function encodeSaveInput(verb, input, server = false) {
     }
     if (verb === "snapshot")
         return { targets: encodeReads(input.targets, server) };
+    if (verb === "recentOperations") {
+        const limit = input.limit ?? 16;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 32)
+            invalid("Recovery limit must be 1 to 32.");
+        if (input.cursor !== undefined)
+            checkText(input.cursor, "recovery cursor", 2048);
+        return { limit, ...(input.cursor === undefined ? {} : { cursor: input.cursor }) };
+    }
     checkText(input.operationId, "operation id", MAX_KEY_BYTES);
     if (verb === "operation")
         return { operationId: input.operationId };
-    if (verb === "transaction") {
+    if (verb === "transaction" || verb === "conditionalWrite") {
+        if (verb === "conditionalWrite") {
+            const changes = input.changes;
+            const checks = input.checks ?? [];
+            if (!Array.isArray(changes) || !changes.length || changes.length + checks.length > 8)
+                invalid("Conditional writes require 1 to 8 targets.");
+        }
         return {
-            ...encodeTransaction(input, server),
+            ...encodeTransaction(input, server, verb === "conditionalWrite"),
         };
     }
     if (input.expectedAccess !== undefined) {
@@ -422,6 +441,34 @@ export function createSaveApi(call, server = false) {
         }
     }
     return {
+        async conditionalWrite(input) {
+            const result = await send("conditionalWrite", { ...input });
+            return decodeReceipt(result, input.operationId, input.changes.map((change) => change.target));
+        },
+        async recentOperations(input = {}) {
+            const page = (await send("recentOperations", {
+                ...input,
+            }));
+            if (!page ||
+                !Array.isArray(page.operations) ||
+                page.operations.length > (input.limit ?? 16) ||
+                (page.cursor !== null && typeof page.cursor !== "string"))
+                invalidResponse();
+            return {
+                operations: page.operations.map((operation) => {
+                    if (!operation ||
+                        typeof operation.operationId !== "string" ||
+                        typeof operation.committedAt !== "string")
+                        invalidResponse();
+                    return {
+                        operationId: operation.operationId,
+                        committedAt: operation.committedAt,
+                        receipt: decodeReceipt(operation.receipt, operation.operationId, []),
+                    };
+                }),
+                cursor: page.cursor,
+            };
+        },
         async snapshot(input) {
             return decodeSnapshot(await send("snapshot", { ...input }), input.targets);
         },

package/dist/server/hub.d.ts

@@ -64,6 +64,52 @@ export interface MultiplayerHubWearReceipt {
     /** What the player now wears; null when cleared. */
     wearable: MultiplayerHubWearable | null;
 }
+/** The classes of earned item a hub game may give (contract v1.53). */
+export type MultiplayerHubEarnedClass = "badge" | "pin" | "belt" | "sash" | "held";
+/** The home classes a hub game may give (contract v1.70/v1.73), never worn. */
+export type MultiplayerHubHomeClass = "furniture" | "deed" | "pet";
+/**
+ * An earned item: something a hub game gave a player for a stated deed, declared
+ * in that game's castle.json `hub.unlocks` and kept by Castle per account. It has
+ * no rarity. `deckId` is the game that declared it; `id` and `shape` match
+ * /^[a-z][a-z0-9-]{0,23}$/, `color` is '#rrggbb'.
+ */
+export interface MultiplayerHubEarnedItem {
+    deckId: string;
+    id: string;
+    class: MultiplayerHubEarnedClass;
+    shape: string;
+    name: string;
+    deed: string;
+    color: string;
+}
+/** A furniture piece, area deed or adopted pet owned for the house, never shown on an avatar. */
+export interface MultiplayerHubHomeItem {
+    deckId: string;
+    id: string;
+    class: MultiplayerHubHomeClass;
+    piece: string;
+    name: string;
+    deed: string;
+    color: string;
+}
+export interface MultiplayerHubUnlockReceipt {
+    unlocked: true;
+    /** True when this call gave the player the item for the first time. */
+    isNew: boolean;
+    /** What the player now shows in the earned slot (never a home item); null when none. */
+    earned: MultiplayerHubEarnedItem | null;
+}
+export interface MultiplayerHubWearEarnedReceipt {
+    /** What the player now shows in the earned slot; null when cleared. */
+    earned: MultiplayerHubEarnedItem | null;
+}
+export interface MultiplayerHubUnlocksRead {
+    /** Each player's owned wearable and home items, by user id. */
+    players: Record<string, {
+        owned: (MultiplayerHubEarnedItem | MultiplayerHubHomeItem)[];
+    }>;
+}
 export interface MultiplayerHubPadUpdateInput {
     /** A pad door of this place, from ghost's door table. */
     doorId: string;
@@ -91,8 +137,12 @@ export interface MultiplayerHubPlayerResults {
     records: MultiplayerHubRecord[];
     /** The player's platform avatar, chosen or default; null when ghost has none to say. */
     avatar: number | null;
+    /** Account-wide door hearts, oldest first; absent on older ghosts. */
+    hearts?: string[];
     /** The player's wearable; null when none. Absent from a ghost older than wearables. */
     wearable?: MultiplayerHubWearable | null;
+    /** The earned item the player shows (contract v1.53); absent when none. */
+    earned?: MultiplayerHubEarnedItem;
 }
 export interface MultiplayerHubBoard {
     toDeckId: string;
@@ -134,6 +184,27 @@ export interface MultiplayerHubResultsRead {
  * and for a deck that declares no hub block.
  */
 export interface MultiplayerServerHub {
+    /** Durably appends NPC words to a private platform archive. No read operation. */
+    archiveText(playerId: string, entry: {
+        npcId: string;
+        characterId?: string;
+        conversationId?: string;
+        operationId: string;
+        input?: string;
+        reply?: string;
+    }): Promise<void>;
+    /** Numeric hub telemetry; unavailable/refused delivery returns false, never blocks play. */
+    track(playerId: string, event: {
+        kind: number;
+        subject?: number;
+        value?: number;
+        result?: number;
+        flags?: number;
+    }): Promise<boolean>;
+    /** The owner user id, only in an owner door instance. */
+    readonly owner?: string;
+    /** Host-pinned inclusive reconnect grace for this hub place, in milliseconds. */
+    readonly reconnectWindowMs?: number;
     readonly place: string | null;
     readonly title: string | null;
     readonly result: MultiplayerHubResultShape | null;
@@ -156,6 +227,45 @@ export interface MultiplayerServerHub {
      * without it).
      */
     wear(playerId: string, wearable: MultiplayerHubWearable | null): Promise<MultiplayerHubWearReceipt>;
+    /**
+     * Gives a signed-in player one of this deck's declared earned items (castle.json
+     * `hub.unlocks`), by its id. Castle takes it only from a curated hub place, for a
+     * declared id; a first wearable unlock is also shown. Home items are never worn.
+     * Rejects with a `CAULDRON_HUB_*` code
+     * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    unlock(playerId: string, itemId: string): Promise<MultiplayerHubUnlockReceipt>;
+    /**
+     * Chooses which owned earned item a signed-in player shows, or none with null.
+     * Castle takes it only from the town; home items are refused.
+     * Rejects with a `CAULDRON_HUB_*` code
+     * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    wearEarned(playerId: string, earned: {
+        deckId: string;
+        id: string;
+    } | null): Promise<MultiplayerHubWearEarnedReceipt>;
+    /**
+     * The earned items players here own, by user id. Rejects with a `CAULDRON_HUB_*`
+     * code (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    readUnlocks(userIds: readonly string[]): Promise<MultiplayerHubUnlocksRead>;
+    /** The connected player's friends among these candidates; platform refusals reject. */
+    friendsAmong(playerId: string, userIds: readonly string[]): Promise<string[]>;
+    /**
+     * The connected player's mutual friends and follows in either direction among
+     * these candidates, in one host read. Missing lists are empty; refusals reject.
+     * Optional strict mode rejects malformed raw lists and marks the result validated.
+     * These relations belong to this player only; never send them to another client.
+     */
+    relationsAmong(playerId: string, userIds: readonly string[], options?: {
+        strict: true;
+    }): Promise<{
+        validated?: true;
+        friends: string[];
+        follows: string[];
+        followedBy: string[];
+    }>;
     /**
      * Whether a block hides these two players from each other: either one blocked
      * the other, in either direction. Symmetric. The block lists themselves stay

package/dist/server/hub.js

@@ -39,6 +39,18 @@ function hubHiddenUserIds(raw) {
     }
     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}`,
+    });
+}
+function reconnectMetadata(pinned) {
+    const value = pinned.reconnectWindowMs;
+    return pinned.result === null && typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 180_000
+        ? { reconnectWindowMs: value } : {};
+}
 export function createServerHub(platformHandle, arrivals, hiddenPair = () => false) {
     const pinned = platformHandle.hub;
     if (!pinned ||
@@ -65,16 +77,67 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
         }
         return parsed;
     };
-    return Object.freeze({
+    const hub = {
+        async archiveText(playerId, entry) {
+            if (platformHandle.hubTextArchiveEnabled !== true || typeof platformHandle.storage !== "function")
+                throw unavailable("archiveText", "archive NPC transcripts");
+            const raw = await platformHandle.storage("hubTextArchive", JSON.stringify({ ...entry, playerId }));
+            if (JSON.parse(raw)?.recorded !== true)
+                throw unavailable("archiveText", "archive NPC transcripts");
+        },
         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 } : {}),
+        ...reconnectMetadata(pinned),
         arrival(playerId) {
             return arrivals.get(playerId) ?? null;
         },
         hiddenPair(playerIdA, playerIdB) {
             return hiddenPair(playerIdA, playerIdB);
         },
+        async track(playerId, event) {
+            try {
+                const json = JSON.stringify({ ...event, playerId });
+                const raw = await platformHandle.storage?.("hubTrack", json);
+                return JSON.parse(raw ?? "null")?.recorded === true;
+            }
+            catch {
+                return false;
+            }
+        },
+        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, options = undefined) {
+            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");
+            if (options?.strict === true && (!answer || ["userIds", "follows", "followedBy"].some((key) => !Array.isArray(answer[key]) || answer[key].length > 100 || answer[key].some((id) => typeof id !== "string" || !/^\d{1,20}$/.test(id) || !asked.has(id))))) {
+                throw new CastleError({ code: "CAULDRON_HUB_INVALID_RESPONSE", message: "The platform returned an invalid friends response.", operation: "session.hub.relationsAmong" });
+            }
+            const list = (value) => Array.isArray(value)
+                ? value.filter((id) => typeof id === "string" && asked.has(id))
+                : [];
+            return {
+                ...(options?.strict === true ? { validated: true } : {}),
+                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", {
@@ -121,5 +184,44 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
                 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 ?? {}),
+            };
+        },
+    };
+    // Preserve the enumerable API shape and diagnostic serialization of existing
+    // places. Opted-in kits call this method explicitly; it adds no wire field.
+    Object.defineProperty(hub, "track", { enumerable: false });
+    Object.defineProperty(hub, "archiveText", { enumerable: false });
+    return Object.freeze(hub);
 }

package/dist/server/platformHandle.d.ts

@@ -6,6 +6,8 @@ export interface PlayerIdentity {
     username: string;
     isAnonymous: boolean;
     scopedUserId?: string;
+    /** Trusted hub age boundary; omitted by older hosts. Never client supplied. */
+    under13?: boolean;
 }
 export interface PlatformSessionConfig {
     readonly sessionId: string;
@@ -53,6 +55,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.
@@ -65,15 +68,26 @@ export interface PlatformHandle {
     storage?(op: string, argsJson: string): Promise<string>;
     /** False when the host cannot broker storage, so a call can fail at once. */
     readonly storageEnabled?: boolean;
+    readonly hubTextArchiveEnabled?: boolean;
     /** 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[], hubTextArchive?: {
+        npcId: string;
+        conversationId?: string;
+        input: string;
+    }): 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
@@ -83,8 +97,16 @@ export interface PlatformHandle {
     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 {
@@ -98,6 +120,8 @@ export interface PlatformHubResultShape {
     stats: Record<string, "number" | "string">;
 }
 export interface PlatformHubPlace {
+    owner?: string;
+    reconnectWindowMs?: number;
     place?: string;
     title?: string | null;
     result?: PlatformHubResultShape | null;
@@ -124,6 +148,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

@@ -23,6 +23,12 @@ export interface ServerStorageScope extends SaveBucketApi {
     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;
@@ -45,6 +51,8 @@ export interface ServerStorageBoard {
  */
 export interface ServerPlaythrough {
     readonly generation: number;
+    /** Present only after an administrator reset this player's deck progress. */
+    readonly resetGeneration?: number;
     /** Explicit narrative changes for this same player and generation. */
     readonly characters: ServerPlaythroughCharacters;
     get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
@@ -263,6 +271,13 @@ export interface ServerStorage extends SaveApi {
     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>;