@playcademy/sdk 0.0.1-beta.5 → 0.0.1-beta.6

package/dist/bus.d.ts

@@ -0,0 +1,37 @@
+import type { GameContextPayload } from './types';
+export declare enum BusEvents {
+    INIT = "PLAYCADEMY_INIT",
+    TOKEN_REFRESH = "PLAYCADEMY_TOKEN_REFRESH",
+    PAUSE = "PLAYCADEMY_PAUSE",
+    RESUME = "PLAYCADEMY_RESUME",
+    FORCE_EXIT = "PLAYCADEMY_FORCE_EXIT",
+    OVERLAY = "PLAYCADEMY_OVERLAY",
+    READY = "PLAYCADEMY_READY",
+    EXIT = "PLAYCADEMY_EXIT",
+    TELEMETRY = "PLAYCADEMY_TELEMETRY"
+}
+type BusHandler<T = unknown> = (payload: T) => void;
+export type BusEventMap = {
+    [BusEvents.INIT]: GameContextPayload;
+    [BusEvents.TOKEN_REFRESH]: {
+        token: string;
+        exp: number;
+    };
+    [BusEvents.PAUSE]: void;
+    [BusEvents.RESUME]: void;
+    [BusEvents.FORCE_EXIT]: void;
+    [BusEvents.OVERLAY]: boolean;
+    [BusEvents.READY]: void;
+    [BusEvents.EXIT]: void;
+    [BusEvents.TELEMETRY]: {
+        fps: number;
+        mem: number;
+    };
+};
+interface Bus {
+    emit<K extends BusEvents>(type: K, payload: BusEventMap[K]): void;
+    on<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>): void;
+    off<K extends BusEvents>(type: K, handler: BusHandler<BusEventMap[K]>): void;
+}
+export declare const bus: Bus;
+export {};

package/dist/core/client.d.ts

@@ -0,0 +1,144 @@
+import { type Method } from './request';
+import type { Game, GameWithManifest, UpsertGameMetadataInput, InsertReward, UpdateReward } from '@playcademy/types';
+import type { GameState, InventoryItemWithReward, ClientConfig, ClientEvents, LoginResponse, GameTokenResponse, StartSessionResponse, InventoryMutationResponse, DeveloperStatusValue } from '../types';
+export declare class PlaycademyClient {
+    private baseUrl;
+    private token?;
+    private gameId?;
+    private listeners;
+    private internalClientSessionId?;
+    constructor(config: ClientConfig);
+    private _initializeInternalSession;
+    getBaseUrl(): string;
+    on<E extends keyof ClientEvents>(event: E, callback: (payload: ClientEvents[E]) => void): void;
+    private emit;
+    setToken(token: string | null): void;
+    onAuthChange(callback: (token: string | null) => void): void;
+    protected request<T>(path: string, method: Method, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    private _ensureGameId;
+    auth: {
+        logout: () => Promise<void>;
+    };
+    runtime: {
+        getGameToken: (gameId: string, options?: {
+            apply?: boolean;
+        }) => Promise<GameTokenResponse>;
+        exit: () => Promise<void>;
+    };
+    games: {
+        fetch: (gameIdOrSlug: string) => Promise<GameWithManifest>;
+        list: () => Promise<Array<Game>>;
+        saveState: (state: Record<string, unknown>) => Promise<void>;
+        loadState: () => Promise<GameState>;
+        startSession: (gameId?: string) => Promise<StartSessionResponse>;
+        endSession: (sessionId: string, gameId?: string) => Promise<void>;
+    };
+    users: {
+        me: () => Promise<{
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            name: string;
+            username: string | null;
+            email: string;
+            emailVerified: boolean;
+            image: string | null;
+            role: "admin" | "player" | "developer";
+            developerStatus: "none" | "pending" | "approved";
+        }>;
+        inventory: {
+            get: () => Promise<InventoryItemWithReward[]>;
+            add: (rewardId: string, qty: number) => Promise<InventoryMutationResponse>;
+            spend: (rewardId: string, qty: number) => Promise<InventoryMutationResponse>;
+        };
+    };
+    dev: {
+        auth: {
+            applyForDeveloper: () => Promise<void>;
+            getDeveloperStatus: () => Promise<DeveloperStatusValue>;
+        };
+        games: {
+            upsert: (slug: string, metadata: UpsertGameMetadataInput, file: File | Blob) => Promise<Game>;
+            update: (gameId: string, props: Partial<Game>) => Promise<void>;
+            delete: (gameId: string) => Promise<void>;
+        };
+        keys: {
+            createKey: (gameId: string, label?: string) => Promise<{
+                id: string;
+                createdAt: Date;
+                userId: string;
+                label: string | null;
+                keyHash: string;
+            }>;
+            listKeys: (gameId: string) => Promise<{
+                id: string;
+                createdAt: Date;
+                userId: string;
+                label: string | null;
+                keyHash: string;
+            }[]>;
+            revokeKey: (keyId: string) => Promise<void>;
+        };
+    };
+    maps: {
+        elements: (mapId: string) => Promise<{
+            id: string;
+            metadata: ({
+                description?: string | undefined;
+                sourceTiledObjects?: Record<string, unknown>[] | undefined;
+            } & {
+                [k: string]: unknown;
+            }) | null;
+            mapId: string | null;
+            elementSlug: string;
+            interactionType: "game_entry" | "game_registry" | "info" | "teleport" | "door_in" | "door_out" | "npc_interaction" | "quest_trigger";
+            gameId: string | null;
+        }[]>;
+    };
+    admin: {
+        games: {
+            pauseGame: (gameId: string) => Promise<void>;
+            resumeGame: (gameId: string) => Promise<void>;
+        };
+        rewards: {
+            createReward: (props: InsertReward) => Promise<{
+                id: string;
+                displayName: string;
+                metadata: unknown;
+                internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+            }>;
+            getReward: (rewardId: string) => Promise<{
+                id: string;
+                displayName: string;
+                metadata: unknown;
+                internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+            }>;
+            listRewards: () => Promise<{
+                id: string;
+                displayName: string;
+                metadata: unknown;
+                internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+            }[]>;
+            updateReward: (rewardId: string, props: UpdateReward) => Promise<{
+                id: string;
+                displayName: string;
+                metadata: unknown;
+                internalName: string;
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+            }>;
+            deleteReward: (rewardId: string) => Promise<void>;
+        };
+    };
+    telemetry: {
+        pushMetrics: (metrics: Record<string, number>) => Promise<void>;
+    };
+    ping(): string;
+    static login(baseUrl: string, email: string, password: string): Promise<LoginResponse>;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Base error class for Cademy SDK specific errors.
+ */
+export declare class PlaycademyError extends Error {
+    constructor(message: string);
+}
+export declare class ApiError extends Error {
+    status: number;
+    details: unknown;
+    constructor(status: number, message: string, details: unknown);
+}

package/dist/core/request.d.ts

@@ -0,0 +1,24 @@
+import type { ManifestV1 } from '@playcademy/types';
+/** Permitted HTTP verbs */
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface RequestOptions {
+    path: string;
+    baseUrl: string;
+    token?: string | null;
+    method?: Method;
+    body?: unknown;
+    extraHeaders?: Record<string, string>;
+}
+/**
+ * Thin wrapper around `fetch` that:
+ *  • attaches Bearer token if provided
+ *  • stringifies JSON bodies and sets Content‑Type
+ *  • passes FormData untouched so the browser adds multipart boundary
+ *  • normalises non‑2xx responses into ApiError
+ *  • auto‑parses JSON responses, falls back to text/void
+ */
+export declare function request<T = unknown>({ path, baseUrl, token, method, body, extraHeaders, }: RequestOptions): Promise<T>;
+/**
+ * Fetches, parses, and validates the playcademy.manifest.json file from a given base URL.
+ */
+export declare function fetchManifest(assetBundleBase: string): Promise<ManifestV1>;

package/dist/runtime.d.ts

@@ -0,0 +1,7 @@
+import { PlaycademyClient } from './core/client';
+/** For Node, SSR, dashboards, etc. */
+export { PlaycademyClient } from './core/client';
+/** Factory for code running *inside* the CADEMY loader (games) */
+export declare function initFromWindow(): Promise<PlaycademyClient>;
+export { bus, BusEvents } from './bus';
+export { PlaycademyError } from './core/errors';

package/dist/runtime.js

@@ -0,0 +1,363 @@
+// src/bus.ts
+var BusEvents;
+((BusEvents2) => {
+  BusEvents2["INIT"] = "PLAYCADEMY_INIT";
+  BusEvents2["TOKEN_REFRESH"] = "PLAYCADEMY_TOKEN_REFRESH";
+  BusEvents2["PAUSE"] = "PLAYCADEMY_PAUSE";
+  BusEvents2["RESUME"] = "PLAYCADEMY_RESUME";
+  BusEvents2["FORCE_EXIT"] = "PLAYCADEMY_FORCE_EXIT";
+  BusEvents2["OVERLAY"] = "PLAYCADEMY_OVERLAY";
+  BusEvents2["READY"] = "PLAYCADEMY_READY";
+  BusEvents2["EXIT"] = "PLAYCADEMY_EXIT";
+  BusEvents2["TELEMETRY"] = "PLAYCADEMY_TELEMETRY";
+})(BusEvents ||= {});
+var busListeners = new Map;
+var bus = {
+  emit(type, payload) {
+    window.dispatchEvent(new CustomEvent(type, { detail: payload }));
+  },
+  on(type, handler) {
+    const listener = (event) => handler(event.detail);
+    if (!busListeners.has(type)) {
+      busListeners.set(type, new Map);
+    }
+    busListeners.get(type).set(handler, listener);
+    window.addEventListener(type, listener);
+  },
+  off(type, handler) {
+    const typeListeners = busListeners.get(type);
+    if (!typeListeners || !typeListeners.has(handler)) {
+      return;
+    }
+    const actualListener = typeListeners.get(handler);
+    window.removeEventListener(type, actualListener);
+    typeListeners.delete(handler);
+    if (typeListeners.size === 0) {
+      busListeners.delete(type);
+    }
+  }
+};
+
+// src/core/errors.ts
+class PlaycademyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PlaycademyError";
+  }
+}
+
+class ApiError extends Error {
+  status;
+  details;
+  constructor(status, message, details) {
+    super(`${status} ${message}`);
+    this.status = status;
+    this.details = details;
+    Object.setPrototypeOf(this, ApiError.prototype);
+  }
+}
+
+// src/core/request.ts
+async function request({
+  path,
+  baseUrl,
+  token,
+  method = "GET",
+  body,
+  extraHeaders = {}
+}) {
+  const url = baseUrl.replace(/\/$/, "") + (path.startsWith("/") ? path : `/${path}`);
+  const headers = { ...extraHeaders };
+  let payload;
+  if (body instanceof FormData) {
+    payload = body;
+  } else if (body !== undefined && body !== null) {
+    payload = JSON.stringify(body);
+    headers["Content-Type"] = "application/json";
+  }
+  if (token)
+    headers["Authorization"] = `Bearer ${token}`;
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: payload,
+    credentials: "omit"
+  });
+  if (!res.ok) {
+    const errorBody = await res.clone().json().catch(() => res.text().catch(() => {
+      return;
+    })) ?? undefined;
+    throw new ApiError(res.status, res.statusText, errorBody);
+  }
+  if (res.status === 204)
+    return;
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return await res.json();
+  }
+  return await res.text();
+}
+async function fetchManifest(assetBundleBase) {
+  const manifestUrl = `${assetBundleBase.replace(/\/$/, "")}/playcademy.manifest.json`;
+  try {
+    const response = await fetch(manifestUrl);
+    if (!response.ok) {
+      console.error(`[fetchManifest] Failed to fetch manifest from ${manifestUrl}. Status: ${response.status}`);
+      throw new PlaycademyError(`Failed to fetch manifest: ${response.status} ${response.statusText}`);
+    }
+    return await response.json();
+  } catch (error) {
+    if (error instanceof PlaycademyError) {
+      throw error;
+    }
+    console.error(`[fetchManifest] Error fetching or parsing manifest from ${manifestUrl}:`, error);
+    throw new PlaycademyError("Failed to load or parse game manifest");
+  }
+}
+
+// src/core/client.ts
+class PlaycademyClient {
+  baseUrl;
+  token;
+  gameId;
+  listeners = {};
+  internalClientSessionId;
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.token = config.token;
+    this.gameId = config.gameId;
+    if (this.gameId) {
+      this._initializeInternalSession().catch((error) => {
+        console.error("[SDK] Background initialization of auto-session failed:", error);
+      });
+    }
+  }
+  async _initializeInternalSession() {
+    if (!this.gameId || this.internalClientSessionId) {
+      return;
+    }
+    try {
+      const response = await this.games.startSession(this.gameId);
+      this.internalClientSessionId = response.sessionId;
+    } catch (error) {
+      console.error("[SDK] Auto-starting session failed for game", this.gameId, error);
+    }
+  }
+  getBaseUrl() {
+    const isRelative = this.baseUrl.startsWith("/");
+    const isBrowser = typeof window !== "undefined";
+    return isRelative && isBrowser ? `${window.location.origin}${this.baseUrl}` : this.baseUrl;
+  }
+  on(event, callback) {
+    this.listeners[event] = this.listeners[event] ?? [];
+    this.listeners[event].push(callback);
+  }
+  emit(event, payload) {
+    (this.listeners[event] ?? []).forEach((listener) => {
+      listener(payload);
+    });
+  }
+  setToken(token) {
+    this.token = token ?? undefined;
+    this.emit("authChange", { token: this.token ?? null });
+  }
+  onAuthChange(callback) {
+    this.on("authChange", (payload) => callback(payload.token));
+  }
+  async request(path, method, body, headers) {
+    const effectiveHeaders = { ...headers };
+    return request({
+      path,
+      method,
+      body,
+      baseUrl: this.baseUrl,
+      token: this.token,
+      extraHeaders: effectiveHeaders
+    });
+  }
+  _ensureGameId() {
+    if (!this.gameId) {
+      throw new PlaycademyError("This operation requires a gameId, but none was provided when initializing the client.");
+    }
+    return this.gameId;
+  }
+  auth = {
+    logout: async () => {
+      await this.request(`/auth/logout`, "DELETE");
+      this.setToken(null);
+    }
+  };
+  runtime = {
+    getGameToken: async (gameId, options) => {
+      const res = await this.request(`/games/${gameId}/token`, "POST");
+      if (options?.apply) {
+        this.setToken(res.token);
+      }
+      return res;
+    },
+    exit: async () => {
+      if (this.internalClientSessionId && this.gameId) {
+        try {
+          await this.games.endSession(this.internalClientSessionId, this.gameId);
+        } catch (error) {
+          console.error("[SDK] Failed to auto-end session:", this.internalClientSessionId, error);
+        }
+      }
+      bus.emit("PLAYCADEMY_EXIT" /* EXIT */, undefined);
+    }
+  };
+  games = {
+    fetch: async (gameIdOrSlug) => {
+      const baseGameData = await this.request(`/games/${gameIdOrSlug}`, "GET");
+      const manifestData = await fetchManifest(baseGameData.assetBundleBase);
+      return {
+        ...baseGameData,
+        manifest: manifestData
+      };
+    },
+    list: () => this.request("/games", "GET"),
+    saveState: async (state) => {
+      const gameId = this._ensureGameId();
+      await this.request(`/games/${gameId}/state`, "POST", state);
+    },
+    loadState: async () => {
+      const gameId = this._ensureGameId();
+      return this.request(`/games/${gameId}/state`, "GET");
+    },
+    startSession: async (gameId) => {
+      const idToUse = gameId ?? this._ensureGameId();
+      return this.request(`/games/${idToUse}/sessions`, "POST", {});
+    },
+    endSession: async (sessionId, gameId) => {
+      const effectiveGameIdToEnd = gameId ?? this._ensureGameId();
+      if (this.internalClientSessionId && sessionId === this.internalClientSessionId && effectiveGameIdToEnd === this.gameId) {
+        this.internalClientSessionId = undefined;
+      }
+      await this.request(`/games/${effectiveGameIdToEnd}/sessions/${sessionId}/end`, "POST");
+    }
+  };
+  users = {
+    me: async () => {
+      return this.request("/users/me", "GET");
+    },
+    inventory: {
+      get: async () => this.request(`/inventory`, "GET"),
+      add: async (rewardId, qty) => {
+        const res = await this.request(`/inventory/add`, "POST", { rewardId, qty });
+        this.emit("inventoryChange", {
+          rewardId,
+          delta: qty,
+          newTotal: res.newTotal
+        });
+        return res;
+      },
+      spend: async (rewardId, qty) => {
+        const res = await this.request(`/inventory/spend`, "POST", { rewardId, qty });
+        this.emit("inventoryChange", {
+          rewardId,
+          delta: -qty,
+          newTotal: res.newTotal
+        });
+        return res;
+      }
+    }
+  };
+  dev = {
+    auth: {
+      applyForDeveloper: () => this.request("/dev/apply", "POST"),
+      getDeveloperStatus: async () => {
+        const response = await this.request("/dev/status", "GET");
+        return response.status;
+      }
+    },
+    games: {
+      upsert: (slug, metadata, file) => {
+        const form = new FormData;
+        form.append("metadata", JSON.stringify(metadata));
+        form.append("file", file);
+        return this.request(`/games/${slug}`, "PUT", form);
+      },
+      update: (gameId, props) => this.request(`/games/${gameId}`, "PATCH", props),
+      delete: (gameId) => this.request(`/games/${gameId}`, "DELETE")
+    },
+    keys: {
+      createKey: (gameId, label) => this.request(`/dev/games/${gameId}/keys`, "POST", { label }),
+      listKeys: (gameId) => this.request(`/dev/games/${gameId}/keys`, "GET"),
+      revokeKey: (keyId) => this.request(`/dev/keys/${keyId}`, "DELETE")
+    }
+  };
+  maps = {
+    elements: (mapId) => this.request(`/map/elements?mapId=${mapId}`, "GET")
+  };
+  admin = {
+    games: {
+      pauseGame: (gameId) => this.request(`/admin/games/${gameId}/pause`, "POST"),
+      resumeGame: (gameId) => this.request(`/admin/games/${gameId}/resume`, "POST")
+    },
+    rewards: {
+      createReward: (props) => this.request("/rewards", "POST", props),
+      getReward: (rewardId) => this.request(`/rewards/${rewardId}`, "GET"),
+      listRewards: () => this.request("/rewards", "GET"),
+      updateReward: (rewardId, props) => this.request(`/rewards/${rewardId}`, "PATCH", props),
+      deleteReward: (rewardId) => this.request(`/rewards/${rewardId}`, "DELETE")
+    }
+  };
+  telemetry = {
+    pushMetrics: (metrics) => this.request(`/telemetry/metrics`, "POST", metrics)
+  };
+  ping() {
+    return "pong";
+  }
+  static async login(baseUrl, email, password) {
+    let url = baseUrl;
+    if (baseUrl.startsWith("/") && typeof window !== "undefined") {
+      url = window.location.origin + baseUrl;
+    }
+    url = url + "/auth/login";
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ email, password })
+    });
+    if (!response.ok) {
+      try {
+        const errorData = await response.json();
+        const errorMessage = errorData && errorData.message ? String(errorData.message) : response.statusText;
+        throw new PlaycademyError(errorMessage);
+      } catch (error) {
+        console.error("[SDK] Failed to parse error response JSON, using status text instead:", error);
+        throw new PlaycademyError(response.statusText);
+      }
+    }
+    return response.json();
+  }
+}
+
+// src/runtime.ts
+async function initFromWindow() {
+  if (typeof window === "undefined") {
+    throw new Error("initFromWindow must run in a browser context");
+  }
+  const preloaded = window.PLAYCADEMY;
+  const config = preloaded?.token ? preloaded : await new Promise((resolve) => bus.on("PLAYCADEMY_INIT" /* INIT */, resolve));
+  const client = new PlaycademyClient({
+    baseUrl: config.baseUrl,
+    token: config.token,
+    gameId: config.gameId
+  });
+  bus.on("PLAYCADEMY_TOKEN_REFRESH" /* TOKEN_REFRESH */, ({ token }) => client.setToken(token));
+  bus.emit("PLAYCADEMY_READY" /* READY */, undefined);
+  if (import.meta.env?.MODE === "development") {
+    window.PLAYCADEMY_CLIENT = client;
+  }
+  return client;
+}
+export {
+  initFromWindow,
+  bus,
+  PlaycademyError,
+  PlaycademyClient,
+  BusEvents
+};

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+import type { User, InventoryItemWithReward, Game, DeveloperKey, DeveloperStatusResponse, MapElement, Reward, InsertReward, ManifestV1, UpdateReward } from '@playcademy/types';
+export interface ClientConfig {
+    baseUrl: string;
+    token?: string;
+    gameId?: string;
+}
+export interface ClientEvents {
+    authChange: {
+        token: string | null;
+    };
+    inventoryChange: {
+        rewardId: string;
+        delta: number;
+        newTotal: number;
+    };
+}
+export type GameContextPayload = {
+    token: string;
+    baseUrl: string;
+    gameId: string;
+};
+export type EventListeners = {
+    [E in keyof ClientEvents]?: Array<(payload: ClientEvents[E]) => void>;
+};
+export type GameWithManifest = Game & {
+    manifest: ManifestV1;
+};
+export type DeveloperStatusValue = DeveloperStatusResponse['status'];
+export type GameState = Record<string, unknown>;
+export type LoginResponse = {
+    token: string;
+};
+export type GameTokenResponse = {
+    token: string;
+    exp: number;
+};
+export type StartSessionResponse = {
+    sessionId: string;
+};
+export type InventoryMutationResponse = {
+    newTotal: number;
+};
+export type { User, InventoryItemWithReward, Game, ManifestV1, DeveloperKey, DeveloperStatusResponse, MapElement, Reward, InsertReward, UpdateReward, };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@playcademy/sdk",
     "type": "module",
-    "version": "0.0.1-beta.5",
+    "version": "0.0.1-beta.6",
     "exports": {
         ".": {
             "import": "./dist/runtime.js",
@@ -14,6 +14,9 @@
             "types": "./dist/types.d.ts"
         }
     },
+    "files": [
+        "dist"
+    ],
     "main": "dist/runtime.js",
     "module": "dist/runtime.js",
     "scripts": {