@playcademy/sdk 0.0.1-beta.1

package/README.md

@@ -0,0 +1,169 @@
+# Playcademy SDK
+
+A TypeScript SDK for interacting with the Playcademy platform API.
+
+## Overview
+
+This SDK provides a unified client for various interactions with Playcademy.
+
+## Install
+
+```bash
+bun add @playcademy/sdk
+# or
+npm install @playcademy/sdk
+# or
+yarn add @playcademy/sdk
+# or
+pnpm add @playcademy/sdk
+```
+
+## Initialization
+
+### Browser / Mini-Games (Runtime Environment)
+
+For code running within the Playcademy game loader environment (e.g., mini-games):
+
+```ts
+import { initFromWindow } from '@playcademy/sdk'
+
+// Reads configuration from window.PLAYCADEMY injected by the loader
+const client = await initFromWindow() // initFromWindow is async
+```
+
+### General Use (Node.js, Backend, UI Tooling)
+
+For server-side code, UI applications, or other environments where you manage configuration manually:
+
+```ts
+import { PlaycademyClient, type LoginResponse } from '@playcademy/sdk'
+
+async function initializeAndUseClient() {
+    const baseUrl = 'https://api.playcademy.com' // Or your local /api endpoint
+    let loginResponse: LoginResponse
+
+    try {
+        // 1. Authenticate to get a token
+        loginResponse = await PlaycademyClient.login(
+            baseUrl,
+            'user@example.com',
+            'password',
+        )
+    } catch (error) {
+        console.error('Login failed:', error)
+        return
+    }
+
+    // 2. Instantiate the client with the token
+    // Optionally provide a gameId to enable automatic session management for that game.
+    const client = new PlaycademyClient({
+        baseUrl: baseUrl,
+        token: loginResponse.token,
+        // gameId: 'your-game-id' // Optional: if provided, client attempts to auto-start/end session
+    })
+
+    // If the token has appropriate permissions, you can access all namespaces:
+    // client.dev.games.upsert(...)
+    // client.admin.rewards.createReward(...)
+    // Calling a method without sufficient token permissions will result in a server error.
+
+    // Example: Listen for auth changes (e.g., if token is refreshed or cleared by logout)
+    client.onAuthChange(token => {
+        console.log('Authentication token changed:', token)
+        // You might want to update stored token here
+    })
+
+    // Example: Logout
+    // await client.auth.logout();
+}
+
+initializeAndUseClient()
+```
+
+## Quickstart: Mini-Game Example
+
+```ts
+import { initFromWindow } from '@playcademy/sdk'
+
+async function runGame() {
+    const client = await initFromWindow()
+
+    try {
+        // 1) Start a game session (gameId is optional, defaults to client.gameId)
+        const { sessionId } = await client.games.startSession()
+        console.log('Session started:', sessionId)
+
+        // 2) Fetch player's inventory/rewards
+        const rewards = await client.users.inventory.get()
+        console.log('Player inventory:', rewards)
+
+        // 3) Save game state (uses client.gameId implicitly)
+        await client.games.saveState({
+            currentLevel: 'level_2', // This is separate from progress, often more transient
+            health: 95,
+        })
+        console.log('Game state saved')
+
+        // 4) Load game state (uses client.gameId implicitly)
+        const loadedState = await client.games.loadState()
+        console.log('Game state loaded:', loadedState)
+
+        // 5) End the session when finished (gameId is optional)
+        await client.games.endSession(sessionId)
+        console.log('Session ended')
+
+        // 6) Exit the game view (if embedded)
+        client.runtime.exit()
+    } catch (error) {
+        console.error('An error occurred:', error)
+    }
+}
+
+runGame()
+```
+
+## API Modules
+
+The `PlaycademyClient` instance provides access to all API modules.
+The server will determine if the provided token has sufficient permissions for each operation.
+Internal event handling uses a `BusEvents` enum for type safety.
+All methods returning data are strongly typed.
+
+- **`auth`**: User logout. For login, use the static `PlaycademyClient.login()` method.
+    - `logout()`: Logs out the current user and clears the token from the client instance.
+- **`onAuthChange(callback)`**: A top-level client method to subscribe to authentication token changes (login, logout, explicit `setToken`).
+- **`users`**:
+    - `me()`: Fetch current user details.
+    - **`inventory`**:
+        - `get()`: Get player inventory.
+        - `add(rewardId, qty)`: Add item to player inventory.
+        - `spend(rewardId, qty)`: Spend item from player inventory.
+    - **`progress`**: Manages persistent progress data for a game (e.g., levels completed, scores, collectibles).
+        - `get(gameId?)`: Get the entire progress state for a game. `gameId` is optional and defaults to the client's current game context.
+        - `update(data, gameId?)`: Update the progress state for a game. `gameId` is optional. The `data` object can be structured to hold progress for various internal nodes or aspects of the game.
+- **`games`**: Manages game sessions and transient game state.
+    - `fetch(gameIdOrSlug)`: Fetch game details with manifest.
+    - `list()`: List all games.
+    - `saveState(state)`: Save transient game state (e.g., current position, temporary buffs) for the current game context.
+    - `loadState()`: Load transient game state for the current game context.
+    - `startSession(gameId?)`: Start a game session. `gameId` is optional and defaults to `client.gameId` if set. If the client is managing an automatic session, this can be used to start additional, distinct sessions.
+    - `endSession(sessionId, gameId?)`: End a game session. `gameId` is optional. If this ends an automatically managed session, the client will no longer attempt to auto-end it.
+- **`runtime`**:
+    - `getGameToken(gameId, options?: { apply?: boolean })`: Fetches a game-specific token. If `options.apply` is true, it sets this token as the active token on the client instance (default is false).
+    - `exit()`: Signals the hosting environment to close the game view. If the client is managing an automatic session (because `gameId` was provided at construction), this method will attempt to end that session before signaling exit.
+- **`maps`**:
+    - `elements(mapId)`: Fetch elements (like nodes, points of interest) for a specific map.
+- **`dev.auth`**: Apply for developer status, get status.
+- **`dev.games`**: Upsert, update, delete games.
+- **`dev.keys`**: Create, list, revoke API keys for games.
+- **`admin.games`**: Pause/resume games.
+- **`admin.rewards`**: CRUD operations for rewards.
+- **`telemetry`**: Push metrics.
+
+## Contributing
+
+PRs welcome. Fork, build, test, send a PR.
+
+## License
+
+MIT

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, type GameWithManifest, type UpsertGameMetadataInput, type InsertReward, type UpdateReward } from '@playcademy/data/schemas';
+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;
+            name: string;
+            username: string | null;
+            email: string;
+            emailVerified: boolean;
+            image: string | null;
+            role: "admin" | "player" | "developer";
+            developerStatus: "none" | "pending" | "approved";
+            createdAt: Date;
+            updatedAt: Date;
+        }>;
+        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;
+            mapId: string | null;
+            elementSlug: string;
+            interactionType: "game_entry" | "game_registry" | "info" | "teleport" | "door_in" | "door_out" | "npc_interaction" | "quest_trigger";
+            metadata: ({
+                description?: string | undefined;
+                sourceTiledObjects?: Record<string, unknown>[] | undefined;
+            } & {
+                [k: string]: unknown;
+            }) | null;
+            gameId: string | null;
+        }[]>;
+    };
+    admin: {
+        games: {
+            pauseGame: (gameId: string) => Promise<void>;
+            resumeGame: (gameId: string) => Promise<void>;
+        };
+        rewards: {
+            createReward: (props: InsertReward) => Promise<{
+                id: string;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                displayName: string;
+                description: string | null;
+                metadata: unknown;
+                internalName: string;
+            }>;
+            getReward: (rewardId: string) => Promise<{
+                id: string;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                displayName: string;
+                description: string | null;
+                metadata: unknown;
+                internalName: string;
+            }>;
+            listRewards: () => Promise<{
+                id: string;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                displayName: string;
+                description: string | null;
+                metadata: unknown;
+                internalName: string;
+            }[]>;
+            updateReward: (rewardId: string, props: UpdateReward) => Promise<{
+                id: string;
+                type: "currency" | "badge" | "trophy" | "unlock" | "upgrade" | "other";
+                displayName: string;
+                description: string | null;
+                metadata: unknown;
+                internalName: string;
+            }>;
+            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/data/schemas';
+/** 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,370 @@
+// 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
+import { ManifestV1Schema } from "@playcademy/data/schemas";
+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}`);
+    }
+    const manifestJson = await response.json();
+    const validationResult = ManifestV1Schema.safeParse(manifestJson);
+    if (!validationResult.success) {
+      console.error(`[fetchManifest] Invalid manifest file at ${manifestUrl}: `, validationResult.error.flatten());
+      throw new PlaycademyError("Invalid manifest file format");
+    }
+    return validationResult.data;
+  } 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/data/schemas';
+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

@@ -0,0 +1,37 @@
+{
+    "name": "@playcademy/sdk",
+    "type": "module",
+    "version": "0.0.1-beta.1",
+    "exports": {
+        ".": {
+            "import": "./dist/runtime.js",
+            "require": "./dist/runtime.js",
+            "types": "./dist/runtime.d.ts"
+        },
+        "./types": {
+            "import": "./src/types.ts",
+            "require": "./src/types.ts",
+            "types": "./src/types.d.ts"
+        }
+    },
+    "main": "dist/runtime.js",
+    "module": "dist/runtime.js",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "bun build.js",
+        "pub": "bun run build && bunx bumpp --no-tag --no-push && bun publish --access public"
+    },
+    "dependencies": {
+        "@playcademy/data": "0.0.1"
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.0.0",
+        "yocto-spinner": "^0.2.1"
+    },
+    "peerDependencies": {
+        "typescript": "^5"
+    }
+}