castle-web-sdk 0.4.3 → 0.4.5

package/src/transport.ts

@@ -0,0 +1,169 @@
+// 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,
+  type CommandName,
+  type CommandParams,
+  type CommandResponseEnvelope,
+  type CommandResult,
+  type SerializedCommandError,
+} 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: ReadonlySet<CommandName> = new Set<CommandName>([
+  "pass.offer",
+]);
+
+type PostChannel = "mobile" | "web";
+
+interface PendingCommand {
+  resolve: (env: CommandResponseEnvelope) => void;
+  reject: (error: Error) => void;
+  timeout?: ReturnType<typeof setTimeout>;
+}
+
+interface ReactNativeWebViewBridge {
+  postMessage: (message: string) => void;
+}
+
+declare global {
+  interface Window {
+    ReactNativeWebView?: ReactNativeWebViewBridge;
+    __castleSdkHost?: { receive: (message: unknown) => void };
+  }
+}
+
+let nextRequestId = 1;
+const pending = new Map<string, PendingCommand>();
+let listenersInstalled = false;
+
+export async function hostRequest<C extends CommandName>(
+  command: C,
+  params: CommandParams[C],
+): Promise<CommandResult[C]> {
+  try {
+    const channel = resolveChannel();
+    const env =
+      channel === "local"
+        ? await sendLocalCommand(command, params)
+        : await postCommand(channel, command, params);
+    return interpretResponse(command, env) as CommandResult[C];
+  } 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(): PostChannel | "local" {
+  return resolveChannel();
+}
+
+function resolveChannel(): PostChannel | "local" {
+  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<C extends CommandName>(
+  channel: PostChannel,
+  command: C,
+  params: CommandParams[C],
+): Promise<CommandResponseEnvelope> {
+  installResponseListener();
+  const requestId = `csdk_${nextRequestId++}`;
+  return new Promise<CommandResponseEnvelope>((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: PostChannel, envelope: unknown): void {
+  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(): void {
+  if (listenersInstalled || typeof window === "undefined") return;
+  listenersInstalled = true;
+  window.__castleSdkHost = { receive: (message) => settle(message) };
+  window.addEventListener("message", (event: MessageEvent) => {
+    settle(event.data);
+  });
+}
+
+function settle(message: unknown): void {
+  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: CommandName,
+  env: CommandResponseEnvelope,
+): unknown {
+  if (env.ok) return env.data;
+  throw fromSerializedError(env.error, command);
+}
+
+function fromSerializedError(
+  error: SerializedCommandError | undefined,
+  command: CommandName,
+): CastleError {
+  return new CastleError({
+    code: error?.code ?? "CASTLE_HOST_ERROR",
+    message: error?.message ?? `Castle command ${command} failed.`,
+    operation: error?.command ?? command,
+    extensions: error?.extensions,
+  });
+}

package/src/user.ts

@@ -1,6 +1,5 @@
-import { requireAuthToken } from "./auth";
 import { CastleError } from "./errors";
-import { graphqlRequest } from "./graphql";
+import { hostRequest } from "./transport";
 
 export interface CastleUser {
   userId: string;
@@ -12,22 +11,6 @@ export interface CastleUserApi {
   getCurrent(): Promise<CastleUser>;
 }
 
-interface CurrentUserQueryData {
-  me: {
-    userId?: string | null;
-    username?: string | null;
-  } | null;
-}
-
-const CURRENT_USER_QUERY = `
-  query CastleCurrentUser {
-    me {
-      userId
-      username
-    }
-  }
-`;
-
 let currentUser: CastleUser | null = null;
 let currentUserPromise: Promise<CastleUser> | null = null;
 
@@ -46,33 +29,17 @@ async function getCurrent(): Promise<CastleUser> {
 
 async function fetchCurrentUser(): Promise<CastleUser> {
   const operation = "User.getCurrent";
-  const token = await requireAuthToken(operation);
-  const data = await graphqlRequest<CurrentUserQueryData>(
-    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: NonNullable<CurrentUserQueryData["me"]>,
-  operation: string,
-): CastleUser {
   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,
   };
 }
@@ -85,7 +52,7 @@ function requiredString(
   if (typeof value === "string" && value.length > 0) 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/dist/auth.d.ts

@@ -1,8 +0,0 @@
-export interface CastleAuth {
-    token?: string | null;
-    userId?: string | null;
-}
-export declare function getAuth(): Promise<CastleAuth>;
-export declare function getAuthToken(): Promise<string | null>;
-export declare function getUserId(): Promise<string | null>;
-export declare function requireAuthToken(operation?: string): Promise<string>;

package/dist/auth.js

@@ -1,52 +0,0 @@
-import { getCastleEmbed } from "./context";
-import { CastleError } from "./errors";
-let cachedAuth = null;
-let cachedAuthPromise = null;
-export async function getAuth() {
-    return getCachedAuth();
-}
-export async function getAuthToken() {
-    const auth = await getCachedAuth();
-    return auth.token ?? null;
-}
-export async function getUserId() {
-    const auth = await getCachedAuth();
-    return auth.userId ?? null;
-}
-export async function requireAuthToken(operation = "Castle API request") {
-    const token = await getAuthToken();
-    if (!token) {
-        throw new CastleError({
-            code: "LOGIN_REQUIRED",
-            message: "Log in to Castle before using this API.",
-            operation,
-        });
-    }
-    return token;
-}
-function getCachedAuth() {
-    cachedAuthPromise ??= resolveAuth();
-    return cachedAuthPromise;
-}
-async function resolveAuth() {
-    if (cachedAuth)
-        return cachedAuth;
-    const embedded = getCastleEmbed()?.auth;
-    if (embedded && (embedded.token || embedded.userId)) {
-        cachedAuth = { token: embedded.token, userId: embedded.userId };
-        return cachedAuth;
-    }
-    try {
-        const res = await fetch("/__castle/auth");
-        if (res.ok) {
-            const json = (await res.json());
-            cachedAuth = { token: json.token, userId: json.userId };
-            return cachedAuth;
-        }
-    }
-    catch {
-        // endpoint missing or offline -- treat as unauthenticated
-    }
-    cachedAuth = {};
-    return cachedAuth;
-}

package/dist/graphql.d.ts

@@ -1,15 +0,0 @@
-import type { Json } from "./types";
-export declare const GRAPHQL_ENDPOINT = "https://api.castle.xyz/graphql";
-export type GraphqlVariables = Record<string, Json | undefined>;
-export type { GraphqlErrorPayload } from "./errors";
-export interface GraphqlRequestOptions {
-    endpoint?: string;
-    headers?: Record<string, string>;
-    operation?: string;
-    operationName?: string;
-    requireAuth?: boolean;
-    signal?: AbortSignal;
-    timeoutMs?: number;
-    token?: string | null;
-}
-export declare function graphqlRequest<TData = unknown, TVariables extends GraphqlVariables = GraphqlVariables>(query: string, variables?: TVariables, options?: GraphqlRequestOptions): Promise<TData>;

package/dist/graphql.js

@@ -1,120 +0,0 @@
-import { getAuthToken } from "./auth";
-import { getCastleEmbed } from "./context";
-import { CastleError } from "./errors";
-export const GRAPHQL_ENDPOINT = "https://api.castle.xyz/graphql";
-export async function graphqlRequest(query, variables, options = {}) {
-    const operation = options.operation ?? guessGraphqlOperation(query);
-    const token = options.token ?? (await getAuthToken());
-    if (options.requireAuth && !token) {
-        throw new CastleError({
-            code: "LOGIN_REQUIRED",
-            message: "Log in to Castle before using this API.",
-            operation,
-        });
-    }
-    const response = await fetchGraphql(query, variables, {
-        ...options,
-        operation,
-        token,
-    });
-    if (response.errors?.length) {
-        throw graphqlError(response.errors, operation);
-    }
-    if (response.data === null || response.data === undefined) {
-        throw new CastleError({
-            code: "GRAPHQL_NO_DATA",
-            message: "Castle GraphQL response did not include data.",
-            operation,
-        });
-    }
-    return response.data;
-}
-async function fetchGraphql(query, variables, options) {
-    const headers = graphqlHeaders(options);
-    const abort = requestAbort(options);
-    try {
-        const response = await fetch(graphqlEndpoint(options), {
-            method: "POST",
-            headers,
-            body: JSON.stringify(graphqlBody(query, variables, options.operationName)),
-            signal: abort.signal,
-        });
-        const json = (await readGraphqlJson(response, options.operation));
-        if (!response.ok) {
-            throw new CastleError({
-                code: "GRAPHQL_HTTP_ERROR",
-                message: `Castle GraphQL request failed with HTTP ${response.status}.`,
-                operation: options.operation,
-                status: response.status,
-                errors: json?.errors,
-            });
-        }
-        return json ?? {};
-    }
-    finally {
-        abort.cleanup();
-    }
-}
-function requestAbort(options) {
-    if (options.signal)
-        return { signal: options.signal, cleanup: () => { } };
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 10000);
-    return { signal: controller.signal, cleanup: () => clearTimeout(timeout) };
-}
-function graphqlEndpoint(options) {
-    return (options.endpoint ?? getCastleEmbed()?.graphqlEndpoint ?? GRAPHQL_ENDPOINT);
-}
-function graphqlHeaders(options) {
-    const headers = {
-        Accept: "application/json",
-        "Content-Type": "application/json",
-        "X-OS": "web",
-        "X-TimeZone": Intl.DateTimeFormat().resolvedOptions().timeZone,
-        ...options.headers,
-    };
-    if (options.token)
-        headers["X-Auth-Token"] = options.token;
-    return headers;
-}
-function graphqlBody(query, variables, operationName) {
-    const body = { query };
-    if (variables)
-        body.variables = variables;
-    if (operationName)
-        body.operationName = operationName;
-    return body;
-}
-async function readGraphqlJson(response, operation) {
-    try {
-        return await response.json();
-    }
-    catch {
-        if (response.ok)
-            return {};
-        throw new CastleError({
-            code: "GRAPHQL_BAD_RESPONSE",
-            message: "Castle GraphQL response was not valid JSON.",
-            operation,
-            status: response.status,
-        });
-    }
-}
-function graphqlError(errors, operation) {
-    const first = errors[0];
-    return new CastleError({
-        code: graphqlErrorCode(first),
-        message: first?.message ?? "Castle GraphQL request failed.",
-        operation,
-        extensions: first?.extensions,
-        errors,
-    });
-}
-function graphqlErrorCode(error) {
-    const code = error?.extensions?.code;
-    return typeof code === "string" ? code : "GRAPHQL_ERROR";
-}
-function guessGraphqlOperation(query) {
-    const match = /\b(?:query|mutation|subscription)\s+([A-Za-z0-9_]+)/.exec(query);
-    return match?.[1] ?? "Castle GraphQL request";
-}

package/src/auth.ts

@@ -1,64 +0,0 @@
-import { getCastleEmbed } from "./context";
-import { CastleError } from "./errors";
-
-export interface CastleAuth {
-  token?: string | null;
-  userId?: string | null;
-}
-
-let cachedAuth: CastleAuth | null = null;
-let cachedAuthPromise: Promise<CastleAuth> | null = null;
-
-export async function getAuth(): Promise<CastleAuth> {
-  return getCachedAuth();
-}
-
-export async function getAuthToken(): Promise<string | null> {
-  const auth = await getCachedAuth();
-  return auth.token ?? null;
-}
-
-export async function getUserId(): Promise<string | null> {
-  const auth = await getCachedAuth();
-  return auth.userId ?? null;
-}
-
-export async function requireAuthToken(
-  operation = "Castle API request",
-): Promise<string> {
-  const token = await getAuthToken();
-  if (!token) {
-    throw new CastleError({
-      code: "LOGIN_REQUIRED",
-      message: "Log in to Castle before using this API.",
-      operation,
-    });
-  }
-  return token;
-}
-
-function getCachedAuth(): Promise<CastleAuth> {
-  cachedAuthPromise ??= resolveAuth();
-  return cachedAuthPromise;
-}
-
-async function resolveAuth(): Promise<CastleAuth> {
-  if (cachedAuth) return cachedAuth;
-  const embedded = getCastleEmbed()?.auth;
-  if (embedded && (embedded.token || embedded.userId)) {
-    cachedAuth = { token: embedded.token, userId: embedded.userId };
-    return cachedAuth;
-  }
-  try {
-    const res = await fetch("/__castle/auth");
-    if (res.ok) {
-      const json = (await res.json()) as CastleAuth;
-      cachedAuth = { token: json.token, userId: json.userId };
-      return cachedAuth;
-    }
-  } catch {
-    // endpoint missing or offline -- treat as unauthenticated
-  }
-  cachedAuth = {};
-  return cachedAuth;
-}

package/src/graphql.ts

@@ -1,182 +0,0 @@
-import { getAuthToken } from "./auth";
-import { getCastleEmbed } from "./context";
-import { CastleError, type GraphqlErrorPayload } from "./errors";
-import type { Json } from "./types";
-
-export const GRAPHQL_ENDPOINT = "https://api.castle.xyz/graphql";
-
-export type GraphqlVariables = Record<string, Json | undefined>;
-export type { GraphqlErrorPayload } from "./errors";
-
-export interface GraphqlRequestOptions {
-  endpoint?: string;
-  headers?: Record<string, string>;
-  operation?: string;
-  operationName?: string;
-  requireAuth?: boolean;
-  signal?: AbortSignal;
-  timeoutMs?: number;
-  token?: string | null;
-}
-
-interface GraphqlResponse<TData> {
-  data?: TData;
-  errors?: GraphqlErrorPayload[];
-}
-
-export async function graphqlRequest<
-  TData = unknown,
-  TVariables extends GraphqlVariables = GraphqlVariables,
->(
-  query: string,
-  variables?: TVariables,
-  options: GraphqlRequestOptions = {},
-): Promise<TData> {
-  const operation = options.operation ?? guessGraphqlOperation(query);
-  const token = options.token ?? (await getAuthToken());
-  if (options.requireAuth && !token) {
-    throw new CastleError({
-      code: "LOGIN_REQUIRED",
-      message: "Log in to Castle before using this API.",
-      operation,
-    });
-  }
-  const response = await fetchGraphql<TData>(query, variables, {
-    ...options,
-    operation,
-    token,
-  });
-  if (response.errors?.length) {
-    throw graphqlError(response.errors, operation);
-  }
-  if (response.data === null || response.data === undefined) {
-    throw new CastleError({
-      code: "GRAPHQL_NO_DATA",
-      message: "Castle GraphQL response did not include data.",
-      operation,
-    });
-  }
-  return response.data;
-}
-
-async function fetchGraphql<TData>(
-  query: string,
-  variables: GraphqlVariables | undefined,
-  options: Required<Pick<GraphqlRequestOptions, "operation">> &
-    GraphqlRequestOptions,
-): Promise<GraphqlResponse<TData>> {
-  const headers = graphqlHeaders(options);
-  const abort = requestAbort(options);
-  try {
-    const response = await fetch(graphqlEndpoint(options), {
-      method: "POST",
-      headers,
-      body: JSON.stringify(
-        graphqlBody(query, variables, options.operationName),
-      ),
-      signal: abort.signal,
-    });
-    const json = (await readGraphqlJson(response, options.operation)) as
-      | GraphqlResponse<TData>
-      | undefined;
-    if (!response.ok) {
-      throw new CastleError({
-        code: "GRAPHQL_HTTP_ERROR",
-        message: `Castle GraphQL request failed with HTTP ${response.status}.`,
-        operation: options.operation,
-        status: response.status,
-        errors: json?.errors,
-      });
-    }
-    return json ?? {};
-  } finally {
-    abort.cleanup();
-  }
-}
-
-function requestAbort(options: GraphqlRequestOptions): {
-  signal?: AbortSignal;
-  cleanup: () => void;
-} {
-  if (options.signal) return { signal: options.signal, cleanup: () => {} };
-  const controller = new AbortController();
-  const timeout = setTimeout(
-    () => controller.abort(),
-    options.timeoutMs ?? 10000,
-  );
-  return { signal: controller.signal, cleanup: () => clearTimeout(timeout) };
-}
-
-function graphqlEndpoint(options: GraphqlRequestOptions): string {
-  return (
-    options.endpoint ?? getCastleEmbed()?.graphqlEndpoint ?? GRAPHQL_ENDPOINT
-  );
-}
-
-function graphqlHeaders(
-  options: GraphqlRequestOptions,
-): Record<string, string> {
-  const headers: Record<string, string> = {
-    Accept: "application/json",
-    "Content-Type": "application/json",
-    "X-OS": "web",
-    "X-TimeZone": Intl.DateTimeFormat().resolvedOptions().timeZone,
-    ...options.headers,
-  };
-  if (options.token) headers["X-Auth-Token"] = options.token;
-  return headers;
-}
-
-function graphqlBody(
-  query: string,
-  variables: GraphqlVariables | undefined,
-  operationName: string | undefined,
-): Record<string, unknown> {
-  const body: Record<string, unknown> = { query };
-  if (variables) body.variables = variables;
-  if (operationName) body.operationName = operationName;
-  return body;
-}
-
-async function readGraphqlJson(
-  response: Response,
-  operation: string,
-): Promise<unknown> {
-  try {
-    return await response.json();
-  } catch {
-    if (response.ok) return {};
-    throw new CastleError({
-      code: "GRAPHQL_BAD_RESPONSE",
-      message: "Castle GraphQL response was not valid JSON.",
-      operation,
-      status: response.status,
-    });
-  }
-}
-
-function graphqlError(
-  errors: GraphqlErrorPayload[],
-  operation: string,
-): CastleError {
-  const first = errors[0];
-  return new CastleError({
-    code: graphqlErrorCode(first),
-    message: first?.message ?? "Castle GraphQL request failed.",
-    operation,
-    extensions: first?.extensions,
-    errors,
-  });
-}
-
-function graphqlErrorCode(error: GraphqlErrorPayload | undefined): string {
-  const code = error?.extensions?.code;
-  return typeof code === "string" ? code : "GRAPHQL_ERROR";
-}
-
-function guessGraphqlOperation(query: string): string {
-  const match = /\b(?:query|mutation|subscription)\s+([A-Za-z0-9_]+)/.exec(
-    query,
-  );
-  return match?.[1] ?? "Castle GraphQL request";
-}