@playcademy/sdk 0.3.7-beta.1 → 0.3.7-beta.2

package/dist/server/edge.js

@@ -0,0 +1,323 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/core/guards.ts
+var VALID_GRADES = [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+var VALID_SUBJECTS = [
+  "Reading",
+  "Language",
+  "Vocabulary",
+  "Social Studies",
+  "Writing",
+  "Science",
+  "FastMath",
+  "Math",
+  "None"
+];
+function isValidGrade(value) {
+  return typeof value === "number" && Number.isInteger(value) && VALID_GRADES.includes(value);
+}
+function isValidSubject(value) {
+  return typeof value === "string" && VALID_SUBJECTS.includes(value);
+}
+// src/server/namespaces/timeback.ts
+function createTimebackNamespace(client) {
+  function enrichActivityData(data) {
+    return {
+      ...data,
+      appName: data.appName || client.config.name
+    };
+  }
+  return {
+    endActivity: async (studentId, payload) => {
+      if (!isValidGrade(payload.activityData.grade)) {
+        throw new Error("activityData.grade must be a valid grade level (-1 to 13)");
+      }
+      if (!isValidSubject(payload.activityData.subject)) {
+        throw new Error("activityData.subject must be a valid subject");
+      }
+      const enrichedActivityData = enrichActivityData(payload.activityData);
+      return client["request"]("/api/timeback/end-activity", "POST", {
+        gameId: client.gameId,
+        studentId,
+        activityData: enrichedActivityData,
+        scoreData: payload.scoreData,
+        timingData: payload.timingData,
+        xpEarned: payload.xpEarned,
+        masteredUnits: payload.masteredUnits,
+        extensions: payload.extensions
+      });
+    },
+    getStudentXp: async (studentId, options) => {
+      const hasGrade = options?.grade !== undefined;
+      const hasSubject = options?.subject !== undefined;
+      if (hasGrade !== hasSubject) {
+        throw new Error("Both grade and subject must be provided together");
+      }
+      if (hasGrade && !isValidGrade(options.grade)) {
+        throw new Error(`Invalid grade: ${options.grade}. Valid grades: ${VALID_GRADES.join(", ")}`);
+      }
+      if (hasSubject && !isValidSubject(options.subject)) {
+        throw new Error(`Invalid subject: ${options.subject}. Valid subjects: ${VALID_SUBJECTS.join(", ")}`);
+      }
+      const params = new URLSearchParams;
+      params.set("gameId", client.gameId);
+      if (options?.grade !== undefined) {
+        params.set("grade", String(options.grade));
+      }
+      if (options?.subject) {
+        params.set("subject", options.subject);
+      }
+      if (options?.include?.length) {
+        params.set("include", options.include.join(","));
+      }
+      const queryString = params.toString();
+      const endpoint = `/api/timeback/student-xp/${studentId}?${queryString}`;
+      return client["request"](endpoint, "GET");
+    }
+  };
+}
+// src/core/errors.ts
+class PlaycademyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PlaycademyError";
+  }
+}
+
+class ApiError extends Error {
+  code;
+  details;
+  rawBody;
+  status;
+  constructor(status, code, message, details, rawBody) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.rawBody = rawBody;
+    Object.setPrototypeOf(this, ApiError.prototype);
+  }
+  static fromResponse(status, statusText, body) {
+    if (body && typeof body === "object" && "error" in body) {
+      const errorBody = body;
+      const err = errorBody.error;
+      if (err && typeof err === "object") {
+        return new ApiError(status, err.code ?? statusCodeToErrorCode(status), err.message ?? statusText, err.details, body);
+      }
+    }
+    return new ApiError(status, statusCodeToErrorCode(status), statusText, undefined, body);
+  }
+  is(code) {
+    return this.code === code;
+  }
+  isClientError() {
+    return this.status >= 400 && this.status < 500;
+  }
+  isServerError() {
+    return this.status >= 500;
+  }
+  isRetryable() {
+    return this.isServerError() || this.code === "TOO_MANY_REQUESTS" || this.code === "RATE_LIMITED" || this.code === "TIMEOUT";
+  }
+}
+function statusCodeToErrorCode(status) {
+  switch (status) {
+    case 400: {
+      return "BAD_REQUEST";
+    }
+    case 401: {
+      return "UNAUTHORIZED";
+    }
+    case 403: {
+      return "FORBIDDEN";
+    }
+    case 404: {
+      return "NOT_FOUND";
+    }
+    case 405: {
+      return "METHOD_NOT_ALLOWED";
+    }
+    case 409: {
+      return "CONFLICT";
+    }
+    case 410: {
+      return "GONE";
+    }
+    case 412: {
+      return "PRECONDITION_FAILED";
+    }
+    case 413: {
+      return "PAYLOAD_TOO_LARGE";
+    }
+    case 422: {
+      return "VALIDATION_FAILED";
+    }
+    case 429: {
+      return "TOO_MANY_REQUESTS";
+    }
+    case 500: {
+      return "INTERNAL_ERROR";
+    }
+    case 501: {
+      return "NOT_IMPLEMENTED";
+    }
+    case 503: {
+      return "SERVICE_UNAVAILABLE";
+    }
+    case 504: {
+      return "TIMEOUT";
+    }
+    default: {
+      return status >= 500 ? "INTERNAL_ERROR" : "BAD_REQUEST";
+    }
+  }
+}
+function extractApiErrorInfo(error) {
+  if (!(error instanceof ApiError)) {
+    return null;
+  }
+  return {
+    status: error.status,
+    code: error.code,
+    message: error.message,
+    ...error.details !== undefined && { details: error.details }
+  };
+}
+
+// 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);
+  }
+  const response = await fetch(url, options);
+  if (!response.ok) {
+    let errorBody;
+    try {
+      errorBody = await response.json();
+    } catch {
+      try {
+        errorBody = await response.text();
+      } catch {}
+    }
+    throw ApiError.fromResponse(response.status, response.statusText, errorBody);
+  }
+  return await response.json();
+}
+
+// src/server/client-base.ts
+class PlaycademyClient {
+  state;
+  constructor(state) {
+    this.state = state;
+  }
+  static async init(config) {
+    const { apiKey, baseUrl, gameId } = config;
+    if (!apiKey || typeof apiKey !== "string") {
+      throw new Error("[Playcademy SDK] apiKey is required");
+    }
+    if (!config.config) {
+      throw new Error("[Playcademy SDK] config is required in edge environments. " + "Pass config directly, or use PlaycademyClient from @playcademy/sdk/server " + "for filesystem-based config loading.");
+    }
+    const envBaseUrl = typeof process !== "undefined" ? process.env?.PLAYCADEMY_BASE_URL : undefined;
+    const finalBaseUrl = baseUrl || envBaseUrl || "https://hub.playcademy.net";
+    const state = {
+      apiKey,
+      baseUrl: finalBaseUrl,
+      gameId: gameId || "",
+      config: config.config
+    };
+    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");
+  }
+  const baseUrl = options?.baseUrl || process.env.PLAYCADEMY_BASE_URL || process.env.PUBLIC_PLAYCADEMY_BASE_URL || process.env.NEXT_PUBLIC_PLAYCADEMY_BASE_URL;
+  if (!baseUrl) {
+    throw new Error(`[Playcademy SDK] PLAYCADEMY_BASE_URL is not set
+Please set the PLAYCADEMY_BASE_URL environment variable`);
+  }
+  try {
+    const response = await fetch(`${baseUrl}/api/games/verify`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ token: gameToken })
+    });
+    if (!response.ok) {
+      let errorMessage = "Unknown error";
+      try {
+        const data = await response.json();
+        const errorField = data.error || data.message;
+        if (typeof errorField === "string") {
+          errorMessage = errorField;
+        } else if (errorField && typeof errorField === "object") {
+          const errorObj = errorField;
+          if ("message" in errorObj && typeof errorObj.message === "string") {
+            errorMessage = errorObj.message;
+            if ("code" in errorObj && typeof errorObj.code === "string") {
+              errorMessage = `[${errorObj.code}] ${errorMessage}`;
+            }
+          } else {
+            errorMessage = JSON.stringify(errorField);
+          }
+        }
+      } catch {
+        errorMessage = response.statusText || "Unknown error";
+      }
+      throw new Error(`[Playcademy SDK] Token verification failed: ${response.status} ${errorMessage}`);
+    }
+    const result = await response.json();
+    return result;
+  } catch (error) {
+    if (error instanceof Error) {
+      throw error;
+    }
+    throw new Error("[Playcademy SDK] Token verification failed: Network error", {
+      cause: error
+    });
+  }
+}
+export {
+  verifyGameToken,
+  PlaycademyClient
+};

package/dist/server.d.ts

@@ -545,6 +545,8 @@ interface BackendDeploymentBundle {
     bindings?: BackendResourceBindings;
     /** Optional schema information for database setup */
     schema?: SchemaInfo;
+    /** Optional Cloudflare Worker compatibility flags */
+    compatibilityFlags?: string[];
 }
 
 /**
@@ -567,72 +569,39 @@ interface UserInfo {
 /**
  * Server-side Playcademy client for recording student activity to TimeBack.
  *
- * This client automatically loads game configuration from playcademy.config.js
- * and uses it to auto-fill TimeBack metadata (subject, appName, courseId).
+ * This client works in any edge runtime. Config must be provided directly
+ * via the `config` option — there is no filesystem-based config discovery.
  *
  * @example
  * ```typescript
- * // Initialize the client (loads config automatically)
  * const client = await PlaycademyClient.init({
- *   apiKey: process.env.PLAYCADEMY_API_KEY
+ *   apiKey: env.PLAYCADEMY_API_KEY,
+ *   gameId: env.GAME_ID,
+ *   config: { name: 'My Game', integrations: { timeback: {...} } }
  * })
  *
- * // End an activity (metadata auto-filled from config)
- * await client.timeback.endActivity(studentId, {
- *   activityData: { activityId: 'math-quiz-1' },
- *   scoreData: { correctQuestions: 17, totalQuestions: 20, accuracy: 0.85 },
- *   timingData: { durationSeconds: 300 },
- *   xpEarned: 5
- * })
+ * await client.timeback.endActivity(studentId, { ... })
  * ```
  */
-declare class PlaycademyClient {
+declare class PlaycademyClient$1 {
     private state;
-    /**
-     * Private constructor. Use PlaycademyClient.init() to create instances.
-     *
-     * @param state - Internal client state
-     * @private
-     */
-    private constructor();
+    protected constructor(state: PlaycademyServerClientState);
     /**
      * 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.
+     * Requires `config` to be provided directly. For automatic config file
+     * discovery from the filesystem, use `PlaycademyClient` from `@playcademy/sdk/server`.
      *
      * @param config - Client configuration options
      * @param config.apiKey - Playcademy API key for authentication
+     * @param config.config - Game configuration object (required)
      * @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'
-     * })
-     * ```
+     * @throws {Error} If config is not provided
      */
-    static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient>;
+    static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient$1>;
     private fetchGameId;
     /**
      * Makes an authenticated HTTP request to the API.
@@ -670,6 +639,52 @@ declare class PlaycademyClient {
     };
 }
 
+/**
+ * @fileoverview Server-side Playcademy Client (Node.js)
+ *
+ * Extends the edge-safe base client with filesystem-based config discovery.
+ * This is the version exported from `@playcademy/sdk/server` — it supports
+ * both explicit config and automatic `playcademy.config.js` loading from disk.
+ *
+ * For edge runtimes without filesystem access, use the base client from
+ * `./client-base` (re-exported via `./edge`).
+ */
+
+/**
+ * Server-side Playcademy client for recording student activity to TimeBack.
+ *
+ * Extends the edge-safe base with automatic playcademy.config.js loading
+ * from the filesystem. Works in Node.js and other environments with `fs` access.
+ *
+ * @example
+ * ```typescript
+ * // With automatic config discovery (Node.js only)
+ * const client = await PlaycademyClient.init({
+ *   apiKey: process.env.PLAYCADEMY_API_KEY,
+ *   gameId: 'my-math-game'
+ * })
+ *
+ * // With explicit config (works everywhere)
+ * const client = await PlaycademyClient.init({
+ *   apiKey: process.env.PLAYCADEMY_API_KEY,
+ *   gameId: 'my-math-game',
+ *   config: { name: 'My Game', integrations: { timeback: {...} } }
+ * })
+ * ```
+ */
+declare class PlaycademyClient extends PlaycademyClient$1 {
+    /**
+     * Initialize a new PlaycademyClient instance.
+     *
+     * If `config` is not provided, loads playcademy.config.js from the current
+     * directory (or specified path). This filesystem access requires Node.js.
+     *
+     * @param config - Client configuration options
+     * @returns Promise resolving to initialized PlaycademyClient instance
+     */
+    static init(config: PlaycademyServerClientConfig): Promise<PlaycademyClient>;
+}
+
 /**
  * @fileoverview Game Token Verification Utilities
  *