Skip to main content

​
Overview

The Timeback SDK provides a Next.js adapter for the App Router with route handlers. If you are using coding agents, pair this page with timeback-server from the AI Skills catalog.

​
Installation

npm install @timeback/sdk

​
Server Setup

Create a Timeback instance:
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: () => getSession(),
	},
})

​
Route Handler

Create a catch-all route handler:
app/api/timeback/[...timeback]/route.ts
import { toNextjsHandler } from '@timeback/sdk/nextjs'

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

export const { GET, POST, PUT, DELETE, PATCH } = toNextjsHandler(timeback)
This handles all Timeback routes:
RouteMethodPurpose
/api/timeback/identity/signinGETInitiates SSO flow
/api/timeback/identity/callbackGETHandles SSO callback
/api/timeback/identity/signoutGET/POSTSigns out user
/api/timeback/user/verifyGETVerifies user session
/api/timeback/user/meGETFetches user profile
/api/timeback/activity/heartbeatPOSTTime-spent heartbeat
/api/timeback/activity/submitPOSTActivity completion submit

​
Client Provider

Wrap your app with the TimebackProvider:
app/providers.tsx
'use client'

import { TimebackProvider } from '@timeback/sdk/react'

export function Providers({ children }: { children: React.ReactNode }) {
	return <TimebackProvider>{children}</TimebackProvider>
}
app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }) {
	return (
		<html>
			<body>
				<Providers>{children}</Providers>
			</body>
		</html>
	)
}

​
Usage

For the full client-side API, see the React client adapter.
Use hooks in client components:
components/UserStatus.tsx
'use client'

import { SignInButton, useTimeback } from '@timeback/sdk/react'

export function UserStatus() {
	const timeback = useTimeback()

	if (!timeback) {
		return <SignInButton>Sign In</SignInButton>
	}

	return <div>Welcome!</div>
}

​
Next Steps

React Client

Client-side React integration

Identity

Authentication options

Custom Activities

Track learning sessions