timeback 0.1.4 → 0.1.5

package/dist/types/src/config.d.ts

@@ -2,6 +2,10 @@
  * Timeback Config Types
  *
  * Types for timeback.config.ts files.
+ *
+ * Note: Runtime validation is enforced by `@timeback/types/zod` (see
+ * `packages/types/src/zod/config.ts`). These TS types are a convenience layer
+ * and should not be treated as a replacement for Zod validation.
  */
 import type { TimebackGrade, TimebackSubject } from './primitives';
 /**
@@ -79,20 +83,88 @@ export interface CourseDefaults {
     /** Course metadata */
     metadata?: CourseMetadata;
 }
+/**
+ * Environment-specific course overrides.
+ *
+ * Non-identity fields that can differ per environment.
+ * Excludes `subject`, `grade`, `courseCode` (identity) and `ids` (already env-scoped).
+ */
+export interface CourseEnvOverrides {
+    /** Course level override for this environment */
+    level?: string;
+    /** Caliper sensor URL override for this environment */
+    sensor?: string;
+    /** Launch URL override for this environment (used in dashboard resource links) */
+    launchUrl?: string;
+    /** Metadata override for this environment (merged with base metadata) */
+    metadata?: CourseMetadata;
+}
+/**
+ * Per-environment course overrides.
+ *
+ * Allows staging and production to have different non-identity properties.
+ */
+export interface CourseOverrides {
+    /** Overrides applied when syncing to staging */
+    staging?: CourseEnvOverrides;
+    /** Overrides applied when syncing to production */
+    production?: CourseEnvOverrides;
+}
 /**
  * Configuration for a single course in a Timeback app.
+ *
+ * Course identity is determined by one of:
+ * - **Grade-based**: `(subject, grade)` — traditional K-12 courses
+ * - **Grade-less**: `courseCode` — apps without grade levels (e.g., CS platforms)
+ *
+ * At least one identity must be present:
+ * - If `grade` is provided, the course is identified by `(subject, grade)`.
+ * - If `grade` is omitted, `courseCode` is required as the identifier.
+ *
+ * Sensor/LaunchUrl resolution:
+ * - Each course must have an effective sensor (either `course.sensor` or top-level `sensor`).
+ * - Each course must have an effective launchUrl (either `course.launchUrl` or top-level `launchUrl`).
+ *
+ * Environment overrides:
+ * - Use `overrides.staging` or `overrides.production` to vary non-identity fields per env.
  */
 export interface CourseConfig extends CourseDefaults {
     /** Subject area (e.g., 'Math', 'Reading') */
     subject: TimebackSubject;
-    /** Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP) */
-    grade: TimebackGrade;
+    /**
+     * Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP).
+     * Optional for grade-less apps; if omitted, `courseCode` is required.
+     */
+    grade?: TimebackGrade;
     /** Timeback course IDs per environment (populated after sync) */
     ids?: CourseIds | null;
+    /**
+     * Caliper sensor URL for this course.
+     * Overrides the top-level `sensor` if set.
+     */
+    sensor?: string;
+    /**
+     * Launch URL for this course (used in dashboard resource links).
+     * Overrides the top-level `launchUrl` if set.
+     */
+    launchUrl?: string;
+    /**
+     * Environment-specific overrides for non-identity fields.
+     * Merged with base course config when syncing to a specific environment.
+     */
+    overrides?: CourseOverrides;
 }
 /**
  * Root configuration for a Timeback app.
  * Define this in your timeback.config.ts file.
+ *
+ * Sensor resolution: every course must have an effective sensor.
+ * - Set `sensor` at the top level as a default for all courses.
+ * - Override per course with `courses[].sensor`.
+ *
+ * LaunchUrl resolution: every course must have an effective launchUrl.
+ * - Set `launchUrl` at the top level as a default for all courses.
+ * - Override per course with `courses[].launchUrl`.
  */
 export interface TimebackConfig {
     /** Display name for your app */
@@ -101,6 +173,14 @@ export interface TimebackConfig {
     defaults?: CourseDefaults;
     /** Courses available in this app */
     courses: CourseConfig[];
-    /** Caliper sensor URLs for event filtering */
-    sensors?: string[];
+    /**
+     * Default Caliper sensor URL for activity events.
+     * Can be overridden per course with `courses[].sensor`.
+     */
+    sensor?: string;
+    /**
+     * Default launch URL for dashboard resource links.
+     * Can be overridden per course with `courses[].launchUrl`.
+     */
+    launchUrl?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "timeback",
-	"version": "0.1.4",
+	"version": "0.1.5",
 	"type": "module",
 	"exports": {
 		"./config": {
@@ -19,6 +19,7 @@
 	],
 	"scripts": {
 		"build": "bun build.ts",
+		"build:binary": "bun build-binary.ts --checksums",
 		"dev": "DEBUG=1 bun src/cli.ts",
 		"dev:studio": "DEBUG=studio:* bun src/cli.ts studio",
 		"start": "bun dist/cli.js",
@@ -32,18 +33,19 @@
 		"zod": "^4.2.1"
 	},
 	"devDependencies": {
-		"@timeback/caliper": "0.1.1",
-		"@timeback/core": "0.1.2",
+		"@timeback/caliper": "0.1.2",
+		"@timeback/core": "0.1.3",
 		"@timeback/edubridge": "0.1.1",
 		"@timeback/internal-cli-infra": "0.0.0",
 		"@timeback/internal-client-infra": "0.0.0",
 		"@timeback/internal-utils": "0.0.0",
-		"@timeback/oneroster": "0.1.2",
+		"@timeback/oneroster": "0.1.3",
+		"@timeback/powerpath": "0.1.1",
 		"@timeback/qti": "0.1.1",
 		"@timeback/types": "0.0.0",
 		"@types/bun": "latest",
 		"bun-plugin-dts": "^0.3.0",
-		"timeback-studio": "0.1.2"
+		"timeback-studio": "0.1.3"
 	},
 	"peerDependencies": {
 		"typescript": "^5"