@timeback/sdk 0.1.6 → 0.1.7

package/dist/server/adapters/tanstack-start.js

@@ -434,12 +434,32 @@ async function getUserInfo(params) {
   return response.json();
 }
 // src/server/lib/utils.ts
+function safeIdSegment(value) {
+  return encodeURIComponent(value).replace(/%/g, "_");
+}
+function hashSuffix64Base36(value) {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mod64 = 0xffffffffffffffffn;
+  for (let i = 0;i < value.length; i++) {
+    hash ^= BigInt(value.charCodeAt(i));
+    hash = hash * prime & mod64;
+  }
+  const base36 = hash.toString(36);
+  return base36.length > 12 ? base36.slice(-12) : base36;
+}
 function mapEnvForApi(env) {
   if (env === "local" || env === "staging") {
     return "staging";
   }
   return "production";
 }
+function normalizeEnv(env) {
+  if (env === "production" || env === "local" || env === "staging") {
+    return env;
+  }
+  return "staging";
+}
 function jsonResponse(data, status = 200, headers) {
   const responseHeaders = new Headers(headers);
   responseHeaders.set("Content-Type", "application/json");
@@ -15739,14 +15759,20 @@ var TimebackConfig = exports_external.object({
   message: "Duplicate courseCode found; each must be unique",
   path: ["courses"]
 }).refine((config2) => {
-  return config2.courses.every((c) => c.sensor !== undefined || config2.sensor !== undefined);
-}, {
-  message: "Each course must have an effective sensor; set a top-level `sensor` or per-course `sensor`",
-  path: ["courses"]
-}).refine((config2) => {
-  return config2.courses.every((c) => c.launchUrl !== undefined || config2.launchUrl !== undefined);
+  return config2.courses.every((c) => {
+    if (c.sensor !== undefined || config2.sensor !== undefined) {
+      return true;
+    }
+    const launchUrls = [
+      c.launchUrl,
+      config2.launchUrl,
+      c.overrides?.staging?.launchUrl,
+      c.overrides?.production?.launchUrl
+    ].filter(Boolean);
+    return launchUrls.length > 0;
+  });
 }, {
-  message: "Each course must have an effective launchUrl; set a top-level `launchUrl` or per-course `launchUrl`",
+  message: "Each course must have an effective sensor. Either set `sensor` explicitly (top-level or per-course), or provide a `launchUrl` so sensor can be derived from its origin.",
   path: ["courses"]
 });
 var EdubridgeDateString = exports_external.union([IsoDateString, IsoDateTimeString]);
@@ -32142,14 +32168,20 @@ var TimebackConfig2 = exports_external2.object({
   message: "Duplicate courseCode found; each must be unique",
   path: ["courses"]
 }).refine((config22) => {
-  return config22.courses.every((c) => c.sensor !== undefined || config22.sensor !== undefined);
-}, {
-  message: "Each course must have an effective sensor; set a top-level `sensor` or per-course `sensor`",
-  path: ["courses"]
-}).refine((config22) => {
-  return config22.courses.every((c) => c.launchUrl !== undefined || config22.launchUrl !== undefined);
+  return config22.courses.every((c) => {
+    if (c.sensor !== undefined || config22.sensor !== undefined) {
+      return true;
+    }
+    const launchUrls = [
+      c.launchUrl,
+      config22.launchUrl,
+      c.overrides?.staging?.launchUrl,
+      c.overrides?.production?.launchUrl
+    ].filter(Boolean);
+    return launchUrls.length > 0;
+  });
 }, {
-  message: "Each course must have an effective launchUrl; set a top-level `launchUrl` or per-course `launchUrl`",
+  message: "Each course must have an effective sensor. Either set `sensor` explicitly (top-level or per-course), or provide a `launchUrl` so sensor can be derived from its origin.",
   path: ["courses"]
 });
 var EdubridgeDateString2 = exports_external2.union([IsoDateString2, IsoDateTimeString2]);
@@ -49575,14 +49607,20 @@ var TimebackConfig3 = exports_external3.object({
   message: "Duplicate courseCode found; each must be unique",
   path: ["courses"]
 }).refine((config22) => {
-  return config22.courses.every((c) => c.sensor !== undefined || config22.sensor !== undefined);
-}, {
-  message: "Each course must have an effective sensor; set a top-level `sensor` or per-course `sensor`",
-  path: ["courses"]
-}).refine((config22) => {
-  return config22.courses.every((c) => c.launchUrl !== undefined || config22.launchUrl !== undefined);
+  return config22.courses.every((c) => {
+    if (c.sensor !== undefined || config22.sensor !== undefined) {
+      return true;
+    }
+    const launchUrls = [
+      c.launchUrl,
+      config22.launchUrl,
+      c.overrides?.staging?.launchUrl,
+      c.overrides?.production?.launchUrl
+    ].filter(Boolean);
+    return launchUrls.length > 0;
+  });
 }, {
-  message: "Each course must have an effective launchUrl; set a top-level `launchUrl` or per-course `launchUrl`",
+  message: "Each course must have an effective sensor. Either set `sensor` explicitly (top-level or per-course), or provide a `launchUrl` so sensor can be derived from its origin.",
   path: ["courses"]
 });
 var EdubridgeDateString3 = exports_external3.union([IsoDateString3, IsoDateTimeString3]);
@@ -67207,14 +67245,20 @@ var TimebackConfig4 = exports_external4.object({
   message: "Duplicate courseCode found; each must be unique",
   path: ["courses"]
 }).refine((config22) => {
-  return config22.courses.every((c) => c.sensor !== undefined || config22.sensor !== undefined);
-}, {
-  message: "Each course must have an effective sensor; set a top-level `sensor` or per-course `sensor`",
-  path: ["courses"]
-}).refine((config22) => {
-  return config22.courses.every((c) => c.launchUrl !== undefined || config22.launchUrl !== undefined);
+  return config22.courses.every((c) => {
+    if (c.sensor !== undefined || config22.sensor !== undefined) {
+      return true;
+    }
+    const launchUrls = [
+      c.launchUrl,
+      config22.launchUrl,
+      c.overrides?.staging?.launchUrl,
+      c.overrides?.production?.launchUrl
+    ].filter(Boolean);
+    return launchUrls.length > 0;
+  });
 }, {
-  message: "Each course must have an effective launchUrl; set a top-level `launchUrl` or per-course `launchUrl`",
+  message: "Each course must have an effective sensor. Either set `sensor` explicitly (top-level or per-course), or provide a `launchUrl` so sensor can be derived from its origin.",
   path: ["courses"]
 });
 var EdubridgeDateString4 = exports_external4.union([IsoDateString4, IsoDateTimeString4]);
@@ -83869,14 +83913,20 @@ var TimebackConfig5 = exports_external5.object({
   message: "Duplicate courseCode found; each must be unique",
   path: ["courses"]
 }).refine((config22) => {
-  return config22.courses.every((c) => c.sensor !== undefined || config22.sensor !== undefined);
-}, {
-  message: "Each course must have an effective sensor; set a top-level `sensor` or per-course `sensor`",
-  path: ["courses"]
-}).refine((config22) => {
-  return config22.courses.every((c) => c.launchUrl !== undefined || config22.launchUrl !== undefined);
+  return config22.courses.every((c) => {
+    if (c.sensor !== undefined || config22.sensor !== undefined) {
+      return true;
+    }
+    const launchUrls = [
+      c.launchUrl,
+      config22.launchUrl,
+      c.overrides?.staging?.launchUrl,
+      c.overrides?.production?.launchUrl
+    ].filter(Boolean);
+    return launchUrls.length > 0;
+  });
 }, {
-  message: "Each course must have an effective launchUrl; set a top-level `launchUrl` or per-course `launchUrl`",
+  message: "Each course must have an effective sensor. Either set `sensor` explicitly (top-level or per-course), or provide a `launchUrl` so sensor can be derived from its origin.",
   path: ["courses"]
 });
 var EdubridgeDateString5 = exports_external5.union([IsoDateString5, IsoDateTimeString5]);
@@ -85634,163 +85684,6 @@ async function lookupTimebackIdByEmail(params) {
     throw new TimebackUserResolutionError(`Failed to lookup Timeback user: ${message}`, "timeback_user_lookup_failed");
   }
 }
-
-class ActivityCourseResolutionError extends Error {
-  code;
-  selector;
-  count;
-  constructor(code, selector, count) {
-    super(code);
-    this.code = code;
-    this.selector = selector;
-    this.count = count;
-  }
-  get selectorDescription() {
-    if ("grade" in this.selector) {
-      return `${this.selector.subject} grade ${this.selector.grade}`;
-    }
-    return `code "${this.selector.code}"`;
-  }
-}
-function resolveActivityCourse(courses, courseRef) {
-  let matches;
-  if ("grade" in courseRef) {
-    matches = courses.filter((c) => c.subject === courseRef.subject && c.grade === courseRef.grade);
-  } else {
-    matches = courses.filter((c) => c.courseCode === courseRef.code);
-  }
-  if (matches.length === 0) {
-    throw new ActivityCourseResolutionError("unknown_course", courseRef);
-  }
-  if (matches.length > 1) {
-    throw new ActivityCourseResolutionError("ambiguous_course", courseRef, matches.length);
-  }
-  return matches[0];
-}
-// src/server/lib/build-activity-events.ts
-class MissingSyncedCourseIdError extends Error {
-  course;
-  env;
-  constructor(course, env) {
-    const identifier = course.grade === undefined ? course.courseCode ?? course.subject : `${course.subject} grade ${course.grade}`;
-    super(`Course "${identifier}" is missing a synced ID for ${env}. Run \`timeback sync\` first.`);
-    this.name = "MissingSyncedCourseIdError";
-    this.course = course;
-    this.env = env;
-  }
-}
-function buildCourseId(course, apiEnv) {
-  const courseId = course.ids?.[apiEnv];
-  if (!courseId) {
-    throw new MissingSyncedCourseIdError(course, apiEnv);
-  }
-  return courseId;
-}
-function buildCourseName(course) {
-  if (course.courseCode) {
-    return course.courseCode;
-  }
-  if (course.grade !== undefined) {
-    return `${course.subject} G${String(course.grade)}`;
-  }
-  return course.subject;
-}
-
-class InvalidSensorUrlError extends Error {
-  sensor;
-  constructor(sensor) {
-    super(`Invalid sensor URL "${sensor}". Sensor must be a valid absolute URL (e.g., "https://sensor.example.com") to support slug-based activity IDs.`);
-    this.name = "InvalidSensorUrlError";
-    this.sensor = sensor;
-  }
-}
-function buildCanonicalActivityUrl(sensor, selector, slug) {
-  let base;
-  try {
-    base = new URL(sensor);
-  } catch {
-    throw new InvalidSensorUrlError(sensor);
-  }
-  const pathSegment = "grade" in selector ? `${selector.subject}/g${String(selector.grade)}` : selector.code;
-  const basePath = base.pathname.replace(/\/+$/, "");
-  base.pathname = `${basePath}/activities/${pathSegment}/${encodeURIComponent(slug)}`;
-  return base.toString();
-}
-function buildActivityContext(payload, course, appName, apiEnv, sensor) {
-  return {
-    id: buildCanonicalActivityUrl(sensor, payload.course, payload.id),
-    type: "TimebackActivityContext",
-    subject: course.subject,
-    app: { name: appName },
-    activity: { name: payload.name },
-    course: {
-      id: buildCourseId(course, apiEnv),
-      name: buildCourseName(course)
-    }
-  };
-}
-function buildActivityMetrics(metrics) {
-  const result = [];
-  if (metrics.totalQuestions !== undefined) {
-    result.push({ type: "totalQuestions", value: metrics.totalQuestions });
-  }
-  if (metrics.correctQuestions !== undefined) {
-    result.push({ type: "correctQuestions", value: metrics.correctQuestions });
-  }
-  if (metrics.xpEarned !== undefined) {
-    result.push({ type: "xpEarned", value: metrics.xpEarned });
-  }
-  if (metrics.masteredUnits !== undefined) {
-    result.push({ type: "masteredUnits", value: metrics.masteredUnits });
-  }
-  return result;
-}
-function buildTimeSpentMetrics(elapsedMs, pausedMs) {
-  const result = [{ type: "active", value: Math.max(0, elapsedMs) / 1000 }];
-  if (pausedMs > 0) {
-    result.push({ type: "inactive", value: Math.max(0, pausedMs) / 1000 });
-  }
-  return result;
-}
-async function sendCaliperEnvelope(client, sensor, activityEvent, timeSpentEvent) {
-  await client.caliper.events.send(sensor, [activityEvent, timeSpentEvent]);
-}
-// src/server/lib/build-user-profile.ts
-function buildCourseLookup(courses, apiEnv) {
-  const courseById = new Map;
-  for (const course of courses) {
-    const courseId = course.ids?.[apiEnv];
-    if (courseId) {
-      courseById.set(courseId, course);
-    }
-  }
-  return courseById;
-}
-function mapEnrollmentsToCourses(enrollments, courseById) {
-  return enrollments.map((enrollment) => {
-    const configuredCourse = courseById.get(enrollment.course.id);
-    return {
-      id: enrollment.course.id,
-      code: configuredCourse?.courseCode ?? enrollment.course.id,
-      name: enrollment.course.title
-    };
-  });
-}
-function pickGoalsFromEnrollments(enrollments) {
-  return enrollments.map((enrollment) => enrollment.metadata?.goals).find(Boolean);
-}
-function getUtcDayRange(date6) {
-  const start = new Date(Date.UTC(date6.getUTCFullYear(), date6.getUTCMonth(), date6.getUTCDate()));
-  const end = new Date(Date.UTC(date6.getUTCFullYear(), date6.getUTCMonth(), date6.getUTCDate(), 23, 59, 59, 999));
-  return { start, end };
-}
-function sumXp(facts) {
-  return Object.values(facts).reduce((dateTotal, subjects) => {
-    return dateTotal + Object.values(subjects).reduce((subjectTotal, metrics) => {
-      return subjectTotal + (metrics.activityMetrics?.xpEarned ?? 0);
-    }, 0);
-  }, 0);
-}
 // src/shared/constants.ts
 var ROUTES = {
   ACTIVITY: "/activity",
@@ -85800,10 +85693,83 @@ var ROUTES = {
     CALLBACK: "/identity/callback"
   },
   USER: {
-    ME: "/user/me"
+    ME: "/user/me",
+    VERIFY: "/user/verify"
   }
 };
 
+// src/server/lib/sso.ts
+function buildErrorContext(error57, errorCode, state, req) {
+  return {
+    error: error57,
+    errorCode,
+    state,
+    req,
+    redirect: redirectResponse,
+    json: jsonResponse
+  };
+}
+function tryDecodeState(stateParam) {
+  try {
+    return decodeBase64Url(stateParam);
+  } catch {
+    ssoLog.warn("Failed to decode state");
+    return;
+  }
+}
+function handleIdpError(errorParam, url6, state, req, onCallbackError) {
+  const errorDesc = url6.searchParams.get("error_description");
+  ssoLog.error("IdP returned error", { error: errorParam, description: errorDesc });
+  const error57 = new Error(errorDesc ?? errorParam);
+  if (onCallbackError) {
+    return onCallbackError(buildErrorContext(error57, errorParam, state, req));
+  }
+  return jsonResponse({ error: errorParam }, 400);
+}
+function handleMissingCode(state, req, onCallbackError) {
+  ssoLog.error("Missing authorization code in callback");
+  const error57 = new Error("Missing authorization code");
+  if (onCallbackError) {
+    return onCallbackError(buildErrorContext(error57, "missing_code", state, req));
+  }
+  return jsonResponse({ error: "Missing authorization code" }, 400);
+}
+async function initiateSignIn(params) {
+  const { req, env, clientId, buildState } = params;
+  const issuer = params.issuer ?? getIssuer(env);
+  const url6 = new URL(req.url);
+  let redirectUri = params.redirectUri;
+  if (!redirectUri) {
+    const basePath = url6.pathname.replace(ROUTES.IDENTITY.SIGNIN, "");
+    redirectUri = `${url6.origin}${basePath}${ROUTES.IDENTITY.CALLBACK}`;
+  }
+  ssoLog.debug("SSO sign-in initiated", { env, issuer, clientId, redirectUri });
+  const stateData = buildState ? buildState({ req, url: url6 }) : {};
+  const state = encodeBase64Url(stateData);
+  const authUrl = await buildAuthorizationUrl({
+    issuer,
+    clientId,
+    redirectUri,
+    state
+  });
+  return redirectResponse(authUrl);
+}
+function parseCallback(req) {
+  const url6 = new URL(req.url);
+  const code = url6.searchParams.get("code");
+  const errorParam = url6.searchParams.get("error");
+  const stateParam = url6.searchParams.get("state");
+  ssoLog.debug("Received callback from IdP", { hasCode: !!code, error: errorParam });
+  const state = stateParam ? tryDecodeState(stateParam) : undefined;
+  return { url: url6, code, errorParam, state };
+}
+function computeRedirectUri(url6, configuredRedirectUri) {
+  if (configuredRedirectUri) {
+    return configuredRedirectUri;
+  }
+  const basePath = url6.pathname.replace(ROUTES.IDENTITY.CALLBACK, "");
+  return `${url6.origin}${basePath}${ROUTES.IDENTITY.CALLBACK}`;
+}
 // src/server/adapters/utils.ts
 function normalizePathname(path) {
   const raw = path.trim();
@@ -85853,6 +85819,8 @@ function matchTimebackRoute(params) {
         return "identity.signOut";
       if (relative === ROUTES.USER.ME)
         return "user.me";
+      if (relative === ROUTES.USER.VERIFY)
+        return "user.verify";
     }
     if (method === "POST") {
       if (relative === ROUTES.ACTIVITY)
@@ -85878,6 +85846,8 @@ function matchTimebackRoute(params) {
       return "identity.signOut";
     if (pathname.endsWith(ROUTES.USER.ME))
       return "user.me";
+    if (pathname.endsWith(ROUTES.USER.VERIFY))
+      return "user.verify";
   }
   if (method === "POST") {
     if (pathname.endsWith(ROUTES.ACTIVITY))
@@ -85918,6 +85888,11 @@ function toTanStackStartHandler(input) {
         return jsonResponse({ error: "Not found" }, 404);
       return handle.user.me(event.request);
     }
+    if (route === "user.verify") {
+      if (!hasUserHandler(handle))
+        return jsonResponse({ error: "Not found" }, 404);
+      return handle.user.verify(event.request);
+    }
     if (route === "activity") {
       if (!hasActivityHandler(handle))
         return jsonResponse({ error: "Not found" }, 404);

package/dist/server/adapters/utils.d.ts

@@ -12,7 +12,7 @@ type AnyHandlers = Handlers | IdentityOnlyHandlers;
 /**
  * A canonical route identifier for Timeback's built-in endpoints.
  */
-type TimebackRouteId = 'identity.signIn' | 'identity.callback' | 'identity.signOut' | 'user.me' | 'activity';
+type TimebackRouteId = 'identity.signIn' | 'identity.callback' | 'identity.signOut' | 'user.me' | 'user.verify' | 'activity';
 /**
  * Normalize a path-like string to a pathname only (no query string).
  *

package/dist/server/adapters/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;GAEG;AACH,KAAK,WAAW,GAAG,QAAQ,GAAG,oBAAoB,CAAA;AAElD;;GAEG;AACH,KAAK,eAAe,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,kBAAkB,GAClB,SAAS,GACT,UAAU,CAAA;AAEb;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBtD;AA8BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,eAAe,GAAG,IAAI,CAsDzB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE1E"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;GAEG;AACH,KAAK,WAAW,GAAG,QAAQ,GAAG,oBAAoB,CAAA;AAElD;;GAEG;AACH,KAAK,eAAe,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,kBAAkB,GAClB,SAAS,GACT,aAAa,GACb,UAAU,CAAA;AAEb;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBtD;AA8BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,eAAe,GAAG,IAAI,CAwDzB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,QAAQ,CAE1E"}

package/dist/server/{lib/build-activity-events.d.ts → handlers/activity/caliper.d.ts}

@@ -1,7 +1,13 @@
 import type { ActivityCompletedEvent, TimebackActivityContext, TimebackActivityMetric, TimeSpentEvent, TimeSpentMetric } from '@timeback/caliper';
 import type { TimebackClient } from '@timeback/core';
-import type { ActivityEndPayload, ActivityMetrics } from '../../shared/types';
-import type { AppConfig } from '../types';
+import type { ActivityCourseRef, ActivityMetrics } from '../../../shared/types';
+import type { ActivityBeforeSendData, AppConfig } from '../../types';
+import type { ValidatedActivityPayload } from './types';
+/**
+ * Activity Caliper Events
+ *
+ * Build and send Caliper events for activity submissions.
+ */
 /**
  * Error thrown when a course is missing a synced ID for the target environment.
  */
@@ -39,7 +45,11 @@ export declare class InvalidSensorUrlError extends Error {
  * @param sensor - Sensor URL for building the canonical activity URL
  * @returns Caliper activity context payload
  */
-export declare function buildActivityContext(payload: ActivityEndPayload, course: AppConfig['courses'][number], appName: string, apiEnv: 'staging' | 'production', sensor: string): TimebackActivityContext;
+export declare function buildActivityContext(payload: {
+    id: string;
+    name: string;
+    course: ActivityCourseRef;
+}, course: AppConfig['courses'][number], appName: string, apiEnv: 'staging' | 'production', sensor: string): TimebackActivityContext;
 /**
  * Build Caliper activity metrics from the client payload.
  *
@@ -55,6 +65,21 @@ export declare function buildActivityMetrics(metrics: ActivityMetrics): Timeback
  * @returns Normalized Caliper time spent metrics
  */
 export declare function buildTimeSpentMetrics(elapsedMs: number, pausedMs: number): TimeSpentMetric[];
+/**
+ * Build Caliper events for an activity.
+ *
+ * @param params - Event building parameters
+ * @returns Built events and context
+ */
+export declare function buildActivityEvents(params: {
+    sensor: string;
+    timebackId: string;
+    email: string;
+    payload: ValidatedActivityPayload;
+    course: AppConfig['courses'][number];
+    appName: string;
+    apiEnv: 'staging' | 'production';
+}): ActivityBeforeSendData;
 /**
  * Send a batch of Caliper events as a single envelope.
  *
@@ -64,4 +89,4 @@ export declare function buildTimeSpentMetrics(elapsedMs: number, pausedMs: numbe
  * @param timeSpentEvent - TimeSpentEvent payload
  */
 export declare function sendCaliperEnvelope(client: TimebackClient, sensor: string, activityEvent: ActivityCompletedEvent, timeSpentEvent: TimeSpentEvent): Promise<void>;
-//# sourceMappingURL=build-activity-events.d.ts.map
+//# sourceMappingURL=caliper.d.ts.map

package/dist/server/handlers/activity/caliper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caliper.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/activity/caliper.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EAEtB,cAAc,EACd,eAAe,EACf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAEvD;;;;GAIG;AAMH;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;IAC7C,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,YAAY,CAAA;IAEtC,YAAY,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,YAAY,EAW9E;CACD;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB,YAAY,MAAM,EAAE,MAAM,EAMzB;CACD;AAiHD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,EAChE,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,GAAG,YAAY,EAChC,MAAM,EAAE,MAAM,GACZ,uBAAuB,CAmBzB;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,sBAAsB,EAAE,CAoBvF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAQ5F;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,wBAAwB,CAAA;IACjC,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;CAChC,GAAG,sBAAsB,CA4CzB;AAMD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,sBAAsB,EACrC,cAAc,EAAE,cAAc,GAC5B,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/server/handlers/activity/gradebook.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Activity Gradebook (OneRoster)
+ *
+ * Write assessment line items and results for activity submissions.
+ *
+ * Attempt semantics:
+ * - `attempt` is the primary identity (1-based) stored in `metadata.attempt`
+ * - Results are written via PUT upsert using a deterministic `sourcedId`
+ * - Retry detection: if `payload.endedAt` matches an existing result's `scoreDate` (and `metadata.endedAt`),
+ *   the same attempt number is reused to make retries idempotent
+ * - New attempt: if no matching `endedAt` is found, attempt is `max(existingAttempt) + 1`
+ *
+ * Concurrency note:
+ * - Two concurrent "new attempts" for the same (lineItem, student) can race.
+ * - We avoid silent overwrites by including `endedAt` in the result `sourcedId` so two distinct submissions
+ *   never share an identifier even if they compute the same attempt number.
+ */
+import type { TimebackClient } from '@timeback/core';
+import type { ValidatedActivityPayload } from './types';
+/**
+ * Resolve the attempt number for a gradebook result.
+ *
+ * - If an existing result has `scoreDate === endedAt` or `metadata.endedAt === endedAt`,
+ *   return its `metadata.attempt` (retry of the same attempt).
+ * - Otherwise, return `max(metadata.attempt) + 1` (new attempt).
+ *
+ * @param client - Timeback client
+ * @param lineItemId - The assessment line item sourcedId
+ * @param timebackId - The student's Timeback user sourcedId
+ * @param endedAt - The activity end timestamp from the client payload
+ * @returns The attempt number to use (1-based)
+ */
+export declare function resolveAttemptNumber(client: TimebackClient, lineItemId: string, timebackId: string, endedAt: string): Promise<number>;
+/**
+ * Write gradebook entry (assessment line item + result) for an activity.
+ *
+ * This is best-effort: if the write fails, we log and continue.
+ * Gradebook writes are only performed when both totalQuestions and correctQuestions are present.
+ *
+ * Result identity is based on attempt number:
+ * - `resultId = lineItemId:studentId:attempt-N`
+ * - Retries of the same attempt (same `endedAt`) reuse the same result ID
+ * - New attempts get an incremented attempt number
+ *
+ * @param params - Gradebook write parameters
+ */
+export declare function writeGradebookEntry(params: {
+    client: TimebackClient;
+    courseId: string;
+    activityId: string;
+    activityName: string;
+    timebackId: string;
+    payload: ValidatedActivityPayload;
+    appName: string;
+}): Promise<void>;
+//# sourceMappingURL=gradebook.d.ts.map

package/dist/server/handlers/activity/gradebook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradebook.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/activity/gradebook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAGpD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAkEvD;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACzC,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAuCjB;AAyMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,cAAc,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,wBAAwB,CAAA;IACjC,OAAO,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB"}

package/dist/server/handlers/activity/handler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Activity Handler
+ *
+ * HTTP route handler for activity submissions.
+ * Orchestrates validation, user resolution, gradebook writes, and Caliper event sending.
+ */
+import type { ActivityHandler, ActivityHandlerConfig } from './types';
+/**
+ * Create the activity POST handler.
+ *
+ * @param config - Handler configuration
+ * @returns The activity request handler
+ */
+export declare function createActivityHandler(config: ActivityHandlerConfig): ActivityHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/server/handlers/activity/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/activity/handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAoB,MAAM,SAAS,CAAA;AAmFvF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAuGpF"}

package/dist/server/handlers/activity/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Activity Handler
+ *
+ * Route handler for activity tracking and submission.
+ */
+export { createActivityHandler } from './handler';
+export { buildActivityContext, buildActivityMetrics, buildTimeSpentMetrics, InvalidSensorUrlError, MissingSyncedCourseIdError, sendCaliperEnvelope, } from './caliper';
+export type { ActivityHandler, ActivityHandlerConfig, ActivityUserInfo, ValidatedActivityPayload, ValidationResult, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/handlers/activity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/activity/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAEjD,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,GACnB,MAAM,WAAW,CAAA;AAElB,YAAY,EACX,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,GAChB,MAAM,SAAS,CAAA"}

package/dist/server/handlers/activity/resolve.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Activity Course Resolution
+ *
+ * Resolves course selectors from activity payloads to configured courses.
+ */
+import type { ActivityCourseRef } from '../../../shared/types';
+import type { AppConfig } from '../../types';
+/**
+ * Error thrown when a course selector cannot be resolved against config.
+ */
+export declare class ActivityCourseResolutionError extends Error {
+    readonly code: 'unknown_course' | 'ambiguous_course';
+    readonly selector: ActivityCourseRef;
+    readonly count?: number;
+    constructor(code: ActivityCourseResolutionError['code'], selector: ActivityCourseRef, count?: number);
+    /**
+     * Get a human-readable description of the selector.
+     *
+     * @returns Human-readable selector description
+     */
+    get selectorDescription(): string;
+}
+/**
+ * Resolve a course config entry from an activity course selector.
+ *
+ * **Use case:** Activity handler — match the client's course selector
+ * to a configured course in `timeback.config.json`.
+ *
+ * Supports two selector modes:
+ * - **subjectGrade**: Match by `(subject, grade)`
+ * - **courseCode**: Match by `courseCode`
+ *
+ * @param courses - Configured courses from `timeback.config.json`
+ * @param courseRef - Course selector from the client payload
+ * @returns Matched course config entry
+ * @throws {ActivityCourseResolutionError} When selector is unknown or ambiguous
+ */
+export declare function resolveActivityCourse(courses: AppConfig['courses'], courseRef: ActivityCourseRef): AppConfig['courses'][number];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/server/handlers/activity/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/activity/resolve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;GAEG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAAA;IACpD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IAEvB,YACC,IAAI,EAAE,6BAA6B,CAAC,MAAM,CAAC,EAC3C,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,CAAC,EAAE,MAAM,EAMd;IAED;;;;OAIG;IACH,IAAI,mBAAmB,IAAI,MAAM,CAKhC;CACD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,EAC7B,SAAS,EAAE,iBAAiB,GAC1B,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAoB9B"}