@timeback/core 0.1.3 → 0.1.4

package/dist/utils.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(", ")}`;
 }
@@ -1264,10 +1286,10 @@ function validateNonEmptyString(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 resolveToProvider2(config, registry = DEFAULT_PROVIDER_REGISTRY) {
   return resolveToProvider(config, EDUBRIDGE_ENV_VARS, registry);
@@ -3595,7 +3617,7 @@ class Doc {
 var version = {
   major: 4,
   minor: 3,
-  patch: 5
+  patch: 6
 };
 var $ZodType = /* @__PURE__ */ $constructor("$ZodType", (inst, def) => {
   var _a;
@@ -4879,7 +4901,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) {
@@ -12196,7 +12218,7 @@ function finalize(ctx, schema) {
           }
         }
       }
-      if (refSchema.$ref) {
+      if (refSchema.$ref && refSeen.def) {
         for (const key in schema2) {
           if (key === "$ref" || key === "allOf")
             continue;
@@ -14828,7 +14850,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),
@@ -14845,7 +14867,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",
@@ -15075,62 +15100,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);
 }, {
@@ -15151,17 +15198,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(),
@@ -15225,13 +15278,11 @@ 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 SubjectTrackUpsertInput = SubjectTrackInput;
 var EdubridgeListEnrollmentsParams = exports_external.object({
   userId: NonEmptyString
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@timeback/core",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"type": "module",
 	"exports": {
 		".": {
@@ -30,14 +30,15 @@
 		"test": "bun test --no-env-file unit.test.ts"
 	},
 	"devDependencies": {
-		"@timeback/caliper": "0.1.2",
-		"@timeback/edubridge": "0.1.1",
+		"@timeback/caliper": "0.1.3",
+		"@timeback/edubridge": "0.1.3",
 		"@timeback/internal-client-infra": "0.0.0",
 		"@timeback/internal-constants": "0.0.0",
+		"@timeback/internal-test": "0.0.0",
 		"@timeback/internal-utils": "0.0.0",
-		"@timeback/oneroster": "0.1.3",
-		"@timeback/powerpath": "0.1.1",
-		"@timeback/qti": "0.1.1",
+		"@timeback/oneroster": "0.1.5",
+		"@timeback/powerpath": "0.1.2",
+		"@timeback/qti": "0.1.2",
 		"@types/bun": "latest"
 	},
 	"peerDependencies": {