@timeback/core 0.1.3 → 0.1.4

package/dist/index.js

@@ -699,7 +699,17 @@ class TimebackProvider {
 }
 function getEnv(key) {
   try {
-    return typeof process === "undefined" ? undefined : process.env[key];
+    if (typeof process === "undefined")
+      return;
+    if (typeof key === "string") {
+      return process.env[key];
+    }
+    for (const k of key) {
+      const value = process.env[k];
+      if (value !== undefined)
+        return value;
+    }
+    return;
   } catch {
     return;
   }
@@ -730,6 +740,18 @@ var DEFAULT_PROVIDER_REGISTRY = {
     }
   }
 };
+function primaryEnvVar(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (key.length === 0) {
+    throw new Error(`Missing env var key: ${key}`);
+  }
+  return key[0];
+}
+function formatEnvVarKey(key) {
+  return primaryEnvVar(key);
+}
 function validateEnv(env) {
   if (env !== "staging" && env !== "production") {
     throw new Error(`Invalid env "${env}": must be "staging" or "production"`);
@@ -740,10 +762,10 @@ function validateAuth(auth, envVars) {
   const clientId = auth?.clientId ?? getEnv(envVars.clientId);
   const clientSecret = auth?.clientSecret ?? getEnv(envVars.clientSecret);
   if (!clientId) {
-    throw new Error(`Missing clientId: provide in config or set ${envVars.clientId}`);
+    throw new Error(`Missing clientId: provide in config or set ${formatEnvVarKey(envVars.clientId)}`);
   }
   if (!clientSecret) {
-    throw new Error(`Missing clientSecret: provide in config or set ${envVars.clientSecret}`);
+    throw new Error(`Missing clientSecret: provide in config or set ${formatEnvVarKey(envVars.clientSecret)}`);
   }
   return { clientId, clientSecret };
 }
@@ -759,21 +781,21 @@ function buildMissingEnvError(envVars) {
   const clientId = getEnv(envVars.clientId);
   const clientSecret = getEnv(envVars.clientSecret);
   if (baseUrl === undefined && clientId === undefined) {
-    const hint = envVars.env ?? envVars.baseUrl;
+    const hint = formatEnvVarKey(envVars.env ?? envVars.baseUrl);
     return `Missing env: provide in config or set ${hint}`;
   }
   const missing = [];
   if (baseUrl === undefined) {
-    missing.push(envVars.env ?? envVars.baseUrl);
+    missing.push(formatEnvVarKey(envVars.env ?? envVars.baseUrl));
   }
   if (baseUrl !== undefined && authUrl === undefined) {
-    missing.push(envVars.authUrl);
+    missing.push(formatEnvVarKey(envVars.authUrl));
   }
   if (clientId === undefined) {
-    missing.push(envVars.clientId);
+    missing.push(formatEnvVarKey(envVars.clientId));
   }
   if (clientSecret === undefined) {
-    missing.push(envVars.clientSecret);
+    missing.push(formatEnvVarKey(envVars.clientSecret));
   }
   return `Missing environment variables: ${missing.join(", ")}`;
 }
@@ -1473,10 +1495,10 @@ function validateOffsetListParams(params) {
   }
 }
 var CALIPER_ENV_VARS = {
-  baseUrl: "CALIPER_BASE_URL",
-  authUrl: "CALIPER_TOKEN_URL",
-  clientId: "CALIPER_CLIENT_ID",
-  clientSecret: "CALIPER_CLIENT_SECRET"
+  baseUrl: ["TIMEBACK_API_BASE_URL", "TIMEBACK_BASE_URL", "CALIPER_BASE_URL"],
+  authUrl: ["TIMEBACK_API_AUTH_URL", "TIMEBACK_AUTH_URL", "CALIPER_TOKEN_URL"],
+  clientId: ["TIMEBACK_API_CLIENT_ID", "TIMEBACK_CLIENT_ID", "CALIPER_CLIENT_ID"],
+  clientSecret: ["TIMEBACK_API_CLIENT_SECRET", "TIMEBACK_CLIENT_SECRET", "CALIPER_CLIENT_SECRET"]
 };
 var CALIPER_DATA_VERSION = "http://purl.imsglobal.org/ctx/caliper/v1p2";
 function resolveToProvider2(config, registry = DEFAULT_PROVIDER_REGISTRY) {
@@ -3725,7 +3747,7 @@ class Doc {
 var version = {
   major: 4,
   minor: 3,
-  patch: 5
+  patch: 6
 };
 var $ZodType = /* @__PURE__ */ $constructor("$ZodType", (inst, def) => {
   var _a;
@@ -5009,7 +5031,7 @@ var $ZodRecord = /* @__PURE__ */ $constructor("$ZodRecord", (inst, def) => {
         if (keyResult instanceof Promise) {
           throw new Error("Async schemas not supported in object keys currently");
         }
-        const checkNumericKey = typeof key === "string" && number.test(key) && keyResult.issues.length && keyResult.issues.some((iss) => iss.code === "invalid_type" && iss.expected === "number");
+        const checkNumericKey = typeof key === "string" && number.test(key) && keyResult.issues.length;
         if (checkNumericKey) {
           const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
           if (retryResult instanceof Promise) {
@@ -12326,7 +12348,7 @@ function finalize(ctx, schema) {
           }
         }
       }
-      if (refSchema.$ref) {
+      if (refSchema.$ref && refSeen.def) {
         for (const key in schema2) {
           if (key === "$ref" || key === "allOf")
             continue;
@@ -14958,7 +14980,7 @@ var TimebackSubject = exports_external.enum([
   "Math",
   "None",
   "Other"
-]);
+]).meta({ id: "TimebackSubject", description: "Subject area" });
 var TimebackGrade = exports_external.union([
   exports_external.literal(-1),
   exports_external.literal(0),
@@ -14975,7 +14997,10 @@ var TimebackGrade = exports_external.union([
   exports_external.literal(11),
   exports_external.literal(12),
   exports_external.literal(13)
-]);
+]).meta({
+  id: "TimebackGrade",
+  description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+});
 var ScoreStatus = exports_external.enum([
   "exempt",
   "fully graded",
@@ -15205,62 +15230,84 @@ var CaliperListEventsParams = exports_external.object({
   actorEmail: exports_external.email().optional()
 }).strict();
 var CourseIds = exports_external.object({
-  staging: exports_external.string().optional(),
-  production: exports_external.string().optional()
-});
-var CourseType = exports_external.enum(["base", "hole-filling", "optional"]);
-var PublishStatus = exports_external.enum(["draft", "testing", "published", "deactivated"]);
+  staging: exports_external.string().meta({ description: "Course ID in staging environment" }).optional(),
+  production: exports_external.string().meta({ description: "Course ID in production environment" }).optional()
+}).meta({ id: "CourseIds", description: "Environment-specific course IDs (populated by sync)" });
+var CourseType = exports_external.enum(["base", "hole-filling", "optional"]).meta({ id: "CourseType", description: "Course classification type" });
+var PublishStatus = exports_external.enum(["draft", "testing", "published", "deactivated"]).meta({ id: "PublishStatus", description: "Course publication status" });
 var CourseGoals = exports_external.object({
-  dailyXp: exports_external.number().int().positive().optional(),
-  dailyLessons: exports_external.number().int().positive().optional(),
-  dailyActiveMinutes: exports_external.number().int().positive().optional(),
-  dailyAccuracy: exports_external.number().int().min(0).max(100).optional(),
-  dailyMasteredUnits: exports_external.number().int().positive().optional()
-});
+  dailyXp: exports_external.number().int().positive().meta({ description: "Target XP to earn per day" }).optional(),
+  dailyLessons: exports_external.number().int().positive().meta({ description: "Target lessons to complete per day" }).optional(),
+  dailyActiveMinutes: exports_external.number().int().positive().meta({ description: "Target active learning minutes per day" }).optional(),
+  dailyAccuracy: exports_external.number().int().min(0).max(100).meta({ description: "Target accuracy percentage (0-100)" }).optional(),
+  dailyMasteredUnits: exports_external.number().int().positive().meta({ description: "Target units to master per day" }).optional()
+}).meta({ id: "CourseGoals", description: "Daily learning goals for a course" });
 var CourseMetrics = exports_external.object({
-  totalXp: exports_external.number().int().positive().optional(),
-  totalLessons: exports_external.number().int().positive().optional(),
-  totalGrades: exports_external.number().int().positive().optional()
-});
+  totalXp: exports_external.number().int().positive().meta({ description: "Total XP available in the course" }).optional(),
+  totalLessons: exports_external.number().int().positive().meta({ description: "Total number of lessons/activities" }).optional(),
+  totalGrades: exports_external.number().int().positive().meta({ description: "Total grade levels covered" }).optional()
+}).meta({ id: "CourseMetrics", description: "Aggregate metrics for a course" });
 var CourseMetadata = exports_external.object({
   courseType: CourseType.optional(),
-  isSupplemental: exports_external.boolean().optional(),
-  isCustom: exports_external.boolean().optional(),
+  isSupplemental: exports_external.boolean().meta({ description: "Whether this is supplemental to a base course" }).optional(),
+  isCustom: exports_external.boolean().meta({ description: "Whether this is a custom course for an individual student" }).optional(),
   publishStatus: PublishStatus.optional(),
-  contactEmail: exports_external.email().optional(),
-  primaryApp: exports_external.string().optional(),
+  contactEmail: exports_external.email().meta({ description: "Contact email for course issues" }).optional(),
+  primaryApp: exports_external.string().meta({ description: "Primary application identifier" }).optional(),
   goals: CourseGoals.optional(),
   metrics: CourseMetrics.optional()
-});
+}).meta({ id: "CourseMetadata", description: "Course metadata (matches API metadata object)" });
 var CourseDefaults = exports_external.object({
-  courseCode: exports_external.string().optional(),
-  level: exports_external.string().optional(),
+  courseCode: exports_external.string().meta({ description: "Course code (e.g., 'MATH101')" }).optional(),
+  level: exports_external.string().meta({ description: "Course level (e.g., 'AP', 'Honors')" }).optional(),
   metadata: CourseMetadata.optional()
+}).meta({
+  id: "CourseDefaults",
+  description: "Default properties that apply to all courses unless overridden"
 });
 var CourseEnvOverrides = exports_external.object({
-  level: exports_external.string().optional(),
-  sensor: exports_external.string().url().optional(),
-  launchUrl: exports_external.string().url().optional(),
+  level: exports_external.string().meta({ description: "Course level for this environment" }).optional(),
+  sensor: exports_external.url().meta({ description: "Caliper sensor endpoint URL for this environment" }).optional(),
+  launchUrl: exports_external.url().meta({ description: "LTI launch URL for this environment" }).optional(),
   metadata: CourseMetadata.optional()
+}).meta({
+  id: "CourseEnvOverrides",
+  description: "Environment-specific course overrides (non-identity fields)"
 });
 var CourseOverrides = exports_external.object({
-  staging: CourseEnvOverrides.optional(),
-  production: CourseEnvOverrides.optional()
-});
+  staging: CourseEnvOverrides.meta({
+    description: "Overrides for staging environment"
+  }).optional(),
+  production: CourseEnvOverrides.meta({
+    description: "Overrides for production environment"
+  }).optional()
+}).meta({ id: "CourseOverrides", description: "Per-environment course overrides" });
 var CourseConfig = CourseDefaults.extend({
-  subject: TimebackSubject,
-  grade: TimebackGrade.optional(),
+  subject: TimebackSubject.meta({ description: "Subject area for this course" }),
+  grade: TimebackGrade.meta({
+    description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+  }).optional(),
   ids: CourseIds.nullable().optional(),
-  sensor: exports_external.string().url().optional(),
-  launchUrl: exports_external.string().url().optional(),
+  sensor: exports_external.url().meta({ description: "Caliper sensor endpoint URL for this course" }).optional(),
+  launchUrl: exports_external.url().meta({ description: "LTI launch URL for this course" }).optional(),
   overrides: CourseOverrides.optional()
+}).meta({
+  id: "CourseConfig",
+  description: "Configuration for a single course. Must have either grade or courseCode (or both)."
 });
 var TimebackConfig = exports_external.object({
-  name: exports_external.string().min(1, "App name is required"),
-  defaults: CourseDefaults.optional(),
-  courses: exports_external.array(CourseConfig).min(1, "At least one course is required"),
-  sensor: exports_external.string().url().optional(),
-  launchUrl: exports_external.string().url().optional()
+  $schema: exports_external.string().meta({ description: "JSON Schema reference for editor support" }).optional(),
+  name: exports_external.string().min(1, "App name is required").meta({ description: "Display name for your app" }),
+  defaults: CourseDefaults.meta({
+    description: "Default properties applied to all courses"
+  }).optional(),
+  courses: exports_external.array(CourseConfig).min(1, "At least one course is required").meta({ description: "Courses available in this app" }),
+  sensor: exports_external.url().meta({ description: "Default Caliper sensor endpoint URL for all courses" }).optional(),
+  launchUrl: exports_external.url().meta({ description: "Default LTI launch URL for all courses" }).optional()
+}).meta({
+  id: "TimebackConfig",
+  title: "Timeback Config",
+  description: "Configuration schema for timeback.config.json files"
 }).refine((config2) => {
   return config2.courses.every((c) => c.grade !== undefined || c.courseCode !== undefined);
 }, {
@@ -15281,17 +15328,23 @@ 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]);
+var EdubridgeDateString = IsoDateTimeString;
 var EduBridgeEnrollment = exports_external.object({
   id: exports_external.string(),
   role: exports_external.string(),
@@ -15355,12 +15408,9 @@ var EmailOrStudentId = exports_external.object({
 });
 var SubjectTrackInput = exports_external.object({
   subject: NonEmptyString,
-  gradeLevel: NonEmptyString,
-  targetCourseId: NonEmptyString,
-  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
-});
-var SubjectTrackUpsertInput = SubjectTrackInput.extend({
-  id: NonEmptyString
+  grade: NonEmptyString,
+  courseId: NonEmptyString,
+  orgSourcedId: NonEmptyString.optional()
 });
 var EdubridgeListEnrollmentsParams = exports_external.object({
   userId: NonEmptyString
@@ -17244,7 +17294,17 @@ class TimebackProvider2 {
 }
 function getEnv2(key) {
   try {
-    return typeof process === "undefined" ? undefined : process.env[key];
+    if (typeof process === "undefined")
+      return;
+    if (typeof key === "string") {
+      return process.env[key];
+    }
+    for (const k of key) {
+      const value = process.env[k];
+      if (value !== undefined)
+        return value;
+    }
+    return;
   } catch {
     return;
   }
@@ -17275,6 +17335,18 @@ var DEFAULT_PROVIDER_REGISTRY2 = {
     }
   }
 };
+function primaryEnvVar2(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (key.length === 0) {
+    throw new Error(`Missing env var key: ${key}`);
+  }
+  return key[0];
+}
+function formatEnvVarKey2(key) {
+  return primaryEnvVar2(key);
+}
 function validateEnv2(env) {
   if (env !== "staging" && env !== "production") {
     throw new Error(`Invalid env "${env}": must be "staging" or "production"`);
@@ -17285,10 +17357,10 @@ function validateAuth2(auth, envVars) {
   const clientId = auth?.clientId ?? getEnv2(envVars.clientId);
   const clientSecret = auth?.clientSecret ?? getEnv2(envVars.clientSecret);
   if (!clientId) {
-    throw new Error(`Missing clientId: provide in config or set ${envVars.clientId}`);
+    throw new Error(`Missing clientId: provide in config or set ${formatEnvVarKey2(envVars.clientId)}`);
   }
   if (!clientSecret) {
-    throw new Error(`Missing clientSecret: provide in config or set ${envVars.clientSecret}`);
+    throw new Error(`Missing clientSecret: provide in config or set ${formatEnvVarKey2(envVars.clientSecret)}`);
   }
   return { clientId, clientSecret };
 }
@@ -17304,21 +17376,21 @@ function buildMissingEnvError2(envVars) {
   const clientId = getEnv2(envVars.clientId);
   const clientSecret = getEnv2(envVars.clientSecret);
   if (baseUrl === undefined && clientId === undefined) {
-    const hint = envVars.env ?? envVars.baseUrl;
+    const hint = formatEnvVarKey2(envVars.env ?? envVars.baseUrl);
     return `Missing env: provide in config or set ${hint}`;
   }
   const missing = [];
   if (baseUrl === undefined) {
-    missing.push(envVars.env ?? envVars.baseUrl);
+    missing.push(formatEnvVarKey2(envVars.env ?? envVars.baseUrl));
   }
   if (baseUrl !== undefined && authUrl === undefined) {
-    missing.push(envVars.authUrl);
+    missing.push(formatEnvVarKey2(envVars.authUrl));
   }
   if (clientId === undefined) {
-    missing.push(envVars.clientId);
+    missing.push(formatEnvVarKey2(envVars.clientId));
   }
   if (clientSecret === undefined) {
-    missing.push(envVars.clientSecret);
+    missing.push(formatEnvVarKey2(envVars.clientSecret));
   }
   return `Missing environment variables: ${missing.join(", ")}`;
 }
@@ -17809,10 +17881,10 @@ function validateNonEmptyString2(value, name) {
   }
 }
 var EDUBRIDGE_ENV_VARS = {
-  baseUrl: "EDUBRIDGE_BASE_URL",
-  clientId: "EDUBRIDGE_CLIENT_ID",
-  clientSecret: "EDUBRIDGE_CLIENT_SECRET",
-  authUrl: "EDUBRIDGE_TOKEN_URL"
+  baseUrl: ["TIMEBACK_API_BASE_URL", "TIMEBACK_BASE_URL", "EDUBRIDGE_BASE_URL"],
+  clientId: ["TIMEBACK_API_CLIENT_ID", "TIMEBACK_CLIENT_ID", "EDUBRIDGE_CLIENT_ID"],
+  clientSecret: ["TIMEBACK_API_CLIENT_SECRET", "TIMEBACK_CLIENT_SECRET", "EDUBRIDGE_CLIENT_SECRET"],
+  authUrl: ["TIMEBACK_API_AUTH_URL", "TIMEBACK_AUTH_URL", "EDUBRIDGE_TOKEN_URL"]
 };
 function resolveToProvider22(config2, registry2 = DEFAULT_PROVIDER_REGISTRY2) {
   return resolveToProvider3(config2, EDUBRIDGE_ENV_VARS, registry2);
@@ -20140,7 +20212,7 @@ class Doc2 {
 var version2 = {
   major: 4,
   minor: 3,
-  patch: 5
+  patch: 6
 };
 var $ZodType2 = /* @__PURE__ */ $constructor2("$ZodType", (inst, def) => {
   var _a2;
@@ -21424,7 +21496,7 @@ var $ZodRecord2 = /* @__PURE__ */ $constructor2("$ZodRecord", (inst, def) => {
         if (keyResult instanceof Promise) {
           throw new Error("Async schemas not supported in object keys currently");
         }
-        const checkNumericKey = typeof key === "string" && number4.test(key) && keyResult.issues.length && keyResult.issues.some((iss) => iss.code === "invalid_type" && iss.expected === "number");
+        const checkNumericKey = typeof key === "string" && number4.test(key) && keyResult.issues.length;
         if (checkNumericKey) {
           const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
           if (retryResult instanceof Promise) {
@@ -28741,7 +28813,7 @@ function finalize2(ctx, schema) {
           }
         }
       }
-      if (refSchema.$ref) {
+      if (refSchema.$ref && refSeen.def) {
         for (const key in schema2) {
           if (key === "$ref" || key === "allOf")
             continue;
@@ -31373,7 +31445,7 @@ var TimebackSubject2 = exports_external2.enum([
   "Math",
   "None",
   "Other"
-]);
+]).meta({ id: "TimebackSubject", description: "Subject area" });
 var TimebackGrade2 = exports_external2.union([
   exports_external2.literal(-1),
   exports_external2.literal(0),
@@ -31390,7 +31462,10 @@ var TimebackGrade2 = exports_external2.union([
   exports_external2.literal(11),
   exports_external2.literal(12),
   exports_external2.literal(13)
-]);
+]).meta({
+  id: "TimebackGrade",
+  description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+});
 var ScoreStatus2 = exports_external2.enum([
   "exempt",
   "fully graded",
@@ -31620,62 +31695,84 @@ var CaliperListEventsParams2 = exports_external2.object({
   actorEmail: exports_external2.email().optional()
 }).strict();
 var CourseIds2 = exports_external2.object({
-  staging: exports_external2.string().optional(),
-  production: exports_external2.string().optional()
-});
-var CourseType2 = exports_external2.enum(["base", "hole-filling", "optional"]);
-var PublishStatus2 = exports_external2.enum(["draft", "testing", "published", "deactivated"]);
+  staging: exports_external2.string().meta({ description: "Course ID in staging environment" }).optional(),
+  production: exports_external2.string().meta({ description: "Course ID in production environment" }).optional()
+}).meta({ id: "CourseIds", description: "Environment-specific course IDs (populated by sync)" });
+var CourseType2 = exports_external2.enum(["base", "hole-filling", "optional"]).meta({ id: "CourseType", description: "Course classification type" });
+var PublishStatus2 = exports_external2.enum(["draft", "testing", "published", "deactivated"]).meta({ id: "PublishStatus", description: "Course publication status" });
 var CourseGoals2 = exports_external2.object({
-  dailyXp: exports_external2.number().int().positive().optional(),
-  dailyLessons: exports_external2.number().int().positive().optional(),
-  dailyActiveMinutes: exports_external2.number().int().positive().optional(),
-  dailyAccuracy: exports_external2.number().int().min(0).max(100).optional(),
-  dailyMasteredUnits: exports_external2.number().int().positive().optional()
-});
+  dailyXp: exports_external2.number().int().positive().meta({ description: "Target XP to earn per day" }).optional(),
+  dailyLessons: exports_external2.number().int().positive().meta({ description: "Target lessons to complete per day" }).optional(),
+  dailyActiveMinutes: exports_external2.number().int().positive().meta({ description: "Target active learning minutes per day" }).optional(),
+  dailyAccuracy: exports_external2.number().int().min(0).max(100).meta({ description: "Target accuracy percentage (0-100)" }).optional(),
+  dailyMasteredUnits: exports_external2.number().int().positive().meta({ description: "Target units to master per day" }).optional()
+}).meta({ id: "CourseGoals", description: "Daily learning goals for a course" });
 var CourseMetrics2 = exports_external2.object({
-  totalXp: exports_external2.number().int().positive().optional(),
-  totalLessons: exports_external2.number().int().positive().optional(),
-  totalGrades: exports_external2.number().int().positive().optional()
-});
+  totalXp: exports_external2.number().int().positive().meta({ description: "Total XP available in the course" }).optional(),
+  totalLessons: exports_external2.number().int().positive().meta({ description: "Total number of lessons/activities" }).optional(),
+  totalGrades: exports_external2.number().int().positive().meta({ description: "Total grade levels covered" }).optional()
+}).meta({ id: "CourseMetrics", description: "Aggregate metrics for a course" });
 var CourseMetadata2 = exports_external2.object({
   courseType: CourseType2.optional(),
-  isSupplemental: exports_external2.boolean().optional(),
-  isCustom: exports_external2.boolean().optional(),
+  isSupplemental: exports_external2.boolean().meta({ description: "Whether this is supplemental to a base course" }).optional(),
+  isCustom: exports_external2.boolean().meta({ description: "Whether this is a custom course for an individual student" }).optional(),
   publishStatus: PublishStatus2.optional(),
-  contactEmail: exports_external2.email().optional(),
-  primaryApp: exports_external2.string().optional(),
+  contactEmail: exports_external2.email().meta({ description: "Contact email for course issues" }).optional(),
+  primaryApp: exports_external2.string().meta({ description: "Primary application identifier" }).optional(),
   goals: CourseGoals2.optional(),
   metrics: CourseMetrics2.optional()
-});
+}).meta({ id: "CourseMetadata", description: "Course metadata (matches API metadata object)" });
 var CourseDefaults2 = exports_external2.object({
-  courseCode: exports_external2.string().optional(),
-  level: exports_external2.string().optional(),
+  courseCode: exports_external2.string().meta({ description: "Course code (e.g., 'MATH101')" }).optional(),
+  level: exports_external2.string().meta({ description: "Course level (e.g., 'AP', 'Honors')" }).optional(),
   metadata: CourseMetadata2.optional()
+}).meta({
+  id: "CourseDefaults",
+  description: "Default properties that apply to all courses unless overridden"
 });
 var CourseEnvOverrides2 = exports_external2.object({
-  level: exports_external2.string().optional(),
-  sensor: exports_external2.string().url().optional(),
-  launchUrl: exports_external2.string().url().optional(),
+  level: exports_external2.string().meta({ description: "Course level for this environment" }).optional(),
+  sensor: exports_external2.url().meta({ description: "Caliper sensor endpoint URL for this environment" }).optional(),
+  launchUrl: exports_external2.url().meta({ description: "LTI launch URL for this environment" }).optional(),
   metadata: CourseMetadata2.optional()
+}).meta({
+  id: "CourseEnvOverrides",
+  description: "Environment-specific course overrides (non-identity fields)"
 });
 var CourseOverrides2 = exports_external2.object({
-  staging: CourseEnvOverrides2.optional(),
-  production: CourseEnvOverrides2.optional()
-});
+  staging: CourseEnvOverrides2.meta({
+    description: "Overrides for staging environment"
+  }).optional(),
+  production: CourseEnvOverrides2.meta({
+    description: "Overrides for production environment"
+  }).optional()
+}).meta({ id: "CourseOverrides", description: "Per-environment course overrides" });
 var CourseConfig2 = CourseDefaults2.extend({
-  subject: TimebackSubject2,
-  grade: TimebackGrade2.optional(),
+  subject: TimebackSubject2.meta({ description: "Subject area for this course" }),
+  grade: TimebackGrade2.meta({
+    description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+  }).optional(),
   ids: CourseIds2.nullable().optional(),
-  sensor: exports_external2.string().url().optional(),
-  launchUrl: exports_external2.string().url().optional(),
+  sensor: exports_external2.url().meta({ description: "Caliper sensor endpoint URL for this course" }).optional(),
+  launchUrl: exports_external2.url().meta({ description: "LTI launch URL for this course" }).optional(),
   overrides: CourseOverrides2.optional()
+}).meta({
+  id: "CourseConfig",
+  description: "Configuration for a single course. Must have either grade or courseCode (or both)."
 });
 var TimebackConfig2 = exports_external2.object({
-  name: exports_external2.string().min(1, "App name is required"),
-  defaults: CourseDefaults2.optional(),
-  courses: exports_external2.array(CourseConfig2).min(1, "At least one course is required"),
-  sensor: exports_external2.string().url().optional(),
-  launchUrl: exports_external2.string().url().optional()
+  $schema: exports_external2.string().meta({ description: "JSON Schema reference for editor support" }).optional(),
+  name: exports_external2.string().min(1, "App name is required").meta({ description: "Display name for your app" }),
+  defaults: CourseDefaults2.meta({
+    description: "Default properties applied to all courses"
+  }).optional(),
+  courses: exports_external2.array(CourseConfig2).min(1, "At least one course is required").meta({ description: "Courses available in this app" }),
+  sensor: exports_external2.url().meta({ description: "Default Caliper sensor endpoint URL for all courses" }).optional(),
+  launchUrl: exports_external2.url().meta({ description: "Default LTI launch URL for all courses" }).optional()
+}).meta({
+  id: "TimebackConfig",
+  title: "Timeback Config",
+  description: "Configuration schema for timeback.config.json files"
 }).refine((config22) => {
   return config22.courses.every((c) => c.grade !== undefined || c.courseCode !== undefined);
 }, {
@@ -31696,17 +31793,23 @@ 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]);
+var EdubridgeDateString2 = IsoDateTimeString2;
 var EduBridgeEnrollment2 = exports_external2.object({
   id: exports_external2.string(),
   role: exports_external2.string(),
@@ -31770,13 +31873,11 @@ var EmailOrStudentId2 = exports_external2.object({
 });
 var SubjectTrackInput2 = exports_external2.object({
   subject: NonEmptyString4,
-  gradeLevel: NonEmptyString4,
-  targetCourseId: NonEmptyString4,
-  metadata: exports_external2.record(exports_external2.string(), exports_external2.unknown()).optional()
-});
-var SubjectTrackUpsertInput2 = SubjectTrackInput2.extend({
-  id: NonEmptyString4
+  grade: NonEmptyString4,
+  courseId: NonEmptyString4,
+  orgSourcedId: NonEmptyString4.optional()
 });
+var SubjectTrackUpsertInput = SubjectTrackInput2;
 var EdubridgeListEnrollmentsParams2 = exports_external2.object({
   userId: NonEmptyString4
 });
@@ -32834,7 +32935,7 @@ class SubjectTrackResource {
     return response.subjectTrack;
   }
   async upsert(data) {
-    validateWithSchema2(SubjectTrackUpsertInput2, data, "subject track");
+    validateWithSchema2(SubjectTrackUpsertInput, data, "subject track");
     const response = await this.transport.request(`${this.transport.paths.base}/subject-track/`, { method: "PUT", body: data });
     return response.subjectTrack;
   }
@@ -33625,7 +33726,17 @@ class TimebackProvider3 {
 // ../../internal/client-infra/src/utils/utils.ts
 function getEnv3(key) {
   try {
-    return typeof process === "undefined" ? undefined : process.env[key];
+    if (typeof process === "undefined")
+      return;
+    if (typeof key === "string") {
+      return process.env[key];
+    }
+    for (const k of key) {
+      const value = process.env[k];
+      if (value !== undefined)
+        return value;
+    }
+    return;
   } catch {
     return;
   }
@@ -33646,6 +33757,18 @@ var DEFAULT_PROVIDER_REGISTRY3 = {
 };
 
 // ../../internal/client-infra/src/config/resolve.ts
+function primaryEnvVar3(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (key.length === 0) {
+    throw new Error(`Missing env var key: ${key}`);
+  }
+  return key[0];
+}
+function formatEnvVarKey3(key) {
+  return primaryEnvVar3(key);
+}
 function validateEnv3(env) {
   if (env !== "staging" && env !== "production") {
     throw new Error(`Invalid env "${env}": must be "staging" or "production"`);
@@ -33656,10 +33779,10 @@ function validateAuth3(auth, envVars) {
   const clientId = auth?.clientId ?? getEnv3(envVars.clientId);
   const clientSecret = auth?.clientSecret ?? getEnv3(envVars.clientSecret);
   if (!clientId) {
-    throw new Error(`Missing clientId: provide in config or set ${envVars.clientId}`);
+    throw new Error(`Missing clientId: provide in config or set ${formatEnvVarKey3(envVars.clientId)}`);
   }
   if (!clientSecret) {
-    throw new Error(`Missing clientSecret: provide in config or set ${envVars.clientSecret}`);
+    throw new Error(`Missing clientSecret: provide in config or set ${formatEnvVarKey3(envVars.clientSecret)}`);
   }
   return { clientId, clientSecret };
 }
@@ -33675,21 +33798,21 @@ function buildMissingEnvError3(envVars) {
   const clientId = getEnv3(envVars.clientId);
   const clientSecret = getEnv3(envVars.clientSecret);
   if (baseUrl === undefined && clientId === undefined) {
-    const hint = envVars.env ?? envVars.baseUrl;
+    const hint = formatEnvVarKey3(envVars.env ?? envVars.baseUrl);
     return `Missing env: provide in config or set ${hint}`;
   }
   const missing = [];
   if (baseUrl === undefined) {
-    missing.push(envVars.env ?? envVars.baseUrl);
+    missing.push(formatEnvVarKey3(envVars.env ?? envVars.baseUrl));
   }
   if (baseUrl !== undefined && authUrl === undefined) {
-    missing.push(envVars.authUrl);
+    missing.push(formatEnvVarKey3(envVars.authUrl));
   }
   if (clientId === undefined) {
-    missing.push(envVars.clientId);
+    missing.push(formatEnvVarKey3(envVars.clientId));
   }
   if (clientSecret === undefined) {
-    missing.push(envVars.clientSecret);
+    missing.push(formatEnvVarKey3(envVars.clientSecret));
   }
   return `Missing environment variables: ${missing.join(", ")}`;
 }
@@ -34651,7 +34774,17 @@ class TimebackProvider4 {
 }
 function getEnv4(key) {
   try {
-    return typeof process === "undefined" ? undefined : process.env[key];
+    if (typeof process === "undefined")
+      return;
+    if (typeof key === "string") {
+      return process.env[key];
+    }
+    for (const k of key) {
+      const value = process.env[k];
+      if (value !== undefined)
+        return value;
+    }
+    return;
   } catch {
     return;
   }
@@ -34682,6 +34815,18 @@ var DEFAULT_PROVIDER_REGISTRY4 = {
     }
   }
 };
+function primaryEnvVar4(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (key.length === 0) {
+    throw new Error(`Missing env var key: ${key}`);
+  }
+  return key[0];
+}
+function formatEnvVarKey4(key) {
+  return primaryEnvVar4(key);
+}
 function validateEnv4(env) {
   if (env !== "staging" && env !== "production") {
     throw new Error(`Invalid env "${env}": must be "staging" or "production"`);
@@ -34692,10 +34837,10 @@ function validateAuth4(auth, envVars) {
   const clientId = auth?.clientId ?? getEnv4(envVars.clientId);
   const clientSecret = auth?.clientSecret ?? getEnv4(envVars.clientSecret);
   if (!clientId) {
-    throw new Error(`Missing clientId: provide in config or set ${envVars.clientId}`);
+    throw new Error(`Missing clientId: provide in config or set ${formatEnvVarKey4(envVars.clientId)}`);
   }
   if (!clientSecret) {
-    throw new Error(`Missing clientSecret: provide in config or set ${envVars.clientSecret}`);
+    throw new Error(`Missing clientSecret: provide in config or set ${formatEnvVarKey4(envVars.clientSecret)}`);
   }
   return { clientId, clientSecret };
 }
@@ -34711,21 +34856,21 @@ function buildMissingEnvError4(envVars) {
   const clientId = getEnv4(envVars.clientId);
   const clientSecret = getEnv4(envVars.clientSecret);
   if (baseUrl === undefined && clientId === undefined) {
-    const hint = envVars.env ?? envVars.baseUrl;
+    const hint = formatEnvVarKey4(envVars.env ?? envVars.baseUrl);
     return `Missing env: provide in config or set ${hint}`;
   }
   const missing = [];
   if (baseUrl === undefined) {
-    missing.push(envVars.env ?? envVars.baseUrl);
+    missing.push(formatEnvVarKey4(envVars.env ?? envVars.baseUrl));
   }
   if (baseUrl !== undefined && authUrl === undefined) {
-    missing.push(envVars.authUrl);
+    missing.push(formatEnvVarKey4(envVars.authUrl));
   }
   if (clientId === undefined) {
-    missing.push(envVars.clientId);
+    missing.push(formatEnvVarKey4(envVars.clientId));
   }
   if (clientSecret === undefined) {
-    missing.push(envVars.clientSecret);
+    missing.push(formatEnvVarKey4(envVars.clientSecret));
   }
   return `Missing environment variables: ${missing.join(", ")}`;
 }
@@ -35441,10 +35586,10 @@ function validateSourcedId2(sourcedId, context) {
   }
 }
 var ONEROSTER_ENV_VARS = {
-  baseUrl: "ONEROSTER_BASE_URL",
-  clientId: "ONEROSTER_CLIENT_ID",
-  clientSecret: "ONEROSTER_CLIENT_SECRET",
-  authUrl: "ONEROSTER_TOKEN_URL"
+  baseUrl: ["TIMEBACK_API_BASE_URL", "TIMEBACK_BASE_URL", "ONEROSTER_BASE_URL"],
+  clientId: ["TIMEBACK_API_CLIENT_ID", "TIMEBACK_CLIENT_ID", "ONEROSTER_CLIENT_ID"],
+  clientSecret: ["TIMEBACK_API_CLIENT_SECRET", "TIMEBACK_CLIENT_SECRET", "ONEROSTER_CLIENT_SECRET"],
+  authUrl: ["TIMEBACK_API_AUTH_URL", "TIMEBACK_AUTH_URL", "ONEROSTER_TOKEN_URL"]
 };
 function resolveToProvider23(config3, registry3 = DEFAULT_PROVIDER_REGISTRY4) {
   return resolveToProvider6(config3, ONEROSTER_ENV_VARS, registry3);
@@ -37699,7 +37844,7 @@ class Doc3 {
 var version3 = {
   major: 4,
   minor: 3,
-  patch: 5
+  patch: 6
 };
 var $ZodType3 = /* @__PURE__ */ $constructor3("$ZodType", (inst, def) => {
   var _a3;
@@ -38983,7 +39128,7 @@ var $ZodRecord3 = /* @__PURE__ */ $constructor3("$ZodRecord", (inst, def) => {
         if (keyResult instanceof Promise) {
           throw new Error("Async schemas not supported in object keys currently");
         }
-        const checkNumericKey = typeof key === "string" && number6.test(key) && keyResult.issues.length && keyResult.issues.some((iss) => iss.code === "invalid_type" && iss.expected === "number");
+        const checkNumericKey = typeof key === "string" && number6.test(key) && keyResult.issues.length;
         if (checkNumericKey) {
           const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
           if (retryResult instanceof Promise) {
@@ -46300,7 +46445,7 @@ function finalize3(ctx, schema) {
           }
         }
       }
-      if (refSchema.$ref) {
+      if (refSchema.$ref && refSeen.def) {
         for (const key in schema2) {
           if (key === "$ref" || key === "allOf")
             continue;
@@ -48932,7 +49077,7 @@ var TimebackSubject3 = exports_external3.enum([
   "Math",
   "None",
   "Other"
-]);
+]).meta({ id: "TimebackSubject", description: "Subject area" });
 var TimebackGrade3 = exports_external3.union([
   exports_external3.literal(-1),
   exports_external3.literal(0),
@@ -48949,7 +49094,10 @@ var TimebackGrade3 = exports_external3.union([
   exports_external3.literal(11),
   exports_external3.literal(12),
   exports_external3.literal(13)
-]);
+]).meta({
+  id: "TimebackGrade",
+  description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+});
 var ScoreStatus3 = exports_external3.enum([
   "exempt",
   "fully graded",
@@ -49179,62 +49327,84 @@ var CaliperListEventsParams3 = exports_external3.object({
   actorEmail: exports_external3.email().optional()
 }).strict();
 var CourseIds3 = exports_external3.object({
-  staging: exports_external3.string().optional(),
-  production: exports_external3.string().optional()
-});
-var CourseType3 = exports_external3.enum(["base", "hole-filling", "optional"]);
-var PublishStatus3 = exports_external3.enum(["draft", "testing", "published", "deactivated"]);
+  staging: exports_external3.string().meta({ description: "Course ID in staging environment" }).optional(),
+  production: exports_external3.string().meta({ description: "Course ID in production environment" }).optional()
+}).meta({ id: "CourseIds", description: "Environment-specific course IDs (populated by sync)" });
+var CourseType3 = exports_external3.enum(["base", "hole-filling", "optional"]).meta({ id: "CourseType", description: "Course classification type" });
+var PublishStatus3 = exports_external3.enum(["draft", "testing", "published", "deactivated"]).meta({ id: "PublishStatus", description: "Course publication status" });
 var CourseGoals3 = exports_external3.object({
-  dailyXp: exports_external3.number().int().positive().optional(),
-  dailyLessons: exports_external3.number().int().positive().optional(),
-  dailyActiveMinutes: exports_external3.number().int().positive().optional(),
-  dailyAccuracy: exports_external3.number().int().min(0).max(100).optional(),
-  dailyMasteredUnits: exports_external3.number().int().positive().optional()
-});
+  dailyXp: exports_external3.number().int().positive().meta({ description: "Target XP to earn per day" }).optional(),
+  dailyLessons: exports_external3.number().int().positive().meta({ description: "Target lessons to complete per day" }).optional(),
+  dailyActiveMinutes: exports_external3.number().int().positive().meta({ description: "Target active learning minutes per day" }).optional(),
+  dailyAccuracy: exports_external3.number().int().min(0).max(100).meta({ description: "Target accuracy percentage (0-100)" }).optional(),
+  dailyMasteredUnits: exports_external3.number().int().positive().meta({ description: "Target units to master per day" }).optional()
+}).meta({ id: "CourseGoals", description: "Daily learning goals for a course" });
 var CourseMetrics3 = exports_external3.object({
-  totalXp: exports_external3.number().int().positive().optional(),
-  totalLessons: exports_external3.number().int().positive().optional(),
-  totalGrades: exports_external3.number().int().positive().optional()
-});
+  totalXp: exports_external3.number().int().positive().meta({ description: "Total XP available in the course" }).optional(),
+  totalLessons: exports_external3.number().int().positive().meta({ description: "Total number of lessons/activities" }).optional(),
+  totalGrades: exports_external3.number().int().positive().meta({ description: "Total grade levels covered" }).optional()
+}).meta({ id: "CourseMetrics", description: "Aggregate metrics for a course" });
 var CourseMetadata3 = exports_external3.object({
   courseType: CourseType3.optional(),
-  isSupplemental: exports_external3.boolean().optional(),
-  isCustom: exports_external3.boolean().optional(),
+  isSupplemental: exports_external3.boolean().meta({ description: "Whether this is supplemental to a base course" }).optional(),
+  isCustom: exports_external3.boolean().meta({ description: "Whether this is a custom course for an individual student" }).optional(),
   publishStatus: PublishStatus3.optional(),
-  contactEmail: exports_external3.email().optional(),
-  primaryApp: exports_external3.string().optional(),
+  contactEmail: exports_external3.email().meta({ description: "Contact email for course issues" }).optional(),
+  primaryApp: exports_external3.string().meta({ description: "Primary application identifier" }).optional(),
   goals: CourseGoals3.optional(),
   metrics: CourseMetrics3.optional()
-});
+}).meta({ id: "CourseMetadata", description: "Course metadata (matches API metadata object)" });
 var CourseDefaults3 = exports_external3.object({
-  courseCode: exports_external3.string().optional(),
-  level: exports_external3.string().optional(),
+  courseCode: exports_external3.string().meta({ description: "Course code (e.g., 'MATH101')" }).optional(),
+  level: exports_external3.string().meta({ description: "Course level (e.g., 'AP', 'Honors')" }).optional(),
   metadata: CourseMetadata3.optional()
+}).meta({
+  id: "CourseDefaults",
+  description: "Default properties that apply to all courses unless overridden"
 });
 var CourseEnvOverrides3 = exports_external3.object({
-  level: exports_external3.string().optional(),
-  sensor: exports_external3.string().url().optional(),
-  launchUrl: exports_external3.string().url().optional(),
+  level: exports_external3.string().meta({ description: "Course level for this environment" }).optional(),
+  sensor: exports_external3.url().meta({ description: "Caliper sensor endpoint URL for this environment" }).optional(),
+  launchUrl: exports_external3.url().meta({ description: "LTI launch URL for this environment" }).optional(),
   metadata: CourseMetadata3.optional()
+}).meta({
+  id: "CourseEnvOverrides",
+  description: "Environment-specific course overrides (non-identity fields)"
 });
 var CourseOverrides3 = exports_external3.object({
-  staging: CourseEnvOverrides3.optional(),
-  production: CourseEnvOverrides3.optional()
-});
+  staging: CourseEnvOverrides3.meta({
+    description: "Overrides for staging environment"
+  }).optional(),
+  production: CourseEnvOverrides3.meta({
+    description: "Overrides for production environment"
+  }).optional()
+}).meta({ id: "CourseOverrides", description: "Per-environment course overrides" });
 var CourseConfig3 = CourseDefaults3.extend({
-  subject: TimebackSubject3,
-  grade: TimebackGrade3.optional(),
+  subject: TimebackSubject3.meta({ description: "Subject area for this course" }),
+  grade: TimebackGrade3.meta({
+    description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+  }).optional(),
   ids: CourseIds3.nullable().optional(),
-  sensor: exports_external3.string().url().optional(),
-  launchUrl: exports_external3.string().url().optional(),
+  sensor: exports_external3.url().meta({ description: "Caliper sensor endpoint URL for this course" }).optional(),
+  launchUrl: exports_external3.url().meta({ description: "LTI launch URL for this course" }).optional(),
   overrides: CourseOverrides3.optional()
+}).meta({
+  id: "CourseConfig",
+  description: "Configuration for a single course. Must have either grade or courseCode (or both)."
 });
 var TimebackConfig3 = exports_external3.object({
-  name: exports_external3.string().min(1, "App name is required"),
-  defaults: CourseDefaults3.optional(),
-  courses: exports_external3.array(CourseConfig3).min(1, "At least one course is required"),
-  sensor: exports_external3.string().url().optional(),
-  launchUrl: exports_external3.string().url().optional()
+  $schema: exports_external3.string().meta({ description: "JSON Schema reference for editor support" }).optional(),
+  name: exports_external3.string().min(1, "App name is required").meta({ description: "Display name for your app" }),
+  defaults: CourseDefaults3.meta({
+    description: "Default properties applied to all courses"
+  }).optional(),
+  courses: exports_external3.array(CourseConfig3).min(1, "At least one course is required").meta({ description: "Courses available in this app" }),
+  sensor: exports_external3.url().meta({ description: "Default Caliper sensor endpoint URL for all courses" }).optional(),
+  launchUrl: exports_external3.url().meta({ description: "Default LTI launch URL for all courses" }).optional()
+}).meta({
+  id: "TimebackConfig",
+  title: "Timeback Config",
+  description: "Configuration schema for timeback.config.json files"
 }).refine((config22) => {
   return config22.courses.every((c) => c.grade !== undefined || c.courseCode !== undefined);
 }, {
@@ -49255,17 +49425,23 @@ 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]);
+var EdubridgeDateString3 = IsoDateTimeString3;
 var EduBridgeEnrollment3 = exports_external3.object({
   id: exports_external3.string(),
   role: exports_external3.string(),
@@ -49329,12 +49505,9 @@ var EmailOrStudentId3 = exports_external3.object({
 });
 var SubjectTrackInput3 = exports_external3.object({
   subject: NonEmptyString6,
-  gradeLevel: NonEmptyString6,
-  targetCourseId: NonEmptyString6,
-  metadata: exports_external3.record(exports_external3.string(), exports_external3.unknown()).optional()
-});
-var SubjectTrackUpsertInput3 = SubjectTrackInput3.extend({
-  id: NonEmptyString6
+  grade: NonEmptyString6,
+  courseId: NonEmptyString6,
+  orgSourcedId: NonEmptyString6.optional()
 });
 var EdubridgeListEnrollmentsParams3 = exports_external3.object({
   userId: NonEmptyString6
@@ -50303,7 +50476,8 @@ class BaseResource {
     return this.stream(params).toArray();
   }
   async first(params) {
-    const result = await this.list({ ...params, limit: 1 });
+    const limitedParams = { ...params ?? {}, limit: 1 };
+    const result = await new Paginator22(this.transport, this.basePath, limitedParams, this.unwrapKey, this.transform.bind(this)).firstPage();
     return result.data[0];
   }
   stream(params) {
@@ -50386,7 +50560,8 @@ class ReadOnlyResource {
     return this.stream(params).toArray();
   }
   async first(params) {
-    const result = await this.list({ ...params, limit: 1 });
+    const limitedParams = { ...params ?? {}, limit: 1 };
+    const result = await new Paginator22(this.transport, this.basePath, limitedParams, this.unwrapKey, this.transform.bind(this)).firstPage();
     return result.data[0];
   }
   stream(params) {
@@ -52305,7 +52480,17 @@ class TimebackProvider5 {
 }
 function getEnv5(key) {
   try {
-    return typeof process === "undefined" ? undefined : process.env[key];
+    if (typeof process === "undefined")
+      return;
+    if (typeof key === "string") {
+      return process.env[key];
+    }
+    for (const k of key) {
+      const value = process.env[k];
+      if (value !== undefined)
+        return value;
+    }
+    return;
   } catch {
     return;
   }
@@ -52336,6 +52521,18 @@ var DEFAULT_PROVIDER_REGISTRY5 = {
     }
   }
 };
+function primaryEnvVar5(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (key.length === 0) {
+    throw new Error(`Missing env var key: ${key}`);
+  }
+  return key[0];
+}
+function formatEnvVarKey5(key) {
+  return primaryEnvVar5(key);
+}
 function validateEnv5(env) {
   if (env !== "staging" && env !== "production") {
     throw new Error(`Invalid env "${env}": must be "staging" or "production"`);
@@ -52346,10 +52543,10 @@ function validateAuth5(auth, envVars) {
   const clientId = auth?.clientId ?? getEnv5(envVars.clientId);
   const clientSecret = auth?.clientSecret ?? getEnv5(envVars.clientSecret);
   if (!clientId) {
-    throw new Error(`Missing clientId: provide in config or set ${envVars.clientId}`);
+    throw new Error(`Missing clientId: provide in config or set ${formatEnvVarKey5(envVars.clientId)}`);
   }
   if (!clientSecret) {
-    throw new Error(`Missing clientSecret: provide in config or set ${envVars.clientSecret}`);
+    throw new Error(`Missing clientSecret: provide in config or set ${formatEnvVarKey5(envVars.clientSecret)}`);
   }
   return { clientId, clientSecret };
 }
@@ -52365,21 +52562,21 @@ function buildMissingEnvError5(envVars) {
   const clientId = getEnv5(envVars.clientId);
   const clientSecret = getEnv5(envVars.clientSecret);
   if (baseUrl === undefined && clientId === undefined) {
-    const hint = envVars.env ?? envVars.baseUrl;
+    const hint = formatEnvVarKey5(envVars.env ?? envVars.baseUrl);
     return `Missing env: provide in config or set ${hint}`;
   }
   const missing = [];
   if (baseUrl === undefined) {
-    missing.push(envVars.env ?? envVars.baseUrl);
+    missing.push(formatEnvVarKey5(envVars.env ?? envVars.baseUrl));
   }
   if (baseUrl !== undefined && authUrl === undefined) {
-    missing.push(envVars.authUrl);
+    missing.push(formatEnvVarKey5(envVars.authUrl));
   }
   if (clientId === undefined) {
-    missing.push(envVars.clientId);
+    missing.push(formatEnvVarKey5(envVars.clientId));
   }
   if (clientSecret === undefined) {
-    missing.push(envVars.clientSecret);
+    missing.push(formatEnvVarKey5(envVars.clientSecret));
   }
   return `Missing environment variables: ${missing.join(", ")}`;
 }
@@ -53063,10 +53260,14 @@ function validateNonEmptyString4(value, name) {
   }
 }
 var POWERPATH_ENV_VARS = {
-  baseUrl: "POWERPATH_BASE_URL",
-  clientId: "POWERPATH_CLIENT_ID",
-  clientSecret: "POWERPATH_CLIENT_SECRET",
-  authUrl: "POWERPATH_TOKEN_URL"
+  baseUrl: ["TIMEBACK_API_BASE_URL", "TIMEBACK_BASE_URL", "POWERPATH_BASE_URL"],
+  clientId: ["TIMEBACK_API_CLIENT_ID", "TIMEBACK_CLIENT_ID", "POWERPATH_CLIENT_ID"],
+  clientSecret: [
+    "TIMEBACK_API_CLIENT_SECRET",
+    "TIMEBACK_CLIENT_SECRET",
+    "POWERPATH_CLIENT_SECRET"
+  ],
+  authUrl: ["TIMEBACK_API_AUTH_URL", "TIMEBACK_AUTH_URL", "POWERPATH_TOKEN_URL"]
 };
 function resolveToProvider24(config4, registry4 = DEFAULT_PROVIDER_REGISTRY5) {
   return resolveToProvider7(config4, POWERPATH_ENV_VARS, registry4);
@@ -55308,7 +55509,7 @@ class Doc4 {
 var version4 = {
   major: 4,
   minor: 3,
-  patch: 5
+  patch: 6
 };
 var $ZodType4 = /* @__PURE__ */ $constructor4("$ZodType", (inst, def) => {
   var _a4;
@@ -56592,7 +56793,7 @@ var $ZodRecord4 = /* @__PURE__ */ $constructor4("$ZodRecord", (inst, def) => {
         if (keyResult instanceof Promise) {
           throw new Error("Async schemas not supported in object keys currently");
         }
-        const checkNumericKey = typeof key === "string" && number7.test(key) && keyResult.issues.length && keyResult.issues.some((iss) => iss.code === "invalid_type" && iss.expected === "number");
+        const checkNumericKey = typeof key === "string" && number7.test(key) && keyResult.issues.length;
         if (checkNumericKey) {
           const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
           if (retryResult instanceof Promise) {
@@ -63909,7 +64110,7 @@ function finalize4(ctx, schema) {
           }
         }
       }
-      if (refSchema.$ref) {
+      if (refSchema.$ref && refSeen.def) {
         for (const key in schema2) {
           if (key === "$ref" || key === "allOf")
             continue;
@@ -66541,7 +66742,7 @@ var TimebackSubject4 = exports_external4.enum([
   "Math",
   "None",
   "Other"
-]);
+]).meta({ id: "TimebackSubject", description: "Subject area" });
 var TimebackGrade4 = exports_external4.union([
   exports_external4.literal(-1),
   exports_external4.literal(0),
@@ -66558,7 +66759,10 @@ var TimebackGrade4 = exports_external4.union([
   exports_external4.literal(11),
   exports_external4.literal(12),
   exports_external4.literal(13)
-]);
+]).meta({
+  id: "TimebackGrade",
+  description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+});
 var ScoreStatus4 = exports_external4.enum([
   "exempt",
   "fully graded",
@@ -66788,62 +66992,84 @@ var CaliperListEventsParams4 = exports_external4.object({
   actorEmail: exports_external4.email().optional()
 }).strict();
 var CourseIds4 = exports_external4.object({
-  staging: exports_external4.string().optional(),
-  production: exports_external4.string().optional()
-});
-var CourseType4 = exports_external4.enum(["base", "hole-filling", "optional"]);
-var PublishStatus4 = exports_external4.enum(["draft", "testing", "published", "deactivated"]);
+  staging: exports_external4.string().meta({ description: "Course ID in staging environment" }).optional(),
+  production: exports_external4.string().meta({ description: "Course ID in production environment" }).optional()
+}).meta({ id: "CourseIds", description: "Environment-specific course IDs (populated by sync)" });
+var CourseType4 = exports_external4.enum(["base", "hole-filling", "optional"]).meta({ id: "CourseType", description: "Course classification type" });
+var PublishStatus4 = exports_external4.enum(["draft", "testing", "published", "deactivated"]).meta({ id: "PublishStatus", description: "Course publication status" });
 var CourseGoals4 = exports_external4.object({
-  dailyXp: exports_external4.number().int().positive().optional(),
-  dailyLessons: exports_external4.number().int().positive().optional(),
-  dailyActiveMinutes: exports_external4.number().int().positive().optional(),
-  dailyAccuracy: exports_external4.number().int().min(0).max(100).optional(),
-  dailyMasteredUnits: exports_external4.number().int().positive().optional()
-});
+  dailyXp: exports_external4.number().int().positive().meta({ description: "Target XP to earn per day" }).optional(),
+  dailyLessons: exports_external4.number().int().positive().meta({ description: "Target lessons to complete per day" }).optional(),
+  dailyActiveMinutes: exports_external4.number().int().positive().meta({ description: "Target active learning minutes per day" }).optional(),
+  dailyAccuracy: exports_external4.number().int().min(0).max(100).meta({ description: "Target accuracy percentage (0-100)" }).optional(),
+  dailyMasteredUnits: exports_external4.number().int().positive().meta({ description: "Target units to master per day" }).optional()
+}).meta({ id: "CourseGoals", description: "Daily learning goals for a course" });
 var CourseMetrics4 = exports_external4.object({
-  totalXp: exports_external4.number().int().positive().optional(),
-  totalLessons: exports_external4.number().int().positive().optional(),
-  totalGrades: exports_external4.number().int().positive().optional()
-});
+  totalXp: exports_external4.number().int().positive().meta({ description: "Total XP available in the course" }).optional(),
+  totalLessons: exports_external4.number().int().positive().meta({ description: "Total number of lessons/activities" }).optional(),
+  totalGrades: exports_external4.number().int().positive().meta({ description: "Total grade levels covered" }).optional()
+}).meta({ id: "CourseMetrics", description: "Aggregate metrics for a course" });
 var CourseMetadata4 = exports_external4.object({
   courseType: CourseType4.optional(),
-  isSupplemental: exports_external4.boolean().optional(),
-  isCustom: exports_external4.boolean().optional(),
+  isSupplemental: exports_external4.boolean().meta({ description: "Whether this is supplemental to a base course" }).optional(),
+  isCustom: exports_external4.boolean().meta({ description: "Whether this is a custom course for an individual student" }).optional(),
   publishStatus: PublishStatus4.optional(),
-  contactEmail: exports_external4.email().optional(),
-  primaryApp: exports_external4.string().optional(),
+  contactEmail: exports_external4.email().meta({ description: "Contact email for course issues" }).optional(),
+  primaryApp: exports_external4.string().meta({ description: "Primary application identifier" }).optional(),
   goals: CourseGoals4.optional(),
   metrics: CourseMetrics4.optional()
-});
+}).meta({ id: "CourseMetadata", description: "Course metadata (matches API metadata object)" });
 var CourseDefaults4 = exports_external4.object({
-  courseCode: exports_external4.string().optional(),
-  level: exports_external4.string().optional(),
+  courseCode: exports_external4.string().meta({ description: "Course code (e.g., 'MATH101')" }).optional(),
+  level: exports_external4.string().meta({ description: "Course level (e.g., 'AP', 'Honors')" }).optional(),
   metadata: CourseMetadata4.optional()
+}).meta({
+  id: "CourseDefaults",
+  description: "Default properties that apply to all courses unless overridden"
 });
 var CourseEnvOverrides4 = exports_external4.object({
-  level: exports_external4.string().optional(),
-  sensor: exports_external4.string().url().optional(),
-  launchUrl: exports_external4.string().url().optional(),
+  level: exports_external4.string().meta({ description: "Course level for this environment" }).optional(),
+  sensor: exports_external4.url().meta({ description: "Caliper sensor endpoint URL for this environment" }).optional(),
+  launchUrl: exports_external4.url().meta({ description: "LTI launch URL for this environment" }).optional(),
   metadata: CourseMetadata4.optional()
+}).meta({
+  id: "CourseEnvOverrides",
+  description: "Environment-specific course overrides (non-identity fields)"
 });
 var CourseOverrides4 = exports_external4.object({
-  staging: CourseEnvOverrides4.optional(),
-  production: CourseEnvOverrides4.optional()
-});
+  staging: CourseEnvOverrides4.meta({
+    description: "Overrides for staging environment"
+  }).optional(),
+  production: CourseEnvOverrides4.meta({
+    description: "Overrides for production environment"
+  }).optional()
+}).meta({ id: "CourseOverrides", description: "Per-environment course overrides" });
 var CourseConfig4 = CourseDefaults4.extend({
-  subject: TimebackSubject4,
-  grade: TimebackGrade4.optional(),
+  subject: TimebackSubject4.meta({ description: "Subject area for this course" }),
+  grade: TimebackGrade4.meta({
+    description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+  }).optional(),
   ids: CourseIds4.nullable().optional(),
-  sensor: exports_external4.string().url().optional(),
-  launchUrl: exports_external4.string().url().optional(),
+  sensor: exports_external4.url().meta({ description: "Caliper sensor endpoint URL for this course" }).optional(),
+  launchUrl: exports_external4.url().meta({ description: "LTI launch URL for this course" }).optional(),
   overrides: CourseOverrides4.optional()
+}).meta({
+  id: "CourseConfig",
+  description: "Configuration for a single course. Must have either grade or courseCode (or both)."
 });
 var TimebackConfig4 = exports_external4.object({
-  name: exports_external4.string().min(1, "App name is required"),
-  defaults: CourseDefaults4.optional(),
-  courses: exports_external4.array(CourseConfig4).min(1, "At least one course is required"),
-  sensor: exports_external4.string().url().optional(),
-  launchUrl: exports_external4.string().url().optional()
+  $schema: exports_external4.string().meta({ description: "JSON Schema reference for editor support" }).optional(),
+  name: exports_external4.string().min(1, "App name is required").meta({ description: "Display name for your app" }),
+  defaults: CourseDefaults4.meta({
+    description: "Default properties applied to all courses"
+  }).optional(),
+  courses: exports_external4.array(CourseConfig4).min(1, "At least one course is required").meta({ description: "Courses available in this app" }),
+  sensor: exports_external4.url().meta({ description: "Default Caliper sensor endpoint URL for all courses" }).optional(),
+  launchUrl: exports_external4.url().meta({ description: "Default LTI launch URL for all courses" }).optional()
+}).meta({
+  id: "TimebackConfig",
+  title: "Timeback Config",
+  description: "Configuration schema for timeback.config.json files"
 }).refine((config22) => {
   return config22.courses.every((c) => c.grade !== undefined || c.courseCode !== undefined);
 }, {
@@ -66864,17 +67090,23 @@ 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]);
+var EdubridgeDateString4 = IsoDateTimeString4;
 var EduBridgeEnrollment4 = exports_external4.object({
   id: exports_external4.string(),
   role: exports_external4.string(),
@@ -66938,12 +67170,9 @@ var EmailOrStudentId4 = exports_external4.object({
 });
 var SubjectTrackInput4 = exports_external4.object({
   subject: NonEmptyString7,
-  gradeLevel: NonEmptyString7,
-  targetCourseId: NonEmptyString7,
-  metadata: exports_external4.record(exports_external4.string(), exports_external4.unknown()).optional()
-});
-var SubjectTrackUpsertInput4 = SubjectTrackInput4.extend({
-  id: NonEmptyString7
+  grade: NonEmptyString7,
+  courseId: NonEmptyString7,
+  orgSourcedId: NonEmptyString7.optional()
 });
 var EdubridgeListEnrollmentsParams4 = exports_external4.object({
   userId: NonEmptyString7
@@ -68924,7 +69153,17 @@ class TimebackProvider6 {
 }
 function getEnv6(key) {
   try {
-    return typeof process === "undefined" ? undefined : process.env[key];
+    if (typeof process === "undefined")
+      return;
+    if (typeof key === "string") {
+      return process.env[key];
+    }
+    for (const k of key) {
+      const value = process.env[k];
+      if (value !== undefined)
+        return value;
+    }
+    return;
   } catch {
     return;
   }
@@ -68955,6 +69194,18 @@ var DEFAULT_PROVIDER_REGISTRY6 = {
     }
   }
 };
+function primaryEnvVar6(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (key.length === 0) {
+    throw new Error(`Missing env var key: ${key}`);
+  }
+  return key[0];
+}
+function formatEnvVarKey6(key) {
+  return primaryEnvVar6(key);
+}
 function validateEnv6(env) {
   if (env !== "staging" && env !== "production") {
     throw new Error(`Invalid env "${env}": must be "staging" or "production"`);
@@ -68965,10 +69216,10 @@ function validateAuth6(auth, envVars) {
   const clientId = auth?.clientId ?? getEnv6(envVars.clientId);
   const clientSecret = auth?.clientSecret ?? getEnv6(envVars.clientSecret);
   if (!clientId) {
-    throw new Error(`Missing clientId: provide in config or set ${envVars.clientId}`);
+    throw new Error(`Missing clientId: provide in config or set ${formatEnvVarKey6(envVars.clientId)}`);
   }
   if (!clientSecret) {
-    throw new Error(`Missing clientSecret: provide in config or set ${envVars.clientSecret}`);
+    throw new Error(`Missing clientSecret: provide in config or set ${formatEnvVarKey6(envVars.clientSecret)}`);
   }
   return { clientId, clientSecret };
 }
@@ -68984,21 +69235,21 @@ function buildMissingEnvError6(envVars) {
   const clientId = getEnv6(envVars.clientId);
   const clientSecret = getEnv6(envVars.clientSecret);
   if (baseUrl === undefined && clientId === undefined) {
-    const hint = envVars.env ?? envVars.baseUrl;
+    const hint = formatEnvVarKey6(envVars.env ?? envVars.baseUrl);
     return `Missing env: provide in config or set ${hint}`;
   }
   const missing = [];
   if (baseUrl === undefined) {
-    missing.push(envVars.env ?? envVars.baseUrl);
+    missing.push(formatEnvVarKey6(envVars.env ?? envVars.baseUrl));
   }
   if (baseUrl !== undefined && authUrl === undefined) {
-    missing.push(envVars.authUrl);
+    missing.push(formatEnvVarKey6(envVars.authUrl));
   }
   if (clientId === undefined) {
-    missing.push(envVars.clientId);
+    missing.push(formatEnvVarKey6(envVars.clientId));
   }
   if (clientSecret === undefined) {
-    missing.push(envVars.clientSecret);
+    missing.push(formatEnvVarKey6(envVars.clientSecret));
   }
   return `Missing environment variables: ${missing.join(", ")}`;
 }
@@ -69698,10 +69949,10 @@ function validatePageListParams2(params) {
   }
 }
 var QTI_ENV_VARS = {
-  baseUrl: "QTI_BASE_URL",
-  clientId: "QTI_CLIENT_ID",
-  clientSecret: "QTI_CLIENT_SECRET",
-  authUrl: "QTI_TOKEN_URL"
+  baseUrl: ["TIMEBACK_API_BASE_URL", "TIMEBACK_BASE_URL", "QTI_BASE_URL"],
+  clientId: ["TIMEBACK_API_CLIENT_ID", "TIMEBACK_CLIENT_ID", "QTI_CLIENT_ID"],
+  clientSecret: ["TIMEBACK_API_CLIENT_SECRET", "TIMEBACK_CLIENT_SECRET", "QTI_CLIENT_SECRET"],
+  authUrl: ["TIMEBACK_API_AUTH_URL", "TIMEBACK_AUTH_URL", "QTI_TOKEN_URL"]
 };
 function resolveToProvider25(config5, registry5 = DEFAULT_PROVIDER_REGISTRY6) {
   return resolveToProvider8(config5, QTI_ENV_VARS, registry5);
@@ -71947,7 +72198,7 @@ class Doc5 {
 var version5 = {
   major: 4,
   minor: 3,
-  patch: 5
+  patch: 6
 };
 var $ZodType5 = /* @__PURE__ */ $constructor5("$ZodType", (inst, def) => {
   var _a5;
@@ -73231,7 +73482,7 @@ var $ZodRecord5 = /* @__PURE__ */ $constructor5("$ZodRecord", (inst, def) => {
         if (keyResult instanceof Promise) {
           throw new Error("Async schemas not supported in object keys currently");
         }
-        const checkNumericKey = typeof key === "string" && number8.test(key) && keyResult.issues.length && keyResult.issues.some((iss) => iss.code === "invalid_type" && iss.expected === "number");
+        const checkNumericKey = typeof key === "string" && number8.test(key) && keyResult.issues.length;
         if (checkNumericKey) {
           const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
           if (retryResult instanceof Promise) {
@@ -80548,7 +80799,7 @@ function finalize5(ctx, schema) {
           }
         }
       }
-      if (refSchema.$ref) {
+      if (refSchema.$ref && refSeen.def) {
         for (const key in schema2) {
           if (key === "$ref" || key === "allOf")
             continue;
@@ -83180,7 +83431,7 @@ var TimebackSubject5 = exports_external5.enum([
   "Math",
   "None",
   "Other"
-]);
+]).meta({ id: "TimebackSubject", description: "Subject area" });
 var TimebackGrade5 = exports_external5.union([
   exports_external5.literal(-1),
   exports_external5.literal(0),
@@ -83197,7 +83448,10 @@ var TimebackGrade5 = exports_external5.union([
   exports_external5.literal(11),
   exports_external5.literal(12),
   exports_external5.literal(13)
-]);
+]).meta({
+  id: "TimebackGrade",
+  description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+});
 var ScoreStatus5 = exports_external5.enum([
   "exempt",
   "fully graded",
@@ -83427,62 +83681,84 @@ var CaliperListEventsParams5 = exports_external5.object({
   actorEmail: exports_external5.email().optional()
 }).strict();
 var CourseIds5 = exports_external5.object({
-  staging: exports_external5.string().optional(),
-  production: exports_external5.string().optional()
-});
-var CourseType5 = exports_external5.enum(["base", "hole-filling", "optional"]);
-var PublishStatus5 = exports_external5.enum(["draft", "testing", "published", "deactivated"]);
+  staging: exports_external5.string().meta({ description: "Course ID in staging environment" }).optional(),
+  production: exports_external5.string().meta({ description: "Course ID in production environment" }).optional()
+}).meta({ id: "CourseIds", description: "Environment-specific course IDs (populated by sync)" });
+var CourseType5 = exports_external5.enum(["base", "hole-filling", "optional"]).meta({ id: "CourseType", description: "Course classification type" });
+var PublishStatus5 = exports_external5.enum(["draft", "testing", "published", "deactivated"]).meta({ id: "PublishStatus", description: "Course publication status" });
 var CourseGoals5 = exports_external5.object({
-  dailyXp: exports_external5.number().int().positive().optional(),
-  dailyLessons: exports_external5.number().int().positive().optional(),
-  dailyActiveMinutes: exports_external5.number().int().positive().optional(),
-  dailyAccuracy: exports_external5.number().int().min(0).max(100).optional(),
-  dailyMasteredUnits: exports_external5.number().int().positive().optional()
-});
+  dailyXp: exports_external5.number().int().positive().meta({ description: "Target XP to earn per day" }).optional(),
+  dailyLessons: exports_external5.number().int().positive().meta({ description: "Target lessons to complete per day" }).optional(),
+  dailyActiveMinutes: exports_external5.number().int().positive().meta({ description: "Target active learning minutes per day" }).optional(),
+  dailyAccuracy: exports_external5.number().int().min(0).max(100).meta({ description: "Target accuracy percentage (0-100)" }).optional(),
+  dailyMasteredUnits: exports_external5.number().int().positive().meta({ description: "Target units to master per day" }).optional()
+}).meta({ id: "CourseGoals", description: "Daily learning goals for a course" });
 var CourseMetrics5 = exports_external5.object({
-  totalXp: exports_external5.number().int().positive().optional(),
-  totalLessons: exports_external5.number().int().positive().optional(),
-  totalGrades: exports_external5.number().int().positive().optional()
-});
+  totalXp: exports_external5.number().int().positive().meta({ description: "Total XP available in the course" }).optional(),
+  totalLessons: exports_external5.number().int().positive().meta({ description: "Total number of lessons/activities" }).optional(),
+  totalGrades: exports_external5.number().int().positive().meta({ description: "Total grade levels covered" }).optional()
+}).meta({ id: "CourseMetrics", description: "Aggregate metrics for a course" });
 var CourseMetadata5 = exports_external5.object({
   courseType: CourseType5.optional(),
-  isSupplemental: exports_external5.boolean().optional(),
-  isCustom: exports_external5.boolean().optional(),
+  isSupplemental: exports_external5.boolean().meta({ description: "Whether this is supplemental to a base course" }).optional(),
+  isCustom: exports_external5.boolean().meta({ description: "Whether this is a custom course for an individual student" }).optional(),
   publishStatus: PublishStatus5.optional(),
-  contactEmail: exports_external5.email().optional(),
-  primaryApp: exports_external5.string().optional(),
+  contactEmail: exports_external5.email().meta({ description: "Contact email for course issues" }).optional(),
+  primaryApp: exports_external5.string().meta({ description: "Primary application identifier" }).optional(),
   goals: CourseGoals5.optional(),
   metrics: CourseMetrics5.optional()
-});
+}).meta({ id: "CourseMetadata", description: "Course metadata (matches API metadata object)" });
 var CourseDefaults5 = exports_external5.object({
-  courseCode: exports_external5.string().optional(),
-  level: exports_external5.string().optional(),
+  courseCode: exports_external5.string().meta({ description: "Course code (e.g., 'MATH101')" }).optional(),
+  level: exports_external5.string().meta({ description: "Course level (e.g., 'AP', 'Honors')" }).optional(),
   metadata: CourseMetadata5.optional()
+}).meta({
+  id: "CourseDefaults",
+  description: "Default properties that apply to all courses unless overridden"
 });
 var CourseEnvOverrides5 = exports_external5.object({
-  level: exports_external5.string().optional(),
-  sensor: exports_external5.string().url().optional(),
-  launchUrl: exports_external5.string().url().optional(),
+  level: exports_external5.string().meta({ description: "Course level for this environment" }).optional(),
+  sensor: exports_external5.url().meta({ description: "Caliper sensor endpoint URL for this environment" }).optional(),
+  launchUrl: exports_external5.url().meta({ description: "LTI launch URL for this environment" }).optional(),
   metadata: CourseMetadata5.optional()
+}).meta({
+  id: "CourseEnvOverrides",
+  description: "Environment-specific course overrides (non-identity fields)"
 });
 var CourseOverrides5 = exports_external5.object({
-  staging: CourseEnvOverrides5.optional(),
-  production: CourseEnvOverrides5.optional()
-});
+  staging: CourseEnvOverrides5.meta({
+    description: "Overrides for staging environment"
+  }).optional(),
+  production: CourseEnvOverrides5.meta({
+    description: "Overrides for production environment"
+  }).optional()
+}).meta({ id: "CourseOverrides", description: "Per-environment course overrides" });
 var CourseConfig5 = CourseDefaults5.extend({
-  subject: TimebackSubject5,
-  grade: TimebackGrade5.optional(),
+  subject: TimebackSubject5.meta({ description: "Subject area for this course" }),
+  grade: TimebackGrade5.meta({
+    description: "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+  }).optional(),
   ids: CourseIds5.nullable().optional(),
-  sensor: exports_external5.string().url().optional(),
-  launchUrl: exports_external5.string().url().optional(),
+  sensor: exports_external5.url().meta({ description: "Caliper sensor endpoint URL for this course" }).optional(),
+  launchUrl: exports_external5.url().meta({ description: "LTI launch URL for this course" }).optional(),
   overrides: CourseOverrides5.optional()
+}).meta({
+  id: "CourseConfig",
+  description: "Configuration for a single course. Must have either grade or courseCode (or both)."
 });
 var TimebackConfig5 = exports_external5.object({
-  name: exports_external5.string().min(1, "App name is required"),
-  defaults: CourseDefaults5.optional(),
-  courses: exports_external5.array(CourseConfig5).min(1, "At least one course is required"),
-  sensor: exports_external5.string().url().optional(),
-  launchUrl: exports_external5.string().url().optional()
+  $schema: exports_external5.string().meta({ description: "JSON Schema reference for editor support" }).optional(),
+  name: exports_external5.string().min(1, "App name is required").meta({ description: "Display name for your app" }),
+  defaults: CourseDefaults5.meta({
+    description: "Default properties applied to all courses"
+  }).optional(),
+  courses: exports_external5.array(CourseConfig5).min(1, "At least one course is required").meta({ description: "Courses available in this app" }),
+  sensor: exports_external5.url().meta({ description: "Default Caliper sensor endpoint URL for all courses" }).optional(),
+  launchUrl: exports_external5.url().meta({ description: "Default LTI launch URL for all courses" }).optional()
+}).meta({
+  id: "TimebackConfig",
+  title: "Timeback Config",
+  description: "Configuration schema for timeback.config.json files"
 }).refine((config22) => {
   return config22.courses.every((c) => c.grade !== undefined || c.courseCode !== undefined);
 }, {
@@ -83503,17 +83779,23 @@ 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]);
+var EdubridgeDateString5 = IsoDateTimeString5;
 var EduBridgeEnrollment5 = exports_external5.object({
   id: exports_external5.string(),
   role: exports_external5.string(),
@@ -83577,12 +83859,9 @@ var EmailOrStudentId5 = exports_external5.object({
 });
 var SubjectTrackInput5 = exports_external5.object({
   subject: NonEmptyString8,
-  gradeLevel: NonEmptyString8,
-  targetCourseId: NonEmptyString8,
-  metadata: exports_external5.record(exports_external5.string(), exports_external5.unknown()).optional()
-});
-var SubjectTrackUpsertInput5 = SubjectTrackInput5.extend({
-  id: NonEmptyString8
+  grade: NonEmptyString8,
+  courseId: NonEmptyString8,
+  orgSourcedId: NonEmptyString8.optional()
 });
 var EdubridgeListEnrollmentsParams5 = exports_external5.object({
   userId: NonEmptyString8
@@ -84978,11 +85257,21 @@ var QtiClient = createQtiClient();
 // src/constants.ts
 var TIMEBACK_ENV_VARS = {
   env: "TIMEBACK_ENV",
-  baseUrl: "TIMEBACK_BASE_URL",
-  authUrl: "TIMEBACK_TOKEN_URL",
-  clientId: "TIMEBACK_CLIENT_ID",
-  clientSecret: "TIMEBACK_CLIENT_SECRET"
+  baseUrl: ["TIMEBACK_API_BASE_URL", "TIMEBACK_BASE_URL"],
+  authUrl: ["TIMEBACK_API_AUTH_URL", "TIMEBACK_AUTH_URL"],
+  clientId: ["TIMEBACK_API_CLIENT_ID", "TIMEBACK_CLIENT_ID"],
+  clientSecret: ["TIMEBACK_API_CLIENT_SECRET", "TIMEBACK_CLIENT_SECRET"]
 };
+function getServiceUrlsForEnv(env, platform = DEFAULT_PLATFORM3) {
+  const endpoints = PLATFORM_ENDPOINTS3[platform];
+  return {
+    oneroster: endpoints.api[env],
+    caliper: endpoints.caliper[env],
+    edubridge: endpoints.api[env],
+    qti: endpoints.qti[env],
+    authUrl: endpoints.token[env]
+  };
+}
 
 // src/client.ts
 class TimebackClient {
@@ -85160,6 +85449,7 @@ class TimebackManager {
 export {
   whereToFilter2 as whereToFilter,
   isApiError,
+  getServiceUrlsForEnv,
   ValidationError3 as ValidationError,
   UnauthorizedError3 as UnauthorizedError,
   TimebackManager,