castle-web-sdk 0.4.36 → 0.4.38

package/dist/server/wrapper.js

@@ -1,4 +1,5 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
+import { encodeStorageValue } from "../storageJson";
 import { createServerStorage } from "./storage";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
@@ -42,6 +43,109 @@ async function bootSession(platformHandle, callbacks) {
     catch {
         // Older shims may reject event names they do not recognize.
     }
+    if (callbacks.onWorldCharacterTurn &&
+        typeof platformHandle.worldCharacterSend === "function" &&
+        typeof platformHandle.worldCharacterReject === "function") {
+        platformHandle.on("worldCharacterTurn", async (raw) => {
+            const request = assertPlatformWorldCharacterTurn(raw);
+            let settled = false;
+            const turn = Object.freeze({
+                requestId: request.requestId,
+                operationId: request.operationId,
+                speaker: Object.freeze({ ...request.speaker }),
+                characterId: request.characterId,
+                input: request.input,
+                audience: Object.freeze({
+                    disclosure: request.audience.disclosure,
+                    players: Object.freeze(request.audience.players.map((player) => Object.freeze({ ...player }))),
+                    characterIds: Object.freeze([...request.audience.characterIds]),
+                }),
+                async send() {
+                    if (settled)
+                        throw new TypeError("This shared character request is already settled.");
+                    settled = true;
+                    const rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
+                    return parseWorldCharacterAdmission(rawReceipt, request.operationId);
+                },
+                reject(code) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    platformHandle.worldCharacterReject(request.grantId, code);
+                },
+            });
+            try {
+                await callbacks.onWorldCharacterTurn(session, turn);
+            }
+            finally {
+                if (!settled)
+                    turn.reject();
+            }
+        });
+    }
+    if (callbacks.onWorldCharacterCommand &&
+        hasWorldCharacterPlatform(platformHandle, "worldCharacterCommand")) {
+        platformHandle.on("worldCharacterCommand", async (raw) => {
+            const request = assertPlatformWorldCharacterCommand(raw);
+            let settled = false;
+            const command = Object.freeze({
+                requestId: request.requestId,
+                operationId: request.operationId,
+                speaker: Object.freeze({ ...request.speaker }),
+                command: deepFreezeJsonObject(request.command),
+                async apply() {
+                    if (settled)
+                        throw new TypeError("This shared character command is already settled.");
+                    settled = true;
+                    return parseSharedCharacterJson(await platformHandle.worldCharacterCommand(request.grantId));
+                },
+                reject(code) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    platformHandle.worldCharacterReject(request.grantId, code);
+                },
+            });
+            try {
+                await callbacks.onWorldCharacterCommand(session, command);
+            }
+            finally {
+                if (!settled)
+                    command.reject();
+            }
+        });
+    }
+    if (callbacks.onWorldCharacterRead &&
+        hasWorldCharacterPlatform(platformHandle, "worldCharacterRead")) {
+        platformHandle.on("worldCharacterRead", async (raw) => {
+            const request = assertPlatformWorldCharacterRead(raw);
+            let settled = false;
+            const read = Object.freeze({
+                requestId: request.requestId,
+                speaker: Object.freeze({ ...request.speaker }),
+                query: deepFreezeJsonObject(request.query),
+                async read() {
+                    if (settled)
+                        throw new TypeError("This shared character read is already settled.");
+                    settled = true;
+                    return parseSharedCharacterJson(await platformHandle.worldCharacterRead(request.grantId));
+                },
+                reject(code) {
+                    if (settled)
+                        return;
+                    settled = true;
+                    platformHandle.worldCharacterReject(request.grantId, code);
+                },
+            });
+            try {
+                await callbacks.onWorldCharacterRead(session, read);
+            }
+            finally {
+                if (!settled)
+                    read.reject();
+            }
+        });
+    }
     platformHandle.on("replaced", async () => {
         await callbacks.onReplaced?.(session);
     });
@@ -68,6 +172,7 @@ function createAuthorSession(platformHandle, players) {
         deckId: platformHandle.config.deckId,
         mode: platformHandle.config.mode,
         storage: createServerStorage(platformHandle),
+        world: createServerWorld(platformHandle),
         send(playerId, data) {
             if (isBinaryPayload(data)) {
                 requireSendBinary(platformHandle);
@@ -106,6 +211,235 @@ function createAuthorSession(platformHandle, players) {
         },
     };
 }
+const WORLD_OPERATION_ID_MAX_BYTES = 128;
+const WORLD_OPERATION_ID_MAX_CHARACTERS = 120;
+const WORLD_CHECKPOINT_VERSION_MAX = 2_147_483_647;
+function createServerWorld(platformHandle) {
+    if (!platformHandle.config.world)
+        return null;
+    if (typeof platformHandle.worldCheckpointRead !== "function" ||
+        typeof platformHandle.worldCheckpointCommit !== "function") {
+        throw worldError("The persistent-world checkpoint broker is unavailable.", "read");
+    }
+    const initial = parseWorldSnapshot(platformHandle.config.world, "read");
+    return Object.freeze({
+        snapshot: initial,
+        characters: createServerWorldCharacters(platformHandle),
+        async read() {
+            const result = await platformHandle.worldCheckpointRead();
+            return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
+        },
+        async commit(input) {
+            const expectedRevision = assertWorldRevision(input?.expectedRevision);
+            const operationId = assertWorldOperationId(input?.operationId);
+            const checkpoint = assertWorldCheckpoint(input?.checkpoint);
+            const raw = await platformHandle.worldCheckpointCommit(JSON.stringify({
+                expectedRevision,
+                operationId,
+                checkpoint,
+            }));
+            const result = parsePlatformJson(raw, "commit");
+            if (typeof result.replayed !== "boolean") {
+                throw worldError("The platform returned an invalid commit receipt.", "commit");
+            }
+            return Object.freeze({
+                revision: assertWorldRevision(result.revision),
+                replayed: result.replayed,
+                operationId,
+            });
+        },
+    });
+}
+function createServerWorldCharacters(platformHandle) {
+    return Object.freeze({
+        async publicInspect() {
+            if (typeof platformHandle.storage !== "function") {
+                throw new TypeError("The shared character broker is unavailable.");
+            }
+            return parseSharedCharacterJson(await platformHandle.storage("worldCharacterPublicInspect", "{}"));
+        },
+        async publicRelay(input) {
+            if (typeof platformHandle.storage !== "function") {
+                throw new TypeError("The shared character broker is unavailable.");
+            }
+            const operationId = assertWorldOperationId(input?.operationId);
+            const sourceId = assertWorldCharacterId(input?.sourceId, "sourceId", 128);
+            const transmittingCharacterId = assertWorldCharacterId(input?.transmittingCharacterId, "transmittingCharacterId");
+            if (!Array.isArray(input?.recipientCharacterIds) ||
+                input.recipientCharacterIds.length > 3) {
+                throw new TypeError("session.world.characters.publicRelay: recipientCharacterIds may contain at most 3 ids.");
+            }
+            const recipientCharacterIds = input.recipientCharacterIds.map((id) => assertWorldCharacterId(id, "recipientCharacterIds"));
+            if (new Set(recipientCharacterIds).size !== recipientCharacterIds.length) {
+                throw new TypeError("session.world.characters.publicRelay: recipientCharacterIds may not contain duplicates.");
+            }
+            return parseSharedCharacterJson(await platformHandle.storage("worldCharacterPublicRelay", JSON.stringify({
+                operationId,
+                sourceId,
+                transmittingCharacterId,
+                recipientCharacterIds: recipientCharacterIds.sort(),
+            })));
+        },
+    });
+}
+function parseWorldSnapshot(value, operation) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw worldError("The platform returned an invalid world checkpoint.", "read");
+    }
+    const raw = value;
+    return Object.freeze({
+        revision: assertWorldRevision(raw.revision),
+        checkpoint: raw.checkpoint === null
+            ? null
+            : assertWorldCheckpoint(raw.checkpoint, operation),
+    });
+}
+function assertPlatformWorldCharacterTurn(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.grantId !== "string" ||
+        typeof value.requestId !== "string" ||
+        typeof value.operationId !== "string" ||
+        typeof value.characterId !== "string" ||
+        typeof value.input !== "string" ||
+        !value.speaker ||
+        typeof value.speaker.playerId !== "string" ||
+        !value.audience ||
+        (value.audience.disclosure !== "participants" && value.audience.disclosure !== "world") ||
+        !Array.isArray(value.audience.players) ||
+        !Array.isArray(value.audience.characterIds)) {
+        throw new TypeError("The platform sent an invalid shared character request.");
+    }
+    return value;
+}
+function assertPlatformWorldCharacterCommand(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.grantId !== "string" ||
+        typeof value.requestId !== "string" ||
+        typeof value.operationId !== "string" ||
+        !value.speaker ||
+        typeof value.speaker.playerId !== "string" ||
+        !value.command ||
+        typeof value.command !== "object" ||
+        Array.isArray(value.command)) {
+        throw new TypeError("The platform sent an invalid shared character command.");
+    }
+    return value;
+}
+function assertPlatformWorldCharacterRead(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.grantId !== "string" ||
+        typeof value.requestId !== "string" ||
+        !value.speaker ||
+        typeof value.speaker.playerId !== "string" ||
+        !value.query ||
+        typeof value.query !== "object" ||
+        Array.isArray(value.query)) {
+        throw new TypeError("The platform sent an invalid shared character read.");
+    }
+    return value;
+}
+function hasWorldCharacterPlatform(platformHandle, operation) {
+    return (typeof platformHandle[operation] === "function" &&
+        typeof platformHandle.worldCharacterReject === "function");
+}
+function deepFreezeJsonObject(value) {
+    const normalized = JSON.parse(JSON.stringify(value));
+    deepFreeze(normalized);
+    return normalized;
+}
+function deepFreeze(value) {
+    if (!value || typeof value !== "object")
+        return;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+}
+function parseSharedCharacterJson(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        throw new TypeError("The platform returned an invalid shared character response.");
+    }
+}
+function assertWorldCharacterId(value, field, maxCharacters = 100) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maxCharacters ||
+        value.includes("\0") ||
+        new TextEncoder().encode(value).byteLength > 128) {
+        throw new TypeError(`session.world.characters: ${field} must be non-empty text of at most ${maxCharacters} characters and 128 bytes.`);
+    }
+    return value;
+}
+function parseWorldCharacterAdmission(json, operationId) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        throw new TypeError("The platform returned an invalid shared character receipt.");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("The platform returned an invalid shared character receipt.");
+    }
+    const receipt = value;
+    if (receipt.operationId !== operationId ||
+        (receipt.status !== "queued" &&
+            receipt.status !== "completed" &&
+            receipt.status !== "interrupted") ||
+        typeof receipt.replayed !== "boolean") {
+        throw new TypeError("The platform returned an invalid shared character receipt.");
+    }
+    return Object.freeze({
+        operationId,
+        status: receipt.status,
+        replayed: receipt.replayed,
+    });
+}
+function assertWorldCheckpoint(value, operation = "commit") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw worldError("A world checkpoint requires version and value.", operation);
+    }
+    const raw = value;
+    if (!Number.isSafeInteger(raw.version) ||
+        raw.version < 0 ||
+        raw.version > WORLD_CHECKPOINT_VERSION_MAX) {
+        throw worldError(`A world checkpoint version must be an integer from 0 through ${WORLD_CHECKPOINT_VERSION_MAX}.`, operation);
+    }
+    const text = encodeStorageValue(raw.value, `session.world.${operation}`);
+    const normalized = JSON.parse(text);
+    return Object.freeze({ version: raw.version, value: normalized });
+}
+function assertWorldRevision(value) {
+    if (typeof value === "string" && /^(?:0|[1-9][0-9]*)$/.test(value))
+        return value;
+    throw worldError("A world checkpoint revision must be a canonical decimal string.", "commit");
+}
+function assertWorldOperationId(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > WORLD_OPERATION_ID_MAX_CHARACTERS ||
+        value.includes("\0") ||
+        new TextEncoder().encode(value).byteLength > WORLD_OPERATION_ID_MAX_BYTES) {
+        throw worldError(`A world checkpoint operation id must be at most ${WORLD_OPERATION_ID_MAX_CHARACTERS} characters and ${WORLD_OPERATION_ID_MAX_BYTES} bytes.`, "commit");
+    }
+    return value;
+}
+function parsePlatformJson(value, operation) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw worldError("The platform returned an invalid world checkpoint response.", operation);
+    }
+}
+function worldError(message, operation) {
+    return new TypeError(`session.world.${operation}: ${message}`);
+}
 function requireSendBinary(platformHandle) {
     if (typeof platformHandle.sendBinary !== "function")
         unsupportedBinaryRuntime();

package/dist/transport.js

@@ -23,6 +23,7 @@ const INTERACTIVE_COMMANDS = new Set([
     "pass.offer",
     "snapshot.offer",
     "portal.open",
+    "multiplayer.joinDestination",
     // The host's voice prompt and the browser's microphone permission.
     "voice.requestJoin",
 ]);

package/package.json

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