timeback 0.1.3 → 0.1.5

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

@@ -0,0 +1,186 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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).
+     * 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 */
+    name: string;
+    /** Default properties applied to all courses */
+    defaults?: CourseDefaults;
+    /** Courses available in this app */
+    courses: CourseConfig[];
+    /**
+     * 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/dist/types/src/index.d.ts

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

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

@@ -0,0 +1,53 @@
+/**
+ * Timeback Shared Primitives
+ *
+ * Core types used across multiple Timeback protocols.
+ *
+ * Organization:
+ * - Shared types (this file): Used by multiple protocols (Caliper, OneRoster, etc.)
+ * - Protocol-specific types: Live in their respective protocols/X/primitives.ts files
+ *
+ * What belongs here:
+ * - TimebackSubject - Used in OneRoster courses AND Caliper events
+ * - TimebackGrade - Used across OneRoster, Caliper, and QTI
+ * - IMSErrorResponse - IMS Global standard used by multiple 1EdTech protocols
+ *
+ * What doesn't belong here:
+ * - OneRoster-specific: protocols/oneroster/primitives.ts
+ * - QTI-specific: protocols/qti/primitives.ts
+ */
+/**
+ * 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';
+/**
+ * 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

@@ -1,115 +1,53 @@
 {
 	"name": "timeback",
-	"version": "0.1.3",
-	"description": "Timeback SDK for frontend and backend integration",
+	"version": "0.1.5",
 	"type": "module",
 	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./client": {
-			"types": "./dist/client.d.ts",
-			"import": "./dist/client.js"
-		},
-		"./identity": {
-			"types": "./dist/identity.d.ts",
-			"import": "./dist/identity.js"
-		},
-		"./edge": {
-			"types": "./dist/edge.d.ts",
-			"import": "./dist/edge.js"
-		},
-		"./react": {
-			"types": "./dist/client/adapters/react/index.d.ts",
-			"import": "./dist/client/adapters/react/index.js"
-		},
-		"./svelte": {
-			"types": "./dist/client/adapters/svelte/index.d.ts",
-			"svelte": "./dist/client/adapters/svelte/index.ts",
-			"import": "./dist/client/adapters/svelte/index.ts"
-		},
-		"./solid": {
-			"types": "./dist/client/adapters/solid/index.d.ts",
-			"solid": "./dist/client/adapters/solid/index.ts",
-			"import": "./dist/client/adapters/solid/index.ts"
-		},
-		"./native": {
-			"types": "./dist/server/adapters/native.d.ts",
-			"import": "./dist/server/adapters/native.js"
-		},
-		"./nextjs": {
-			"types": "./dist/server/adapters/nextjs.d.ts",
-			"import": "./dist/server/adapters/nextjs.js"
-		},
-		"./svelte-kit": {
-			"types": "./dist/server/adapters/svelte-kit.d.ts",
-			"import": "./dist/server/adapters/svelte-kit.js"
-		},
-		"./solid-start": {
-			"types": "./dist/server/adapters/solid-start.d.ts",
-			"import": "./dist/server/adapters/solid-start.js"
-		},
-		"./express": {
-			"types": "./dist/server/adapters/express.d.ts",
-			"import": "./dist/server/adapters/express.js"
-		},
-		"./tanstack-start": {
-			"types": "./dist/server/adapters/tanstack-start.d.ts",
-			"import": "./dist/server/adapters/tanstack-start.js"
-		},
-		"./vue": {
-			"types": "./dist/client/adapters/vue/index.d.ts",
-			"import": "./dist/client/adapters/vue/index.ts"
-		},
-		"./nuxt": {
-			"types": "./dist/server/adapters/nuxt.d.ts",
-			"import": "./dist/server/adapters/nuxt.js"
+		"./config": {
+			"types": "./dist/config.d.ts",
+			"import": "./dist/config.d.ts",
+			"default": "./dist/config.d.ts"
 		}
 	},
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
+	"types": "./dist/config.d.ts",
+	"bin": {
+		"timeback": "./dist/cli.js"
+	},
 	"files": [
-		"dist"
+		"dist",
+		"schema.json"
 	],
 	"scripts": {
 		"build": "bun build.ts",
-		"test": "bun test --no-env-file unit.test.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",
+		"unused": "bunx ts-unused-exports tsconfig.json --ignoreFiles='(dist|timeback\\.config\\.ts|src/config\\.ts)'"
 	},
 	"dependencies": {
-		"@timeback/core": "0.1.1",
+		"@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/caliper": "0.1.2",
+		"@timeback/core": "0.1.3",
+		"@timeback/edubridge": "0.1.1",
 		"@timeback/internal-cli-infra": "0.0.0",
-		"@timeback/internal-logger": "0.0.0",
+		"@timeback/internal-client-infra": "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/types": "0.0.0",
 		"@types/bun": "latest",
-		"@types/express": "^5.0.6",
-		"@types/react": "^19.1.8"
+		"bun-plugin-dts": "^0.3.0",
+		"timeback-studio": "0.1.3"
 	},
 	"peerDependencies": {
-		"react": "^18 || ^19",
-		"solid-js": "^1.9.10",
-		"svelte": "^4 || ^5",
-		"typescript": "^5",
-		"vue": "^3"
-	},
-	"peerDependenciesMeta": {
-		"react": {
-			"optional": true
-		},
-		"solid-js": {
-			"optional": true
-		},
-		"svelte": {
-			"optional": true
-		},
-		"vue": {
-			"optional": true
-		}
+		"typescript": "^5"
 	}
 }

package/schema.json

@@ -0,0 +1,222 @@
+{
+	"$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",
+				"Other"
+			],
+			"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
+		}
+	}
+}

package/dist/client/adapters/react/SignInButton.d.ts

@@ -1,60 +0,0 @@
-/**
- * Sign In with Timeback Button
- *
- * A pre-styled button for Timeback SSO authentication.
- * Fully customizable via CSS variables.
- */
-import * as React from 'react';
-/**
- * Props for SignInButton component.
- */
-export interface SignInButtonProps {
-    /** Button text (default: "Sign in with Timeback") */
-    children?: React.ReactNode;
-    /** Additional CSS class names */
-    className?: string;
-    /** Inline styles */
-    style?: React.CSSProperties;
-    /** Disabled state */
-    disabled?: boolean;
-    /** Show loading spinner when clicked */
-    showLoading?: boolean;
-    /** Called before redirect (can prevent with e.preventDefault()) */
-    onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-    /** Button variant */
-    variant?: 'default' | 'outline' | 'minimal';
-    /** Button size */
-    size?: 'sm' | 'md' | 'lg';
-    /** Show Timeback logo */
-    showLogo?: boolean;
-}
-/**
- * Sign In with Timeback button component.
- *
- * Triggers SSO authentication flow when clicked.
- *
- * @param props - Component props
- * @returns Button element
- *
- * @example
- * ```tsx
- * // Basic usage
- * <SignInButton />
- *
- * // Custom text
- * <SignInButton>Continue with Timeback</SignInButton>
- *
- * // Outline variant
- * <SignInButton variant="outline" />
- *
- * // Custom styling via CSS variables
- * <SignInButton
- *   style={{
- *     '--tb-btn-bg': '#6366f1',
- *     '--tb-btn-bg-hover': '#4f46e5',
- *   } as React.CSSProperties}
- * />
- * ```
- */
-export declare function SignInButton(props: SignInButtonProps): React.ReactElement;
-//# sourceMappingURL=SignInButton.d.ts.map

package/dist/client/adapters/react/SignInButton.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SignInButton.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/react/SignInButton.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wCAAwC;IACxC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAA;IAC1D,qBAAqB;IACrB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;IAC3C,kBAAkB;IAClB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB;AA8MD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,CAAC,YAAY,CA4DzE"}