@playcademy/sdk 0.2.2 → 0.2.3

package/dist/server.d.ts

@@ -1,43 +1,292 @@
 import { SchemaInfo } from '@playcademy/cloudflare';
-import * as _playcademy_timeback_types from '@playcademy/timeback/types';
-import { CourseConfig, OrganizationConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
-export { ActivityData, ComponentConfig, ComponentResourceConfig, EndActivityPayload, OrganizationConfig, ResourceConfig, TimebackGrade, TimebackSubject } from '@playcademy/timeback/types';
 
 /**
- * Basic user information in the shape of the claims from identity providers
+ * TimeBack Enums & Literal Types
+ *
+ * Basic type definitions used throughout the TimeBack integration.
+ *
+ * @module types/timeback/types
  */
-interface UserInfo {
-    /** Unique user identifier (sub claim from JWT) */
-    sub: string;
-    /** User's email address */
-    email: string;
-    /** User's display name */
-    name: string;
-    /** Whether the email has been verified */
-    email_verified: boolean;
-    /** Optional given name (first name) */
-    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 */
+/**
+ * Valid TimeBack subject values for course configuration.
+ * These are the supported subject values for OneRoster courses.
+ */
+type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+/**
+ * Grade levels per AE OneRoster GradeEnum.
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ */
+type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+/**
+ * Valid Caliper subject values.
+ * Matches OneRoster subjects, with "None" as a Caliper-specific fallback.
+ */
+type CaliperSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
+/**
+ * OneRoster organization types.
+ */
+type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * Lesson types for PowerPath integration.
+ */
+type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
+
+/**
+ * TimeBack Configuration Types
+ *
+ * Configuration interfaces for Organization, Course, Component,
+ * Resource, and complete TimeBack setup.
+ *
+ * @module types/timeback/config
+ */
+
+/**
+ * Organization configuration for TimeBack (user input - optionals allowed)
+ */
+interface OrganizationConfig {
+    /** Display name for your organization */
+    name?: string;
+    /** Organization type */
+    type?: OrganizationType;
+    /** Unique identifier (defaults to Playcademy's org) */
+    identifier?: string;
+}
+/**
+ * Course goals for daily student targets
+ */
+interface CourseGoals {
+    /** Target XP students should earn per day */
+    dailyXp?: number;
+    /** Target lessons per day */
+    dailyLessons?: number;
+    /** Target active minutes per day */
+    dailyActiveMinutes?: number;
+    /** Target accuracy percentage */
+    dailyAccuracy?: number;
+    /** Target mastered units per day */
+    dailyMasteredUnits?: number;
+}
+/**
+ * Course metrics and totals
+ */
+interface CourseMetrics {
+    /** Total XP available in the course */
+    totalXp?: number;
+    /** Total lessons/activities in the course */
+    totalLessons?: number;
+    /** Total number of grade levels covered by this course */
+    totalGrades?: number;
+    /** The type of course (e.g. 'optional', 'hole-filling', 'base') */
+    courseType?: 'base' | 'hole-filling' | 'optional' | 'Base' | 'Hole-Filling' | 'Optional';
+    /** Indicates whether the course is supplemental content */
+    isSupplemental?: boolean;
+}
+/**
+ * Complete course metadata structure
+ */
+interface CourseMetadata {
+    /** Define the type of course and priority for the student */
+    courseType?: 'base' | 'hole-filling' | 'optional';
+    /** Boolean value to determine if a course is supplemental to a base course */
+    isSupplemental?: boolean;
+    /** Boolean value to determine if a course is custom to an individual student */
+    isCustom?: boolean;
+    /** Signals whether a course is in production with students */
+    publishStatus?: 'draft' | 'testing' | 'published' | 'deactivated';
+    /** Who to contact when issues reported with questions */
+    contactEmail?: string;
+    /** Primary app identifier */
+    primaryApp?: string;
+    /** Learning goals for students */
+    goals?: CourseGoals;
+    /** Course metrics and totals */
+    metrics?: CourseMetrics;
+    /** Vendor-specific metadata (e.g., AlphaLearn) */
     [key: string]: unknown;
 }
 /**
- * Minimal course configuration for TimeBack integration (used in user-facing config).
+ * Course configuration for TimeBack (user input)
+ */
+interface CourseConfig {
+    /** Allocated OneRoster sourcedId (set after creation) */
+    sourcedId?: string;
+    /** Course title (defaults to game name) */
+    title?: string;
+    /** Subjects (REQUIRED for TimeBack integration) */
+    subjects: TimebackSubject[];
+    /** Used when recording progress/sessions if not explicitly specified per event. */
+    defaultSubject?: TimebackSubject;
+    /** Grade levels (REQUIRED for TimeBack integration) */
+    grades: TimebackGrade[];
+    /** Short course code (optional, auto-generated) */
+    courseCode?: string;
+    /** Course level (auto-derived from grades) */
+    level?: 'Elementary' | 'Middle' | 'High' | 'AP' | string;
+    /** Grading system */
+    gradingScheme?: 'STANDARD';
+    /** Total XP available in this course (REQUIRED before setup) */
+    totalXp?: number | null;
+    /** Total masterable units in this course (REQUIRED before setup) */
+    masterableUnits?: number | null;
+    /** Custom Playcademy metadata */
+    metadata?: CourseMetadata;
+}
+/**
+ * Component configuration for TimeBack (user input)
+ */
+interface ComponentConfig {
+    /** Component title (defaults to "{course.title} Activities") */
+    title?: string;
+    /** Display order */
+    sortOrder?: number;
+    /** Required prior components */
+    prerequisites?: string[];
+    /** How prerequisites work */
+    prerequisiteCriteria?: 'ALL' | 'ANY';
+}
+/**
+ * Playcademy-specific resource extensions
+ */
+interface PlaycademyResourceMetadata {
+    /** Mastery configuration for tracking discrete learning units */
+    mastery?: {
+        /** Total number of masterable units in the resource */
+        masterableUnits: number;
+        /** Type of mastery unit for semantic clarity */
+        unitType?: 'level' | 'rank' | 'skill' | 'module';
+    };
+}
+/**
+ * Resource configuration for TimeBack (user input)
+ */
+interface ResourceConfig {
+    /** Resource title (defaults to "{course.title} Game") */
+    title?: string;
+    /** Internal resource ID (auto-generated from package.json) */
+    vendorResourceId?: string;
+    /** Vendor identifier */
+    vendorId?: string;
+    /** Application identifier */
+    applicationId?: string;
+    /** Resource roles */
+    roles?: ('primary' | 'secondary')[];
+    /** Resource importance */
+    importance?: 'primary' | 'secondary';
+    /** Interactive resource metadata */
+    metadata?: {
+        /** Resource type */
+        type?: 'interactive';
+        /** Launch URL (defaults to Playcademy game URL) */
+        launchUrl?: string;
+        /** Platform name */
+        toolProvider?: string;
+        /** Teaching method */
+        instructionalMethod?: 'exploratory' | 'direct-instruction';
+        /** Subject area */
+        subject?: TimebackSubject;
+        /** Target grades */
+        grades?: TimebackGrade[];
+        /** Content language */
+        language?: string;
+        /** Base XP for completion */
+        xp?: number;
+        /** Playcademy-specific extensions */
+        playcademy?: PlaycademyResourceMetadata;
+    };
+}
+/**
+ * Component Resource link configuration (user input)
+ */
+interface ComponentResourceConfig {
+    /** Link title (defaults to "{resource.title} Activity") */
+    title?: string;
+    /** Display order */
+    sortOrder?: number;
+    /** Lesson type for PowerPath integration */
+    lessonType?: LessonType;
+}
+interface TimebackCourseConfig {
+    subject: string;
+    grade: number;
+}
+
+/**
+ * TimeBack Client SDK DTOs
  *
- * NOTE: Per-course overrides (title, courseCode, level, metadata) are defined
- * in @playcademy/sdk/server as TimebackCourseConfigWithOverrides.
- * This base type only includes the minimal required fields.
+ * Data transfer objects for the TimeBack client SDK including
+ * progress tracking, session management, and activity completion.
  *
- * For totalXp, use metadata.metrics.totalXp (aligns with upstream TimeBack structure).
+ * Note: TimebackClientConfig lives in @playcademy/timeback as it's
+ * SDK configuration, not a DTO.
+ *
+ * @module types/timeback/client
  */
-type TimebackCourseConfig = {
-    subject: string;
+
+/**
+ * Activity data for ending an activity
+ */
+interface ActivityData {
+    /** Unique activity identifier (required) */
+    activityId: string;
+    /** Grade level for this activity (required for multi-grade course routing) */
     grade: number;
-};
-type EndActivityResponse = {
+    /** Subject area (required for multi-grade course routing) */
+    subject: CaliperSubject;
+    /** Activity display name (optional) */
+    activityName?: string;
+    /** Course identifier (auto-filled from config if not provided) */
+    courseId?: string;
+    /** Course display name (auto-filled from config if not provided) */
+    courseName?: string;
+    /** Student email address (optional) */
+    studentEmail?: string;
+    /** Application name for Caliper events (defaults to 'Game') */
+    appName?: string;
+    /** Sensor URL for Caliper events (defaults to baseUrl) */
+    sensorUrl?: string;
+}
+/**
+ * Score data for activity completion
+ */
+interface ScoreData {
+    /** Number of questions answered correctly */
+    correctQuestions: number;
+    /** Total number of questions */
+    totalQuestions: number;
+}
+/**
+ * Timing data for activity completion
+ */
+interface TimingData {
+    /** Duration of the activity in seconds */
+    durationSeconds: number;
+}
+/**
+ * Complete payload for ending an activity
+ */
+interface EndActivityPayload {
+    /** Activity metadata */
+    activityData: ActivityData;
+    /** Score information */
+    scoreData: ScoreData;
+    /** Timing information */
+    timingData: TimingData;
+    /** Explicit XP value to override automatic calculation */
+    xpEarned?: number;
+    /** Number of learning units mastered */
+    masteredUnits?: number;
+}
+
+/**
+ * TimeBack API Request/Response Types
+ *
+ * Types for TimeBack API endpoints including XP tracking,
+ * setup, verification, and activity completion.
+ *
+ * @module types/timeback/api
+ */
+
+interface EndActivityResponse {
     status: 'ok';
     courseId: string;
     xpAwarded: number;
@@ -45,7 +294,7 @@ type EndActivityResponse = {
     pctCompleteApp?: number;
     scoreStatus?: string;
     inProgress?: string;
-};
+}
 
 /**
  * @fileoverview Server SDK Type Definitions
@@ -253,6 +502,23 @@ interface BackendDeploymentBundle {
     secrets?: Record<string, string>;
 }
 
+/**
+ * OpenID Connect UserInfo claims (NOT a database row).
+ */
+interface UserInfo {
+    sub: string;
+    email: string;
+    name: string | null;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    issuer?: string;
+    lti_roles?: unknown;
+    lti_context?: unknown;
+    lti_resource_link?: unknown;
+    timeback_id?: string;
+}
+
 /**
  * Server-side Playcademy client for recording student activity to TimeBack.
  *
@@ -322,13 +588,6 @@ declare class PlaycademyClient {
      * ```
      */
     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.
@@ -357,7 +616,7 @@ declare class PlaycademyClient {
     get config(): PlaycademyServerClientState['config'];
     /** TimeBack integration methods (endActivity) */
     timeback: {
-        endActivity: (studentId: string, payload: _playcademy_timeback_types.EndActivityPayload) => Promise<EndActivityResponse>;
+        endActivity: (studentId: string, payload: EndActivityPayload) => Promise<EndActivityResponse>;
     };
 }
 
@@ -420,4 +679,4 @@ declare function verifyGameToken(gameToken: string, options?: {
 }): Promise<VerifyGameTokenResponse>;
 
 export { PlaycademyClient, verifyGameToken };
-export type { BackendDeploymentBundle, BackendResourceBindings, IntegrationsConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackIntegrationConfig, UserInfo };
+export type { ActivityData, BackendDeploymentBundle, BackendResourceBindings, ComponentConfig, ComponentResourceConfig, EndActivityPayload, IntegrationsConfig, OrganizationConfig, PlaycademyConfig, PlaycademyServerClientConfig, PlaycademyServerClientState, ResourceConfig, TimebackBaseConfig, TimebackCourseConfigWithOverrides, TimebackGrade, TimebackIntegrationConfig, TimebackSubject, UserInfo };

package/dist/server.js

@@ -27,6 +27,99 @@ function createTimebackNamespace(client) {
     }
   };
 }
+// src/core/errors.ts
+class PlaycademyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PlaycademyError";
+  }
+}
+
+class ApiError extends Error {
+  status;
+  code;
+  details;
+  rawBody;
+  constructor(status, code, message, details, rawBody) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+    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}`;
@@ -40,16 +133,19 @@ async function makeApiRequest(baseUrl, apiToken, endpoint, method = "GET", body)
   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}`);
+  const response = await fetch(url, options);
+  if (!response.ok) {
+    let errorBody;
+    try {
+      errorBody = await response.json();
+    } catch {
+      try {
+        errorBody = await response.text();
+      } catch {}
     }
-    return await response.json();
-  } catch (error) {
-    throw new Error(`Request failed: ${error instanceof Error ? error.message : String(error)}`);
+    throw ApiError.fromResponse(response.status, response.statusText, errorBody);
   }
+  return await response.json();
 }
 
 // src/server/utils/config-loader.ts