Express - Timeback Docs (Beta)

Overview

The Timeback SDK provides an Express middleware adapter. The catch-all route below uses Express 5 path syntax.

Installation

npm install @timeback/sdk express

pnpm add @timeback/sdk express

yarn add @timeback/sdk express

bun add @timeback/sdk express

Server Setup

Create a server-only Timeback instance. The session helpers below belong to your application: persist the callback user in your authenticated session, and return that session user (including email) or null from getUser. These helpers are not SDK exports. Keep API and SSO secrets on the server:

lib/timeback.ts

import { createTimeback } from '@timeback/sdk'

export const timeback = await createTimeback({
    env: 'staging',
    api: {
        clientId: process.env.TIMEBACK_API_CLIENT_ID!,
        clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
    },
    identity: {
        mode: 'sso',
        clientId: process.env.AWS_COGNITO_CLIENT_ID!,
        clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
        redirectUri: 'http://localhost:3000/api/timeback/identity/callback',
        onCallbackSuccess: async ({ user, state, redirect }) => {
            await setSession({ id: user.id, email: user.email })
            return redirect(state?.returnTo ?? '/')
        },
        onCallbackError: ({ error, redirect }) => {
            return redirect('/?error=sso_failed')
        },
        getUser: req => getSessionFromRequest(req),
    },
})

Middleware

Add the Timeback middleware to your Express app:

server.ts

import { toExpressMiddleware } from '@timeback/sdk/express'
import express from 'express'

import { timeback } from './lib/timeback'

const app = express()

// Parse JSON bodies
app.use(express.json())

// Mount Timeback routes
app.use('/api/timeback', toExpressMiddleware(timeback))

// Your other routes...
app.get('/', (req, res) => {
    res.send('Hello World')
})

app.listen(3000, () => {
    console.log('Server running on port 3000')
})

Alternative: Mount on Router

For more control, you can mount routes on an Express Router:

server.ts

import { mountExpressRoutes } from '@timeback/sdk/express'
import express from 'express'

import { timeback } from './lib/timeback'

const app = express()
const router = express.Router()
app.use(express.json())

// Mount Timeback routes on router
mountExpressRoutes(timeback, router)

// Use the router
app.use('/api/timeback', router)

Routes

The middleware handles these routes under /api/timeback:

Route	Method	Purpose
`/identity/signin`	GET	Initiates SSO flow
`/identity/callback`	GET	Handles SSO callback
`/identity/signout`	GET	Initiates Timeback sign-out
`/user/verify`	GET	Verifies user session
`/user/me`	GET	Fetches user profile
`/activity/heartbeat`	POST	Time-spent heartbeat
`/activity/submit`	POST	Activity completion submit

Usage

Beyond the HTTP routes, you can use the Timeback instance directly for server-side operations like verifying users, fetching profiles, or recording activity completions:

server.ts

import { timeback } from './lib/timeback'

// Verify a user exists in Timeback
const result = await timeback.user.verify('student@example.com')

if (result.verified) {
    console.log(result.timebackId)
}

// Fetch full enriched profile
const profile = await timeback.user.getProfile('student@example.com')

console.log(profile.xp?.today, profile.courses)

See user profile for full documentation on verify() and getProfile().

With Frontend Framework

When using Express with a frontend framework like React:

server.ts

import path from 'path'

import { toExpressMiddleware } from '@timeback/sdk/express'
import express from 'express'

import { timeback } from './lib/timeback'

const app = express()

app.use(express.json())
app.use('/api/timeback', toExpressMiddleware(timeback))

// Serve static files from React build
app.use(express.static(path.join(__dirname, 'dist')))

// Handle client-side routing
// Express 5 catch-all, including the root path
app.get('/{*path}', (req, res) => {
    res.sendFile(path.join(__dirname, 'dist', 'index.html'))
})

app.listen(3000)

Next Steps

React Client

Client-side React integration

Identity

Authentication options

Custom Activities

Track learning sessions

​Overview

​Installation

​Server Setup

​Middleware

​Alternative: Mount on Router

​Routes

​Usage

​With Frontend Framework

​Next Steps

React Client

Identity

Custom Activities

Overview

Installation

Server Setup

Middleware

Alternative: Mount on Router

Routes

Usage

With Frontend Framework

Next Steps