@playcademy/sdk 0.1.1 → 0.1.3

package/README.md

@@ -152,6 +152,29 @@ console.log(`Level ${userLevel.currentLevel}, ${progress.xpToNextLevel} XP to ne
 // XP updates come from TimeBack webhooks only.
 ```
 
+### TimeBack Integration
+
+Track learning activities and automatically calculate XP based on time spent and accuracy:
+
+```typescript
+// Start tracking an activity (only activityId required!)
+client.timeback.startActivity({
+    activityId: 'math-quiz-level-1',
+})
+// Auto-derived: activityName "Math Quiz Level 1"
+// Auto-filled by backend: appName, subject, sensorUrl
+
+// ... player completes activity ...
+
+// End activity and submit results (XP calculated automatically)
+await client.timeback.endActivity({
+    correctQuestions: 8,
+    totalQuestions: 10,
+})
+// XP calculation: base (1 min = 1 XP) × accuracy multiplier
+// 100%: 1.25x | 80-99%: 1.0x | 65-79%: 0.5x | <65%: 0x
+```
+
 ### Real-time Communication
 
 Open a direct, low-latency communication channel for your game, perfect for multiplayer interactions.
@@ -228,6 +251,23 @@ channel.onMessage(data => {
 - `open(channelName?)`: Opens a game-scoped WebSocket channel.
 - `token.get()`: Retrieves a JWT for the real-time service.
 
+#### **TimeBack** (`client.timeback`)
+
+- `startActivity(metadata)`: Start tracking an activity (stores start time and metadata)
+    - `metadata.activityId`: Unique activity identifier (required)
+    - `metadata.activityName`: Human-readable activity name
+    - `metadata.subject`: Subject area (Math, Reading, Science, etc.)
+    - `metadata.appName`: Application name
+    - `metadata.sensorUrl`: Sensor URL for tracking
+- `endActivity(scoreData)`: End activity and submit results
+    - `scoreData.correctQuestions`: Number of correct answers
+    - `scoreData.totalQuestions`: Total number of questions
+- **XP Query** (`client.timeback.xp`):
+    - `today(options?)`: Get today's XP (supports timezone parameter)
+    - `total()`: Get total accumulated XP
+    - `history(options?)`: Get XP history with optional date filtering
+    - `summary(options?)`: Get both today's and total XP in one call
+
 #### **Leaderboard** (`client.leaderboard`) - Game-specific
 
 - `fetch(options?)`: Get leaderboard for a specific game

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { InferSelectModel } from 'drizzle-orm';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as drizzle_zod from 'drizzle-zod';
 import { z } from 'zod';
+import * as _playcademy_timeback_types from '@playcademy/timeback/types';
 import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
 import { AUTH_PROVIDER_IDS } from '@playcademy/constants';
 
@@ -3022,7 +3023,6 @@ type XpHistoryResponse = {
         xp: number;
     }>;
 };
-type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
 type TimebackSetupRequest = {
     gameId: string;
     config: {
@@ -3106,70 +3106,7 @@ type TimebackVerifyResponse = {
     };
     errors?: string[];
 };
-type RecordProgressRequest = {
-    gameId: string;
-    studentId: string;
-    progressData: {
-        sensorUrl?: string;
-        subject?: TimebackSubject;
-        appName?: string;
-        score?: number;
-        totalQuestions?: number;
-        correctQuestions?: number;
-        xpEarned?: number;
-        masteredUnits?: number;
-        attemptNumber?: number;
-        activityId?: string;
-        activityName?: string;
-        courseId?: string;
-        classId?: string;
-        courseName?: string;
-        studentEmail?: string;
-    };
-};
-type RecordProgressResponse = {
-    status: 'ok';
-    courseId: string;
-};
-type RecordSessionEndRequest = {
-    gameId: string;
-    studentId: string;
-    sessionData: {
-        sensorUrl?: string;
-        subject?: TimebackSubject;
-        appName?: string;
-        activeTimeSeconds: number;
-        inactiveTimeSeconds?: number;
-        wasteTimeSeconds?: number;
-        activityId?: string;
-        activityName?: string;
-        courseId?: string;
-        courseName?: string;
-        studentEmail?: string;
-    };
-};
-type RecordSessionEndResponse = {
-    status: 'ok';
-    courseId: string;
-};
-type AwardXpRequest = {
-    gameId: string;
-    studentId: string;
-    xpAmount: number;
-    metadata: {
-        sensorUrl: string;
-        subject: TimebackSubject;
-        appName: string;
-        reason: string;
-        activityId?: string;
-        activityName?: string;
-        courseId?: string;
-        courseName?: string;
-        studentEmail?: string;
-        bonusType?: string;
-    };
-};
-type AwardXpResponse = {
+type EndActivityResponse = {
     status: 'ok';
     courseId: string;
     xpAwarded: number;
@@ -4077,9 +4014,10 @@ declare class PlaycademyClient {
     };
     /** TimeBack XP methods (today, total, history) */
     timeback: {
-        recordProgress: (progressData: RecordProgressRequest["progressData"]) => Promise<RecordProgressResponse>;
-        recordSessionEnd: (sessionData: RecordSessionEndRequest["sessionData"]) => Promise<RecordSessionEndResponse>;
-        awardXP: (xpAmount: number, metadata: AwardXpRequest["metadata"]) => Promise<AwardXpResponse>;
+        startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
+        pauseActivity: () => void;
+        resumeActivity: () => void;
+        endActivity: (data: _playcademy_timeback_types.EndActivityScoreData) => Promise<EndActivityResponse>;
         management: {
             setup: (request: TimebackSetupRequest) => Promise<TimebackSetupResponse>;
             verify: (gameId: string) => Promise<TimebackVerifyResponse>;

package/dist/index.js

@@ -110,10 +110,18 @@ var isBrowser = () => {
     default:
       return console.log;
   }
+}, levelPriority, getMinimumLogLevel = () => {
+  const envLevel = (process.env.LOG_LEVEL ?? "").toLowerCase();
+  if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+    return envLevel;
+  }
+  return isProduction() ? "info" : "debug";
+}, shouldLog = (level) => {
+  const minLevel = getMinimumLogLevel();
+  return levelPriority[level] >= levelPriority[minLevel];
 }, performLog = (level, message, context) => {
-  if (level === "debug" && isProduction()) {
+  if (!shouldLog(level))
     return;
-  }
   const outputFormat = detectOutputFormat();
   switch (outputFormat) {
     case "browser":
@@ -148,6 +156,12 @@ var init_src = __esm(() => {
     cyan: "\x1B[36m",
     gray: "\x1B[90m"
   };
+  levelPriority = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3
+  };
   log = createLogger();
 });
 
@@ -906,9 +920,16 @@ function checkDevWarnings(data) {
   if (!warningType)
     return;
   switch (warningType) {
-    case "timeback-disabled":
-      console.warn("%c⚠️ TimeBack Disabled in Dev", "background: #f59e0b; color: white; padding: 4px 8px; border-radius: 3px; font-weight: bold", `
-` + (response.__playcademyDevMessage || "TimeBack is disabled in local development"));
+    case "timeback-not-configured":
+      console.warn("%c⚠️ TimeBack Not Configured", "background: #f59e0b; color: white; padding: 6px 12px; border-radius: 4px; font-weight: bold; font-size: 13px");
+      console.log("%cTimeBack is configured in playcademy.config.js but the sandbox does not have TimeBack credentials.", "color: #f59e0b; font-weight: 500");
+      console.log("To test TimeBack locally:");
+      console.log("  Set the following environment variables:");
+      console.log("    • %cTIMEBACK_ONEROSTER_API_URL", "color: #0ea5e9; font-weight: 600; font-family: monospace");
+      console.log("    • %cTIMEBACK_CALIPER_API_URL", "color: #0ea5e9; font-weight: 600; font-family: monospace");
+      console.log("    • %cTIMEBACK_API_CLIENT_ID/SECRET", "color: #0ea5e9; font-weight: 600; font-family: monospace");
+      console.log("  Or deploy your game: %cplaycademy deploy", "color: #10b981; font-weight: 600; font-family: monospace");
+      console.log("  Or wait for %c@superbuilders/timeback-local%c (coming soon)", "color: #8b5cf6; font-weight: 600; font-family: monospace", "color: inherit");
       break;
     default:
       console.warn(`[Playcademy Dev Warning] ${warningType}`);
@@ -1548,9 +1569,7 @@ var init_overworld = __esm(() => {
 var TIMEBACK_ROUTES;
 var init_timeback = __esm(() => {
   TIMEBACK_ROUTES = {
-    PROGRESS: "/integrations/timeback/progress",
-    SESSION_END: "/integrations/timeback/session-end",
-    AWARD_XP: "/integrations/timeback/award-xp"
+    END_ACTIVITY: "/integrations/timeback/end-activity"
   };
 });
 
@@ -2039,18 +2058,69 @@ var init_achievements = () => {};
 
 // src/core/namespaces/timeback.ts
 function createTimebackNamespace(client) {
+  let currentActivity = null;
   return {
-    recordProgress: (progressData) => {
-      return client["requestGameBackend"](TIMEBACK_ROUTES.PROGRESS, "POST", { progressData });
+    startActivity: (metadata) => {
+      currentActivity = {
+        startTime: Date.now(),
+        metadata,
+        pausedTime: 0,
+        pauseStartTime: null
+      };
+    },
+    pauseActivity: () => {
+      if (!currentActivity) {
+        throw new Error("No activity in progress. Call startActivity() before pauseActivity().");
+      }
+      if (currentActivity.pauseStartTime !== null) {
+        throw new Error("Activity is already paused.");
+      }
+      currentActivity.pauseStartTime = Date.now();
     },
-    recordSessionEnd: (sessionData) => {
-      return client["requestGameBackend"](TIMEBACK_ROUTES.SESSION_END, "POST", { sessionData });
+    resumeActivity: () => {
+      if (!currentActivity) {
+        throw new Error("No activity in progress. Call startActivity() before resumeActivity().");
+      }
+      if (currentActivity.pauseStartTime === null) {
+        throw new Error("Activity is not paused.");
+      }
+      const pauseDuration = Date.now() - currentActivity.pauseStartTime;
+      currentActivity.pausedTime += pauseDuration;
+      currentActivity.pauseStartTime = null;
     },
-    awardXP: (xpAmount, metadata) => {
-      return client["requestGameBackend"](TIMEBACK_ROUTES.AWARD_XP, "POST", {
-        xpAmount,
-        metadata
-      });
+    endActivity: async (data) => {
+      if (!currentActivity) {
+        throw new Error("No activity in progress. Call startActivity() before endActivity().");
+      }
+      if (currentActivity.pauseStartTime !== null) {
+        const pauseDuration = Date.now() - currentActivity.pauseStartTime;
+        currentActivity.pausedTime += pauseDuration;
+        currentActivity.pauseStartTime = null;
+      }
+      const endTime = Date.now();
+      const totalElapsed = endTime - currentActivity.startTime;
+      const activeTime = totalElapsed - currentActivity.pausedTime;
+      const durationSeconds = Math.floor(activeTime / 1000);
+      const { correctQuestions, totalQuestions } = data;
+      const request2 = {
+        activityData: currentActivity.metadata,
+        scoreData: {
+          correctQuestions,
+          totalQuestions
+        },
+        timingData: {
+          durationSeconds
+        },
+        xpEarned: data.xpAwarded
+      };
+      try {
+        const response = await client["requestGameBackend"](TIMEBACK_ROUTES.END_ACTIVITY, "POST", request2);
+        currentActivity = null;
+        return response;
+      } catch (error) {
+        currentActivity = null;
+        throw error;
+      }
     },
     management: {
       setup: (request2) => {

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 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';
+export { ActivityData, ComponentConfig, ComponentResourceConfig, CourseConfig, EndActivityPayload, OrganizationConfig, ResourceConfig, TimebackGrade, TimebackSubject } from '@playcademy/timeback/types';
 
 /**
  * @fileoverview Server SDK Type Definitions
@@ -161,22 +161,14 @@ interface UserInfo {
     /** Additional user attributes from the identity provider */
     [key: string]: unknown;
 }
-type RecordProgressResponse = {
-    status: 'ok';
-    courseId: string;
-};
-type RecordSessionEndResponse = {
-    status: 'ok';
-    courseId: string;
-};
-type AwardXpResponse = {
+type EndActivityResponse = {
     status: 'ok';
     courseId: string;
     xpAwarded: number;
 };
 
 /**
- * Server-side Playcademy client for recording student progress to TimeBack.
+ * 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).
@@ -188,11 +180,12 @@ type AwardXpResponse = {
  *   apiKey: process.env.PLAYCADEMY_API_KEY
  * })
  *
- * // Record progress (metadata auto-filled from config)
- * await client.timeback.recordProgress(studentId, {
- *   score: 85,
- *   totalQuestions: 20,
- *   correctQuestions: 17
+ * // 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
  * })
  * ```
  */
@@ -276,12 +269,10 @@ declare class PlaycademyClient {
      * @returns The loaded configuration object
      */
     get config(): PlaycademyServerClientState['config'];
-    /** TimeBack integration methods (recordProgress, recordSessionEnd, awardXP) */
+    /** TimeBack integration methods (endActivity) */
     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>;
+        endActivity: (studentId: string, payload: _playcademy_timeback_types.EndActivityPayload) => Promise<EndActivityResponse>;
     };
 }
 

package/dist/server.js

@@ -27,30 +27,11 @@ function createTimebackNamespace(client) {
       throw new Error(`Failed to fetch courseId: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  function enrichProgressData(data) {
+  function enrichActivityData(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
     };
   }
@@ -58,35 +39,16 @@ function createTimebackNamespace(client) {
     get courseId() {
       return courseId;
     },
-    recordProgress: async (studentId, progressData) => {
+    endActivity: async (studentId, payload) => {
       await ensureCourseId();
-      const enrichedData = enrichProgressData(progressData);
-      return client["request"]("/api/timeback/progress", "POST", {
+      const enrichedActivityData = enrichActivityData(payload.activityData);
+      return client["request"]("/api/timeback/end-activity", "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
+        activityData: enrichedActivityData,
+        scoreData: payload.scoreData,
+        timingData: payload.timingData,
+        xpEarned: payload.xpEarned
       });
     }
   };
@@ -348,8 +310,14 @@ Please set the PLAYCADEMY_BASE_URL environment variable`);
       body: JSON.stringify({ token: gameToken })
     });
     if (!response.ok) {
-      const errorText = await response.text().catch(() => "Unknown error");
-      throw new Error(`[Playcademy SDK] Token verification failed: ${response.status} ${errorText}`);
+      let errorMessage = "Unknown error";
+      try {
+        const data = await response.json();
+        errorMessage = data.error || data.message || "Unknown error";
+      } catch {
+        errorMessage = response.statusText || "Unknown error";
+      }
+      throw new Error(`[Playcademy SDK] Token verification failed: ${response.status} ${errorMessage}`);
     }
     const result = await response.json();
     return result;

package/dist/types.d.ts

@@ -4,6 +4,7 @@ import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as drizzle_zod from 'drizzle-zod';
 import { z } from 'zod';
 import * as _playcademy_realtime_server_types from '@playcademy/realtime/server/types';
+import * as _playcademy_timeback_types from '@playcademy/timeback/types';
 import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
 
 declare const userRoleEnum: drizzle_orm_pg_core.PgEnum<["admin", "player", "developer"]>;
@@ -3706,7 +3707,6 @@ type XpHistoryResponse = {
         xp: number;
     }>;
 };
-type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None';
 type TimebackSetupRequest = {
     gameId: string;
     config: {
@@ -3790,70 +3790,7 @@ type TimebackVerifyResponse = {
     };
     errors?: string[];
 };
-type RecordProgressRequest = {
-    gameId: string;
-    studentId: string;
-    progressData: {
-        sensorUrl?: string;
-        subject?: TimebackSubject;
-        appName?: string;
-        score?: number;
-        totalQuestions?: number;
-        correctQuestions?: number;
-        xpEarned?: number;
-        masteredUnits?: number;
-        attemptNumber?: number;
-        activityId?: string;
-        activityName?: string;
-        courseId?: string;
-        classId?: string;
-        courseName?: string;
-        studentEmail?: string;
-    };
-};
-type RecordProgressResponse = {
-    status: 'ok';
-    courseId: string;
-};
-type RecordSessionEndRequest = {
-    gameId: string;
-    studentId: string;
-    sessionData: {
-        sensorUrl?: string;
-        subject?: TimebackSubject;
-        appName?: string;
-        activeTimeSeconds: number;
-        inactiveTimeSeconds?: number;
-        wasteTimeSeconds?: number;
-        activityId?: string;
-        activityName?: string;
-        courseId?: string;
-        courseName?: string;
-        studentEmail?: string;
-    };
-};
-type RecordSessionEndResponse = {
-    status: 'ok';
-    courseId: string;
-};
-type AwardXpRequest = {
-    gameId: string;
-    studentId: string;
-    xpAmount: number;
-    metadata: {
-        sensorUrl: string;
-        subject: TimebackSubject;
-        appName: string;
-        reason: string;
-        activityId?: string;
-        activityName?: string;
-        courseId?: string;
-        courseName?: string;
-        studentEmail?: string;
-        bonusType?: string;
-    };
-};
-type AwardXpResponse = {
+type EndActivityResponse = {
     status: 'ok';
     courseId: string;
     xpAwarded: number;
@@ -4765,9 +4702,10 @@ declare class PlaycademyClient {
     };
     /** TimeBack XP methods (today, total, history) */
     timeback: {
-        recordProgress: (progressData: RecordProgressRequest["progressData"]) => Promise<RecordProgressResponse>;
-        recordSessionEnd: (sessionData: RecordSessionEndRequest["sessionData"]) => Promise<RecordSessionEndResponse>;
-        awardXP: (xpAmount: number, metadata: AwardXpRequest["metadata"]) => Promise<AwardXpResponse>;
+        startActivity: (metadata: _playcademy_timeback_types.ActivityData) => void;
+        pauseActivity: () => void;
+        resumeActivity: () => void;
+        endActivity: (data: _playcademy_timeback_types.EndActivityScoreData) => Promise<EndActivityResponse>;
         management: {
             setup: (request: TimebackSetupRequest) => Promise<TimebackSetupResponse>;
             verify: (gameId: string) => Promise<TimebackVerifyResponse>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/sdk",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "type": "module",
     "exports": {
         ".": {
@@ -42,7 +42,7 @@
         "@playcademy/timeback": "0.0.1",
         "@playcademy/utils": "0.0.1",
         "@types/bun": "latest",
-        "playcademy": "0.11.2",
+        "playcademy": "0.11.4",
         "rollup": "^4.50.2",
         "rollup-plugin-dts": "^6.2.3",
         "typescript": "^5.7.2",