timeback-cli 0.1.0

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

@@ -0,0 +1,83 @@
+/**
+ * Caliper Types
+ *
+ * Types for the IMS Caliper Analytics standard with Timeback Profile extensions.
+ * Used for learning activity and time spent tracking.
+ *
+ * @see https://www.imsglobal.org/activity/caliper
+ */
+import type { TimebackSubject } from './primitives';
+export interface TimebackUser {
+    id: string;
+    type: 'TimebackUser';
+    email: string;
+}
+export interface TimebackActivityContext {
+    id: string;
+    type: 'TimebackActivityContext';
+    subject: TimebackSubject;
+    app?: {
+        name: string;
+    };
+    activity?: {
+        id?: string;
+        name?: string;
+    };
+    course: {
+        id: string;
+        name: string;
+    };
+    process?: boolean;
+}
+export interface CaliperEventBase {
+    '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2';
+    id: string;
+    type: string;
+    eventTime: string;
+    profile: 'TimebackProfile';
+    actor: TimebackUser;
+    action: string;
+    object: TimebackActivityContext;
+    edApp?: {
+        id: string;
+        name?: string;
+    };
+}
+export interface TimebackActivityMetric {
+    type: 'totalQuestions' | 'correctQuestions' | 'xpEarned' | 'masteredUnits';
+    value: number;
+}
+export interface TimebackActivityMetricsCollection {
+    id: string;
+    type: 'TimebackActivityMetricsCollection';
+    attempt?: number;
+    items: TimebackActivityMetric[];
+    extensions?: Record<string, unknown>;
+}
+export interface TimebackActivityEvent extends CaliperEventBase {
+    type: 'ActivityEvent';
+    action: 'Completed';
+    generated: TimebackActivityMetricsCollection;
+}
+export interface TimebackTimeMetric {
+    type: 'active' | 'inactive' | 'waste' | 'unknown' | 'anti-pattern';
+    value: number;
+    subType?: string;
+}
+export interface TimebackTimeSpentMetricsCollection {
+    id: string;
+    type: 'TimebackTimeSpentMetricsCollection';
+    items: TimebackTimeMetric[];
+}
+export interface TimebackTimeSpentEvent extends CaliperEventBase {
+    type: 'TimeSpentEvent';
+    action: 'SpentTime';
+    generated: TimebackTimeSpentMetricsCollection;
+}
+export type TimebackEvent = TimebackActivityEvent | TimebackTimeSpentEvent;
+export interface CaliperEnvelope {
+    sensor: string;
+    sendTime: string;
+    dataVersion: 'http://purl.imsglobal.org/ctx/caliper/v1p2';
+    data: TimebackEvent[];
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Timeback Config Types
+ *
+ * Types for timeback.config.ts files.
+ */
+import type { TimebackGrade, TimebackSubject } from './primitives';
+/**
+ * Environment-specific course IDs.
+ * Populated by `timeback sync` for each environment.
+ */
+export interface CourseIds {
+    staging?: string;
+    production?: string;
+}
+/**
+ * Course classification type.
+ */
+export type CourseType = 'base' | 'hole-filling' | 'optional';
+/**
+ * Course publication status.
+ */
+export type PublishStatus = 'draft' | 'testing' | 'published' | 'deactivated';
+/**
+ * Daily learning goals for a course.
+ */
+export interface CourseGoals {
+    /** Target XP to earn per day */
+    dailyXp?: number;
+    /** Target lessons to complete per day */
+    dailyLessons?: number;
+    /** Target active learning minutes per day */
+    dailyActiveMinutes?: number;
+    /** Target accuracy percentage (0-100) */
+    dailyAccuracy?: number;
+    /** Target units to master per day */
+    dailyMasteredUnits?: number;
+}
+/**
+ * Aggregate metrics for a course.
+ */
+export interface CourseMetrics {
+    /** Total XP available in the course */
+    totalXp?: number;
+    /** Total number of lessons/activities */
+    totalLessons?: number;
+    /** Total grade levels covered */
+    totalGrades?: number;
+}
+/**
+ * Course metadata (matches API metadata object).
+ */
+export interface CourseMetadata {
+    /** Course classification (base, hole-filling, optional) */
+    courseType?: CourseType;
+    /** Whether this is supplemental to a base course */
+    isSupplemental?: boolean;
+    /** Whether this is a custom course for an individual student */
+    isCustom?: boolean;
+    /** Publication status */
+    publishStatus?: PublishStatus;
+    /** Contact email for course issues */
+    contactEmail?: string;
+    /** Primary application identifier */
+    primaryApp?: string;
+    /** Daily learning goals */
+    goals?: CourseGoals;
+    /** Aggregate metrics */
+    metrics?: CourseMetrics;
+}
+/**
+ * Default properties that apply to all courses unless overridden.
+ * Set these at the root level to avoid repetition.
+ */
+export interface CourseDefaults {
+    /** Course code (e.g., "MATH101") */
+    courseCode?: string;
+    /** Course level (e.g., "AP", "Honors") */
+    level?: string;
+    /** Course metadata */
+    metadata?: CourseMetadata;
+}
+/**
+ * Configuration for a single course in a Timeback app.
+ */
+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;
+    /** Timeback course IDs per environment (populated after sync) */
+    ids?: CourseIds | null;
+}
+/**
+ * Root configuration for a Timeback app.
+ * Define this in your timeback.config.ts file.
+ */
+export interface TimebackConfig {
+    /** Display name for your app */
+    name: string;
+    /** Default properties applied to all courses */
+    defaults?: CourseDefaults;
+    /** Courses available in this app */
+    courses: CourseConfig[];
+    /** Caliper sensor URLs for event filtering */
+    sensors?: string[];
+}

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

@@ -0,0 +1,67 @@
+/**
+ * EduBridge Types
+ *
+ * Types for the EduBridge analytics aggregation API.
+ * Provides enrollment and metrics data.
+ */
+/**
+ * EduBridge enrollment data.
+ * Note: EduBridge returns grades/subjects as strings, not typed values.
+ */
+export interface EduBridgeEnrollment {
+    id: string;
+    role: string;
+    beginDate: string | null;
+    endDate: string | null;
+    metadata?: {
+        goals?: {
+            dailyXp?: number;
+        };
+        metrics?: {
+            totalXp?: number;
+            totalLessons?: number;
+        };
+    };
+    course: {
+        id: string;
+        title: string;
+        subjects: string[] | null;
+        grades: string[] | null;
+    };
+    school: {
+        id: string;
+        name: string;
+    };
+}
+/**
+ * EduBridge analytics facts indexed by date and subject.
+ */
+export interface EduBridgeAnalyticsFacts {
+    [date: string]: {
+        [subject: string]: {
+            activityMetrics: {
+                xpEarned: number;
+                totalQuestions: number;
+                correctQuestions: number;
+                masteredUnits: number;
+            };
+            timeSpentMetrics: {
+                activeSeconds: number;
+                inactiveSeconds: number;
+                wasteSeconds: number;
+            };
+            apps: string[];
+        };
+    };
+}
+/**
+ * EduBridge enrollment analytics response.
+ */
+export interface EduBridgeEnrollmentAnalyticsResponse {
+    message: string;
+    enrollmentId: string;
+    startDate: string;
+    endDate: string;
+    facts: EduBridgeAnalyticsFacts;
+    factsByApp: unknown;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * TypeScript types for Timeback platform protocols.
+ */
+export * from './primitives';
+export * from './caliper';
+export * from './config';
+export * from './edubridge';

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

@@ -0,0 +1,56 @@
+/**
+ * Timeback Primitives
+ *
+ * Core enums and literal types used across Timeback protocols.
+ */
+/**
+ * Valid Timeback subject values.
+ * Used in OneRoster courses and Caliper events.
+ */
+export type TimebackSubject = 'Reading' | 'Language' | 'Vocabulary' | 'Social Studies' | 'Writing' | 'Science' | 'FastMath' | 'Math' | 'None' | 'Other';
+/**
+ * Grade levels per Timeback OneRoster GradeEnum (numeric).
+ * -1 = Pre-K, 0 = Kindergarten, 1-12 = Grades 1-12, 13 = AP
+ *
+ * Use for input types where numbers are accepted.
+ */
+export type TimebackGrade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+/**
+ * Grade levels as strings (API response format).
+ * The database stores grades as text, so API responses return strings.
+ *
+ * Use for response types.
+ */
+export type TimebackGradeString = '-1' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13';
+/**
+ * OneRoster assessment result score status values.
+ */
+export type ScoreStatus = 'exempt' | 'fully graded' | 'not submitted' | 'partially graded' | 'submitted';
+/**
+ * OneRoster organization types.
+ */
+export type OrganizationType = 'department' | 'school' | 'district' | 'local' | 'state' | 'national';
+/**
+ * OneRoster user role types.
+ */
+export type OneRosterUserRole = 'administrator' | 'aide' | 'guardian' | 'parent' | 'proctor' | 'relative' | 'student' | 'teacher';
+/**
+ * Lesson types for PowerPath integration.
+ */
+export type LessonType = 'powerpath-100' | 'quiz' | 'test-out' | 'placement' | 'unit-test' | 'alpha-read-article' | null;
+/**
+ * IMS Global error response format.
+ * Used across OneRoster, Caliper, and other 1EdTech protocols.
+ */
+export interface IMSErrorResponse {
+    imsx_codeMajor: 'failure' | 'success';
+    imsx_severity: 'error' | 'warning' | 'status';
+    imsx_description: string;
+    imsx_CodeMinor?: {
+        imsx_codeMinorField: Array<{
+            imsx_codeMinorFieldName: string;
+            imsx_codeMinorFieldValue: string;
+        }>;
+    };
+    imsx_error_details?: Array<Record<string, string>>;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "timeback-cli",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		"./config": {
+			"types": "./dist/config.d.ts",
+			"import": "./dist/config.d.ts",
+			"default": "./dist/config.d.ts"
+		}
+	},
+	"types": "./dist/config.d.ts",
+	"bin": {
+		"timeback": "./dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"schema.json"
+	],
+	"scripts": {
+		"build": "bun build.ts",
+		"dev": "DEBUG=1 bun src/cli.ts",
+		"dev:studio": "DEBUG=studio:* bun src/cli.ts studio",
+		"start": "bun dist/cli.js",
+		"unused": "bunx ts-unused-exports tsconfig.json --ignoreFiles='(dist|timeback\\.config\\.ts|src/config\\.ts)'"
+	},
+	"dependencies": {
+		"@clack/prompts": "^0.11.0",
+		"colorette": "^2.0.20",
+		"commander": "^14.0.2",
+		"jiti": "^2.6.1",
+		"zod": "^4.2.1"
+	},
+	"devDependencies": {
+		"@timeback/caliper": "0.1.0",
+		"@timeback/core": "0.1.0",
+		"@timeback/edubridge": "0.1.0",
+		"@timeback/internal-cli-infra": "0.0.0",
+		"@timeback/internal-client-infra": "0.0.0",
+		"@timeback/internal-utils": "0.0.0",
+		"@timeback/oneroster": "0.1.0",
+		"@timeback/types": "0.0.0",
+		"@types/bun": "latest",
+		"bun-plugin-dts": "^0.3.0",
+		"timeback-studio": "0.1.0"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}

package/schema.json

@@ -0,0 +1,221 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://timeback.dev/schemas/timeback.config.schema.json",
+	"title": "Timeback Config",
+	"description": "Configuration schema for timeback.config.ts files",
+	"type": "object",
+	"required": ["name", "courses"],
+	"properties": {
+		"$schema": {
+			"type": "string",
+			"description": "JSON Schema reference for editor support"
+		},
+		"name": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Display name for your app"
+		},
+		"defaults": {
+			"$ref": "#/$defs/CourseDefaults",
+			"description": "Default properties applied to all courses"
+		},
+		"courses": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"$ref": "#/$defs/CourseConfig"
+			},
+			"description": "Courses available in this app"
+		}
+	},
+	"$defs": {
+		"TimebackSubject": {
+			"type": "string",
+			"enum": [
+				"Reading",
+				"Language",
+				"Vocabulary",
+				"Social Studies",
+				"Writing",
+				"Science",
+				"FastMath",
+				"Math",
+				"None"
+			],
+			"description": "Subject area"
+		},
+		"TimebackGrade": {
+			"type": "integer",
+			"minimum": -1,
+			"maximum": 13,
+			"description": "Grade level (-1 = Pre-K, 0 = K, 1-12 = grades, 13 = AP)"
+		},
+		"CourseType": {
+			"type": "string",
+			"enum": ["base", "hole-filling", "optional"],
+			"description": "Course classification type"
+		},
+		"PublishStatus": {
+			"type": "string",
+			"enum": ["draft", "testing", "published", "deactivated"],
+			"description": "Course publication status"
+		},
+		"CourseGoals": {
+			"type": "object",
+			"description": "Daily learning goals for a course",
+			"properties": {
+				"dailyXp": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Target XP to earn per day"
+				},
+				"dailyLessons": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Target lessons to complete per day"
+				},
+				"dailyActiveMinutes": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Target active learning minutes per day"
+				},
+				"dailyAccuracy": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 100,
+					"description": "Target accuracy percentage (0-100)"
+				},
+				"dailyMasteredUnits": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Target units to master per day"
+				}
+			},
+			"additionalProperties": false
+		},
+		"CourseMetrics": {
+			"type": "object",
+			"description": "Aggregate metrics for a course",
+			"properties": {
+				"totalXp": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Total XP available in the course"
+				},
+				"totalLessons": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Total number of lessons/activities"
+				},
+				"totalGrades": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Total grade levels covered"
+				}
+			},
+			"additionalProperties": false
+		},
+		"CourseIds": {
+			"type": ["object", "null"],
+			"description": "Environment-specific course IDs (populated by sync)",
+			"properties": {
+				"staging": {
+					"type": "string",
+					"description": "Course ID in staging environment"
+				},
+				"production": {
+					"type": "string",
+					"description": "Course ID in production environment"
+				}
+			},
+			"additionalProperties": false
+		},
+		"CourseMetadata": {
+			"type": "object",
+			"description": "Course metadata (matches API metadata object)",
+			"properties": {
+				"courseType": {
+					"$ref": "#/$defs/CourseType"
+				},
+				"isSupplemental": {
+					"type": "boolean",
+					"description": "Whether this is supplemental to a base course"
+				},
+				"isCustom": {
+					"type": "boolean",
+					"description": "Whether this is a custom course for an individual student"
+				},
+				"publishStatus": {
+					"$ref": "#/$defs/PublishStatus"
+				},
+				"contactEmail": {
+					"type": "string",
+					"format": "email",
+					"description": "Contact email for course issues"
+				},
+				"primaryApp": {
+					"type": "string",
+					"description": "Primary application identifier"
+				},
+				"goals": {
+					"$ref": "#/$defs/CourseGoals"
+				},
+				"metrics": {
+					"$ref": "#/$defs/CourseMetrics"
+				}
+			},
+			"additionalProperties": false
+		},
+		"CourseDefaults": {
+			"type": "object",
+			"description": "Default properties that apply to all courses unless overridden",
+			"properties": {
+				"courseCode": {
+					"type": "string",
+					"description": "Course code (e.g., 'MATH101')"
+				},
+				"level": {
+					"type": "string",
+					"description": "Course level (e.g., 'AP', 'Honors')"
+				},
+				"metadata": {
+					"$ref": "#/$defs/CourseMetadata"
+				}
+			},
+			"additionalProperties": false
+		},
+		"CourseConfig": {
+			"type": "object",
+			"description": "Configuration for a single course",
+			"required": ["subject", "grade"],
+			"allOf": [
+				{
+					"$ref": "#/$defs/CourseDefaults"
+				}
+			],
+			"properties": {
+				"subject": {
+					"$ref": "#/$defs/TimebackSubject"
+				},
+				"grade": {
+					"$ref": "#/$defs/TimebackGrade"
+				},
+				"courseCode": {
+					"type": "string",
+					"description": "Course code (e.g., 'MATH101')"
+				},
+				"level": {
+					"type": "string",
+					"description": "Course level (e.g., 'AP', 'Honors')"
+				},
+				"metadata": {
+					"$ref": "#/$defs/CourseMetadata"
+				},
+				"ids": {
+					"$ref": "#/$defs/CourseIds"
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}