castle-web-sdk 0.4.4 → 0.4.6

package/README.md

@@ -0,0 +1,321 @@
+# Castle Web SDK Reference
+
+`castle-web-sdk` lets a deck use services provided by the Castle
+platform — for example, a deck can save per-player data, post and read
+scores on a leaderboard, or get a server-synced time for daily content.
+
+Comes with `castle-web init`. Import what you need from
+`castle-web-sdk`:
+
+```js
+import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
+```
+
+## Contents
+
+- [Storage](#storage)
+- [SharedStorage](#sharedstorage)
+- [Leaderboard](#leaderboard)
+- [Time](#time)
+- [User](#user)
+- [Pass](#pass)
+- [Setup](#setup)
+- [CastleError](#castleerror)
+
+## Storage
+
+`Storage` saves data for the current player. Nobody else can read it.
+Use it for save files, settings, progress.
+
+### `Storage.get<T>(key): Promise<T | null>`
+
+Returns the value at `key`, or `null` if not set.
+
+```js
+const level = (await Storage.get("level")) ?? 1;
+```
+
+### `Storage.set(key, value)`
+
+Sets `key` to `value`. `value` must be something that can convert to
+JSON (`null`, booleans, finite numbers, strings, arrays, plain
+objects). The next `get(key)` returns the new value immediately. Writes
+save in the background.
+
+```js
+Storage.set("level", 7);
+Storage.set("settings", { sound: true, music: false });
+```
+
+### `Storage.remove(key)`
+
+Removes `key`.
+
+## SharedStorage
+
+`SharedStorage` saves data that other players can read. Values must
+be something that can convert to JSON, same as `Storage`.
+
+Scopes:
+
+- `'deck'` — one shared bucket for the whole deck. Any player can read
+  or write.
+- `'user'` — a per-player public bucket. Any player can read; only the
+  owning player can write.
+
+### `SharedStorage.get(scope, key): Promise<T | null>`
+
+Reads a shared value. For `'user'`, omit the user id to read the
+current player's bucket, or pass one to read someone else's:
+
+```js
+const worldHighScore = await SharedStorage.get("deck", "highScore");
+const myColor = await SharedStorage.get("user", "color");
+const theirColor = await SharedStorage.get("user", otherUserId, "color");
+```
+
+### `SharedStorage.set(scope, key, value)`
+
+Writes a shared value. `'user'` writes always go to the current
+player's bucket. Writes save in the background.
+
+```js
+SharedStorage.set("deck", "highScore", 9001);
+SharedStorage.set("user", "color", "red");
+```
+
+### `SharedStorage.remove(scope, key)`
+
+Removes a shared value.
+
+## Leaderboard
+
+`Leaderboard` ranks players by a numeric score, per deck and per
+variable name. Pick a variable name for each leaderboard the deck has
+(e.g. `'score'`, `'time'`).
+
+### `Leaderboard.write(variable, score, options?)`
+
+Submits a score. Only the player's best score for that `variable` (and
+scope) is kept. In the editor it does nothing — safe to call from
+gameplay code unconditionally.
+
+`options` is `{ scope?: string }`. By default the score goes to the
+deck's global leaderboard for `variable`; pass `scope` to write to a
+separate leaderboard (for example a daily one, or a custom id):
+
+```js
+Leaderboard.write("score", 1200);
+
+// A daily leaderboard: scope by the current Castle day so each day gets
+// its own board (see Time.getServerDate).
+const { daysSinceCastleEpoch } = await Time.getServerDate();
+Leaderboard.write("score", 1200, { scope: `daily-${daysSinceCastleEpoch}` });
+```
+
+### `Leaderboard.fetch(variable, type, options?): Promise<LeaderboardData>`
+
+Fetches the leaderboard for `variable`. `type` is `'high'` (highest
+first) or `'low'` (lowest first). `options.scope` works the same as in
+`write`.
+
+If the player has written a score this session, a `fetch` reflects
+**their own** new score right away — you can `write` then `fetch` and
+show the result without waiting. Other players' recent scores still
+appear on their own normal timing.
+
+The returned `LeaderboardData` has:
+
+- `list` — array of entries, each `{ place, value, username, userId? }`.
+- `playerRank` — the current player's place on the board (if they have
+  a score).
+- `playerValue` — the current player's score (if they have one).
+
+```js
+const data = await Leaderboard.fetch("score", "high");
+for (const entry of data.list) {
+  console.log(`${entry.place}. ${entry.username} — ${entry.value}`);
+}
+if (data.playerRank) {
+  console.log(`you are #${data.playerRank} with ${data.playerValue}`);
+}
+```
+
+## Time
+
+### `Time.getServerTime(): Promise<number>`
+
+Returns the current server time as a Unix timestamp in seconds.
+
+```js
+const now = await Time.getServerTime();
+```
+
+### `Time.getServerDate(timezone?): Promise<CastleDateParts>`
+
+Returns the current server time broken into date parts. `timezone` is
+`'Castle'` (default; Castle's server timezone, same for every player)
+or `'player'` (the player's local timezone).
+
+The returned `CastleDateParts` has:
+
+- `sec`, `min`, `hour` — time of day.
+- `day` (1-31), `month` (1-12), `year` — date.
+- `wday` — day of the week (1-7, Sunday = 1).
+- `yday` — day of the year (1-366).
+- `daysSinceCastleEpoch` — a day number that increments every day.
+  Use it for daily content.
+
+```js
+const date = await Time.getServerDate("player");
+const dailyPuzzle = (date.daysSinceCastleEpoch % 30) + 1;
+```
+
+## User
+
+### `User.getCurrent(): Promise<CastleUser>`
+
+Returns the signed-in player. Throws `CastleError`
+(`LOGIN_REQUIRED`) when nobody is signed in.
+
+The returned `CastleUser` has `userId`, `username`, and `isActive`.
+
+```js
+const me = await User.getCurrent();
+greet(me.username);
+```
+
+## Pass
+
+A pass is something a creator sells to players for Castle bricks (the
+in-app currency): buy it once, own it for good. Use one to gate part of a
+deck behind a purchase — bonus levels, a cosmetic, supporting the
+creator. Set up the pass (name, art, price) on Castle; a deck refers to
+it by id.
+
+### `Pass.has(passId): Promise<boolean>`
+
+Returns `true` if the current player owns the pass. No UI, nothing
+charged — use it to gate content.
+
+```js
+if (await Pass.has(bonusLevelsPassId)) {
+  showBonusLevels();
+}
+```
+
+### `Pass.offer(passId): Promise<PassOfferResult>`
+
+Presents the pass for the player to buy; resolves when they're done.
+Bricks cost real money, so this only works in the Castle mobile app —
+elsewhere (the website, the dev server) it resolves `unavailable`.
+`PassOfferResult` has a `status`:
+
+- `'purchased'` — just bought it; grant access.
+- `'alreadyOwned'` — already had it (not charged); grant access.
+- `'cancelled'` — dismissed without buying.
+- `'unavailable'` — can't buy here (e.g. the website).
+
+```js
+const { status } = await Pass.offer(bonusLevelsPassId);
+if (status === "purchased" || status === "alreadyOwned") {
+  showBonusLevels();
+}
+```
+
+## Setup
+
+Startup, editor-mode check, and a file-write call for editor UI.
+
+### `setup()`
+
+Call this once at the start of the deck, before any other SDK call.
+`setup()` initializes the SDK so the rest of the API is usable and
+mounts the centered 5:7 card shell around whatever the deck renders
+into `#root` (when the deck is being played standalone in a browser).
+While running locally with `castle-web serve`, it also forwards
+`console` output to the CLI and reloads the page when `castle-web
+restart` runs.
+
+```js
+import { setup } from "castle-web-sdk";
+
+setup();
+```
+
+### `initCard(): HTMLDivElement`
+
+Use this when the deck draws into a `<canvas>` (or anything else)
+rather than into the React tree at `#root`. Returns a centered,
+viewport-sized `<div>` with the standard Castle 5:7 card aspect ratio.
+The div resizes itself when the window resizes.
+
+```js
+import { setup, initCard } from "castle-web-sdk";
+
+setup();
+const card = initCard();
+
+const canvas = document.createElement("canvas");
+canvas.style.cssText = "width: 100%; height: 100%; display: block;";
+card.appendChild(canvas);
+```
+
+If the deck mounts a React tree into `#root` instead, you don't need
+`initCard()` — `setup()` already wraps `#root`'s children in a card.
+
+### `CARD_RATIO`
+
+The card aspect ratio (`5 / 7`). Use this if you need to size something
+to match the card.
+
+### `isEdit(): boolean`
+
+`true` when the deck is being edited, `false` when it's being played.
+Use this to show editor UI only in edit mode.
+
+```js
+import { isEdit, setup } from "castle-web-sdk";
+
+setup();
+if (isEdit()) {
+  mountEditor();
+} else {
+  startGame();
+}
+```
+
+### `writeFile(path, contents): Promise<void>`
+
+Writes a file in the deck directory. `path` is relative to the deck
+root, `contents` is a string. Use this from editor UI to save scenes,
+drawings, or generated source.
+
+```js
+import { writeFile } from "castle-web-sdk";
+
+await writeFile("scenes/main.scene", JSON.stringify(scene, null, 2));
+```
+
+Only works while editing locally with `castle-web serve`. Calls from a
+published deck fail.
+
+## CastleError
+
+Every error the SDK throws is a `CastleError`. Check `code` to tell
+the kinds apart.
+
+Common codes:
+
+- `LOGIN_REQUIRED` — the player needs to be signed in.
+- `MISSING_DECK_ID` — the deck hasn't been saved to Castle yet, so it
+  has no id.
+- `CASTLE_STORAGE_SERIALIZE_FAILED` — value isn't plain JSON (e.g. a
+  class instance, a function, a non-finite number, or a cycle).
+- `INVALID_LEADERBOARD_VARIABLE`, `INVALID_LEADERBOARD_SCORE`,
+  `INVALID_LEADERBOARD_TYPE` — bad argument to a `Leaderboard` call.
+- `UNSUPPORTED_TIMEZONE` — `Time.getServerDate` got a zone other than
+  `'Castle'` or `'player'`.
+- `CASTLE_HOST_UNAVAILABLE` — the Castle host (the app or website running
+  the deck) didn't handle the request — e.g. it timed out or wasn't
+  reachable. Usually transient; retry or surface a gentle error.

package/dist/castle.d.ts

@@ -2,6 +2,8 @@ export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardSort, } from "./leaderboard";
+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";

package/dist/castle.js

@@ -2,6 +2,7 @@
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
+export { Pass } from "./passes";
 export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";

package/dist/commands.d.ts

@@ -0,0 +1,117 @@
+import type { Json } from "./types";
+export declare const CASTLE_SDK_PROTOCOL = 1;
+export type StorageBlob = Record<string, string>;
+export type SharedScope = "deck" | "user";
+export interface StorageUpdate {
+    key: string;
+    value: string | null;
+}
+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;
+        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;
+    };
+    "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;
+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 declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;

package/dist/commands.js

@@ -0,0 +1,16 @@
+// 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.
+// 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 function isResponseEnvelope(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (record.castleSdk === CASTLE_SDK_PROTOCOL &&
+        typeof record.requestId === "string" &&
+        typeof record.ok === "boolean");
+}

package/dist/context.d.ts

@@ -1,21 +1,8 @@
-export interface CastleDeckContext {
-    deckId?: string | null;
-    cardId?: string | null;
-    sessionId?: string | null;
-}
-interface CastleEmbedAuth {
-    token?: string | null;
-    userId?: string | null;
-}
+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 {
     interface Window {
@@ -24,7 +11,3 @@ declare global {
 }
 export declare function getCastleEmbed(): CastleEmbed | undefined;
 export declare function isEdit(): boolean;
-export declare function configureDeckContext(context: CastleDeckContext): void;
-export declare function getDeckContext(): Promise<CastleDeckContext>;
-export declare function requireDeckId(operation?: string): Promise<string>;
-export {};

package/dist/context.js

@@ -1,7 +1,3 @@
-import { CastleError } from "./errors";
-let configuredDeckContext = {};
-let cachedDeckContext = null;
-let cachedDeckContextPromise = null;
 export function getCastleEmbed() {
     return typeof window === "undefined" ? undefined : window.CastleEmbed;
 }
@@ -17,70 +13,3 @@ export function isEdit() {
     }
     return !!getCastleEmbed()?.edit;
 }
-export function configureDeckContext(context) {
-    configuredDeckContext = cleanDeckContext(context);
-    cachedDeckContext = null;
-    cachedDeckContextPromise = null;
-}
-export async function getDeckContext() {
-    if (cachedDeckContext)
-        return cachedDeckContext;
-    cachedDeckContextPromise ??= resolveDeckContext();
-    return cachedDeckContextPromise;
-}
-export async function requireDeckId(operation = "Castle API request") {
-    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() {
-    const embedded = embeddedDeckContext();
-    const local = await localDeckContext();
-    const context = mergeDeckContexts(configuredDeckContext, embedded, local);
-    cachedDeckContext = context;
-    return context;
-}
-function embeddedDeckContext() {
-    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() {
-    try {
-        const res = await fetch("/__castle/context");
-        if (!res.ok)
-            return {};
-        return cleanDeckContext((await res.json()));
-    }
-    catch {
-        return {};
-    }
-}
-function cleanDeckContext(context) {
-    return {
-        deckId: stringOrNull(context.deckId),
-        cardId: stringOrNull(context.cardId),
-        sessionId: stringOrNull(context.sessionId),
-    };
-}
-function mergeDeckContexts(...contexts) {
-    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) {
-    if (typeof value !== "string")
-        return null;
-    return value.length > 0 ? value : null;
-}