castle-web-sdk 0.4.3 → 0.4.5

package/dist/transport.js

@@ -0,0 +1,126 @@
+// Deck-side command-poster. The SDK never makes API calls or holds the auth
+// token; every privileged operation becomes a `command` posted to the outer
+// runtime (host), which validates it, stamps trusted context, runs the call
+// with its own auth, and replies. Three host channels:
+//   - mobile  → window.ReactNativeWebView.postMessage; host pushes responses
+//               back by calling window.__castleSdkHost.receive(...)
+//   - web     → window.parent.postMessage; responses via 'message' events
+//   - local   → the castle-web serve dev server, over runtime.ts's websocket
+// Error reconstruction is uniform here so callers always get a CastleError.
+import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, } from "./commands";
+import { getCastleEmbed } from "./context";
+import { CastleError } from "./errors";
+import { sendLocalCommand } from "./runtime";
+const REQUEST_TIMEOUT_MS = 15000;
+// Interactive platform commands hold the screen while the player interacts with
+// a host-native sheet (e.g. a pass purchase), so the flat data-command timeout
+// is wrong for them: they get NO timeout and resolve only when the host replies.
+const INTERACTIVE_COMMANDS = new Set([
+    "pass.offer",
+]);
+let nextRequestId = 1;
+const pending = new Map();
+let listenersInstalled = false;
+export async function hostRequest(command, params) {
+    try {
+        const channel = resolveChannel();
+        const env = channel === "local"
+            ? await sendLocalCommand(command, params)
+            : await postCommand(channel, command, params);
+        return interpretResponse(command, env);
+    }
+    catch (error) {
+        // Honor the SDK contract that every thrown error is a CastleError. Errors
+        // surfaced by the host (interpretResponse) are already CastleErrors; this
+        // wraps transport-level failures (host timeout / unreachable / dev server
+        // disconnected) that would otherwise be plain Errors.
+        if (error instanceof CastleError)
+            throw error;
+        throw new CastleError({
+            code: "CASTLE_HOST_UNAVAILABLE",
+            message: error instanceof Error
+                ? error.message
+                : `Castle host did not handle ${command}.`,
+            operation: command,
+        });
+    }
+}
+// Exposed so capability modules (e.g. passes) can tell whether the current host
+// has its own UI surface over the deck. "mobile"/"web" hosts render their own
+// purchase/upsell UI; the "local" dev server has none, so the SDK itself shows
+// a minimal in-page notice there.
+export function getCommandChannel() {
+    return resolveChannel();
+}
+function resolveChannel() {
+    if (typeof window === "undefined")
+        return "local";
+    if (window.ReactNativeWebView)
+        return "mobile";
+    const host = getCastleEmbed()?.host;
+    if (host === "web")
+        return "web";
+    if (host === "dev")
+        return "local";
+    // Fallback: an iframe with a parent is the web player; otherwise assume the
+    // local dev server (top-level page served by `castle-web serve`).
+    return window.parent && window.parent !== window ? "web" : "local";
+}
+function postCommand(channel, command, params) {
+    installResponseListener();
+    const requestId = `csdk_${nextRequestId++}`;
+    return new Promise((resolve, reject) => {
+        const timeout = INTERACTIVE_COMMANDS.has(command)
+            ? undefined
+            : setTimeout(() => {
+                pending.delete(requestId);
+                reject(new Error(`Castle host did not respond to ${command}.`));
+            }, REQUEST_TIMEOUT_MS);
+        pending.set(requestId, { resolve, reject, timeout });
+        sendEnvelope(channel, { castleSdk: CASTLE_SDK_PROTOCOL, requestId, command, params });
+    });
+}
+function sendEnvelope(channel, envelope) {
+    const json = JSON.stringify(envelope);
+    if (channel === "mobile") {
+        window.ReactNativeWebView?.postMessage(json);
+    }
+    else {
+        window.parent.postMessage(envelope, "*");
+    }
+}
+// The mobile host can't dispatch a DOM 'message' event, so it calls this global
+// directly with the parsed envelope. The web host posts a 'message' event.
+function installResponseListener() {
+    if (listenersInstalled || typeof window === "undefined")
+        return;
+    listenersInstalled = true;
+    window.__castleSdkHost = { receive: (message) => settle(message) };
+    window.addEventListener("message", (event) => {
+        settle(event.data);
+    });
+}
+function settle(message) {
+    if (!isResponseEnvelope(message))
+        return;
+    const entry = pending.get(message.requestId);
+    if (!entry)
+        return;
+    if (entry.timeout)
+        clearTimeout(entry.timeout);
+    pending.delete(message.requestId);
+    entry.resolve(message);
+}
+function interpretResponse(command, env) {
+    if (env.ok)
+        return env.data;
+    throw fromSerializedError(env.error, command);
+}
+function fromSerializedError(error, command) {
+    return new CastleError({
+        code: error?.code ?? "CASTLE_HOST_ERROR",
+        message: error?.message ?? `Castle command ${command} failed.`,
+        operation: error?.command ?? command,
+        extensions: error?.extensions,
+    });
+}

package/dist/user.js

@@ -1,14 +1,5 @@
-import { requireAuthToken } from "./auth";
 import { CastleError } from "./errors";
-import { graphqlRequest } from "./graphql";
-const CURRENT_USER_QUERY = `
-  query CastleCurrentUser {
-    me {
-      userId
-      username
-    }
-  }
-`;
+import { hostRequest } from "./transport";
 let currentUser = null;
 let currentUserPromise = null;
 export const User = {
@@ -25,25 +16,17 @@ async function getCurrent() {
 }
 async function fetchCurrentUser() {
     const operation = "User.getCurrent";
-    const token = await requireAuthToken(operation);
-    const data = await graphqlRequest(CURRENT_USER_QUERY, undefined, {
-        operation,
-        requireAuth: true,
-        token,
-    });
-    if (!data.me) {
+    const { user } = await hostRequest("user.getCurrent", {});
+    if (!user) {
         throw new CastleError({
             code: "LOGIN_REQUIRED",
             message: "Log in to Castle before using User.getCurrent().",
             operation,
         });
     }
-    return normalizeCurrentUser(data.me, operation);
-}
-function normalizeCurrentUser(user, operation) {
     return {
-        userId: requiredString(user.userId, "me.userId", operation),
-        username: requiredString(user.username, "me.username", operation),
+        userId: requiredString(user.userId, "user.userId", operation),
+        username: requiredString(user.username, "user.username", operation),
         isActive: true,
     };
 }
@@ -52,7 +35,7 @@ function requiredString(value, field, operation) {
         return value;
     throw new CastleError({
         code: "GRAPHQL_BAD_DATA",
-        message: `Castle GraphQL response did not include ${field}.`,
+        message: `Castle response did not include ${field}.`,
         operation,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",
@@ -10,13 +10,17 @@
       "default": "./dist/castle.js"
     }
   },
+  "//host": "host.{js,d.ts} is the host-side executor — deliberately NOT exported and NOT packaged. It is vendored into host repos via scripts/copy-host-module.mjs; decks must never receive it.",
   "files": [
     "dist",
-    "src"
+    "src",
+    "!dist/host.js",
+    "!dist/host.d.ts",
+    "!src/host.ts"
   ],
   "scripts": {
-    "build": "tsc",
-    "check": "eslint . && jscpd && tsc --noEmit && tsc"
+    "build": "rm -rf dist && tsc",
+    "check": "eslint . && jscpd && tsc --noEmit && npm run build"
   },
   "jscpd": {
     "path": [

package/src/castle.ts

@@ -10,7 +10,13 @@ export type {
   LeaderboardScope,
   LeaderboardSort,
 } from "./leaderboard";
-export { CARD_RATIO, initCard, setup, writeFile } from "./runtime";
+export { Pass } from "./passes";
+export type {
+  CastlePassApi,
+  PassOfferResult,
+  PassOfferStatus,
+} from "./passes";
+export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";

package/src/commands.ts

@@ -0,0 +1,136 @@
+// The SDK↔host command contract. This is the single source of truth for the
+// wire protocol shared by the deck-side command-poster (`transport.ts`) and the
+// host-side executor (`host.ts`). It carries ONLY names and types — no GraphQL
+// query strings and no auth — so importing it into a deck bundle reveals
+// nothing privileged.
+
+import type { Json } from "./types";
+
+// Marker + protocol version. Doubles as a discriminator so host messages can't
+// be confused with embed.js `castlexyz:` strings or RN console messages.
+export const CASTLE_SDK_PROTOCOL = 1;
+
+export type StorageBlob = Record<string, string>;
+export type SharedScope = "deck" | "user";
+
+export interface StorageUpdate {
+  key: string;
+  value: string | null;
+}
+
+// The raw GraphQL leaderboard shape the host returns; the SDK normalizes it
+// (and computes playerRank from `currentUserId`) into the public LeaderboardData.
+export interface RawLeaderboardEntry {
+  place?: string | number | null;
+  score?: string | number | null;
+  user?: { userId?: string | null; username?: string | null } | null;
+}
+
+export interface RawLeaderboard {
+  list?: RawLeaderboardEntry[] | null;
+  yourScore?: { score?: string | number | null } | null;
+}
+
+export type PassOfferStatus =
+  | "purchased"
+  | "alreadyOwned"
+  | "cancelled"
+  | "unavailable";
+
+export interface PassOfferResult {
+  status: PassOfferStatus;
+}
+
+export interface CommandParams {
+  "deckStorage.load": Record<string, never>;
+  "deckStorage.update": { updates: StorageUpdate[] };
+  "sharedDeckStorage.load": {
+    scope: SharedScope;
+    userId?: string | null;
+    keys: string[];
+  };
+  "sharedDeckStorage.update": { scope: SharedScope; updates: StorageUpdate[] };
+  "leaderboard.fetch": {
+    variable: string;
+    type: "high" | "low";
+    scope?: string | null;
+    // When present, the deck has a freshly-written score for this
+    // variable+scope that hasn't settled server-side yet. The host routes
+    // through the leaderboardV2 mutation, which writes this score and returns
+    // the post-write leaderboard atomically, so the player's own score shows
+    // up immediately. Absent → a plain read of the settled leaderboard.
+    score?: number | null;
+  };
+  "leaderboard.save": { variable: string; score: number; scope?: string | null };
+  "user.getCurrent": Record<string, never>;
+  "time.getServerTime": Record<string, never>;
+  "pass.has": { passId: string };
+  // Platform/interactive command — dispatched to the host's platformHandler,
+  // not graphqlFetch. Unlike the data commands above, this one can stay open
+  // for a long time (the player interacting with a native sheet), so the
+  // deck-side transport gives it no timeout.
+  "pass.offer": { passId: string };
+}
+
+export interface CommandResult {
+  "deckStorage.load": { blob: StorageBlob };
+  "deckStorage.update": { blob: StorageBlob };
+  "sharedDeckStorage.load": { blob: StorageBlob };
+  "sharedDeckStorage.update": { ok: true };
+  "leaderboard.fetch": {
+    leaderboard: RawLeaderboard;
+    currentUserId: string | null;
+  };
+  "leaderboard.save": { ok: true };
+  "user.getCurrent": { user: { userId: string; username: string } | null };
+  "time.getServerTime": {
+    timestamp: number;
+    timezoneOffset: number;
+    castleEpochData: Json;
+  };
+  "pass.has": { hasPass: boolean };
+  "pass.offer": PassOfferResult;
+}
+
+export type CommandName = keyof CommandParams;
+
+// NB: the runtime command allowlist (COMMAND_NAMES / isCommandName) lives in
+// host.ts, not here, so that host.ts can keep ALL of its imports type-only and
+// compile to a single self-contained file (zero runtime imports) that vendors
+// cleanly into Node-ESM / webpack / Metro hosts in other repos.
+
+// Serializable error that survives the postMessage boundary. The deck-side
+// rebuilds a real CastleError from it, preserving `code` so decks can branch.
+export interface SerializedCommandError {
+  code: string;
+  message: string;
+  command?: string;
+  extensions?: Record<string, unknown>;
+}
+
+export interface CommandRequestEnvelope {
+  castleSdk: typeof CASTLE_SDK_PROTOCOL;
+  requestId: string;
+  command: CommandName;
+  params: unknown;
+}
+
+export interface CommandResponseEnvelope {
+  castleSdk: typeof CASTLE_SDK_PROTOCOL;
+  requestId: string;
+  ok: boolean;
+  data?: unknown;
+  error?: SerializedCommandError;
+}
+
+export function isResponseEnvelope(
+  value: unknown,
+): value is CommandResponseEnvelope {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    record.castleSdk === CASTLE_SDK_PROTOCOL &&
+    typeof record.requestId === "string" &&
+    typeof record.ok === "boolean"
+  );
+}

package/src/context.ts

@@ -1,25 +1,11 @@
-import { CastleError } from "./errors";
-
-export interface CastleDeckContext {
-  deckId?: string | null;
-  cardId?: string | null;
-  sessionId?: string | null;
-}
-
-interface CastleEmbedAuth {
-  token?: string | null;
-  userId?: string | null;
-}
+// Which outer runtime is hosting the deck. Set by each host alongside the
+// (now non-secret) CastleEmbed flags; used by transport.ts to pick a channel.
+export type CastleHost = "web" | "mobile" | "dev";
 
 export interface CastleEmbed {
   edit?: boolean;
   feed?: boolean;
-  auth?: CastleEmbedAuth;
-  deck?: CastleDeckContext;
-  deckId?: string;
-  cardId?: string;
-  sessionId?: string | null;
-  graphqlEndpoint?: string;
+  host?: CastleHost;
 }
 
 declare global {
@@ -28,10 +14,6 @@ declare global {
   }
 }
 
-let configuredDeckContext: CastleDeckContext = {};
-let cachedDeckContext: CastleDeckContext | null = null;
-let cachedDeckContextPromise: Promise<CastleDeckContext> | null = null;
-
 export function getCastleEmbed(): CastleEmbed | undefined {
   return typeof window === "undefined" ? undefined : window.CastleEmbed;
 }
@@ -46,79 +28,3 @@ export function isEdit(): boolean {
   }
   return !!getCastleEmbed()?.edit;
 }
-
-export function configureDeckContext(context: CastleDeckContext): void {
-  configuredDeckContext = cleanDeckContext(context);
-  cachedDeckContext = null;
-  cachedDeckContextPromise = null;
-}
-
-export async function getDeckContext(): Promise<CastleDeckContext> {
-  if (cachedDeckContext) return cachedDeckContext;
-  cachedDeckContextPromise ??= resolveDeckContext();
-  return cachedDeckContextPromise;
-}
-
-export async function requireDeckId(
-  operation = "Castle API request",
-): Promise<string> {
-  const context = await getDeckContext();
-  if (!context.deckId) {
-    throw new CastleError({
-      code: "MISSING_DECK_ID",
-      message: "This Castle API needs a deck id.",
-      operation,
-    });
-  }
-  return context.deckId;
-}
-
-async function resolveDeckContext(): Promise<CastleDeckContext> {
-  const embedded = embeddedDeckContext();
-  const local = await localDeckContext();
-  const context = mergeDeckContexts(configuredDeckContext, embedded, local);
-  cachedDeckContext = context;
-  return context;
-}
-
-function embeddedDeckContext(): CastleDeckContext {
-  const embed = getCastleEmbed();
-  return cleanDeckContext({
-    deckId: embed?.deck?.deckId ?? embed?.deckId,
-    cardId: embed?.deck?.cardId ?? embed?.cardId,
-    sessionId: embed?.deck?.sessionId ?? embed?.sessionId,
-  });
-}
-
-async function localDeckContext(): Promise<CastleDeckContext> {
-  try {
-    const res = await fetch("/__castle/context");
-    if (!res.ok) return {};
-    return cleanDeckContext((await res.json()) as CastleDeckContext);
-  } catch {
-    return {};
-  }
-}
-
-function cleanDeckContext(context: CastleDeckContext): CastleDeckContext {
-  return {
-    deckId: stringOrNull(context.deckId),
-    cardId: stringOrNull(context.cardId),
-    sessionId: stringOrNull(context.sessionId),
-  };
-}
-
-function mergeDeckContexts(
-  ...contexts: CastleDeckContext[]
-): CastleDeckContext {
-  return cleanDeckContext({
-    deckId: contexts.find((context) => context.deckId)?.deckId,
-    cardId: contexts.find((context) => context.cardId)?.cardId,
-    sessionId: contexts.find((context) => context.sessionId)?.sessionId,
-  });
-}
-
-function stringOrNull(value: string | null | undefined): string | null {
-  if (typeof value !== "string") return null;
-  return value.length > 0 ? value : null;
-}