@timeback/sdk 0.1.4 → 0.1.6

package/README.md

@@ -40,7 +40,7 @@ bun add timeback
 
 ## Server Adapters
 
-All server adapters use the same core configuration:
+All server adapters use the same core configuration and require a `timeback.config.json` file:
 
 ```typescript
 // lib/timeback.ts
@@ -76,7 +76,6 @@ export const timeback = await createTimeback({
 ```typescript
 // app/api/timeback/[...timeback]/route.ts
 import { toNextjsHandler } from '@timeback/sdk/nextjs'
-
 import { timeback } from '@/lib/timeback'
 
 export const { GET, POST } = toNextjsHandler(timeback)
@@ -105,6 +104,7 @@ export default defineEventHandler(async event => {
 // src/hooks.server.ts
 import { building } from '$app/environment'
 import { timeback } from '$lib/timeback'
+
 import { svelteKitHandler } from '@timeback/sdk/svelte-kit'
 
 import type { Handle } from '@sveltejs/kit'
@@ -125,6 +125,7 @@ export const handle: Handle = ({ event, resolve }) => {
 // src/middleware.ts
 import { createMiddleware } from '@solidjs/start/middleware'
 import { timeback } from '~/lib/timeback'
+
 import { solidStartHandler } from '@timeback/sdk/solid-start'
 
 export default createMiddleware({
@@ -145,8 +146,8 @@ export default createMiddleware({
 ```typescript
 // src/routes/api/timeback/$.ts
 import { createFileRoute } from '@tanstack/react-router'
-import { toTanStackStartHandler } from '@timeback/sdk/tanstack-start'
 
+import { toTanStackStartHandler } from '@timeback/sdk/tanstack-start'
 import { timeback } from '@/lib/timeback'
 
 const handlers = toTanStackStartHandler(timeback)
@@ -161,6 +162,7 @@ export const Route = createFileRoute('/api/timeback/$')({
 ```typescript
 // server.ts
 import express from 'express'
+
 import { toExpressMiddleware } from '@timeback/sdk/express'
 
 import { timeback } from './lib/timeback'
@@ -188,6 +190,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
 ```tsx
 // components/ActivityTracker.tsx
 import { useEffect } from 'react'
+
 import { SignInButton, useTimeback } from '@timeback/sdk/react'
 
 function MyComponent() {
@@ -227,9 +230,10 @@ import { TimebackProvider } from '@timeback/sdk/vue'
 ```vue
 <!-- components/ActivityTracker.vue -->
 <script setup>
-import { SignInButton, useTimeback } from '@timeback/sdk/vue'
 import { onMounted, onUnmounted } from 'vue'
 
+import { SignInButton, useTimeback } from '@timeback/sdk/vue'
+
 const timeback = useTimeback()
 let activity
 
@@ -306,6 +310,7 @@ export default function App() {
 ```tsx
 // components/ActivityTracker.tsx
 import { onCleanup, onMount } from 'solid-js'
+
 import { SignInButton, useTimeback } from '@timeback/sdk/solid'
 
 function MyComponent() {
@@ -401,21 +406,21 @@ For apps with existing auth (Clerk, Auth0, Supabase, etc.):
 ```typescript
 identity: {
 	mode: 'custom',
-	getUser: async (req) => {
+	getEmail: async (req) => {
 		const session = await getSession(req)
-		if (!session) return undefined
-		// Return user with timebackId as the id
-		return { id: session.timebackId, email: session.email, name: session.name }
+		return session?.email
 	},
 }
 ```
 
+The SDK resolves the Timeback user by email. You only need to provide the authenticated user's email address.
+
 ## Identity-Only Integration
 
 If you only need Timeback SSO authentication without activity tracking or Timeback API integration, use `createTimebackIdentity()`. This is a lightweight alternative that:
 
 - Does not require Timeback API credentials
-- Does not require `timeback.config.ts`
+- Does not require `timeback.config.json`
 - Only exposes identity routes (sign-in, callback, sign-out)
 - Returns raw OIDC user info (no Timeback profile enrichment)
 
@@ -424,8 +429,8 @@ If you only need Timeback SSO authentication without activity tracking or Timeba
 ### Cloudflare Workers / workerd compatibility
 
 `createTimebackIdentity()` is runtime-agnostic, but the main `timeback` entrypoint also includes
-Node-oriented functionality (notably config loading via `jiti`). Some edge runtimes
-(Cloudflare Workers / workerd) do not support the Node modules that `jiti` depends on.
+Node-oriented functionality (notably config loading via `c12`). Some edge runtimes
+(Cloudflare Workers / workerd) do not support the Node modules that `c12` depends on.
 
 If you're deploying identity-only SSO on Workers/workerd, import from the worker-safe entrypoint:
 
@@ -469,7 +474,6 @@ export const timeback = createTimebackIdentity({
 ```typescript
 // app/api/timeback/[...timeback]/route.ts
 import { toNextjsHandler } from '@timeback/sdk/nextjs'
-
 import { timeback } from '@/lib/timeback'
 
 export const { GET, POST } = toNextjsHandler(timeback)
@@ -480,6 +484,7 @@ export const { GET, POST } = toNextjsHandler(timeback)
 ```typescript
 // server.ts
 import express from 'express'
+
 import { toExpressMiddleware } from '@timeback/sdk/express'
 
 import { timeback } from './lib/timeback'
@@ -529,21 +534,39 @@ await activity.end({
 	totalQuestions: 10,
 	correctQuestions: 8,
 	xpEarned: 80,
-	masteredUnits: 1,
+	masteredUnits: 1, // optional (default: omitted)
+	attemptNumber: 2, // optional (default: omitted)
+	pctCompleteApp: 67, // optional (default: omitted; clamped to 0–100 by the SDK server handler if present)
 })
 ```
 
 The SDK automatically sends activity data to your server, which forwards it to the Timeback API.
 
-**Note:** Activity ingestion requires **exactly one** Caliper sensor URL in `timeback.config.ts`:
-
-```typescript
-export default {
-	name: 'My App',
-	courses: [
-		/* ... */
-	],
-	sensors: ['https://my-app.example.com/sensors/main'],
+**Note:** Activity ingestion requires an **effective Caliper sensor URL per course** in `timeback.config.json`.
+
+Sensor precedence (highest → lowest):
+
+- per-course env override: `course.overrides[env].sensor`
+- per-course base override: `course.sensor`
+- top-level default: `config.sensor`
+
+```json
+{
+	"$schema": "https://timeback.dev/schema.json",
+	"name": "My App",
+	"sensor": "https://my-app.example.com/sensors/default",
+	"courses": [
+		{
+			"subject": "Math",
+			"grade": 3,
+			"courseCode": "MATH-3",
+			"sensor": "https://my-app.example.com/sensors/math",
+			"overrides": {
+				"staging": { "sensor": "https://staging.my-app.example.com/sensors/math" },
+				"production": { "sensor": "https://my-app.example.com/sensors/math" }
+			}
+		}
+	]
 }
 ```
 
@@ -575,7 +598,7 @@ export const timeback = await createTimeback({
 		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
 		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
 	},
-	identity: { mode: 'custom', getUser: () => getSession() },
+	identity: { mode: 'custom', getEmail: () => getSession()?.email },
 })
 
 // Access the API client via timeback.api

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

@@ -25,12 +25,11 @@
  *   }
  *
  *   const handleStartActivity = () => {
- *     const activity = timeback?.activity.new({
+ *     const activity = timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity?.start()
  *   }
  *
  *   return <SignInButton />

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAG7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAGvD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAG7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAGvD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/client/adapters/react/index.js

@@ -35,24 +35,16 @@ class Activity {
   constructor(params, sendActivity) {
     this.params = params;
     this.sendActivity = sendActivity;
-  }
-  get isStarted() {
-    return this._startedAt !== undefined;
+    this._startedAt = new Date;
   }
   get startedAt() {
     return this._startedAt;
   }
-  start() {
-    if (this._startedAt)
-      return this;
-    this._startedAt = new Date;
-    return this;
-  }
   get isPaused() {
     return this._isPaused;
   }
   get elapsedMs() {
-    if (!this._startedAt || this._ended) {
+    if (this._ended) {
       return 0;
     }
     const now = new Date;
@@ -62,8 +54,30 @@ class Activity {
     }
     return Math.max(0, elapsed);
   }
+  _buildPayload(data) {
+    const now = new Date;
+    const pausedMs = this._totalPausedMs + (this._isPaused && this._pausedAt ? now.getTime() - this._pausedAt.getTime() : 0);
+    const elapsedMs = now.getTime() - this._startedAt.getTime() - pausedMs;
+    return {
+      id: this.params.id,
+      name: this.params.name,
+      course: this.params.course,
+      startedAt: this._startedAt.toISOString(),
+      endedAt: now.toISOString(),
+      elapsedMs: Math.max(0, elapsedMs),
+      pausedMs,
+      metrics: {
+        totalQuestions: data.totalQuestions,
+        correctQuestions: data.correctQuestions,
+        ...data.xpEarned === undefined ? {} : { xpEarned: data.xpEarned },
+        ...data.masteredUnits === undefined ? {} : { masteredUnits: data.masteredUnits }
+      },
+      ...data.attemptNumber === undefined ? {} : { attemptNumber: data.attemptNumber },
+      ...data.pctCompleteApp === undefined ? {} : { pctCompleteApp: data.pctCompleteApp }
+    };
+  }
   pause() {
-    if (!this._startedAt || this._isPaused || this._ended)
+    if (this._isPaused || this._ended)
       return;
     this._isPaused = true;
     this._pausedAt = new Date;
@@ -75,43 +89,26 @@ class Activity {
     this._isPaused = false;
     this._pausedAt = undefined;
   }
-  async end(metrics) {
-    if (!this._startedAt) {
-      throw new Error("Cannot end activity that was never started");
-    }
+  async end(data) {
     if (this._ended)
       return;
     this._ended = true;
     if (this._isPaused && this._pausedAt) {
       this._totalPausedMs += new Date().getTime() - this._pausedAt.getTime();
+      this._isPaused = false;
+      this._pausedAt = undefined;
     }
-    const endedAt = new Date;
-    const elapsedMs = endedAt.getTime() - this._startedAt.getTime() - this._totalPausedMs;
-    const payload = {
-      id: this.params.id,
-      name: this.params.name,
-      course: this.params.course,
-      startedAt: this._startedAt.toISOString(),
-      endedAt: endedAt.toISOString(),
-      elapsedMs: Math.max(0, elapsedMs),
-      pausedMs: this._totalPausedMs,
-      metrics
-    };
+    const payload = this._buildPayload(data);
     await this.sendActivity(payload);
   }
 }
-
-// src/client/lib/activity/activity.ts
-function createActivity(params, sendActivity) {
-  return new Activity(params, sendActivity);
-}
 // src/client/namespaces/activity.ts
 class ActivityManager {
   sendActivity;
   constructor(sendActivity) {
     this.sendActivity = sendActivity;
   }
-  new(params) {
+  start(params) {
     return new Activity(params, this.sendActivity);
   }
 }

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

@@ -61,12 +61,11 @@ export declare function TimebackProvider({ client: providedClient, children }: T
  *   }
  *
  *   const handleStartActivity = () => {
- *     const activity = timeback.activity.new({
+ *     const activity = timeback.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity.start()
  *   }
  *
  *   return <button onClick={handleSignIn}>Sign In</button>

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

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/react/provider.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAO5D;;GAEG;AACH,UAAU,qBAAqB;IAC9B,wFAAwF;IACxF,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,uBAAuB;IACvB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CACzB;AAiBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,EAChC,MAAM,EAAE,cAAc,EACtB,QAAQ,EACR,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,CAU5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,IAAI,cAAc,GAAG,SAAS,CAExD"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/react/provider.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAO5D;;GAEG;AACH,UAAU,qBAAqB;IAC9B,wFAAwF;IACxF,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,uBAAuB;IACvB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CACzB;AAiBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,EAChC,MAAM,EAAE,cAAc,EACtB,QAAQ,EACR,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,CAU5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,IAAI,cAAc,GAAG,SAAS,CAExD"}

package/dist/client/adapters/solid/context.d.ts

@@ -57,12 +57,11 @@ export declare function TimebackProvider(props: TimebackProviderProps): JSX.Elem
  *   }
  *
  *   const handleStartActivity = () => {
- *     const activity = timeback?.activity.new({
+ *     const activity = timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 }
  *     })
- *     activity?.start()
  *   }
  *
  *   return <button onClick={handleSignIn}>Sign In</button>

package/dist/client/adapters/solid/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/solid/context.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAOnC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,sCAAsC;IACtC,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,yBAAyB;IACzB,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAI1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,IAAI,cAAc,GAAG,SAAS,CAExD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/solid/context.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAOnC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,sCAAsC;IACtC,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,yBAAyB;IACzB,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAI1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,IAAI,cAAc,GAAG,SAAS,CAExD"}

package/dist/client/adapters/solid/context.tsx

@@ -74,12 +74,11 @@ export function TimebackProvider(props: TimebackProviderProps): JSX.Element {
  *   }
  *
  *   const handleStartActivity = () => {
- *     const activity = timeback?.activity.new({
+ *     const activity = timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 }
  *     })
- *     activity?.start()
  *   }
  *
  *   return <button onClick={handleSignIn}>Sign In</button>

package/dist/client/adapters/solid/index.d.ts

@@ -25,12 +25,11 @@
  *   }
  *
  *   const handleStartActivity = () => {
- *     const activity = timeback?.activity.new({
+ *     const activity = timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity?.start()
  *   }
  *
  *   return <SignInButton />

package/dist/client/adapters/solid/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/solid/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACzD,YAAY,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAGtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/solid/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACzD,YAAY,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAGtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/client/adapters/solid/index.ts

@@ -25,12 +25,11 @@
  *   }
  *
  *   const handleStartActivity = () => {
- *     const activity = timeback?.activity.new({
+ *     const activity = timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity?.start()
  *   }
  *
  *   return <SignInButton />

package/dist/client/adapters/svelte/index.d.ts

@@ -17,12 +17,11 @@
  *   }
  *
  *   function handleStartActivity() {
- *     const activity = $timeback?.activity.new({
+ *     const activity = $timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity?.start()
  *   }
  * </script>
  *

package/dist/client/adapters/svelte/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/svelte/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGjD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/svelte/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGjD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/client/adapters/svelte/index.ts

@@ -17,12 +17,11 @@
  *   }
  *
  *   function handleStartActivity() {
- *     const activity = $timeback?.activity.new({
+ *     const activity = $timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity?.start()
  *   }
  * </script>
  *

package/dist/client/adapters/svelte/stores.d.ts

@@ -51,12 +51,11 @@ export declare function initTimeback(client?: TimebackClient): void;
  *   }
  *
  *   function handleStartActivity() {
- *     const activity = $timeback?.activity.new({
+ *     const activity = $timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity?.start()
  *   }
  * </script>
  * ```

package/dist/client/adapters/svelte/stores.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/svelte/stores.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD;;;;GAIG;AACH,UAAU,QAAQ,CAAC,CAAC;IACnB,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;CAClD;AAqDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAQ1D;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,cAAc,GAAG,SAAS,CAAe,CAAA"}
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/svelte/stores.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD;;;;GAIG;AACH,UAAU,QAAQ,CAAC,CAAC;IACnB,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;CAClD;AAqDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAQ1D;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,cAAc,GAAG,SAAS,CAAe,CAAA"}

package/dist/client/adapters/svelte/stores.ts

@@ -130,12 +130,11 @@ if (isBrowser()) {
  *   }
  *
  *   function handleStartActivity() {
- *     const activity = $timeback?.activity.new({
+ *     const activity = $timeback?.activity.start({
  *       id: 'lesson-1',
  *       name: 'Intro',
  *       course: { subject: 'Math', grade: 3 },
  *     })
- *     activity?.start()
  *   }
  * </script>
  * ```

package/dist/client/adapters/vue/index.d.ts

@@ -19,12 +19,11 @@
  * }
  *
  * function handleStartActivity() {
- *   const activity = timeback.value?.activity.new({
+ *   const activity = timeback.value?.activity.start({
  *     id: 'lesson-1',
  *     name: 'Intro',
  *     course: { subject: 'Math', grade: 3 }
  *   })
- *   activity?.start()
  * }
  * </script>
  *

package/dist/client/adapters/vue/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/vue/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG1D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC5D,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/vue/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG7F,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG1D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC5D,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/client/adapters/vue/index.ts

@@ -19,12 +19,11 @@
  * }
  *
  * function handleStartActivity() {
- *   const activity = timeback.value?.activity.new({
+ *   const activity = timeback.value?.activity.start({
  *     id: 'lesson-1',
  *     name: 'Intro',
  *     course: { subject: 'Math', grade: 3 }
  *   })
- *   activity?.start()
  * }
  * </script>
  *

package/dist/client/adapters/vue/provider.d.ts

@@ -76,12 +76,11 @@ export declare const TimebackProvider: import("@vue/runtime-core").DefineCompone
  * }
  *
  * function handleStartActivity() {
- *   const activity = timeback.value?.activity.new({
+ *   const activity = timeback.value?.activity.start({
  *     id: 'lesson-1',
  *     name: 'Intro',
  *     course: { subject: 'Math', grade: 3 }
  *   })
- *   activity?.start()
  * }
  * </script>
  *

package/dist/client/adapters/vue/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/vue/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAGrD,OAAO,KAAK,EAAgB,QAAQ,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AAqC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,gBAAgB;IAG3B,wFAAwF;;;;;;;;IAAxF,wFAAwF;;;;;;;0FAoBxF,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAAC,cAAc,GAAG,SAAS,CAAC,CAQpE"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/client/adapters/vue/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAGrD,OAAO,KAAK,EAAgB,QAAQ,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AAqC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,gBAAgB;IAG3B,wFAAwF;;;;;;;;IAAxF,wFAAwF;;;;;;;0FAoBxF,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAAC,cAAc,GAAG,SAAS,CAAC,CAQpE"}

package/dist/client/adapters/vue/provider.ts

@@ -122,12 +122,11 @@ export const TimebackProvider = defineComponent({
  * }
  *
  * function handleStartActivity() {
- *   const activity = timeback.value?.activity.new({
+ *   const activity = timeback.value?.activity.start({
  *     id: 'lesson-1',
  *     name: 'Intro',
  *     course: { subject: 'Math', grade: 3 }
  *   })
- *   activity?.start()
  * }
  * </script>
  *

package/dist/client/index.d.ts

@@ -5,5 +5,5 @@
  */
 export { createClient } from './timeback-client';
 export { TimebackClient } from './timeback-client.class';
-export { createActivity, Activity } from './lib/activity';
+export { Activity } from './lib/activity';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAGxD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAGxD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/client/lib/activity/activity.class.d.ts

@@ -6,42 +6,33 @@
 import type { ActivityEndPayload, ActivityMetrics, ActivityParams } from '../../../shared/types';
 /**
  * Activity tracker that tracks time spent on an activity.
+ *
+ * Activities are started immediately on construction. Use `pause()`, `resume()`,
+ * and `end()` to control the activity lifecycle.
  */
 export declare class Activity {
     private readonly params;
     private readonly sendActivity;
-    private _startedAt;
+    private readonly _startedAt;
     private _isPaused;
     private _pausedAt;
     private _totalPausedMs;
     private _ended;
     /**
-     * Create a new activity tracker.
+     * Create and start a new activity tracker.
      *
-     * The activity is created but not started. Call `.start()` to begin tracking.
+     * The activity timer begins immediately.
      *
      * @param params - Activity parameters
      * @param sendActivity - Function to send activity to server
      */
     constructor(params: ActivityParams, sendActivity: (payload: ActivityEndPayload) => Promise<void>);
-    /**
-     * Whether the activity has been started.
-     *
-     * @returns True if started
-     */
-    get isStarted(): boolean;
     /**
      * When the activity was started.
      *
-     * @returns Start date or undefined if not started
+     * @returns Start date
      */
-    get startedAt(): Date | undefined;
-    /**
-     * Start tracking the activity.
-     *
-     * @returns This activity for chaining
-     */
-    start(): this;
+    get startedAt(): Date;
     /**
      * Whether the activity is currently paused.
      *
@@ -51,9 +42,19 @@ export declare class Activity {
     /**
      * Total elapsed time in milliseconds (excluding paused time).
      *
-     * @returns Elapsed milliseconds (0 if not started)
+     * @returns Elapsed milliseconds (0 if ended)
      */
     get elapsedMs(): number;
+    /**
+     * Build the activity end payload without sending it.
+     *
+     * Useful for "preview" flows in examples where you want to inspect the payload
+     * that would be POSTed to the server without calling `end()`.
+     *
+     * @param data - Activity completion data (metrics + optional metadata)
+     * @returns Activity end payload
+     */
+    _buildPayload(data: ActivityMetrics & Pick<Partial<ActivityEndPayload>, 'attemptNumber' | 'pctCompleteApp'>): ActivityEndPayload;
     /**
      * Pause the activity timer.
      */
@@ -65,9 +66,8 @@ export declare class Activity {
     /**
      * End the activity and send to server.
      *
-     * @param metrics - Activity metrics (required)
-     * @throws Error if activity was never started
+     * @param data - Activity completion data (metrics + optional metadata)
      */
-    end(metrics: ActivityMetrics): Promise<void>;
+    end(data: ActivityMetrics & Pick<Partial<ActivityEndPayload>, 'attemptNumber' | 'pctCompleteApp'>): Promise<void>;
 }
 //# sourceMappingURL=activity.class.d.ts.map