init() / createClient()

The TypeScript SDK provides two initialization functions: init() for synchronous setup and createClient() for async setup with connection validation.

init()

function init(options: SideSeatOptions): SideSeat;

Synchronous initialization. Returns a SideSeat instance.

Parameters

options

interface SideSeatOptions {
  framework: Framework | string;  // required
  disabled?: boolean;
  endpoint?: string;
  apiKey?: string;
  projectId?: string;
  serviceName?: string;
  serviceVersion?: string;
  enableTraces?: boolean;
  logLevel?: LogLevel;
  debug?: boolean;
}

framework is required. Omitting it throws a SideSeatError at runtime. Use a Frameworks.* constant.

See Configuration for details on each option.

Returns

SideSeat — the initialized client instance.

Behavior

When called, init():

1. Creates a NodeTracerProvider with resource attributes
2. Configures a BatchSpanProcessor with OTLP HTTP exporter
3. Registers the provider globally via provider.register()

The function is idempotent. Multiple calls return the existing instance:

const a = init({ framework: Frameworks.VercelAI });   // Initializes OpenTelemetry
const b = init({ framework: Frameworks.VercelAI });   // Returns same instance, logs warning
console.log(a === b); // true

Note

Once initialized, the configuration cannot be changed. If you need different settings, restart your application.

Examples

import { init, Frameworks } from '@sideseat/sdk';

// Minimal
init({ framework: Frameworks.VercelAI });

// With options
const client = init({
  framework: Frameworks.Strands,
  endpoint: 'http://sideseat.example.com:5388',
  projectId: 'my-project',
  serviceName: 'my-ai-agent',
  debug: true
});

// Environment-based
init({ framework: Frameworks.VercelAI, debug: process.env.NODE_ENV !== 'production' });

createClient()

function createClient(options?: SideSeatOptions): Promise<SideSeat>;

Async initialization with connection validation. Preferred for production use.

Returns

Promise<SideSeat> — resolves to the initialized client instance.

Behavior

Same as init() but additionally validates the endpoint is reachable before returning. Safe against concurrent calls — returns the same promise if called while initialization is in progress.

Examples

import { createClient } from '@sideseat/sdk';

const client = await createClient({
  endpoint: 'http://sideseat.internal:5388',
  projectId: 'production'
});

getClient()

function getClient(): SideSeat;

Get the global SideSeat instance. Throws SideSeatError if not initialized.

import { init, getClient, Frameworks } from '@sideseat/sdk';

init({ framework: Frameworks.VercelAI });

// Later, in another module
const client = getClient();

shutdown()

function shutdown(): Promise<void>;

Shutdown the global instance, flushing pending spans and releasing resources.

import { shutdown } from '@sideseat/sdk';

await shutdown();

isInitialized()

function isInitialized(): boolean;

Check whether SideSeat has been initialized.

Global Registration

After initialization, any code using @opentelemetry/api will use the configured provider:

import { init, Frameworks } from '@sideseat/sdk';
import { trace } from '@opentelemetry/api';

init({ framework: Frameworks.VercelAI });

// This tracer uses the SideSeat-configured provider
const tracer = trace.getTracer('my-module');

Usage with Frameworks

Vercel AI SDK

import { init, Frameworks } from '@sideseat/sdk';
import { generateText } from 'ai';
import { bedrock } from '@ai-sdk/amazon-bedrock';

init({ framework: Frameworks.VercelAI });

const { text } = await generateText({
  model: bedrock('us.anthropic.claude-sonnet-4-5-20250929-v1:0'),
  prompt: 'Hello!',
  experimental_telemetry: { isEnabled: true },
});

Strands (TypeScript)

import { init, Frameworks } from '@sideseat/sdk';
import { Agent } from '@strands-agents/sdk';

init({ framework: Frameworks.Strands });

const agent = new Agent({ model: 'global.anthropic.claude-haiku-4-5-20251001-v1:0' });
const result = await agent.invoke('Hello!');
console.log(result.toString());

Express

import { init, Frameworks } from '@sideseat/sdk';
import express from 'express';

// Initialize before creating the app
init({ framework: Frameworks.VercelAI });

const app = express();

app.get('/chat', async (req, res) => {
  const response = await callAIModel(req.query.message);
  res.json({ response });
});

app.listen(3000);

Automatic Shutdown

The SDK automatically handles shutdown via Node.js process events. For explicit control:

import { trace } from '@opentelemetry/api';

const provider = trace.getTracerProvider();
if ('forceFlush' in provider) {
  await provider.forceFlush();
}

Next Steps

• Configuration — all configuration options
• Integrations — framework-specific guides