castle-web-sdk 0.4.1 → 0.4.3

package/dist/auth.d.ts

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,52 @@
+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/castle.d.ts

@@ -0,0 +1,11 @@
+export { isEdit } from "./context";
+export { CastleError } from "./errors";
+export { Leaderboard } from "./leaderboard";
+export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardSort, } from "./leaderboard";
+export { CARD_RATIO, initCard, setup, writeFile } from "./runtime";
+export { SharedStorage, Storage } from "./storage";
+export { Time } from "./time";
+export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
+export type { Json } from "./types";
+export { User } from "./user";
+export type { CastleUser, CastleUserApi } from "./user";

package/dist/castle.js

@@ -0,0 +1,8 @@
+// Castle Web SDK
+export { isEdit } from "./context";
+export { CastleError } from "./errors";
+export { Leaderboard } from "./leaderboard";
+export { CARD_RATIO, initCard, setup, writeFile } from "./runtime";
+export { SharedStorage, Storage } from "./storage";
+export { Time } from "./time";
+export { User } from "./user";

package/dist/context.d.ts

@@ -0,0 +1,30 @@
+export interface CastleDeckContext {
+    deckId?: string | null;
+    cardId?: string | null;
+    sessionId?: string | null;
+}
+interface CastleEmbedAuth {
+    token?: string | null;
+    userId?: string | null;
+}
+export interface CastleEmbed {
+    edit?: boolean;
+    feed?: boolean;
+    auth?: CastleEmbedAuth;
+    deck?: CastleDeckContext;
+    deckId?: string;
+    cardId?: string;
+    sessionId?: string | null;
+    graphqlEndpoint?: string;
+}
+declare global {
+    interface Window {
+        CastleEmbed?: CastleEmbed;
+    }
+}
+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

@@ -0,0 +1,86 @@
+import { CastleError } from "./errors";
+let configuredDeckContext = {};
+let cachedDeckContext = null;
+let cachedDeckContextPromise = null;
+export function getCastleEmbed() {
+    return typeof window === "undefined" ? undefined : window.CastleEmbed;
+}
+export function isEdit() {
+    try {
+        const params = new URLSearchParams(window.location.search);
+        const override = params.get("edit");
+        if (override === "0" || override === "false")
+            return false;
+    }
+    catch {
+        // ignore -- window.location may be unavailable
+    }
+    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;
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+export interface GraphqlErrorPayload {
+    message?: string;
+    extensions?: Record<string, unknown>;
+    path?: Array<string | number>;
+}
+interface CastleErrorInput {
+    code: string;
+    message: string;
+    operation?: string;
+    status?: number;
+    extensions?: Record<string, unknown>;
+    errors?: GraphqlErrorPayload[];
+}
+export declare class CastleError extends Error {
+    code: string;
+    operation?: string;
+    status?: number;
+    extensions?: Record<string, unknown>;
+    errors?: GraphqlErrorPayload[];
+    constructor(input: CastleErrorInput);
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,16 @@
+export class CastleError extends Error {
+    code;
+    operation;
+    status;
+    extensions;
+    errors;
+    constructor(input) {
+        super(input.message);
+        this.name = "CastleError";
+        this.code = input.code;
+        this.operation = input.operation;
+        this.status = input.status;
+        this.extensions = input.extensions;
+        this.errors = input.errors;
+    }
+}

package/dist/graphql.d.ts

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,120 @@
+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/dist/leaderboard.d.ts

@@ -0,0 +1,20 @@
+export type LeaderboardSort = "high" | "low";
+export type LeaderboardScope = string;
+export interface LeaderboardOptions {
+    scope?: LeaderboardScope | null;
+}
+export interface LeaderboardEntry {
+    place: number;
+    value: number;
+    username: string;
+    userId?: string;
+}
+export interface LeaderboardData {
+    list: LeaderboardEntry[];
+    playerRank?: number;
+    playerValue?: number;
+}
+export declare const Leaderboard: {
+    readonly write: (variable: string, score: number, options?: LeaderboardOptions) => void;
+    readonly fetch: (variable: string, type: LeaderboardSort, options?: LeaderboardOptions) => Promise<LeaderboardData>;
+};

package/dist/leaderboard.js

@@ -0,0 +1,296 @@
+import { getAuth, requireAuthToken } from "./auth";
+import { isEdit, requireDeckId } from "./context";
+import { CastleError } from "./errors";
+import { graphqlRequest } from "./graphql";
+const LEADERBOARD_FLUSH_INTERVAL_MS = 5000;
+const leaderboardWrites = new Map();
+let leaderboardFlushTimer = null;
+let leaderboardFlushPromise = null;
+let leaderboardUnloadHooked = false;
+export const Leaderboard = {
+    write(variable, score, options = {}) {
+        writeLeaderboard(variable, score, options);
+    },
+    fetch(variable, type, options = {}) {
+        return fetchLeaderboardData(variable, type, options);
+    },
+};
+function writeLeaderboard(variable, score, options) {
+    if (isEdit())
+        return;
+    void bufferLeaderboardWrite(variable, score, options).catch(reportLeaderboardError);
+}
+async function fetchLeaderboardData(variable, type, options) {
+    const request = await leaderboardRequest("Leaderboard.fetch", variable, type, options);
+    return normalizeLeaderboard(await fetchLeaderboard(request), request.userId);
+}
+async function bufferLeaderboardWrite(variable, score, options) {
+    assertLeaderboardVariable(variable, "Leaderboard.write");
+    assertLeaderboardScore(score, "Leaderboard.write");
+    const deckId = await requireDeckId("Leaderboard.write");
+    await requireAuthToken("Leaderboard.write");
+    const scope = leaderboardScope(options);
+    const key = leaderboardWriteKey(deckId, variable, scope);
+    const record = leaderboardWrites.get(key);
+    if (record) {
+        updatePendingLeaderboardWrite(record, score);
+    }
+    else {
+        leaderboardWrites.set(key, newPendingLeaderboardWrite(deckId, variable, scope, score));
+    }
+    ensureLeaderboardUnloadFlush();
+    scheduleLeaderboardFlush();
+}
+function newPendingLeaderboardWrite(deckId, variable, scope, score) {
+    return {
+        deckId,
+        variable,
+        scope,
+        highScore: score,
+        lowScore: score,
+        isHighDirty: true,
+        isLowDirty: true,
+    };
+}
+function updatePendingLeaderboardWrite(record, score) {
+    if (score > record.highScore) {
+        record.highScore = score;
+        record.isHighDirty = true;
+    }
+    if (score < record.lowScore) {
+        record.lowScore = score;
+        record.isLowDirty = true;
+    }
+}
+function scheduleLeaderboardFlush() {
+    if (leaderboardFlushTimer)
+        return;
+    leaderboardFlushTimer = setTimeout(() => {
+        leaderboardFlushTimer = null;
+        void flushLeaderboardWrites().catch(reportLeaderboardError);
+    }, LEADERBOARD_FLUSH_INTERVAL_MS);
+}
+function ensureLeaderboardUnloadFlush() {
+    if (leaderboardUnloadHooked || typeof window === "undefined")
+        return;
+    leaderboardUnloadHooked = true;
+    window.addEventListener("pagehide", () => {
+        void flushLeaderboardWrites().catch(reportLeaderboardError);
+    });
+}
+async function flushLeaderboardWrites() {
+    if (leaderboardFlushPromise)
+        return leaderboardFlushPromise;
+    leaderboardFlushPromise = flushLeaderboardWritesOnce().finally(() => {
+        leaderboardFlushPromise = null;
+        if (hasDirtyLeaderboardWrites())
+            scheduleLeaderboardFlush();
+    });
+    return leaderboardFlushPromise;
+}
+async function flushLeaderboardWritesOnce() {
+    const jobs = leaderboardWriteJobs();
+    if (jobs.length === 0)
+        return;
+    const token = await requireAuthToken("Leaderboard.write");
+    for (const job of jobs) {
+        await saveLeaderboardScore(job.record, job.score, token);
+        markLeaderboardWriteClean(job);
+    }
+}
+function leaderboardWriteJobs() {
+    const jobs = [];
+    for (const record of leaderboardWrites.values()) {
+        if (record.isHighDirty &&
+            record.isLowDirty &&
+            record.highScore === record.lowScore) {
+            jobs.push({ record, type: "both", score: record.highScore });
+        }
+        else {
+            if (record.isHighDirty)
+                jobs.push({ record, type: "high", score: record.highScore });
+            if (record.isLowDirty)
+                jobs.push({ record, type: "low", score: record.lowScore });
+        }
+    }
+    return jobs;
+}
+function markLeaderboardWriteClean(job) {
+    const { record, score, type } = job;
+    if ((type === "high" || type === "both") && record.highScore === score) {
+        record.isHighDirty = false;
+    }
+    if ((type === "low" || type === "both") && record.lowScore === score) {
+        record.isLowDirty = false;
+    }
+}
+function hasDirtyLeaderboardWrites() {
+    for (const record of leaderboardWrites.values()) {
+        if (record.isHighDirty || record.isLowDirty)
+            return true;
+    }
+    return false;
+}
+async function leaderboardRequest(operation, variable, type, options) {
+    assertLeaderboardVariable(variable, operation);
+    assertLeaderboardType(type, operation);
+    const [deckId, token, auth] = await Promise.all([
+        requireDeckId(operation),
+        requireAuthToken(operation),
+        getAuth(),
+    ]);
+    return {
+        deckId,
+        variable,
+        type,
+        scope: leaderboardScope(options),
+        token,
+        userId: auth.userId ?? null,
+    };
+}
+async function fetchLeaderboard(request) {
+    const data = await graphqlRequest(`
+      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
+        ) ${leaderboardFields()}
+      }
+    `, leaderboardVariables(request), {
+        operation: "CastleLeaderboard",
+        token: request.token,
+        requireAuth: true,
+    });
+    return data.leaderboard;
+}
+async function saveLeaderboardScore(record, score, token) {
+    await graphqlRequest(`
+      mutation CastleSaveVariableToLeaderboard(
+        $deckId: ID!
+        $variable: String!
+        $score: Float!
+        $scope: String
+      ) {
+        saveVariableToLeaderboard(
+          deckId: $deckId
+          variable: $variable
+          score: $score
+          scope: $scope
+        )
+      }
+    `, {
+        deckId: record.deckId,
+        variable: record.variable,
+        score,
+        scope: record.scope,
+    }, {
+        operation: "CastleSaveVariableToLeaderboard",
+        token,
+        requireAuth: true,
+    });
+}
+function leaderboardVariables(request) {
+    return {
+        deckId: request.deckId,
+        variable: request.variable,
+        type: request.type,
+        filter: "dedupUsers",
+        includeFollowList: false,
+        includeParties: false,
+        scope: request.scope,
+    };
+}
+function leaderboardFields() {
+    return `{
+    yourScore { score }
+    list {
+      place
+      score
+      user {
+        userId
+        username
+      }
+    }
+  }`;
+}
+function leaderboardScope(options) {
+    return options.scope ?? null;
+}
+function normalizeLeaderboard(leaderboard, userId) {
+    const list = (leaderboard.list ?? []).map(normalizeLeaderboardEntry);
+    const playerRank = playerRankFromList(list, userId);
+    const playerValue = scoreNumber(leaderboard.yourScore?.score);
+    return {
+        list,
+        ...(playerRank === undefined ? {} : { playerRank }),
+        ...(playerValue === undefined ? {} : { playerValue }),
+    };
+}
+function normalizeLeaderboardEntry(entry) {
+    const userId = entry.user?.userId ?? undefined;
+    return {
+        place: scoreNumber(entry.place) ?? 0,
+        value: scoreNumber(entry.score) ?? 0,
+        username: entry.user?.username ?? "",
+        ...(userId ? { userId } : {}),
+    };
+}
+function playerRankFromList(list, userId) {
+    return userId
+        ? list.find((entry) => entry.userId === userId)?.place
+        : undefined;
+}
+function scoreNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== "string")
+        return undefined;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function leaderboardWriteKey(deckId, variable, scope) {
+    return `${deckId}::${variable}${scope ? `::${scope}` : ""}`;
+}
+function assertLeaderboardVariable(variable, operation) {
+    if (variable.trim().length > 0)
+        return;
+    throw new CastleError({
+        code: "INVALID_LEADERBOARD_VARIABLE",
+        message: "Leaderboard variable must be a non-empty string.",
+        operation,
+    });
+}
+function assertLeaderboardScore(score, operation) {
+    if (Number.isFinite(score))
+        return;
+    throw new CastleError({
+        code: "INVALID_LEADERBOARD_SCORE",
+        message: "Leaderboard score must be a finite number.",
+        operation,
+    });
+}
+function assertLeaderboardType(type, operation) {
+    if (type === "high" || type === "low")
+        return;
+    throw new CastleError({
+        code: "INVALID_LEADERBOARD_TYPE",
+        message: "Leaderboard type must be high or low.",
+        operation,
+    });
+}
+function reportLeaderboardError(error) {
+    console.warn("Castle leaderboard request failed", error);
+}