castle-web-sdk 0.4.1 → 0.4.2

package/src/auth.ts

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

@@ -0,0 +1,19 @@
+// Castle Web SDK
+
+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/src/context.ts

@@ -0,0 +1,124 @@
+import { CastleError } from "./errors";
+
+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;
+  }
+}
+
+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;
+}
+
+export function isEdit(): boolean {
+  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: 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;
+}

package/src/errors.ts

@@ -0,0 +1,32 @@
+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 class CastleError extends Error {
+  code: string;
+  operation?: string;
+  status?: number;
+  extensions?: Record<string, unknown>;
+  errors?: GraphqlErrorPayload[];
+
+  constructor(input: CastleErrorInput) {
+    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/src/graphql.ts

@@ -0,0 +1,182 @@
+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";
+}