castle-web-sdk 0.4.0 → 0.4.2

package/src/time.ts

@@ -0,0 +1,226 @@
+import { CastleError } from "./errors";
+import { graphqlRequest } from "./graphql";
+import type { Json } from "./types";
+
+export type CastleClockZone = "player" | "Castle";
+
+export interface CastleDateParts {
+  sec: number;
+  min: number;
+  hour: number;
+  day: number;
+  month: number;
+  year: number;
+  wday: number;
+  yday: number;
+  daysSinceCastleEpoch: number;
+}
+
+export interface CastleTimeApi {
+  getServerTime(): Promise<number>;
+  getServerDate(timezone?: CastleClockZone): Promise<CastleDateParts>;
+}
+
+interface ServerTimeQueryData {
+  serverTime: {
+    timestamp: number;
+    timezoneOffset: number;
+    castleEpochData: Json;
+  };
+}
+
+interface ServerTimeSnapshot {
+  offsetSeconds: number;
+  castleTimezoneOffsetMinutes: number;
+  daysSinceCastleEpoch: Record<CastleClockZone, number>;
+}
+
+const SERVER_TIME_QUERY = `
+  query CastleServerTime {
+    serverTime {
+      timestamp
+      timezoneOffset
+      castleEpochData
+    }
+  }
+`;
+
+let serverTimeSnapshot: ServerTimeSnapshot | null = null;
+let serverTimePromise: Promise<ServerTimeSnapshot> | null = null;
+
+export const Time: CastleTimeApi = {
+  getServerTime,
+  getServerDate,
+};
+
+async function getServerTime(): Promise<number> {
+  const snapshot = await syncServerTime();
+  return clientUnixSeconds() + snapshot.offsetSeconds;
+}
+
+async function getServerDate(
+  timezone: string = "Castle",
+): Promise<CastleDateParts> {
+  const operation = "Time.getServerDate";
+  const zone = clockZone(timezone, operation);
+  const snapshot = await syncServerTime();
+  return dateParts(
+    clientUnixSeconds() + snapshot.offsetSeconds,
+    zone,
+    snapshot,
+  );
+}
+
+async function syncServerTime(): Promise<ServerTimeSnapshot> {
+  if (serverTimeSnapshot) return serverTimeSnapshot;
+  if (!serverTimePromise) {
+    serverTimePromise = fetchServerTime().then((snapshot) => {
+      serverTimeSnapshot = snapshot;
+      return snapshot;
+    });
+  }
+  return serverTimePromise;
+}
+
+async function fetchServerTime(): Promise<ServerTimeSnapshot> {
+  const operation = "Time.getServerTime";
+  const data = await graphqlRequest<ServerTimeQueryData>(
+    SERVER_TIME_QUERY,
+    undefined,
+    {
+      operation,
+    },
+  );
+  const timestamp = numberField(
+    data.serverTime.timestamp,
+    "serverTime.timestamp",
+    operation,
+  );
+  const timezoneOffset = numberField(
+    data.serverTime.timezoneOffset,
+    "serverTime.timezoneOffset",
+    operation,
+  );
+  const epochData = jsonObject(
+    data.serverTime.castleEpochData,
+    "serverTime.castleEpochData",
+    operation,
+  );
+  return {
+    offsetSeconds: snappedOffset(timestamp - clientUnixSeconds()),
+    castleTimezoneOffsetMinutes: timezoneOffset,
+    daysSinceCastleEpoch: {
+      Castle: numberField(
+        epochData.daysSinceServerTz,
+        "castleEpochData.daysSinceServerTz",
+        operation,
+      ),
+      player: numberField(
+        epochData.daysSinceUserTz,
+        "castleEpochData.daysSinceUserTz",
+        operation,
+      ),
+    },
+  };
+}
+
+function dateParts(
+  unixSeconds: number,
+  timezone: CastleClockZone,
+  snapshot: ServerTimeSnapshot,
+): CastleDateParts {
+  const shiftedSeconds =
+    timezone === "Castle"
+      ? unixSeconds + snapshot.castleTimezoneOffsetMinutes * 60
+      : unixSeconds;
+  const date = new Date(shiftedSeconds * 1000);
+  return timezone === "Castle"
+    ? utcDateParts(date, snapshot.daysSinceCastleEpoch.Castle)
+    : localDateParts(date, snapshot.daysSinceCastleEpoch.player);
+}
+
+function utcDateParts(
+  date: Date,
+  daysSinceCastleEpoch: number,
+): CastleDateParts {
+  return {
+    sec: date.getUTCSeconds(),
+    min: date.getUTCMinutes(),
+    hour: date.getUTCHours(),
+    day: date.getUTCDate(),
+    month: date.getUTCMonth() + 1,
+    year: date.getUTCFullYear(),
+    wday: date.getUTCDay() + 1,
+    yday: dayOfYear(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+    ),
+    daysSinceCastleEpoch,
+  };
+}
+
+function localDateParts(
+  date: Date,
+  daysSinceCastleEpoch: number,
+): CastleDateParts {
+  return {
+    sec: date.getSeconds(),
+    min: date.getMinutes(),
+    hour: date.getHours(),
+    day: date.getDate(),
+    month: date.getMonth() + 1,
+    year: date.getFullYear(),
+    wday: date.getDay() + 1,
+    yday: dayOfYear(date.getFullYear(), date.getMonth(), date.getDate()),
+    daysSinceCastleEpoch,
+  };
+}
+
+function dayOfYear(year: number, monthIndex: number, day: number): number {
+  const start = Date.UTC(year, 0, 1);
+  const current = Date.UTC(year, monthIndex, day);
+  return Math.floor((current - start) / 86400000) + 1;
+}
+
+function clockZone(timezone: string, operation: string): CastleClockZone {
+  const normalized = timezone.trim().toLowerCase();
+  if (normalized === "castle") return "Castle";
+  if (normalized === "player") return "player";
+  throw new CastleError({
+    code: "UNSUPPORTED_TIMEZONE",
+    message: 'Time.getServerDate timezone must be "Castle" or "player".',
+    operation,
+  });
+}
+
+function clientUnixSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+function snappedOffset(offsetSeconds: number): number {
+  return Math.abs(offsetSeconds) < 10 ? 0 : offsetSeconds;
+}
+
+function jsonObject(
+  value: Json,
+  field: string,
+  operation: string,
+): Record<string, Json> {
+  if (value !== null && typeof value === "object" && !Array.isArray(value))
+    return value;
+  throw new CastleError({
+    code: "GRAPHQL_BAD_DATA",
+    message: `Castle GraphQL field ${field} was not an object.`,
+    operation,
+  });
+}
+
+function numberField(value: Json, field: string, operation: string): number {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  throw new CastleError({
+    code: "GRAPHQL_BAD_DATA",
+    message: `Castle GraphQL field ${field} was not a number.`,
+    operation,
+  });
+}

package/src/types.ts

@@ -0,0 +1,7 @@
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };

package/src/user.ts

@@ -0,0 +1,91 @@
+import { requireAuthToken } from "./auth";
+import { CastleError } from "./errors";
+import { graphqlRequest } from "./graphql";
+
+export interface CastleUser {
+  userId: string;
+  username: string;
+  isActive: boolean;
+}
+
+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;
+
+export const User: CastleUserApi = {
+  getCurrent,
+};
+
+async function getCurrent(): Promise<CastleUser> {
+  if (currentUser) return currentUser;
+  currentUserPromise ??= fetchCurrentUser().then((user) => {
+    currentUser = user;
+    return user;
+  });
+  return currentUserPromise;
+}
+
+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) {
+    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),
+    isActive: true,
+  };
+}
+
+function requiredString(
+  value: string | null | undefined,
+  field: string,
+  operation: string,
+): string {
+  if (typeof value === "string" && value.length > 0) return value;
+  throw new CastleError({
+    code: "GRAPHQL_BAD_DATA",
+    message: `Castle GraphQL response did not include ${field}.`,
+    operation,
+  });
+}

package/AGENTS.md

@@ -1,27 +0,0 @@
-# Castle Web SDK
-
-Import from `castle-web-sdk` (or `./castle.js` directly).
-
-## API
-
-### `setup()`
-
-Connects to the CLI dev server for console log forwarding, screenshot capture, and live reload. Call once at startup.
-
-```js
-import { setup } from 'castle-web-sdk';
-setup();
-```
-
-### `initCard()` -> HTMLElement
-
-Creates a card-sized container (5:7 aspect ratio) that fills the viewport. Mount your game inside the returned element.
-
-```js
-const card = initCard();
-card.appendChild(myGameElement);
-```
-
-### Constants
-
-- `CARD_RATIO` — `5 / 7`

package/castle.js

@@ -1,116 +0,0 @@
-// Castle Web SDK
-
-export const CARD_RATIO = 5 / 7;
-
-let _ws = null;
-let _logBuffer = [];
-
-export function setup() {
-  _interceptConsole();
-  _connectLocal();
-}
-
-// --- Card shell ---
-
-export function initCard() {
-  const style = document.createElement('style');
-  style.textContent = `
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    html, body { width: 100%; height: 100%; background: #000; overflow: hidden; }
-    body { display: flex; align-items: center; justify-content: center; }
-    #castle-card {
-      position: relative;
-      border-radius: 4% / calc(4% * (5 / 7));
-      overflow: hidden;
-      background: #121213;
-    }
-  `;
-  document.head.appendChild(style);
-
-  const card = document.createElement('div');
-  card.id = 'castle-card';
-  document.body.appendChild(card);
-
-  function resize() {
-    if (window.CastleEmbed) {
-      card.style.width = '100vw';
-      card.style.height = '100vh';
-      return;
-    }
-    const maxW = 450, maxH = 630, pad = 20;
-    const aw = window.innerWidth - pad * 2;
-    const ah = window.innerHeight - pad * 2;
-    let w, h;
-    if (aw / ah < 5 / 7) { w = Math.min(aw, maxW); h = w * 7 / 5; }
-    else { h = Math.min(ah, maxH); w = h * 5 / 7; }
-    card.style.width = w + 'px';
-    card.style.height = h + 'px';
-  }
-  resize();
-  window.addEventListener('resize', resize);
-
-  return card;
-}
-
-// --- Console log forwarding ---
-
-const _origLog = console.log;
-const _origWarn = console.warn;
-const _origError = console.error;
-
-function _sendMsg(msg) {
-  if (_ws && _ws.readyState === WebSocket.OPEN) {
-    _ws.send(JSON.stringify(msg));
-  } else {
-    _logBuffer.push(msg);
-  }
-}
-
-function _interceptConsole() {
-  console.log = (...args) => { _origLog(...args); _sendMsg({ type: 'log', level: 'log', msg: args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ') }); };
-  console.warn = (...args) => { _origWarn(...args); _sendMsg({ type: 'log', level: 'warn', msg: args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ') }); };
-  console.error = (...args) => { _origError(...args); _sendMsg({ type: 'log', level: 'error', msg: args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ') }); };
-}
-
-// --- Screenshot ---
-
-async function _captureScreenshot() {
-  const canvas = document.querySelector('canvas');
-  if (canvas) return canvas.toDataURL('image/png');
-  try {
-    const { default: html2canvas } = await import('https://esm.sh/html2canvas');
-    const c = await html2canvas(document.body);
-    return c.toDataURL('image/png');
-  } catch { return null; }
-}
-
-// --- Local WebSocket ---
-
-function _connectLocal() {
-  fetch('/__castle/ws-port')
-    .then(r => r.json())
-    .then(({ port }) => {
-      if (!port) return;
-      const ws = new WebSocket(`ws://localhost:${port}`);
-      ws.onopen = () => {
-        _ws = ws;
-        for (const msg of _logBuffer) _ws.send(JSON.stringify(msg));
-        _logBuffer = [];
-      };
-      ws.onmessage = (evt) => {
-        try {
-          const msg = JSON.parse(evt.data);
-          if (msg.type === 'screenshot_request') {
-            _captureScreenshot().then(data => {
-              if (data) _sendMsg({ type: 'screenshot_response', requestId: msg.requestId, data });
-            });
-          } else if (msg.type === 'restart') {
-            location.reload();
-          }
-        } catch {}
-      };
-      ws.onclose = () => { _ws = null; setTimeout(_connectLocal, 2000); };
-      ws.onerror = () => ws.close();
-    })
-    .catch(() => {});
-}