castle-web-sdk 0.4.44 → 0.4.46

package/dist/hub.js

@@ -0,0 +1,107 @@
+import { CastleError } from "./errors";
+import { hostRequest, setHubEventHandler } from "./transport";
+export const Hub = {
+    go,
+    back,
+    doors,
+    friends,
+    jump,
+    report,
+    chat,
+    say,
+    reportChat,
+    cancel,
+    onBack,
+};
+async function go(doorId) {
+    if (typeof doorId !== "string" || doorId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.go requires a doorId.",
+            operation: "Hub.go",
+        });
+    }
+    return hostRequest("hub.go", { doorId });
+}
+async function back() {
+    return hostRequest("hub.back", {});
+}
+async function doors() {
+    return hostRequest("hub.doors", {});
+}
+async function friends() {
+    return hostRequest("hub.friends", {});
+}
+async function jump(userId) {
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.jump requires a userId.",
+            operation: "Hub.jump",
+        });
+    }
+    return hostRequest("hub.jump", { userId });
+}
+async function report(userId, reason) {
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.report requires a userId.",
+            operation: "Hub.report",
+        });
+    }
+    return hostRequest("hub.report", typeof reason === "string" && reason.length > 0 ? { userId, reason } : { userId });
+}
+async function chat(after) {
+    return hostRequest("hub.chat", typeof after === "string" && after.length > 0 ? { after } : {});
+}
+async function say(text) {
+    if (typeof text !== "string" || text.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.say requires a text.",
+            operation: "Hub.say",
+        });
+    }
+    return hostRequest("hub.say", { text });
+}
+async function reportChat(messageId) {
+    if (typeof messageId !== "string" || messageId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.reportChat requires a messageId.",
+            operation: "Hub.reportChat",
+        });
+    }
+    return hostRequest("hub.reportChat", { messageId });
+}
+async function cancel() {
+    return hostRequest("hub.cancel", {});
+}
+const backListeners = new Set();
+function onBack(listener) {
+    if (typeof listener !== "function") {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.onBack requires a function.",
+            operation: "Hub.onBack",
+        });
+    }
+    backListeners.add(listener);
+    setHubEventHandler(dispatchHubEvent);
+    return () => {
+        backListeners.delete(listener);
+        if (backListeners.size === 0)
+            setHubEventHandler(null);
+    };
+}
+function dispatchHubEvent() {
+    for (const listener of [...backListeners]) {
+        try {
+            listener();
+        }
+        catch (error) {
+            console.error("Castle Hub.onBack listener threw:", error);
+        }
+    }
+}

package/dist/multiplayer.d.ts

@@ -1,8 +1,9 @@
-import type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
+import type { HubHandoffResult, MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
 import type { Json } from "./types";
 import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
 import { type MultiplayerVoice } from "./multiplayerVoice";
+export type { MultiplayerJoinHint } from "./commands";
 export type MultiplayerJoinOptions = {
     mode: "named";
     key: string;
@@ -10,6 +11,9 @@ export type MultiplayerJoinOptions = {
     mode: "party";
 } | {
     mode: "public";
+} | {
+    mode: "hub";
+    handoff: HubHandoffResult;
 };
 export interface MultiplayerDestinationOptions {
     routeId: string;
@@ -78,7 +82,45 @@ export type MultiplayerWorldCharacterCommand = {
     type: "record_event";
     eventTypeId: string;
     data?: Json;
+    /** Characters that saw it (at most 4); each may act on its own about the recorder. */
+    witnesses?: string[];
+} | MultiplayerEvaluateBeatsCommand | MultiplayerCompleteScheduledBeatCommand;
+export type MultiplayerStoryOpportunity = {
+    type: "approach" | "room_entry" | "world_action";
+    id: string;
 };
+export interface MultiplayerEvaluateBeatsCommand {
+    type: "evaluate_beats";
+    opportunityId: string;
+    opportunity: MultiplayerStoryOpportunity;
+    presentCharacterIds: string[];
+}
+export interface MultiplayerCompleteScheduledBeatCommand {
+    type: "complete_scheduled_beat";
+    deliveryId: string;
+    outcomeId: string;
+}
+export interface MultiplayerScheduledBeatSelection {
+    deliveryId: string;
+    beatId: string;
+    characterId: string;
+    openingText: string;
+}
+export interface MultiplayerScheduledBeatReason {
+    beatId: string;
+    status: "selected" | "expired" | "eligible" | "blocked";
+    reasonCodes: string[];
+}
+export interface MultiplayerEvaluateBeatsResult {
+    selection: MultiplayerScheduledBeatSelection | null;
+    reasons?: MultiplayerScheduledBeatReason[];
+}
+export interface MultiplayerCompleteScheduledBeatResult {
+    deliveryId: string;
+    outcomeId: string;
+    completed: true;
+}
+export type MultiplayerWorldCharacterCommandResultValue<Command extends MultiplayerWorldCharacterCommand> = Command extends MultiplayerEvaluateBeatsCommand ? MultiplayerEvaluateBeatsResult : Command extends MultiplayerCompleteScheduledBeatCommand ? MultiplayerCompleteScheduledBeatResult : Json;
 export type MultiplayerWorldCharacterQuery = {
     type: "inspect";
 } | {
@@ -89,7 +131,33 @@ export type MultiplayerWorldCharacterQuery = {
     characterId?: string;
     limit?: number;
     cursor?: string;
+}
+/** Autonomous-action notices after a cursor (world-visible). */
+ | {
+    type: "actions";
+    after?: string;
 };
+/** One autonomous character decision in a shared world. */
+export interface MultiplayerCharacterActionNotice {
+    characterId: string;
+    /** The participant the character acted about: the one whose deed it witnessed. */
+    participantId: string;
+    trigger: {
+        type: "witnessed";
+        id: string;
+    };
+    outcome: "acted" | "declined" | "failed";
+    actionId?: string;
+    variantId?: string;
+    eventOccurrenceId?: string;
+    probability?: number;
+    /** Feed cursor; pass the last one as `after` to read only newer notices. */
+    sequence: string;
+}
+export interface MultiplayerWorldCharacterActionsResult {
+    notices: MultiplayerCharacterActionNotice[];
+    after: string;
+}
 /** Authenticated, participant-scoped projection of a shared character world. */
 export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, SharedState = unknown, PrivateState = unknown, Source = unknown> {
     /** Durable identity used by gameplay holders and promise debtors. */
@@ -105,11 +173,11 @@ export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, Shar
     }>;
     sources: Source[];
 }
-export interface MultiplayerWorldCharacterCommandResult {
+export interface MultiplayerWorldCharacterCommandResult<Result = unknown> {
     operationId: string;
     status: "applied" | "ineligible";
     replayed: boolean;
-    result: unknown;
+    result: Result;
     worldRevision: string;
 }
 export interface MultiplayerConnection {
@@ -122,17 +190,24 @@ export interface MultiplayerConnection {
      * `private_deck` and `no_server_bundle` are the creator's to fix.
      */
     readonly soloReason: MultiplayerSoloReason | null;
+    /**
+     * Whether the host brokers shared characters into this session (its hello
+     * advertised them): a shared-character world, or a hub place's layer with
+     * place characters. The character calls below refuse while this is false.
+     * Read it when needed: a reconnect can land on a host that says otherwise.
+     */
+    readonly sharedCharacters: boolean;
     /** Sends byte payloads as binary frames and all other payloads as JSON. */
     send(data: unknown): void;
     /** Requests one billed character turn through this authenticated world socket. */
     requestCharacterTurn(request: MultiplayerCharacterTurnRequest): Promise<MultiplayerCharacterTurnAdmission>;
     /** Recovers the durable status of a prior operation after reconnecting. */
     getCharacterTurnStatus(operationId: string): Promise<MultiplayerCharacterTurnStatusResult>;
-    requestCharacterCommand(request: {
+    requestCharacterCommand<Command extends MultiplayerWorldCharacterCommand>(request: {
         requestId: string;
         operationId: string;
-        command: MultiplayerWorldCharacterCommand;
-    }): Promise<MultiplayerWorldCharacterCommandResult>;
+        command: Command;
+    }): Promise<MultiplayerWorldCharacterCommandResult<MultiplayerWorldCharacterCommandResultValue<Command>>>;
     readCharacters(request: {
         requestId: string;
         query: {
@@ -152,7 +227,14 @@ export interface MultiplayerConnection {
     leave(): void;
 }
 export interface CastleMultiplayerApi {
+    /**
+     * True on an SDK whose session server can address a hub place's shared
+     * characters from a layer (`session.characters` without `session.world`).
+     * Absent on older SDKs, so a kit can tell before joining.
+     */
+    readonly placeCharacters: true;
     join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
+    joinHint(): Promise<MultiplayerJoinHint | null>;
     joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;
 }
 export declare const Multiplayer: CastleMultiplayerApi;

package/dist/multiplayer.js

@@ -18,20 +18,88 @@ let nextCharacterStatusRequestId = 1;
 let activeConnection = null;
 let latestJoinAttempt = 0;
 let pendingDestinationJoin = null;
-export const Multiplayer = { join, joinDestination };
+export const Multiplayer = {
+    placeCharacters: true,
+    join,
+    joinHint,
+    joinDestination,
+};
+async function joinHint() {
+    try {
+        return await hostRequest("multiplayer.getJoinHint", {});
+    }
+    catch (error) {
+        if (error instanceof CastleError && error.code === "UNKNOWN_COMMAND")
+            return null;
+        throw error;
+    }
+}
 async function join(options) {
-    const params = joinParams(options);
+    const hub = hubJoin(options);
+    const request = hub
+        ? { command: "hub", nonce: hub.nonce }
+        : { command: "multiplayer.getSession", params: joinParams(options) };
     latestJoinAttempt += 1;
     cancelPendingDestinationJoin();
     activeConnection?.leave();
-    const connection = new MultiplayerConnectionImpl({ command: "multiplayer.getSession", params }, () => {
+    const connection = new MultiplayerConnectionImpl(request, () => {
         if (activeConnection === connection)
             activeConnection = null;
     });
     activeConnection = connection;
-    await connection.start();
+    await connection.start(hub ?? undefined);
+    // The host moves its place (and every place-scoped command with it) when the
+    // trip commits; the deck gets the connection once it has. A trip that did not
+    // commit leaves the player where they were, so its connection is closed.
+    if (!(await connection.hubCommitted())) {
+        connection.leave();
+        throw multiplayerError("MULTIPLAYER_UNAVAILABLE", "The hub trip could not be completed; the player is still where they were.", "Multiplayer.join");
+    }
+    connection.handedOver();
     return connection;
 }
+// A hub handoff is joined as it was acquired; it cannot be acquired again.
+// The host answers `unavailable` while ghost is busy with this player; the
+// trip stays pending there, so asking again is safe.
+const HUB_COMMIT_RETRY_MS = [1_000, 2_000, 4_000, 8_000];
+async function commitHubTrip(nonce, sessionId) {
+    for (let attempt = 0;; attempt++) {
+        let status;
+        try {
+            status = (await hostRequest("hub.commit", { nonce })).status;
+        }
+        catch (error) {
+            status = error instanceof CastleError ? error.code : "unavailable";
+        }
+        if (status === "committed")
+            return true;
+        const delay = HUB_COMMIT_RETRY_MS[attempt];
+        if ((status !== "unavailable" && status !== "CASTLE_HOST_UNAVAILABLE") || delay === undefined) {
+            console.warn(`Castle hub trip to ${sessionId} was not committed: ${status}`);
+            return false;
+        }
+        await pause(delay);
+    }
+}
+function hubJoin(options) {
+    if (!options || typeof options !== "object" || options.mode !== "hub")
+        return null;
+    const handoff = options.handoff;
+    if (!handoff ||
+        handoff.status !== "ok" ||
+        typeof handoff.url !== "string" ||
+        typeof handoff.nonce !== "string" ||
+        typeof handoff.sessionId !== "string") {
+        throw multiplayerError("INVALID_ARGUMENT", "Multiplayer.join({ mode: \"hub\" }) requires an ok result from Hub.go or Hub.back.", "Multiplayer.join");
+    }
+    return {
+        status: "ok",
+        url: handoff.url,
+        nonce: handoff.nonce,
+        sessionId: handoff.sessionId,
+        soloReason: null,
+    };
+}
 async function joinDestination(options) {
     const params = destinationParams(options);
     const attempt = ++latestJoinAttempt;
@@ -102,6 +170,8 @@ async function joinDestination(options) {
     activeConnection = connection;
     return { status: "joined", connection, audience: acquired.audience };
 }
+// How many messages are kept for a deck that has not attached a listener yet.
+const EARLY_MESSAGES_MAX = 512;
 class MultiplayerConnectionImpl {
     request;
     onClosed;
@@ -119,10 +189,22 @@ class MultiplayerConnectionImpl {
     keepalive = null;
     reAcquisitionUsed = false;
     recovering = false;
+    hubSettled = false;
+    hubCommit = Promise.resolve(true);
     roster = null;
     sharedCharactersSupported = false;
     pendingCharacterRequests = new Map();
     messages = new Set();
+    // Messages that arrived before the deck had a listener, on a hub join only.
+    // A hub join resolves some tasks after the socket's hello (it first commits
+    // with the host), and a place greets a player with a snapshot in that gap:
+    // with nobody listening it was dropped, and the deck never saw the state it
+    // joined into. They are kept, in order, for a listener attached as soon as
+    // the deck is handed the connection (`handedOver`); a deck that attaches one
+    // later gets only what arrives from then on. Null on every other join, which
+    // resolves in the hello's own task: nothing is kept there and delivery is
+    // exactly what it always was.
+    early = null;
     rosters = new Set();
     states = new Set();
     voiceImpl = new MultiplayerVoiceImpl({
@@ -150,6 +232,9 @@ class MultiplayerConnectionImpl {
     get soloReason() {
         return this.currentSoloReason;
     }
+    get sharedCharacters() {
+        return this.sharedCharactersSupported;
+    }
     get voice() {
         return this.voiceImpl;
     }
@@ -158,6 +243,7 @@ class MultiplayerConnectionImpl {
             await this.acquire(initial);
         }
         catch (error) {
+            this.settleHub("cancel");
             const castleError = asCastleError(error);
             if (this.currentState !== "closed") {
                 this.finish({ type: "error", error: castleError });
@@ -239,8 +325,43 @@ class MultiplayerConnectionImpl {
     }
     onMessage(callback) {
         this.messages.add(callback);
+        const early = this.early;
+        if (early) {
+            // The first listener takes what arrived before it; later ones get only
+            // what arrives from now on, as before.
+            this.early = null;
+            for (const data of early) {
+                // A listener that leaves part-way hears no more.
+                if (this.currentState === "closed")
+                    break;
+                callListener(callback, data);
+            }
+        }
         return () => this.messages.delete(callback);
     }
+    /**
+     * The deck is being handed this connection. Whatever arrived before that is
+     * kept through the deck's own next step (the code after its `await`), where
+     * a kit attaches its listener; after that, nothing more is kept.
+     */
+    handedOver() {
+        if (!this.early)
+            return;
+        setTimeout(() => {
+            if (this.messages.size === 0)
+                this.early = null;
+        }, 0);
+    }
+    deliver(data) {
+        if (this.early && this.messages.size === 0) {
+            // Bounded: a deck that never listens does not grow this forever.
+            if (this.early.length < EARLY_MESSAGES_MAX)
+                this.early.push(data);
+            return;
+        }
+        for (const callback of this.messages)
+            callListener(callback, data);
+    }
     onRoster(callback) {
         this.rosters.add(callback);
         if (this.roster)
@@ -255,8 +376,27 @@ class MultiplayerConnectionImpl {
     leave() {
         if (this.currentState === "closed")
             return;
+        this.settleHub("cancel");
         this.finish({ type: "left" });
     }
+    // A hub trip is the host's to commit or cancel, once: committed when the
+    // destination first says hello, cancelled if the join ends before that. The
+    // acquisition is named by its nonce, which no other acquisition shares.
+    settleHub(outcome) {
+        if (this.request.command !== "hub" || this.hubSettled)
+            return;
+        this.hubSettled = true;
+        const nonce = this.request.nonce;
+        if (outcome === "cancel") {
+            hostRequest("hub.cancel", { nonce }).catch(() => { });
+            return;
+        }
+        this.early = [];
+        this.hubCommit = commitHubTrip(nonce, this.currentSessionId);
+    }
+    hubCommitted() {
+        return this.hubCommit;
+    }
     matchesDestination(params) {
         return (this.currentState !== "closed" &&
             this.request.command === "multiplayer.joinDestination" &&
@@ -319,6 +459,8 @@ class MultiplayerConnectionImpl {
     }
     connectSolo(result) {
         this.solo = true;
+        // A solo session has no host, so no characters, whatever the last socket's hello offered.
+        this.sharedCharactersSupported = false;
         this.currentSoloReason = result.soloReason ?? "unavailable";
         this.currentPlayerId = "solo";
         this.currentSessionId = result.sessionId ?? "solo";
@@ -412,6 +554,7 @@ class MultiplayerConnectionImpl {
         // is backgrounded many times in a play, and each of those is its own outage;
         // without this the second one finds the budget spent and closes for good.
         this.reAcquisitionUsed = false;
+        this.settleHub("commit");
         this.transition("connected");
         this.startKeepalive();
         void this.voiceImpl.attach();
@@ -422,8 +565,7 @@ class MultiplayerConnectionImpl {
                 this.acceptRoster(frame);
                 break;
             case "m":
-                for (const callback of this.messages)
-                    callListener(callback, frame.d);
+                this.deliver(frame.d);
                 break;
             case "worldCharacterResult":
                 this.acceptWorldCharacterResult(frame);
@@ -448,8 +590,7 @@ class MultiplayerConnectionImpl {
         if (bytes.byteLength < 1 || bytes[0] !== BINARY_MESSAGE_TAG)
             return;
         const payload = new Uint8Array(buffer, 1);
-        for (const callback of this.messages)
-            callListener(callback, payload);
+        this.deliver(payload);
     }
     acceptRoster(frame) {
         const players = frame.players.slice();
@@ -559,6 +700,7 @@ class MultiplayerConnectionImpl {
         this.socketAttempt += 1;
         closeSocket(socket, 1000, "session closed");
         this.currentState = "closed";
+        this.early = null;
         this.voiceImpl.dispose();
         for (const callback of this.states)
             callStateListener(callback, "closed", metadata);
@@ -675,6 +817,11 @@ function cancelPendingDestinationJoin() {
     pending?.connection?.leave();
 }
 async function requestAcquisition(request) {
+    if (request.command === "hub") {
+        // The nonce was single-use and the trip is the host's; a hub session that
+        // cannot be reconnected to is left by going back through the door.
+        throw multiplayerError("MULTIPLAYER_CONNECTION_LOST", "A hub session cannot be acquired again. Go back through the door.");
+    }
     if (request.command === "multiplayer.getSession") {
         return hostRequest(request.command, request.params);
     }
@@ -768,6 +915,42 @@ function normalizeWorldCharacterCommandRequest(request) {
                 type: "record_event",
                 eventTypeId: boundedCharacterText(command.eventTypeId, 128, "command.eventTypeId", WORLD_CHARACTER_ID_MAX_CHARACTERS),
                 ...(command.data === undefined ? {} : { data: normalizeJson(command.data, "command.data") }),
+                ...(command.witnesses === undefined ? {} : { witnesses: normalizeWitnesses(command.witnesses) }),
+            },
+        };
+    }
+    if (command.type === "evaluate_beats") {
+        const opportunity = command.opportunity;
+        if (!opportunity || typeof opportunity !== "object") {
+            throw characterError("INVALID_ARGUMENT", "command.opportunity must be an opportunity object.");
+        }
+        if (opportunity.type !== "approach" &&
+            opportunity.type !== "room_entry" &&
+            opportunity.type !== "world_action") {
+            throw characterError("INVALID_ARGUMENT", "command.opportunity.type is invalid.");
+        }
+        return {
+            requestId,
+            operationId,
+            command: {
+                type: "evaluate_beats",
+                opportunityId: boundedCharacterSafeKey(command.opportunityId, "command.opportunityId"),
+                opportunity: {
+                    type: opportunity.type,
+                    id: boundedCharacterSafeKey(opportunity.id, "command.opportunity.id"),
+                },
+                presentCharacterIds: boundedCharacterSafeKeys(command.presentCharacterIds, 16, "command.presentCharacterIds"),
+            },
+        };
+    }
+    if (command.type === "complete_scheduled_beat") {
+        return {
+            requestId,
+            operationId,
+            command: {
+                type: "complete_scheduled_beat",
+                deliveryId: boundedCharacterSafeKey(command.deliveryId, "command.deliveryId"),
+                outcomeId: boundedCharacterSafeKey(command.outcomeId, "command.outcomeId"),
             },
         };
     }
@@ -798,8 +981,20 @@ function normalizeWorldCharacterReadRequest(request) {
             },
         };
     }
+    if (query.type === "actions") {
+        if (query.after !== undefined && (typeof query.after !== "string" || !/^\d{1,18}$/.test(query.after))) {
+            throw characterError("INVALID_ARGUMENT", "Character actions cursor must be a sequence string.");
+        }
+        return { requestId, query: { type: "actions", ...(query.after === undefined ? {} : { after: query.after }) } };
+    }
     throw characterError("INVALID_ARGUMENT", "Unknown shared character query type.");
 }
+function normalizeWitnesses(value) {
+    if (!Array.isArray(value) || value.length > 4) {
+        throw characterError("INVALID_ARGUMENT", "command.witnesses must be at most 4 character ids.");
+    }
+    return value.map((item, index) => boundedCharacterText(item, 128, `command.witnesses[${index}]`, WORLD_CHARACTER_ID_MAX_CHARACTERS));
+}
 function normalizeJson(value, field) {
     try {
         const text = JSON.stringify(value);
@@ -821,6 +1016,22 @@ function boundedCharacterIds(value, maxItems, field, maxCharacters = 128) {
     }
     return ids;
 }
+function boundedCharacterSafeKeys(value, maxItems, field) {
+    if (!Array.isArray(value) || value.length > maxItems) {
+        throw characterError("INVALID_ARGUMENT", `${field} may contain at most ${maxItems} ids.`);
+    }
+    const ids = value.map((item) => boundedCharacterSafeKey(item, field));
+    if (new Set(ids).size !== ids.length) {
+        throw characterError("INVALID_ARGUMENT", `${field} may not contain duplicate ids.`);
+    }
+    return ids;
+}
+function boundedCharacterSafeKey(value, field) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) {
+        throw characterError("INVALID_ARGUMENT", `${field} must be a safe key of at most 64 characters.`);
+    }
+    return value;
+}
 function boundedCharacterText(value, maxBytes, field, maxCharacters = maxBytes) {
     if (typeof value !== "string" ||
         value.length === 0 ||