timeback 0.1.2 → 0.1.3

package/README.md

@@ -21,6 +21,7 @@ TypeScript SDK for integrating Timeback into your application. Provides server-s
 - [Identity Modes](#identity-modes)
 - [Identity-Only Integration](#identity-only-integration)
 - [Activity Tracking](#activity-tracking)
+- [Advanced: Direct API Access](#advanced-direct-api-access)
 
 ## Installation
 
@@ -43,10 +44,10 @@ All server adapters use the same core configuration:
 
 ```typescript
 // lib/timeback.ts
-import { createServer } from 'timeback'
+import { createTimeback } from 'timeback'
 
-export const timeback = await createServer({
-	env: 'staging', // 'development' | 'staging' | 'production'
+export const timeback = await createTimeback({
+	env: 'staging', // 'local' | 'staging' | 'production'
 	api: {
 		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
 		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
@@ -56,9 +57,10 @@ export const timeback = await createServer({
 		clientId: process.env.AWS_COGNITO_CLIENT_ID!,
 		clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
 		redirectUri: 'http://localhost:3000/api/auth/sso/callback/timeback',
-		onCallbackSuccess: ({ user, redirect }) => {
-			// Set session, then redirect
-			return redirect('/')
+		onCallbackSuccess: async ({ user, state, redirect }) => {
+			// user.id is the timebackId (canonical stable identifier)
+			await setSession({ id: user.id, email: user.email })
+			return redirect(state?.returnTo ?? '/')
 		},
 		onCallbackError: ({ error, redirect }) => {
 			console.error('SSO Error:', error)
@@ -328,7 +330,7 @@ function MyComponent() {
 
 ### SSO Mode
 
-Uses Timeback as the identity provider via OIDC:
+Uses Timeback as the identity provider via OIDC. When using `createTimeback()`, the SDK automatically resolves the Timeback user by email and returns an enriched `TimebackAuthUser` with `user.id` being the canonical `timebackId` (stable identifier).
 
 ```typescript
 identity: {
@@ -336,12 +338,62 @@ identity: {
 	clientId: process.env.AWS_COGNITO_CLIENT_ID!,
 	clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
 	redirectUri: 'http://localhost:3000/api/auth/sso/callback/timeback',
-	onCallbackSuccess: ({ user, state, redirect }) => redirect('/'),
-	onCallbackError: ({ error, redirect }) => redirect('/?error=sso_failed'),
+	onCallbackSuccess: async ({ user, idp, state, redirect }) => {
+		// user.id is the timebackId (canonical stable identifier)
+		// user.email, user.name come from Timeback profile
+		// user.claims contains IdP data (sub, firstName, lastName, pictureUrl)
+		// idp.tokens and idp.userInfo contain raw OIDC data if needed
+		await setSession({ id: user.id, email: user.email })
+		return redirect(state?.returnTo ?? '/')
+	},
+	onCallbackError: ({ error, errorCode, redirect }) => {
+		// errorCode may be: missing_email, timeback_user_not_found,
+		// timeback_user_ambiguous, timeback_user_lookup_failed
+		console.error('SSO Error:', errorCode, error.message)
+		return redirect('/?error=sso_failed')
+	},
 	getUser: () => getCurrentSession(),
 }
 ```
 
+#### TimebackAuthUser Shape
+
+The `user` in `onCallbackSuccess` is a `TimebackAuthUser` with this structure:
+
+```typescript
+interface TimebackAuthUser {
+	id: string // Timeback user ID
+	email: string
+	name?: string
+	school?: { id: string; name: string }
+	grade?: number
+	claims: {
+		sub: string // OIDC subject identifier
+		email: string
+		firstName?: string
+		lastName?: string
+		pictureUrl?: string
+	}
+}
+```
+
+#### Session Storage Guidance
+
+For cookie-only sessions, store only the minimal payload to avoid cookie size limits:
+
+```typescript
+// Recommended: store minimal session
+await setSession({ id: user.id, email: user.email })
+
+// Then in getUser, return what you stored:
+getUser: req => {
+	const session = getSessionFromCookie(req)
+	return session ? { id: session.id, email: session.email } : undefined
+}
+```
+
+For DB-backed sessions, you can store the full `TimebackAuthUser` if desired.
+
 ### Custom Mode
 
 For apps with existing auth (Clerk, Auth0, Supabase, etc.):
@@ -352,34 +404,55 @@ identity: {
 	getUser: async (req) => {
 		const session = await getSession(req)
 		if (!session) return undefined
-		return { id: session.userId, email: session.email, name: session.name }
+		// Return user with timebackId as the id
+		return { id: session.timebackId, email: session.email, name: session.name }
 	},
 }
 ```
 
 ## Identity-Only Integration
 
-If you only need Timeback SSO authentication without activity tracking or Timeback API integration, use `createIdentityServer()`. This is a lightweight alternative that:
+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`
 - Only exposes identity routes (sign-in, callback, sign-out)
+- Returns raw OIDC user info (no Timeback profile enrichment)
+
+**Note:** Unlike `createTimeback()`, the identity-only callback returns raw OIDC user info (`sub`, `email`, `name`, etc.) without resolving a Timeback user. Use `createTimeback()` if you need the canonical `timebackId`.
+
+### 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.
+
+If you're deploying identity-only SSO on Workers/workerd, import from the worker-safe entrypoint:
+
+```ts
+import { createTimebackIdentity, toNativeHandler } from 'timeback/edge'
+```
 
 ### Server Setup
 
 ```typescript
 // lib/timeback.ts
-import { createIdentityServer } from 'timeback'
+import { createTimebackIdentity } from 'timeback'
 
-export const timeback = createIdentityServer({
+export const timeback = createTimebackIdentity({
 	env: 'production',
 	identity: {
 		mode: 'sso',
 		clientId: process.env.AWS_COGNITO_CLIENT_ID!,
 		clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
 		onCallbackSuccess: async ({ user, tokens, redirect }) => {
-			// Create your own session, then redirect
-			await createSession(user)
+			// user is raw OIDC userInfo (sub, email, name, picture, etc.)
+			// No Timeback profile enrichment in identity-only mode
+			await createSession({
+				sub: user.sub,
+				email: user.email,
+				name: user.name,
+			})
 			return redirect('/')
 		},
 		onCallbackError: ({ error, redirect }) => {
@@ -445,3 +518,67 @@ await activity.end({
 ```
 
 The SDK automatically sends activity data to your server, which forwards it to the Timeback API.
+
+## Advanced: Direct API Access
+
+For advanced use cases that need to call Timeback services (OneRoster, Edubridge, Caliper, QTI) beyond what the SDK handlers provide, use `timeback.api`:
+
+```typescript
+// Access via the timeback instance (lazy-initialized on first access)
+const { data: users } = await timeback.api.oneroster.users.list({
+	limit: 10,
+	where: { role: 'student' },
+})
+
+// Access any Timeback service
+const { data: orgs } = await timeback.api.oneroster.orgs.list()
+await timeback.api.caliper.emit(caliperEvent)
+```
+
+### Access Patterns
+
+```typescript
+// lib/timeback.ts
+import { createTimeback } from 'timeback'
+
+export const timeback = await createTimeback({
+	env: 'staging',
+	api: {
+		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
+		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
+	},
+	identity: { mode: 'custom', getUser: () => getSession() },
+})
+
+// Access the API client via timeback.api
+const { data: users } = await timeback.api.oneroster.users.list()
+```
+
+```typescript
+// Elsewhere in your app
+import { timeback } from './lib/timeback'
+
+// The client is available at timeback.api
+const { data: orgs } = await timeback.api.oneroster.orgs.list()
+```
+
+### Environment Mapping
+
+The SDK's `env` config controls runtime mode, but for outbound API calls:
+
+| SDK `env`    | API calls use |
+| ------------ | ------------- |
+| `local`      | `staging`     |
+| `staging`    | `staging`     |
+| `production` | `production`  |
+
+This means `env: 'local'` uses staging Timeback services, so you can develop locally against real (staging) data without additional configuration.
+
+### When to Use
+
+- Fetching data not exposed by SDK handlers (e.g., listing orgs, courses, enrollments)
+- Emitting custom Caliper events
+- Building admin dashboards or reporting tools
+- Any direct Timeback API integration
+
+**Note:** `timeback.api` is only available on the full SDK (`createTimeback()`), not on identity-only instances (`createTimebackIdentity()`).

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

@@ -39,5 +39,5 @@ export { Activity } from '../../lib/activity';
 export { TimebackProvider, useTimeback } from './provider';
 export { SignInButton } from './SignInButton';
 export type { SignInButtonProps } from './SignInButton';
-export type { TimebackUser, ActivityParams, ActivityMetrics } from '../../../shared/types';
+export type { TimebackIdentity, ActivityParams, ActivityMetrics } from '../../../shared/types';
 //# sourceMappingURL=index.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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,YAAY,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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/solid/index.d.ts

@@ -34,7 +34,7 @@
  * ```
  */
 export { Activity, createClient, TimebackClient } from 'timeback/client';
-export type { ActivityMetrics, ActivityParams, TimebackUser } from 'timeback/client';
+export type { ActivityMetrics, ActivityParams, TimebackIdentity } from 'timeback/client';
 export { TimebackProvider, useTimeback } from './context';
 export type { TimebackProviderProps } from './context';
 export { SignInButton } from './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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGpF,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGxF,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

@@ -35,7 +35,7 @@
  */
 
 export { Activity, createClient, TimebackClient } from 'timeback/client'
-export type { ActivityMetrics, ActivityParams, TimebackUser } from 'timeback/client'
+export type { ActivityMetrics, ActivityParams, TimebackIdentity } from 'timeback/client'
 
 // Solid-specific
 export { TimebackProvider, useTimeback } from './context'

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

@@ -26,7 +26,7 @@
  * ```
  */
 export { Activity, createClient, TimebackClient } from 'timeback/client';
-export type { ActivityMetrics, ActivityParams, TimebackUser } from 'timeback/client';
+export type { ActivityMetrics, ActivityParams, TimebackIdentity } from 'timeback/client';
 export { initTimeback, timeback } from './stores';
 export { default as SignInButton } from './SignInButton.svelte';
 export type { SignInButtonProps } from './SignInButton.svelte';

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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGpF,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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGxF,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

@@ -28,7 +28,7 @@
 
 // Re-export from timeback/client for convenience
 export { Activity, createClient, TimebackClient } from 'timeback/client'
-export type { ActivityMetrics, ActivityParams, TimebackUser } from 'timeback/client'
+export type { ActivityMetrics, ActivityParams, TimebackIdentity } from 'timeback/client'
 
 // Svelte-specific
 export { initTimeback, timeback } from './stores'

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

@@ -36,7 +36,7 @@
  * ```
  */
 export { Activity, createClient, TimebackClient } from 'timeback/client';
-export type { ActivityMetrics, ActivityParams, TimebackUser } from 'timeback/client';
+export type { ActivityMetrics, ActivityParams, TimebackIdentity } from 'timeback/client';
 export { TimebackProvider, useTimeback } from './provider';
 export { default as SignInButton } from './SignInButton.vue';
 export type { SignInButtonProps } from './SignInButton.vue';

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,iBAAiB,CAAA;AACxE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGpF,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGxF,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

@@ -38,7 +38,7 @@
 
 // Re-export from timeback/client for convenience
 export { Activity, createClient, TimebackClient } from 'timeback/client'
-export type { ActivityMetrics, ActivityParams, TimebackUser } from 'timeback/client'
+export type { ActivityMetrics, ActivityParams, TimebackIdentity } from 'timeback/client'
 
 // Vue-specific
 export { TimebackProvider, useTimeback } from './provider'

package/dist/client.d.ts

@@ -26,5 +26,5 @@
  */
 export { createClient, TimebackClient } from './client/index';
 export { createActivity, Activity } from './client/index';
-export type { TimebackUser, TimebackIdentity, TimebackProfile, ActivityParams, ActivityMetrics, } from './shared/types';
+export type { TimebackIdentity, TimebackProfile, TimebackSessionUser, ActivityParams, ActivityMetrics, } from './shared/types';
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzD,YAAY,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,GACf,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzD,YAAY,EACX,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,eAAe,GACf,MAAM,gBAAgB,CAAA"}

package/dist/edge.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Timeback (edge/worker friendly entrypoint)
+ *
+ * This entrypoint is intended for runtimes like Cloudflare Workers / workerd.
+ * It avoids importing Node-only dependencies (notably config loading via `jiti`).
+ *
+ * It includes identity-only SSO plus a small set of edge-safe helpers.
+ */
+export { createTimebackIdentity } from './server/timeback-identity';
+export type { IdentityOnlyConfig, IdentityOnlyInstance, IdentityOnlyHandlers } from './server';
+export { toNativeHandler } from './server/adapters/native';
+export { ROUTES } from './shared/constants';
+//# sourceMappingURL=edge.d.ts.map

package/dist/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../src/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AACnE,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE9F,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA"}