@timeback/sdk 0.1.9 → 0.1.11

package/dist/shared/types.ts

@@ -0,0 +1,636 @@
+/**
+ * Shared Types
+ *
+ * Types shared between client and server.
+ */
+
+import type { TimebackGrade, TimebackSubject } from '@timeback/types'
+
+/**
+ * User identity returned from SSO.
+ */
+export interface TimebackIdentity {
+	id: string
+	email: string
+	name?: string
+}
+
+/**
+ * Timeback user profile with enriched data from the Timeback API.
+ */
+export interface TimebackProfile {
+	/** Timeback user ID */
+	id: string
+	/** User's email address */
+	email: string
+	/** User's display name */
+	name?: string
+
+	/** School information */
+	school?: {
+		id: string
+		name: string
+	}
+
+	/** Grade level */
+	grade?: number
+
+	/** XP earned on this app */
+	xp?: {
+		/** XP earned today (UTC day range) */
+		today: number
+		/** XP earned across all time (computed from analytics) */
+		all: number
+	}
+
+	/** Enrolled courses */
+	courses?: Array<{
+		id: string
+		code: string
+		name: string
+	}>
+
+	/** Goals and progress */
+	goals?: {
+		dailyXp?: number
+		dailyLessons?: number
+		dailyActiveMinutes?: number
+		dailyAccuracy?: number
+		dailyMasteredUnits?: number
+	}
+}
+
+/**
+ * Recommended minimal user payload to persist in a session.
+ *
+ * **User-facing note:** this type is part of the SDK’s developer experience.
+ * It exists to give you a “safe default” session shape that works well for
+ * cookie-based sessions (small payload) while still carrying enough Timeback
+ * context to power common UI affordances (e.g. showing a school name or grade).
+ *
+ * **What it is:** a minimal, serializable subset of `TimebackProfile`.
+ * **What it isn’t:** a guarantee that you’ll always have the full Timeback
+ * profile (courses, goals, xp, etc.) in-session. If you need richer data, fetch
+ * it from the API (e.g. `timeback.user.fetch()`) and cache/store it according
+ * to your app’s needs.
+ *
+ * **Stability:** this is still early and we’re actively iterating on identity
+ * and session ergonomics. We may rename, restructure, or remove this type from
+ * the public surface as the SDK evolves.
+ */
+export type TimebackSessionUser = Pick<
+	TimebackProfile,
+	'id' | 'email' | 'name' | 'school' | 'grade'
+>
+
+/**
+ * Claims from the identity provider (IdP).
+ *
+ * Normalized subset of OIDC UserInfo claims.
+ */
+export interface IdentityClaims {
+	/** Subject identifier (unique user ID from IdP) */
+	sub: string
+	/** User's email address */
+	email: string
+	/** User's first/given name */
+	firstName?: string
+	/** User's last/family name */
+	lastName?: string
+	/** User's profile picture URL */
+	pictureUrl?: string
+}
+
+/**
+ * Authenticated user with Timeback profile and IdP claims.
+ *
+ * This is the primary user object returned during SSO callback when using
+ * `createTimeback()`. The `id` field is the canonical `timebackId` (stable identifier).
+ */
+export interface TimebackAuthUser extends TimebackProfile {
+	/** IdP claims (raw identity provider data) */
+	claims: IdentityClaims
+}
+
+/**
+ * Course selector by subject and grade (grade-based apps).
+ *
+ * Use this for traditional K-12 apps where courses are identified by subject + grade.
+ */
+export interface SubjectGradeCourseRef {
+	subject: TimebackSubject
+	grade: TimebackGrade
+}
+
+/**
+ * Course selector by code (grade-less apps).
+ *
+ * Use this for apps without grade levels (e.g., CS platforms) where courses
+ * are identified by a unique course code.
+ */
+export interface CourseCodeRef {
+	code: string
+}
+
+/**
+ * Course selector for activity tracking.
+ *
+ * This should correspond to a unique course entry in `timeback.config.json`.
+ *
+ * Two selector modes are supported:
+ * - **Grade-based**: `{ subject, grade }` — K-12 style
+ * - **Grade-less**: `{ code }` — CS/skill-based
+ *
+ * @example
+ * ```typescript
+ * // Grade-based
+ * { subject: 'Math', grade: 3 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Grade-less
+ * { code: 'CS-101' }
+ * ```
+ */
+export type ActivityCourseRef = SubjectGradeCourseRef | CourseCodeRef
+
+/**
+ * Type guard: Check if a course ref uses subject+grade identity.
+ *
+ * @param ref - Course reference to check
+ * @returns True if grade-based selector
+ */
+export function isSubjectGradeCourseRef(ref: ActivityCourseRef): ref is SubjectGradeCourseRef {
+	return 'grade' in ref && ref.grade !== undefined
+}
+
+/**
+ * Time tracking configuration options.
+ *
+ * Controls how the SDK tracks and reports time-spent data via heartbeats.
+ */
+export interface TimeTrackingOptions {
+	/**
+	 * Interval in milliseconds between automatic heartbeat flushes.
+	 * @default 15000 (15 seconds)
+	 */
+	flushIntervalMs?: number
+	/**
+	 * Whether to pause time tracking when the tab is not visible.
+	 * @default true
+	 */
+	visibilityAware?: boolean
+	/**
+	 * Whether to flush accumulated time when the tab becomes hidden.
+	 * @default true
+	 */
+	flushOnVisibilityHidden?: boolean
+	/**
+	 * Whether to attempt a best-effort flush on page unload (pagehide event).
+	 *
+	 * Implementation notes:
+	 * - Prefer `navigator.sendBeacon()` when available and safe to use
+	 * - Fall back to `fetch(..., { keepalive: true })` otherwise
+	 *
+	 * sendBeacon cannot set arbitrary headers (e.g. Authorization), so
+	 * integrations that rely on bearer tokens typically use the keepalive
+	 * fetch fallback.
+	 * @default true
+	 */
+	flushOnPageHide?: boolean
+	/**
+	 * Timeout in milliseconds after which hidden time stops being tracked.
+	 *
+	 * When the tab is hidden for longer than this duration, heartbeats stop
+	 * and the hidden time is not counted. When the user returns, tracking
+	 * resumes fresh without counting the extended absence.
+	 *
+	 * Set to `null` or `Infinity` to disable (always track hidden time).
+	 * @default 600000 (10 minutes)
+	 */
+	hiddenTimeoutMs?: number | null
+	/**
+	 * Number of retry attempts for failed heartbeat sends.
+	 *
+	 * Set to `0` (default) for no retries. Retries use exponential backoff
+	 * with delays configured by `retryDelaysMs`.
+	 *
+	 * @default 0
+	 */
+	retryAttempts?: number
+	/**
+	 * Delay schedule (in milliseconds) between retry attempts.
+	 *
+	 * Each index corresponds to the delay before that retry attempt.
+	 * If more attempts are made than there are entries, the last value is reused.
+	 *
+	 * @default [100, 300, 1000]
+	 */
+	retryDelaysMs?: number[]
+}
+
+/**
+ * Activity start parameters.
+ *
+ * @remarks
+ * The `id` field is treated as a **slug** (not a URL). The SDK derives the
+ * canonical activity URL (`event.object.id`) from:
+ * - The configured sensor URL
+ * - The course selector (subject + grade or code)
+ * - This slug (URI-encoded)
+ *
+ * This allows upstream systems to process activities without requiring
+ * pre-synced OneRoster component resources.
+ *
+ * @example
+ * ```typescript
+ * // Grade-based course
+ * timeback.activity.start({
+ *   id: 'fractions-with-like-denominators', // slug
+ *   name: 'Fractions with Like Denominators', // human-readable
+ *   course: { subject: 'Math', grade: 3 },
+ * })
+ * // => object.id: https://sensor.example.com/activities/Math/g3/fractions-with-like-denominators
+ *
+ * // Grade-less course
+ * timeback.activity.start({
+ *   id: 'intro-to-loops',
+ *   name: 'Introduction to Loops',
+ *   course: { code: 'CS-101' },
+ * })
+ * // => object.id: https://sensor.example.com/activities/CS-101/intro-to-loops
+ * ```
+ */
+export interface ActivityParams {
+	/**
+	 * Activity slug (stable identifier for the learning object).
+	 *
+	 * This is used to construct the canonical activity URL sent to Caliper.
+	 * Use a short, URL-safe slug like `"fractions-with-like-denominators"` or
+	 * `"lesson-1"`. Special characters will be URI-encoded.
+	 *
+	 * @example
+	 * ```typescript
+	 * // 'fractions-with-like-denominators'
+	 * ```
+	 * @example
+	 * ```typescript
+	 * // 'ccss.math.content.3.nf.a.1'
+	 * ```
+	 * @example
+	 * ```typescript
+	 * // 'lesson-1'
+	 * ```
+	 */
+	id: string
+	/**
+	 * Human-readable display name of the activity.
+	 *
+	 * This is sent as `object.activity.name` in Caliper events.
+	 *
+	 * @example
+	 * ```typescript
+	 * // 'Fractions with Like Denominators'
+	 * ```
+	 */
+	name: string
+	/** Course selector (must match a unique course in timeback.config.json) */
+	course: ActivityCourseRef
+	/**
+	 * Optional run identifier for correlating events across sessions.
+	 *
+	 * When resuming an activity, provide the same `runId` from the previous session
+	 * to correlate time-spent events with the eventual completion event.
+	 *
+	 * If not provided, the SDK generates a new UUID.
+	 */
+	runId?: string
+	/**
+	 * Time tracking configuration options.
+	 *
+	 * Heartbeats are enabled by default. Use this to customize flush intervals
+	 * or disable visibility-aware tracking.
+	 *
+	 * Set to `false` to disable client-side time tracking entirely. When
+	 * disabled, no heartbeats are sent, no visibility handlers are registered,
+	 * and `end()` skips the final time flush. Use this when time is managed
+	 * server-side (e.g. via `timeback.activity.record()`).
+	 */
+	time?: TimeTrackingOptions | false
+
+	/**
+	 * Called when a heartbeat or submission fails.
+	 *
+	 * Heartbeat errors are non-fatal — the SDK continues tracking time
+	 * regardless. Submit errors (from `end()`) are also surfaced here
+	 * before being re-thrown.
+	 *
+	 * @param error - The error that occurred
+	 * @param context - Details about the failed operation
+	 */
+	onError?: (error: Error, context: ActivityErrorContext) => void
+
+	/**
+	 * Called when the activity is paused (via `pause()` or visibility timeout).
+	 */
+	onPause?: () => void
+
+	/**
+	 * Called when the activity resumes after being paused.
+	 */
+	onResume?: () => void
+
+	/**
+	 * Called after each successful heartbeat flush.
+	 *
+	 * @param elapsedMs - Active milliseconds reported in this flush
+	 */
+	onFlush?: (elapsedMs: number) => void
+}
+
+/**
+ * Context passed to the `onError` callback.
+ */
+export interface ActivityErrorContext {
+	/** Which operation failed — aligns with Caliper event types. */
+	type: 'timeSpent' | 'completion'
+	/** The activity slug passed to `activity.start()`. */
+	activityId: string
+	/** The `runId` for this activity instance. */
+	runId: string
+}
+
+/**
+ * Activity metrics (optional performance data).
+ */
+export interface ActivityMetrics {
+	/** Total questions attempted */
+	totalQuestions?: number
+	/** Number of correct answers */
+	correctQuestions?: number
+	/** XP earned from this activity */
+	xpEarned?: number
+	/** Number of units mastered */
+	masteredUnits?: number
+}
+
+/**
+ * Question count metrics for activity completion.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await activity.end({
+ *   xpEarned: 100,
+ *   totalQuestions: 10,
+ *   correctQuestions: 8,
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With time override
+ * await activity.end({
+ *   xpEarned: 100,
+ *   totalQuestions: 10,
+ *   correctQuestions: 8,
+ *   time: { active: 42000, inactive: 3000 },
+ * })
+ * ```
+ */
+type QuestionCountMetrics =
+	| {
+			/**
+			 * Total questions attempted.
+			 *
+			 * If provided, `correctQuestions` is required too.
+			 */
+			totalQuestions: number
+			/**
+			 * Number of correct answers.
+			 *
+			 * Must be provided when `totalQuestions` is provided.
+			 */
+			correctQuestions: number
+	  }
+	| {
+			/** Omit question counts entirely. */
+			totalQuestions?: undefined
+			/** Omit question counts entirely. */
+			correctQuestions?: undefined
+	  }
+
+/** Optional time override for activity.end() */
+interface ActivityEndTimeOverride {
+	/** Active time in milliseconds */
+	active: number
+	/** Inactive/paused time in milliseconds (defaults to 0) */
+	inactive?: number
+}
+
+/**
+ * Time-only end: final flush without completion event.
+ *
+ * Call `activity.end()` with no args or just a time override to flush
+ * accumulated time without sending an ActivityCompletedEvent.
+ */
+type ActivityEndTimeOnly = {
+	totalQuestions?: undefined
+	correctQuestions?: undefined
+	xpEarned?: undefined
+	masteredUnits?: undefined
+	pctComplete?: undefined
+	time?: ActivityEndTimeOverride
+}
+
+/** Completion end: flush + ActivityCompletedEvent. */
+type ActivityEndCompletion = QuestionCountMetrics & {
+	/** XP earned from this activity. */
+	xpEarned: number
+	/** Number of units mastered */
+	masteredUnits?: number
+	/**
+	 * App-reported course progress (0–100). Values outside range are clamped.
+	 */
+	pctComplete?: number
+	/**
+	 * Optional time override. When provided, the SDK uses these values instead
+	 * of the internal timer. Values are clamped to >= 0 and rounded to integers.
+	 */
+	time?: ActivityEndTimeOverride
+}
+
+/**
+ * Data for ending an activity.
+ *
+ * Two modes:
+ * - **Time-only**: `activity.end()` or `activity.end({ time: {...} })` — final
+ *   flush only, no completion event
+ * - **Completion**: `activity.end({ xpEarned, ... })` — final flush + completion event
+ */
+export type ActivityEndData = ActivityEndTimeOnly | ActivityEndCompletion
+
+/**
+ * Activity state sent to the server when ending.
+ *
+ * @see {@link ActivityParams} for documentation on `id` and `name` semantics.
+ */
+export interface ActivityEndPayload {
+	/**
+	 * Activity slug (stable identifier for the learning object).
+	 *
+	 * @see {@link ActivityParams.id}
+	 */
+	id: string
+	/**
+	 * Human-readable display name of the activity.
+	 *
+	 * @see {@link ActivityParams.name}
+	 */
+	name: string
+	/** Course selector (must match a unique course in timeback.config.json) */
+	course: ActivityCourseRef
+	/** ISO 8601 timestamp when activity started */
+	startedAt: string
+	/** ISO 8601 timestamp when activity ended */
+	endedAt: string
+	/** Active time in milliseconds (excluding paused time) */
+	elapsedMs: number
+	/** Total paused time in milliseconds */
+	pausedMs: number
+	/** Activity metrics */
+	metrics: ActivityMetrics
+	/**
+	 * App-reported course progress (per enrollment), as a percentage from 0–100.
+	 *
+	 * This is forwarded to Caliper events as `generated.extensions.pctCompleteApp`.
+	 *
+	 * @remarks
+	 * - Scale: 0 to 100 (not 0 to 1)
+	 * - Values outside 0–100 are clamped
+	 */
+	pctComplete?: number
+}
+
+/**
+ * Activity heartbeat payload for time-spent tracking.
+ *
+ * Sent periodically to report accumulated active time for a time window.
+ * The server builds a `TimeSpentEvent` from this data.
+ */
+export interface ActivityHeartbeatPayload {
+	/**
+	 * Activity slug (stable identifier for the learning object).
+	 */
+	id: string
+	/**
+	 * Human-readable display name of the activity.
+	 */
+	name: string
+	/** Course selector (must match a unique course in timeback.config.json) */
+	course: ActivityCourseRef
+	/**
+	 * Run identifier for correlating heartbeats with the completion event.
+	 */
+	runId: string
+	/**
+	 * ISO 8601 timestamp when this time window started.
+	 */
+	startedAt: string
+	/**
+	 * ISO 8601 timestamp when this time window ended.
+	 */
+	endedAt: string
+	/**
+	 * Active time in this window in milliseconds.
+	 */
+	elapsedMs: number
+	/**
+	 * Paused time in this window in milliseconds.
+	 */
+	pausedMs: number
+}
+
+/**
+ * Activity submit payload for completion events.
+ *
+ * Sent when the activity completes with metrics.
+ * The server builds an `ActivityCompletedEvent` from this data.
+ */
+export interface ActivitySubmitPayload {
+	/**
+	 * Activity slug (stable identifier for the learning object).
+	 */
+	id: string
+	/**
+	 * Human-readable display name of the activity.
+	 */
+	name: string
+	/** Course selector (must match a unique course in timeback.config.json) */
+	course: ActivityCourseRef
+	/**
+	 * Run identifier for correlating with previous heartbeats.
+	 */
+	runId: string
+	/**
+	 * ISO 8601 timestamp when the activity ended.
+	 */
+	endedAt: string
+	/** Activity metrics */
+	metrics: ActivityMetrics
+	/**
+	 * App-reported course progress (per enrollment), as a percentage from 0–100.
+	 */
+	pctComplete?: number
+}
+
+/**
+ * Activity submission response.
+ */
+export interface ActivityResponse {
+	success: boolean
+	error?: string
+}
+
+/**
+ * Result of verifying a user's Timeback status.
+ *
+ * Used by partner apps to check if a user exists in Timeback before
+ * granting access to Timeback-gated features (e.g., free tier for Timeback users).
+ */
+export type TimebackVerifyResult =
+	| {
+			/** User exists in Timeback */
+			verified: true
+			/** Timeback user ID */
+			timebackId: string
+	  }
+	| {
+			/** User does not exist in Timeback */
+			verified: false
+	  }
+
+/**
+ * Verification state for the current user.
+ *
+ * Used by framework adapters (React, Vue, Svelte, Solid) to expose
+ * verification status as a state machine for UI consumption.
+ */
+export type TimebackVerificationState =
+	| { status: 'loading' }
+	| { status: 'verified'; timebackId: string }
+	| { status: 'unverified' }
+	| { status: 'error'; message: string }
+
+/**
+ * Profile state for the current user.
+ *
+ * Used by framework adapters (React, Vue, Svelte, Solid) to expose
+ * profile fetching status as a state machine for UI consumption.
+ */
+export type TimebackProfileState =
+	| { status: 'idle' }
+	| { status: 'loading' }
+	| { status: 'loaded'; profile: TimebackProfile }
+	| { status: 'error'; message: string }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@timeback/sdk",
-	"version": "0.1.9",
+	"version": "0.1.11",
 	"description": "Timeback SDK for frontend and backend integration",
 	"type": "module",
 	"exports": {
@@ -16,10 +16,6 @@
 			"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"
@@ -79,23 +75,24 @@
 		"test:e2e": "bun test --no-env-file e2e.test.ts"
 	},
 	"dependencies": {
-		"@timeback/core": "0.1.4",
+		"@timeback/core": "0.1.5",
 		"c12": "^3.3.3",
 		"zod": "^4.2.1"
 	},
 	"devDependencies": {
-		"@timeback/caliper": "0.1.3",
-		"@timeback/edubridge": "0.1.3",
+		"@timeback/caliper": "0.1.5",
+		"@timeback/edubridge": "0.1.4",
 		"@timeback/internal-cli-infra": "0.0.0",
 		"@timeback/internal-client-infra": "0.0.0",
 		"@timeback/internal-logger": "0.0.0",
 		"@timeback/internal-test": "0.0.0",
 		"@timeback/internal-utils": "0.0.0",
-		"@timeback/oneroster": "0.1.5",
+		"@timeback/oneroster": "0.1.6",
 		"@timeback/types": "0.0.0",
 		"@types/bun": "latest",
 		"@types/express": "^5.0.6",
-		"@types/react": "^19.1.8"
+		"@types/react": "^19.1.8",
+		"esbuild": "^0.27.3"
 	},
 	"peerDependencies": {
 		"react": "^18 || ^19",

package/dist/chunk-07j8zre9.js

@@ -1,2 +0,0 @@
-import{createRequire as k}from"node:module";var g=Object.create;var{getPrototypeOf:h,defineProperty:f,getOwnPropertyNames:i}=Object;var j=Object.prototype.hasOwnProperty;var l=(a,b,c)=>{c=a!=null?g(h(a)):{};let d=b||!a||!a.__esModule?f(c,"default",{value:a,enumerable:!0}):c;for(let e of i(a))if(!j.call(d,e))f(d,e,{get:()=>a[e],enumerable:!0});return d};var m=(a,b)=>()=>(b||a((b={exports:{}}).exports,b),b.exports);var o=k(import.meta.url);
-export{l as M,m as N,o as O};

package/dist/chunk-5171mkp2.js

@@ -1,2 +0,0 @@
-import{C as F}from"./chunk-hnf0tart.js";function M(j){let g=j.trim();if(g==="")return"/";let A=g.indexOf("?");if(A===-1)return g;let L=g.slice(0,A);if(L==="")return"/";return L}function X(j){let g=M(j);if(g!==""&&!g.startsWith("/"))g=`/${g}`;if(g==="/"||g==="")return"";if(g.endsWith("/"))return g.slice(0,-1);return g}function Z(j){let g=j.method.toUpperCase(),A=M(j.pathname),L=j.callbackPath?M(j.callbackPath):void 0;if(L&&A===L)return g==="GET"?"identity.callback":null;let N=j.basePath,Q=N!==void 0,J=Q?X(N):void 0,V=(G)=>{if(g==="GET"){if(G===F.IDENTITY.SIGNIN)return"identity.signIn";if(G===F.IDENTITY.CALLBACK)return"identity.callback";if(G===F.IDENTITY.SIGNOUT)return"identity.signOut";if(G===F.USER.ME)return"user.me";if(G===F.USER.VERIFY)return"user.verify"}if(g==="POST"){if(G===F.ACTIVITY)return"activity"}return null};if(Q&&J!==void 0){if(J!==""&&A===J)return null;if(J!==""&&!A.startsWith(`${J}/`))return null;let G=J===""?A:A.slice(J.length),W=G.startsWith("/")?G:`/${G}`;return V(W)}if(g==="GET"){if(A.endsWith(F.IDENTITY.SIGNIN))return"identity.signIn";if(A.endsWith(F.IDENTITY.CALLBACK))return"identity.callback";if(A.endsWith(F.IDENTITY.SIGNOUT))return"identity.signOut";if(A.endsWith(F.USER.ME))return"user.me";if(A.endsWith(F.USER.VERIFY))return"user.verify"}if(g==="POST"){if(A.endsWith(F.ACTIVITY))return"activity"}return null}function _(j){return"handle"in j?j.handle:j}function $(j){return"activity"in j}function C(j){return"user"in j}
-export{M as x,Z as y,_ as z,$ as A,C as B};