castle-web-cli 0.4.59 → 0.4.61

package/dist/api.d.ts

@@ -1,3 +1,11 @@
+interface GraphqlResponse {
+    data?: Record<string, unknown>;
+    errors?: Array<{
+        message?: string;
+        extensions?: Record<string, unknown>;
+    }>;
+}
+export declare function graphql(query: string, variables?: Record<string, unknown>): Promise<GraphqlResponse>;
 export declare function startCLILogin(): Promise<{
     pollToken: string;
     url: string;
@@ -71,3 +79,4 @@ export interface WebDeckSource {
 }
 export declare function webDeckSource(deckId: string): Promise<WebDeckSource | null>;
 export declare function saveWebDeckSource(deckId: string, uploadId: string): Promise<WebDeckSource>;
+export {};

package/dist/api.js

@@ -1,6 +1,6 @@
 import * as config from './config.js';
 const API_HOST = 'https://api.castle.xyz/graphql';
-async function graphql(query, variables) {
+export async function graphql(query, variables) {
     const token = config.getToken();
     const headers = {
         'X-OS': 'cli',

package/dist/castle-host/host.d.ts

@@ -0,0 +1,58 @@
+// Hand-written declaration for the vendored, self-contained host.js (runtime is
+// copied here by scripts/copy-host-module.mjs). Kept tiny and import-free on
+// purpose — the SDK's emitted .d.ts use extensionless imports that the CLI's
+// Node16 resolution rejects. Mirror the public surface of
+// castle-experimental-web/sdk/src/host.ts; update if that signature changes.
+
+export interface HostContext {
+  deckId: string | null;
+  sessionId: string | null;
+  userId: string | null;
+  username: string | null;
+}
+
+export interface GraphqlError {
+  message?: string;
+  extensions?: Record<string, unknown>;
+}
+
+export interface GraphqlResponse {
+  data?: unknown;
+  errors?: GraphqlError[];
+}
+
+export type GraphqlFetch = (
+  query: string,
+  variables: Record<string, unknown>,
+) => Promise<GraphqlResponse>;
+
+export type PlatformHandler = (
+  command: unknown,
+  params: Record<string, unknown>,
+  ctx: HostContext,
+) => Promise<unknown>;
+
+export interface HostCapabilities {
+  graphqlFetch: GraphqlFetch;
+  platformHandler?: PlatformHandler;
+}
+
+export interface SerializedCommandError {
+  code: string;
+  message: string;
+  command?: string;
+  extensions?: Record<string, unknown>;
+}
+
+export interface HostResult {
+  ok: boolean;
+  data?: unknown;
+  error?: SerializedCommandError;
+}
+
+export function executeCommand(
+  ctx: HostContext,
+  command: unknown,
+  params: unknown,
+  capabilities: HostCapabilities,
+): Promise<HostResult>;

package/dist/castle-host/host.js

@@ -0,0 +1,457 @@
+// GENERATED — do not edit. Vendored from castle-experimental-web/sdk/dist/host.js
+// Re-run `npm run copy-host` in castle-experimental-web after an SDK change.
+
+// Host-side command executor — the shared module run by every trusted host
+// (web DeckPlayer, mobile React Native, the castle-web dev server). It takes a
+// command + params from an untrusted deck, validates it against the allowlist,
+// stamps trusted context (deckId/sessionId/userId — never taken from the deck),
+// builds the GraphQL query, runs it via the host's own authed fetch, and
+// returns a serializable result/error envelope. The deck never sees a token or
+// builds a query. This file is NOT imported by deck-side code.
+//
+// Usage from a host:
+//   import { executeCommand } from "castle-web-sdk/host";
+//   const result = await executeCommand(ctx, command, params, graphqlFetch);
+//   // reply { castleSdk: 1, requestId, ...result } back to the deck.
+// Runtime command allowlist — kept here (not in commands.ts) so the import
+// above stays type-only. Must stay in sync with CommandParams in commands.ts.
+const COMMAND_NAMES = [
+    "deckStorage.load",
+    "deckStorage.update",
+    "sharedDeckStorage.load",
+    "sharedDeckStorage.update",
+    "leaderboard.fetch",
+    "leaderboard.save",
+    "user.getCurrent",
+    "time.getServerTime",
+    "pass.has",
+    "pass.offer",
+];
+// Platform/capability commands: NOT serviced by graphqlFetch. They're dispatched
+// to the host's optional platformHandler (mobile renders native UI; web shows an
+// upsell). A host with no platformHandler returns the command's normalized
+// "unavailable" outcome rather than an error — capability divergence is the
+// host's concern, never a deck-facing gate.
+const PLATFORM_COMMAND_NAMES = ["pass.offer"];
+function isCommandName(value) {
+    return (typeof value === "string" &&
+        COMMAND_NAMES.includes(value));
+}
+function isPlatformCommand(command) {
+    return PLATFORM_COMMAND_NAMES.includes(command);
+}
+class HostCommandError extends Error {
+    code;
+    command;
+    extensions;
+    constructor(code, message, command, extensions) {
+        super(message);
+        this.name = "HostCommandError";
+        this.code = code;
+        this.command = command;
+        this.extensions = extensions;
+    }
+}
+export async function executeCommand(ctx, command, params, capabilities) {
+    if (!isCommandName(command)) {
+        return {
+            ok: false,
+            error: {
+                code: "UNKNOWN_COMMAND",
+                message: "Unknown Castle command.",
+                command: typeof command === "string" ? command : undefined,
+            },
+        };
+    }
+    try {
+        const data = await runCommand(ctx, command, (params ?? {}), capabilities);
+        return { ok: true, data };
+    }
+    catch (error) {
+        return { ok: false, error: toSerializedError(error, command) };
+    }
+}
+function runCommand(ctx, command, params, caps) {
+    if (isPlatformCommand(command)) {
+        return runPlatformCommand(ctx, command, params, caps);
+    }
+    const gql = caps.graphqlFetch;
+    switch (command) {
+        case "deckStorage.load":
+            return deckStorageLoad(ctx, gql);
+        case "deckStorage.update":
+            return deckStorageUpdate(ctx, params, gql);
+        case "sharedDeckStorage.load":
+            return sharedDeckStorageLoad(ctx, params, gql);
+        case "sharedDeckStorage.update":
+            return sharedDeckStorageUpdate(ctx, params, gql);
+        case "leaderboard.fetch":
+            return leaderboardFetch(ctx, params, gql);
+        case "leaderboard.save":
+            return leaderboardSave(ctx, params, gql);
+        case "user.getCurrent":
+            return Promise.resolve(userGetCurrent(ctx));
+        case "time.getServerTime":
+            return timeGetServerTime(gql);
+        case "pass.has":
+            return passHas(ctx, params, gql);
+        // Platform commands are handled above; listed here to keep the switch
+        // exhaustive over CommandName.
+        case "pass.offer":
+            return runPlatformCommand(ctx, command, params, caps);
+    }
+}
+// Dispatch a platform/capability command to the host's platformHandler. No
+// handler → the command's normalized "unavailable" outcome (a SUCCESS, not an
+// error: a deck on a host without this capability still gets one uniform
+// result). The handler's return is normalized so a malformed outcome can't
+// leak through to the deck.
+async function runPlatformCommand(ctx, command, params, caps) {
+    switch (command) {
+        case "pass.offer":
+            return passesOffer(ctx, params, caps);
+        default:
+            return unavailableOutcome(command);
+    }
+}
+async function passHas(ctx, params, gql) {
+    const deckId = requireDeckId(ctx, "pass.has");
+    const passId = asString(params.passId, "passId", "pass.has");
+    const data = await graphql(gql, PASSES_FOR_DECK_QUERY, { deckId }, "pass.has");
+    const match = (data.passesForDeck ?? []).find((p) => p?.passId === passId);
+    return { hasPass: match?.isActive === true };
+}
+async function passesOffer(ctx, params, caps) {
+    const passId = asString(params.passId, "passId", "pass.offer");
+    // Hosts without bricks support (dev CLI — no handler at all) get a normalized
+    // unavailable, never an error or a thrown MISSING_DECK_ID.
+    if (!caps.platformHandler)
+        return { status: "unavailable" };
+    // Real transaction path (mobile native sheet; web upsell): the pass belongs
+    // to a deck, so a trusted deckId is required before handing off.
+    const deckId = requireDeckId(ctx, "pass.offer");
+    const outcome = await caps.platformHandler("pass.offer", { passId, deckId }, ctx);
+    return normalizePassOutcome(outcome);
+}
+function normalizePassOutcome(value) {
+    const record = typeof value === "object" && value !== null
+        ? value
+        : {};
+    const status = record.status;
+    const valid = [
+        "purchased",
+        "alreadyOwned",
+        "cancelled",
+        "unavailable",
+    ];
+    if (typeof status === "string" && valid.includes(status)) {
+        return { status: status };
+    }
+    return { status: "cancelled" };
+}
+function unavailableOutcome(command) {
+    // Only passes exists today; keep this total over future platform commands.
+    if (command === "pass.offer") {
+        return { status: "unavailable" };
+    }
+    return { status: "unavailable" };
+}
+async function deckStorageLoad(ctx, gql) {
+    const deckId = requireDeckId(ctx, "deckStorage.load");
+    const data = await graphql(gql, DECK_STORAGE_QUERY, { deckId, sessionId: ctx.sessionId }, "deckStorage.load");
+    return { blob: data.deckStorage ?? {} };
+}
+async function deckStorageUpdate(ctx, params, gql) {
+    const deckId = requireDeckId(ctx, "deckStorage.update");
+    const data = await graphql(gql, UPDATE_DECK_STORAGE_MUTATION, {
+        deckId,
+        sessionId: ctx.sessionId,
+        updates: asUpdates(params.updates),
+    }, "deckStorage.update");
+    return { blob: data.updateDeckStorage ?? {} };
+}
+async function sharedDeckStorageLoad(ctx, params, gql) {
+    const deckId = requireDeckId(ctx, "sharedDeckStorage.load");
+    const scope = asScope(params.scope, "sharedDeckStorage.load");
+    // 'user' read: an explicit userId targets another player's public bucket;
+    // otherwise the current player's. 'deck' scope ignores userId.
+    const userId = scope === "user" ? asOptionalString(params.userId) ?? ctx.userId : null;
+    const data = await graphql(gql, SHARED_DECK_STORAGE_QUERY, { deckId, sessionId: ctx.sessionId, userId, keys: asKeys(params.keys) }, "sharedDeckStorage.load");
+    return { blob: data.sharedDeckStorage ?? {} };
+}
+async function sharedDeckStorageUpdate(ctx, params, gql) {
+    const deckId = requireDeckId(ctx, "sharedDeckStorage.update");
+    const scope = asScope(params.scope, "sharedDeckStorage.update");
+    // 'user'-scope writes are forced to the current player — the deck cannot
+    // write another player's bucket.
+    const userId = scope === "user" ? requireUserId(ctx, "sharedDeckStorage.update") : null;
+    await graphql(gql, UPDATE_SHARED_DECK_STORAGE_MUTATION, { deckId, sessionId: ctx.sessionId, userId, updates: asUpdates(params.updates) }, "sharedDeckStorage.update");
+    return { ok: true };
+}
+async function leaderboardFetch(ctx, params, gql) {
+    const deckId = requireDeckId(ctx, "leaderboard.fetch");
+    const variables = {
+        deckId,
+        variable: asString(params.variable, "variable", "leaderboard.fetch"),
+        type: asLeaderboardType(params.type),
+        filter: "dedupUsers",
+        includeFollowList: false,
+        includeParties: false,
+        scope: asOptionalString(params.scope) ?? null,
+    };
+    // A non-null score means the deck just wrote this value and wants its own
+    // score reflected immediately: write-and-read atomically via leaderboardV2
+    // (mirrors the engine's getLeaderboard path in core/src/leaderboards.cpp).
+    // No score → plain read of the settled leaderboard.
+    const score = asOptionalNumber(params.score);
+    if (score !== null) {
+        const data = await graphql(gql, LEADERBOARD_V2_MUTATION, { ...variables, score }, "leaderboard.fetch");
+        return { leaderboard: data.leaderboardV2, currentUserId: ctx.userId };
+    }
+    const data = await graphql(gql, LEADERBOARD_QUERY, variables, "leaderboard.fetch");
+    return { leaderboard: data.leaderboard, currentUserId: ctx.userId };
+}
+async function leaderboardSave(ctx, params, gql) {
+    const deckId = requireDeckId(ctx, "leaderboard.save");
+    await graphql(gql, SAVE_LEADERBOARD_MUTATION, {
+        deckId,
+        variable: asString(params.variable, "variable", "leaderboard.save"),
+        score: asNumber(params.score, "score", "leaderboard.save"),
+        scope: asOptionalString(params.scope) ?? null,
+    }, "leaderboard.save");
+    return { ok: true };
+}
+function userGetCurrent(ctx) {
+    if (!ctx.userId || !ctx.username)
+        return { user: null };
+    return { user: { userId: ctx.userId, username: ctx.username } };
+}
+async function timeGetServerTime(gql) {
+    const data = await graphql(gql, SERVER_TIME_QUERY, {}, "time.getServerTime");
+    return {
+        timestamp: data.serverTime.timestamp,
+        timezoneOffset: data.serverTime.timezoneOffset,
+        castleEpochData: data.serverTime.castleEpochData,
+    };
+}
+async function graphql(gql, query, variables, command) {
+    const result = await gql(query, variables);
+    if (result.errors && result.errors.length > 0) {
+        const first = result.errors[0];
+        const code = first?.extensions?.code;
+        throw new HostCommandError(typeof code === "string" ? code : "GRAPHQL_ERROR", first?.message ?? "Castle GraphQL request failed.", command, first?.extensions);
+    }
+    if (result.data === null || result.data === undefined) {
+        throw new HostCommandError("GRAPHQL_NO_DATA", "Castle GraphQL response did not include data.", command);
+    }
+    return result.data;
+}
+function requireDeckId(ctx, command) {
+    if (ctx.deckId)
+        return ctx.deckId;
+    throw new HostCommandError("MISSING_DECK_ID", "Save this deck to Castle before using this API.", command);
+}
+function requireUserId(ctx, command) {
+    if (ctx.userId)
+        return ctx.userId;
+    throw new HostCommandError("LOGIN_REQUIRED", "Log in to Castle before using this API.", command);
+}
+function toSerializedError(error, command) {
+    if (error instanceof HostCommandError) {
+        return {
+            code: error.code,
+            message: error.message,
+            command: error.command ?? command,
+            extensions: error.extensions,
+        };
+    }
+    return {
+        code: "CASTLE_HOST_ERROR",
+        message: error instanceof Error ? error.message : "Castle command failed.",
+        command,
+    };
+}
+function asUpdates(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return [];
+        const record = entry;
+        if (typeof record.key !== "string")
+            return [];
+        const raw = record.value;
+        return [{ key: record.key, value: typeof raw === "string" ? raw : null }];
+    });
+}
+function asKeys(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((key) => typeof key === "string");
+}
+function asScope(value, command) {
+    if (value === "deck" || value === "user")
+        return value;
+    throw new HostCommandError("CASTLE_STORAGE_INVALID_SCOPE", 'SharedStorage scope must be "deck" or "user".', command);
+}
+function asLeaderboardType(value) {
+    if (value === "high" || value === "low")
+        return value;
+    throw new HostCommandError("INVALID_LEADERBOARD_TYPE", "Leaderboard type must be high or low.", "leaderboard.fetch");
+}
+function asString(value, field, command) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    throw new HostCommandError("INVALID_ARGUMENT", `Castle command ${command} requires ${field}.`, command);
+}
+function asNumber(value, field, command) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    throw new HostCommandError("INVALID_ARGUMENT", `Castle command ${command} requires a numeric ${field}.`, command);
+}
+function asOptionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function asOptionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+const DECK_STORAGE_QUERY = `
+  query CastleDeckStorage($deckId: ID!, $sessionId: ID) {
+    deckStorage(deckId: $deckId, sessionId: $sessionId)
+  }
+`;
+const UPDATE_DECK_STORAGE_MUTATION = `
+  mutation CastleUpdateDeckStorage(
+    $deckId: ID!,
+    $updates: [DeckStorageUpdateInput!]!,
+    $sessionId: ID
+  ) {
+    updateDeckStorage(deckId: $deckId, updates: $updates, sessionId: $sessionId)
+  }
+`;
+const SHARED_DECK_STORAGE_QUERY = `
+  query CastleSharedDeckStorage(
+    $deckId: ID!,
+    $keys: [String!]!,
+    $sessionId: ID,
+    $userId: ID
+  ) {
+    sharedDeckStorage(deckId: $deckId, keys: $keys, sessionId: $sessionId, userId: $userId)
+  }
+`;
+const UPDATE_SHARED_DECK_STORAGE_MUTATION = `
+  mutation CastleUpdateSharedDeckStorage(
+    $deckId: ID!,
+    $updates: [SharedDeckStorageUpdateInput!]!,
+    $sessionId: ID,
+    $userId: ID
+  ) {
+    updateSharedDeckStorage(
+      deckId: $deckId,
+      updates: $updates,
+      sessionId: $sessionId,
+      userId: $userId
+    )
+  }
+`;
+const LEADERBOARD_QUERY = `
+  query CastleLeaderboard(
+    $deckId: ID!
+    $variable: String!
+    $type: LeaderboardType!
+    $filter: LeaderboardFilter!
+    $includeFollowList: Boolean
+    $includeParties: Boolean
+    $scope: String
+  ) {
+    leaderboard(
+      deckId: $deckId
+      variable: $variable
+      type: $type
+      filter: $filter
+      includeFollowList: $includeFollowList
+      includeParties: $includeParties
+      scope: $scope
+    ) {
+      yourScore { score }
+      list {
+        place
+        score
+        user {
+          userId
+          username
+        }
+      }
+    }
+  }
+`;
+// Same args + selection as LEADERBOARD_QUERY, plus the required `score`. Unlike
+// saveVariableToLeaderboard, this writes the score AND returns the post-write
+// leaderboard in one round trip, so the deck can show its own fresh score
+// without waiting for server-side settling. Mirrors the engine's leaderboardV2
+// use in core/src/leaderboards.cpp.
+const LEADERBOARD_V2_MUTATION = `
+  mutation CastleLeaderboardV2(
+    $deckId: ID!
+    $variable: String!
+    $type: LeaderboardType!
+    $filter: LeaderboardFilter!
+    $score: Float!
+    $includeFollowList: Boolean
+    $includeParties: Boolean
+    $scope: String
+  ) {
+    leaderboardV2(
+      deckId: $deckId
+      variable: $variable
+      type: $type
+      filter: $filter
+      score: $score
+      includeFollowList: $includeFollowList
+      includeParties: $includeParties
+      scope: $scope
+    ) {
+      yourScore { score }
+      list {
+        place
+        score
+        user {
+          userId
+          username
+        }
+      }
+    }
+  }
+`;
+const SAVE_LEADERBOARD_MUTATION = `
+  mutation CastleSaveVariableToLeaderboard(
+    $deckId: ID!
+    $variable: String!
+    $score: Float!
+    $scope: String
+  ) {
+    saveVariableToLeaderboard(
+      deckId: $deckId
+      variable: $variable
+      score: $score
+      scope: $scope
+    )
+  }
+`;
+const PASSES_FOR_DECK_QUERY = `
+  query CastlePassesForDeck($deckId: ID!) {
+    passesForDeck(deckId: $deckId) {
+      passId
+      isActive
+    }
+  }
+`;
+const SERVER_TIME_QUERY = `
+  query CastleServerTime {
+    serverTime {
+      timestamp
+      timezoneOffset
+      castleEpochData
+    }
+  }
+`;