TypeScript Quickstart

Step 1 — Install the SDK

npm install @keylightdigital/nexus

Zero dependencies. Works in Node.js, Bun, Deno, Cloudflare Workers, and any edge runtime.

Step 2 — Set your API key

Create an API key at /dashboard/keys, then set it as an environment variable:

export NEXUS_API_KEY="nxs_your_api_key_here"

Step 3 — Create your first trace

Wrap your agent run with a trace, and add a span for each step — LLM calls, tool uses, API fetches:

import { NexusClient } from '@keylightdigital/nexus'

const nexus = new NexusClient({
  apiKey: process.env.NEXUS_API_KEY!,
  agentId: 'my-ts-agent',
})

// Start a trace for this agent run
const trace = await nexus.startTrace({ name: 'Summarize document' })

// Add a span for each step
await trace.addSpan({
  name: 'fetch-document',
  input: { url: 'https://example.com/doc.pdf' },
  output: { chars: 4200 },
})

await trace.addSpan({
  name: 'llm-summarize',
  input: { model: 'gpt-4o', promptTokens: 2100 },
  output: { summary: '...', completionTokens: 420 },
})

// Finish the trace
await trace.end({ status: 'success' })

Step 4 — Handle errors

Wrap your logic in try/catch and set status: "error" on failure. Error traces trigger email alerts for Pro users.

const trace = await nexus.startTrace({ name: 'Process order' })

try {
  await trace.addSpan({ name: 'validate-payment', input: { orderId } })
  const result = await processPayment(order)
  await trace.addSpan({
    name: 'payment-complete',
    output: { result },
  })
  await trace.end({ status: 'success' })
} catch (err) {
  await trace.addSpan({
    name: 'payment-error',
    error: String(err),
  })
  await trace.end({ status: 'error' })
  throw err
}

Step 5 — Add metadata for filtering

Attach arbitrary metadata to traces and spans to filter and debug in the dashboard:

const trace = await nexus.startTrace({
  name: 'research-task',
  metadata: {
    model: 'claude-3-5-sonnet',
    userId: 'usr_123',
    sessionId: 'ses_abc',
    environment: 'production',
  },
})

await trace.addSpan({
  name: 'web-search',
  input: { query: 'latest AI news', maxResults: 5 },
  output: { count: results.length },
})

Step 6 — Next.js App Router example

Place this in a route handler. The NexusClient instance is safe to create at module scope — it holds no mutable state across requests:

// app/api/agent/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { NexusClient } from '@keylightdigital/nexus'

const nexus = new NexusClient({
  apiKey: process.env.NEXUS_API_KEY!,
  agentId: 'nextjs-assistant',
})

export async function POST(req: NextRequest) {
  const { prompt } = await req.json()
  const trace = await nexus.startTrace({ name: 'chat-response' })

  try {
    await trace.addSpan({
      name: 'llm-call',
      input: { prompt },
    })

    const response = await callYourLLM(prompt)

    await trace.addSpan({
      name: 'llm-result',
      output: { text: response },
    })
    await trace.end({ status: 'success' })
    return NextResponse.json({ text: response })
  } catch (err) {
    await trace.end({ status: 'error' })
    return NextResponse.json({ error: String(err) }, { status: 500 })
  }
}