castle-web-sdk 0.4.31 → 0.4.32

package/README.md

@@ -591,6 +591,31 @@ link.addEventListener("pointerenter", () => {
 });
 ```
 
+### `Portal.info(deckId): Promise<PortalInfoResult>`
+
+Where a portal leads: the destination deck's title, creator and cover, for a
+sign or label on the portal. A deck can't reach Castle's API or load remote
+images itself, so this is how it shows another deck's details. It needs a
+Castle login, which the app and a signed-in website visitor have; the cloud
+editor's preview and a signed-out visitor get `unavailable`, so keep your own
+label as the fallback. `PortalInfoResult` has a `status`:
+
+- `'ok'` — also has `deckId`, `title`, `creator` (`{ userId, username }` or
+  `null`), and `coverUrl`, a `data:` url of the deck's cover or `null`.
+- `'broken'` — the portal wouldn't work for this player: the deck doesn't
+  exist, has portals turned off, or isn't visible to them.
+- `'unavailable'` — the host couldn't look it up.
+
+```js
+const info = await Portal.info(doorway.deckId);
+if (info.status === "ok") {
+  sign.textContent = `${info.title} by @${info.creator?.username ?? "?"}`;
+  if (info.coverUrl) sign.style.backgroundImage = `url(${info.coverUrl})`;
+}
+```
+
+Answers are kept per deck for the session, so asking again is cheap.
+
 ## Haptics
 
 `Haptics` plays a short device vibration ("buzz") for tactile feedback —

package/dist/commands.d.ts

@@ -57,6 +57,18 @@ export interface PortalOpenResult {
     status: PortalOpenStatus;
 }
 export type PortalPrefetchStatus = "prefetching" | "rejected" | "unavailable";
+export type PortalInfoResult = {
+    status: "ok";
+    deckId: string;
+    title: string;
+    creator: {
+        userId: string;
+        username: string;
+    } | null;
+    coverUrl: string | null;
+} | {
+    status: "broken" | "unavailable";
+};
 export interface PortalPrefetchResult {
     status: PortalPrefetchStatus;
 }
@@ -186,6 +198,9 @@ export interface CommandParams {
     "portal.prefetch": {
         targetDeckId: string;
     };
+    "portal.info": {
+        targetDeckId: string;
+    };
     "haptics.play": {
         style: HapticStyle;
     };
@@ -306,6 +321,7 @@ export interface CommandResult {
     "snapshot.offer": SnapshotOfferResult;
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
+    "portal.info": PortalInfoResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
     "characters.open": CharacterAdmission;

package/dist/portal.d.ts

@@ -1,7 +1,8 @@
-import type { PortalOpenResult, PortalPrefetchResult } from "./commands";
-export type { PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./commands";
+import type { PortalInfoResult, PortalOpenResult, PortalPrefetchResult } from "./commands";
+export type { PortalInfoResult, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./commands";
 export interface CastlePortalApi {
     open(deckId: string): Promise<PortalOpenResult>;
     prefetch(deckId: string): Promise<PortalPrefetchResult>;
+    info(deckId: string): Promise<PortalInfoResult>;
 }
 export declare const Portal: CastlePortalApi;

package/dist/portal.js

@@ -7,11 +7,16 @@
 // Navigation is effectively fire-and-forget: once the host accepts it, the
 // source deck is torn down as the feed moves to the target, so a deck should
 // not rely on code running after a successful `open`.
+//
+// `info` is a plain read of where a portal leads: the target's title, creator
+// and cover, for a sign on the portal. It works on every host that has a
+// Castle login.
 import { CastleError } from "./errors";
 import { hostRequest } from "./transport";
 export const Portal = {
     open,
     prefetch,
+    info,
 };
 async function open(deckId) {
     if (typeof deckId !== "string" || deckId.length === 0) {
@@ -33,3 +38,20 @@ async function prefetch(deckId) {
     }
     return hostRequest("portal.prefetch", { targetDeckId: deckId });
 }
+async function info(deckId) {
+    if (typeof deckId !== "string" || deckId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Portal.info requires a deckId.",
+            operation: "Portal.info",
+        });
+    }
+    try {
+        return await hostRequest("portal.info", { targetDeckId: deckId });
+    }
+    catch {
+        // No login, an old host, or a failed lookup all read the same to a deck:
+        // there is nothing to show, so it keeps whatever label it had.
+        return { status: "unavailable" };
+    }
+}

package/package.json

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