@playcademy/sdk 0.0.7 → 0.0.9

package/dist/server.d.ts

@@ -1,3 +1,145 @@
+import * as _playcademy_timeback_types from '@playcademy/timeback/types';
+import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
+export { ComponentConfig, ComponentResourceConfig, CourseConfig, OrganizationConfig, ProgressData, ResourceConfig, SessionData, TimebackGrade, TimebackSubject, XPAwardMetadata } from '@playcademy/timeback/types';
+
+/**
+ * @fileoverview Server SDK Type Definitions
+ *
+ * TypeScript type definitions for the server-side Playcademy SDK.
+ * Includes configuration types, client state, and re-exported TimeBack types.
+ */
+
+/**
+ * TimeBack integration configuration for Playcademy config file
+ */
+interface TimebackIntegrationConfig {
+    /** Organization overrides */
+    organization?: Partial<OrganizationConfig>;
+    /** Course configuration (subjects and grades REQUIRED) */
+    course: CourseConfig;
+    /** Component overrides */
+    component?: Partial<ComponentConfig>;
+    /** Resource overrides */
+    resource?: Partial<ResourceConfig>;
+    /** Component-Resource link overrides */
+    componentResource?: Partial<ComponentResourceConfig>;
+}
+/**
+ * Integrations configuration
+ */
+interface IntegrationsConfig {
+    /** TimeBack integration (optional) */
+    timeback?: TimebackIntegrationConfig;
+}
+/**
+ * Unified Playcademy configuration
+ * Used for playcademy.config.{js,json}
+ */
+interface PlaycademyConfig {
+    /** Game name */
+    name: string;
+    /** Game description */
+    description?: string;
+    /** Game emoji icon */
+    emoji?: string;
+    /** Build command to run before deployment */
+    buildCommand?: string[];
+    /** Path to build output */
+    buildPath?: string;
+    /** Game type */
+    gameType?: 'hosted' | 'external';
+    /** External URL (for external games) */
+    externalUrl?: string;
+    /** Game platform */
+    platform?: 'web' | 'unity' | 'godot';
+    /** Backend configuration */
+    backend?: {
+        /** Custom API routes directory (defaults to 'api') */
+        directory?: string;
+    };
+    /** External integrations */
+    integrations?: IntegrationsConfig;
+}
+
+/**
+ * Configuration options for initializing a PlaycademyClient instance.
+ *
+ * @example
+ * ```typescript
+ * const config: PlaycademyServerClientConfig = {
+ *   apiKey: process.env.PLAYCADEMY_API_KEY!,
+ *   gameId: 'my-math-game',
+ *   configPath: './playcademy.config.js'
+ * }
+ * ```
+ */
+interface PlaycademyServerClientConfig {
+    /**
+     * Playcademy API key for server-to-server authentication.
+     * Obtain from the Playcademy developer dashboard.
+     */
+    apiKey: string;
+    /**
+     * Optional path to playcademy.config.js file.
+     * If not provided, searches current directory and up to 3 parent directories.
+     * Ignored if `config` is provided directly.
+     *
+     * @example './config/playcademy.config.js'
+     */
+    configPath?: string;
+    /**
+     * Optional config object (for edge environments without filesystem).
+     * If provided, skips filesystem-based config loading.
+     *
+     * @example { name: 'My Game', integrations: { timeback: {...} } }
+     */
+    config?: PlaycademyConfig;
+    /**
+     * Optional base URL for Playcademy API.
+     * Defaults to environment variables or 'https://hub.playcademy.com'.
+     *
+     * @example 'http://localhost:3000' for local development
+     */
+    baseUrl?: string;
+    /**
+     * Optional game ID.
+     * If not provided, will attempt to fetch from API using the API token.
+     *
+     * @example 'my-math-game'
+     */
+    gameId?: string;
+}
+/**
+ * Internal state maintained by the PlaycademyClient instance.
+ *
+ * @internal
+ */
+interface PlaycademyServerClientState {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API requests */
+    baseUrl: string;
+    /** Game identifier */
+    gameId: string;
+    /** Loaded game configuration from playcademy.config.js */
+    config: PlaycademyConfig;
+    /**
+     * TimeBack course ID fetched from the Playcademy API.
+     * Used for all TimeBack event recording.
+     */
+    courseId?: string;
+}
+
+/**
+ * Backend deployment bundle for uploading to Playcademy platform
+ */
+interface BackendDeploymentBundle {
+    /** Bundled JavaScript code ready for deployment */
+    code: string;
+    /** Game configuration */
+    config: PlaycademyConfig;
+}
+
 /**
  * Basic user information in the shape of the claims from identity providers
  */
@@ -14,28 +156,183 @@ interface UserInfo {
     given_name?: string;
     /** Optional family name (last name) */
     family_name?: string;
+    /** TimeBack student ID (if user has TimeBack integration) */
+    timeback_id?: string;
     /** Additional user attributes from the identity provider */
     [key: string]: unknown;
 }
+type RecordProgressResponse = {
+    status: 'ok';
+    courseId: string;
+};
+type RecordSessionEndResponse = {
+    status: 'ok';
+    courseId: string;
+};
+type AwardXpResponse = {
+    status: 'ok';
+    courseId: string;
+    xpAwarded: number;
+};
 
 /**
- * Server-only utilities for Playcademy.
+ * Server-side Playcademy client for recording student progress to TimeBack.
+ *
+ * This client automatically loads game configuration from playcademy.config.js
+ * and uses it to auto-fill TimeBack metadata (subject, appName, courseId).
  *
- * NOTE: This module is intended for backend/server runtimes. It should not be
- * bundled into browser code. The API intentionally avoids requiring a
- * PlaycademyClient instance, offering stateless helpers for auth flows.
+ * @example
+ * ```typescript
+ * // Initialize the client (loads config automatically)
+ * const client = await PlaycademyClient.init({
+ *   apiKey: process.env.PLAYCADEMY_API_KEY
+ * })
+ *
+ * // Record progress (metadata auto-filled from config)
+ * await client.timeback.recordProgress(studentId, {
+ *   score: 85,
+ *   totalQuestions: 20,
+ *   correctQuestions: 17
+ * })
+ * ```
+ */
+declare class PlaycademyClient {
+    private state;
+    /**
+     * Private constructor. Use PlaycademyClient.init() to create instances.
+     *
+     * @param state - Internal client state
+     * @private
+     */
+    private constructor();
+    /**
+     * Initialize a new PlaycademyClient instance.
+     *
+     * Loads playcademy.config.js from the current directory (or specified path),
+     * validates the configuration, and fetches the TimeBack courseId from the API.
+     *
+     * @param config - Client configuration options
+     * @param config.apiKey - Playcademy API key for authentication
+     * @param config.gameId - Optional game ID (will be fetched from API if not provided)
+     * @param config.configPath - Optional path to playcademy.config.js (auto-discovered if not provided)
+     * @param config.baseUrl - Optional base URL for Playcademy API (defaults to production)
+     * @returns Promise resolving to initialized PlaycademyClient instance
+     * @throws {Error} If apiKey is missing or invalid
+     * @throws {Error} If config file cannot be found or loaded
+     * @throws {Error} If TimeBack integration is not set up for the game
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization with API key
+     * const client = await PlaycademyClient.init({
+     *   apiKey: process.env.PLAYCADEMY_API_KEY,
+     *   gameId: 'my-math-game'
+     * })
+     *
+     * // With custom config path
+     * const client = await PlaycademyClient.init({
+     *   apiKey: process.env.PLAYCADEMY_API_KEY,
+     *   configPath: './custom-config.js'
+     * })
+     *
+     * // With custom base URL (for development)
+     * const client = await PlaycademyClient.init({
+     *   apiKey: process.env.PLAYCADEMY_API_KEY,
+     *   baseUrl: 'http://localhost:3000'
+     * })
+     * ```
+     */
+    static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient>;
+    /**
+     * Fetch gameId from API using the API token.
+     *
+     * @private
+     * @throws {Error} Always throws - gameId fetching not yet implemented
+     * @todo Implement API endpoint to fetch gameId from API token
+     */
+    private fetchGameId;
+    /**
+     * Makes an authenticated HTTP request to the API.
+     *
+     * @param path - API endpoint path
+     * @param method - HTTP method
+     * @param body - Request body (optional)
+     * @returns Promise resolving to the response data
+     * @protected
+     */
+    protected request<T>(path: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown): Promise<T>;
+    /**
+     * Gets the current game ID.
+     *
+     * @returns The game ID
+     */
+    get gameId(): string;
+    /**
+     * Gets the loaded game configuration.
+     *
+     * Returns the configuration loaded from playcademy.config.js during
+     * client initialization.
+     *
+     * @returns The loaded configuration object
+     */
+    get config(): PlaycademyServerClientState['config'];
+    /** TimeBack integration methods (recordProgress, recordSessionEnd, awardXP) */
+    timeback: {
+        readonly courseId: string | undefined;
+        recordProgress: (studentId: string, progressData: _playcademy_timeback_types.ProgressData) => Promise<RecordProgressResponse>;
+        recordSessionEnd: (studentId: string, sessionData: _playcademy_timeback_types.SessionData) => Promise<RecordSessionEndResponse>;
+        awardXP: (studentId: string, xpAmount: number, metadata: _playcademy_timeback_types.XPAwardMetadata) => Promise<AwardXpResponse>;
+    };
+}
+
+/**
+ * @fileoverview Game Token Verification Utilities
+ *
+ * Utilities for verifying Playcademy game tokens sent from external games.
  */
 
 /**
  * Verifies a short-lived Playcademy Game Token and returns verified identity claims.
  *
- * This calls the Playcademy API to cryptographically verify the token and
- * returns the verified user information and claims.
+ * Game tokens are JWT tokens minted by Playcademy and sent to external games
+ * running in iframes. They contain verified user identity information and can
+ * be validated server-side to securely identify players.
+ *
+ * This function calls the Playcademy API's `/api/games/verify` endpoint to
+ * cryptographically verify the token and extract the user information.
+ *
+ * @param gameToken - The game JWT token string to verify
+ * @param options - Optional configuration
+ * @param options.baseUrl - Optional base URL override (defaults to env vars or production)
+ * @returns Promise resolving to verified token payload
+ * @returns claims - Arbitrary claims from the JWT payload
+ * @returns gameId - The game ID this token was issued for
+ * @returns user - Verified user information (id, email, name, etc.)
+ * @throws {Error} If gameToken is not a valid string
+ * @throws {Error} If PLAYCADEMY_BASE_URL is not set and no baseUrl provided
+ * @throws {Error} If token verification fails (invalid/expired token)
+ * @throws {Error} If network request fails
  *
- * @param gameToken - The game JWT token to verify
- * @param options - Optional configuration (reserved for future use)
- * @returns Promise containing verified claims, gameId, and user information
- * @throws Error if token is invalid or verification fails
+ * @example
+ * ```typescript
+ * // In your game server
+ * import { verifyGameToken } from '@playcademy/sdk/server'
+ *
+ * app.post('/api/auth/playcademy', async (req, res) => {
+ *   const { gameToken } = req.body
+ *
+ *   try {
+ *     const { user, gameId, claims } = await verifyGameToken(gameToken)
+ *
+ *     // Create session for the verified user
+ *     const session = await createSession(user.id)
+ *
+ *     res.json({ success: true, user, session })
+ *   } catch (error) {
+ *     res.status(401).json({ error: 'Invalid token' })
+ *   }
+ * })
+ * ```
  */
 declare function verifyGameToken(gameToken: string, options?: {
     baseUrl?: string;
@@ -44,10 +341,6 @@ declare function verifyGameToken(gameToken: string, options?: {
     gameId: string;
     user: UserInfo;
 }>;
-declare const PlaycademyServer: {
-    auth: {
-        verifyGameToken: typeof verifyGameToken;
-    };
-};
 
-export { PlaycademyServer, verifyGameToken };
+export { PlaycademyClient, verifyGameToken };
+export type { BackendDeploymentBundle, IntegrationsConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, TimebackIntegrationConfig };

package/dist/server.js

@@ -10,7 +10,326 @@ var __export = (target, all) => {
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
-// src/server.ts
+// src/server/namespaces/timeback.ts
+function createTimebackNamespace(client) {
+  let courseId;
+  async function ensureCourseId() {
+    if (courseId)
+      return courseId;
+    try {
+      const integration = await client["request"](`/api/timeback/integrations/${client.gameId}`, "GET");
+      if (!integration || !integration.courseId) {
+        throw new Error("No TimeBack integration found for this game. Please run TimeBack setup first.");
+      }
+      courseId = integration.courseId;
+      return courseId;
+    } catch (error) {
+      throw new Error(`Failed to fetch courseId: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  function enrichProgressData(data) {
+    return {
+      ...data,
+      subject: data.subject || client.config.integrations?.timeback?.course.subjects?.[0],
+      appName: data.appName || client.config.name,
+      activityName: data.activityName || client.config.name,
+      courseName: data.courseName || client.config.integrations?.timeback?.course.title
+    };
+  }
+  function enrichSessionData(data) {
+    return {
+      ...data,
+      subject: data.subject || client.config.integrations?.timeback?.course.subjects?.[0],
+      appName: data.appName || client.config.name,
+      activityName: data.activityName || client.config.name,
+      courseName: data.courseName || client.config.integrations?.timeback?.course.title
+    };
+  }
+  function enrichXPMetadata(data) {
+    return {
+      ...data,
+      subject: data.subject || client.config.integrations?.timeback?.course.subjects?.[0],
+      appName: data.appName || client.config.name,
+      activityName: data.activityName || client.config.name,
+      courseName: data.courseName || client.config.integrations?.timeback?.course.title
+    };
+  }
+  return {
+    get courseId() {
+      return courseId;
+    },
+    recordProgress: async (studentId, progressData) => {
+      await ensureCourseId();
+      const enrichedData = enrichProgressData(progressData);
+      return client["request"]("/api/timeback/progress", "POST", {
+        gameId: client.gameId,
+        studentId,
+        progressData: enrichedData
+      });
+    },
+    recordSessionEnd: async (studentId, sessionData) => {
+      await ensureCourseId();
+      const enrichedData = enrichSessionData(sessionData);
+      return client["request"]("/api/timeback/session-end", "POST", {
+        gameId: client.gameId,
+        studentId,
+        sessionData: enrichedData
+      });
+    },
+    awardXP: async (studentId, xpAmount, metadata) => {
+      await ensureCourseId();
+      if (typeof xpAmount !== "number" || xpAmount <= 0) {
+        throw new Error("[Playcademy SDK] xpAmount must be a positive number");
+      }
+      const enrichedMetadata = enrichXPMetadata(metadata);
+      return client["request"]("/api/timeback/award-xp", "POST", {
+        gameId: client.gameId,
+        studentId,
+        xpAmount,
+        metadata: enrichedMetadata
+      });
+    }
+  };
+}
+// src/server/request.ts
+async function makeApiRequest(baseUrl, apiToken, endpoint, method = "GET", body) {
+  const url = `${baseUrl}${endpoint}`;
+  const headers = new Headers;
+  headers.set("Content-Type", "application/json");
+  headers.set("x-api-key", apiToken);
+  const options = {
+    method,
+    headers
+  };
+  if (body && (method === "POST" || method === "PUT")) {
+    options.body = JSON.stringify(body);
+  }
+  try {
+    const response = await fetch(url, options);
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      throw new Error(`API request failed: ${response.status} ${errorText}`);
+    }
+    return await response.json();
+  } catch (error) {
+    throw new Error(`Request failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// src/server/utils/config-loader.ts
+import { resolve as resolve2 } from "path";
+
+// ../utils/src/file-loader.ts
+import { existsSync, readdirSync, statSync } from "fs";
+import { readFile } from "fs/promises";
+import { dirname, parse, resolve } from "path";
+function findFilePath(filename, startDir, maxLevels = 3) {
+  const filenames = Array.isArray(filename) ? filename : [filename];
+  let currentDir = resolve(startDir);
+  let levelsSearched = 0;
+  while (levelsSearched <= maxLevels) {
+    for (const fname of filenames) {
+      const filePath = resolve(currentDir, fname);
+      if (existsSync(filePath)) {
+        return {
+          path: filePath,
+          dir: currentDir,
+          filename: fname
+        };
+      }
+    }
+    if (levelsSearched >= maxLevels) {
+      break;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    const parsed = parse(currentDir);
+    if (parsed.root === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+    levelsSearched++;
+  }
+  return null;
+}
+async function loadFile(filename, options = {}) {
+  const {
+    cwd = process.cwd(),
+    required = false,
+    searchUp = false,
+    maxLevels = 3,
+    parseJson = false
+  } = options;
+  let fileResult;
+  if (searchUp) {
+    fileResult = findFilePath(filename, cwd, maxLevels);
+  } else {
+    const filenames = Array.isArray(filename) ? filename : [filename];
+    fileResult = null;
+    for (const fname of filenames) {
+      const filePath = resolve(cwd, fname);
+      if (existsSync(filePath)) {
+        fileResult = {
+          path: filePath,
+          dir: cwd,
+          filename: fname
+        };
+        break;
+      }
+    }
+  }
+  if (!fileResult) {
+    if (required) {
+      const fileList = Array.isArray(filename) ? filename.join(" or ") : filename;
+      const message = searchUp ? `${fileList} not found in ${cwd} or up to ${maxLevels} parent directories` : `${fileList} not found at ${cwd}`;
+      throw new Error(message);
+    }
+    return null;
+  }
+  try {
+    const content = await readFile(fileResult.path, "utf-8");
+    if (parseJson) {
+      return JSON.parse(content);
+    }
+    return content;
+  } catch (error) {
+    throw new Error(`Failed to load ${fileResult.filename} from ${fileResult.path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function findFile(filename, options = {}) {
+  const { cwd = process.cwd(), searchUp = false, maxLevels = 3 } = options;
+  if (searchUp) {
+    return findFilePath(filename, cwd, maxLevels);
+  }
+  const filenames = Array.isArray(filename) ? filename : [filename];
+  for (const fname of filenames) {
+    const filePath = resolve(cwd, fname);
+    if (existsSync(filePath)) {
+      return {
+        path: filePath,
+        dir: cwd,
+        filename: fname
+      };
+    }
+  }
+  return null;
+}
+
+// src/server/utils/config-loader.ts
+async function findConfigPath(configPath) {
+  if (configPath) {
+    return resolve2(configPath);
+  }
+  const result = await findFile(["playcademy.config.js", "playcademy.config.mjs", "playcademy.config.json"], {
+    searchUp: true,
+    maxLevels: 3
+  });
+  if (!result) {
+    throw new Error("playcademy.config.js not found. Please create a playcademy.config.js file or specify the config path.");
+  }
+  return result.path;
+}
+async function loadConfig(configPath) {
+  try {
+    let config;
+    let actualPath;
+    if (configPath) {
+      actualPath = resolve2(configPath);
+      if (actualPath.endsWith(".json")) {
+        config = await loadFile(actualPath, { required: true, parseJson: true });
+      } else {
+        const module = await import(actualPath);
+        config = module.default || module;
+      }
+    } else {
+      actualPath = await findConfigPath();
+      if (actualPath.endsWith(".json")) {
+        config = await loadFile(actualPath, { required: true, parseJson: true });
+      } else {
+        const module = await import(actualPath);
+        config = module.default || module;
+      }
+    }
+    if (!config || typeof config !== "object") {
+      throw new Error("Config file must export/contain an object");
+    }
+    validateConfig(config);
+    return config;
+  } catch (error) {
+    throw new Error(`Failed to load config file: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function validateConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new Error("Configuration must be an object");
+  }
+  const cfg = config;
+  if (!cfg.name || typeof cfg.name !== "string") {
+    throw new Error("Missing required field: name");
+  }
+  if (cfg.timeback) {
+    if (typeof cfg.timeback !== "object") {
+      throw new Error("timeback must be an object if provided");
+    }
+    const tb = cfg.timeback;
+    if (!tb.course) {
+      throw new Error("timeback.course is required for TimeBack integration");
+    }
+    if (typeof tb.course !== "object") {
+      throw new Error("timeback.course must be an object");
+    }
+    const course = tb.course;
+    if (!course.subjects || !Array.isArray(course.subjects) || course.subjects.length === 0) {
+      throw new Error("timeback.course.subjects is required (array of subjects)");
+    }
+    if (!course.grades || !Array.isArray(course.grades) || course.grades.length === 0) {
+      throw new Error("timeback.course.grades is required (array of grade levels)");
+    }
+  }
+}
+
+// src/server/client.ts
+class PlaycademyClient {
+  state;
+  constructor(state) {
+    this.state = state;
+  }
+  static async init(config) {
+    const { apiKey, configPath, baseUrl, gameId } = config;
+    if (!apiKey || typeof apiKey !== "string") {
+      throw new Error("[Playcademy SDK] apiKey is required");
+    }
+    const finalBaseUrl = baseUrl || process.env.PLAYCADEMY_BASE_URL || "https://hub.playcademy.com";
+    const loadedConfig = config.config || await loadConfig(configPath);
+    const state = {
+      apiKey,
+      baseUrl: finalBaseUrl,
+      gameId: gameId || "",
+      config: loadedConfig
+    };
+    const client = new PlaycademyClient(state);
+    if (!gameId) {
+      await client.fetchGameId();
+    }
+    return client;
+  }
+  async fetchGameId() {
+    throw new Error("[Playcademy SDK] gameId is required. Please provide it in the config or implement gameId fetching.");
+  }
+  async request(path, method = "GET", body) {
+    return makeApiRequest(this.state.baseUrl, this.state.apiKey, path, method, body);
+  }
+  get gameId() {
+    return this.state.gameId;
+  }
+  get config() {
+    return this.state.config;
+  }
+  timeback = createTimebackNamespace(this);
+}
+// src/server/utils/verify-game-token.ts
 async function verifyGameToken(gameToken, options) {
   if (!gameToken || typeof gameToken !== "string") {
     throw new Error("[Playcademy SDK] gameToken must be a non-empty string");
@@ -41,10 +360,7 @@ Please set the PLAYCADEMY_BASE_URL environment variable`);
     throw new Error("[Playcademy SDK] Token verification failed: Network error");
   }
 }
-var PlaycademyServer = {
-  auth: { verifyGameToken }
-};
 export {
   verifyGameToken,
-  PlaycademyServer
+  PlaycademyClient
 };