> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trulayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK reference

> Every public export of @trulayer/sdk.

For narrative usage see the [tutorial](/sdks/typescript/tutorial). For config details see [configuration](/sdks/typescript/configuration). For runnable end-to-end demos see [examples](/sdks/typescript/examples).

## Source and issues

* **Source:** [github.com/trulayer/client-typescript](https://github.com/trulayer/client-typescript)
* **Issues / bug reports:** [github.com/trulayer/client-typescript/issues](https://github.com/trulayer/client-typescript/issues)
* **Package:** [`@trulayer/sdk` on npm](https://www.npmjs.com/package/@trulayer/sdk)

## `TruLayer` class

The main client. Import and construct once per app.

```typescript theme={null}
import { TruLayer } from "@trulayer/sdk";

const tl = new TruLayer({
  apiKey: string,
  projectName: string,          // human-readable project name
  projectId?: string,           // @deprecated — use projectName. Removed in 0.3.x.
  endpoint?: string,
  batchSize?: number,
  flushInterval?: number,
  sampleRate?: number | (() => boolean),
  redact?: (value: unknown) => unknown,
  relayUrl?: string,
});
```

### Methods

| Method           | Signature                                                 | Returns                                           |
| ---------------- | --------------------------------------------------------- | ------------------------------------------------- |
| `trace`          | `(name, fn, opts?)`                                       | `Promise<T>` where `T` is the fn's resolved value |
| `submitFeedback` | `({ traceId, label?, score?, comment?, metadata? })`      | `Promise<void>`                                   |
| `runEval`        | `({ traceId, evaluatorType, metricName })`                | `Promise<EvalResult>`                             |
| `getMetrics`     | `({ projectId, from, to, filters? })`                     | `Promise<Metrics>`                                |
| `getTraces`      | `({ projectId?, from?, to?, cursor?, limit?, filters? })` | `Promise<TracesPage>`                             |
| `getTrace`       | `(id)`                                                    | `Promise<TraceData>`                              |
| `flush`          | `()`                                                      | `Promise<void>`                                   |
| `shutdown`       | `()`                                                      | `Promise<void>`                                   |

### `trace()`

```typescript theme={null}
await tl.trace(
  name: string,
  fn: (trace: TraceContext) => Promise<T> | T,
  options?: { sessionId?: string; metadata?: Record<string, unknown> },
): Promise<T>
```

The return value of `fn` becomes the return value of `trace()`. Exceptions are captured onto the trace as errors, then re-thrown.

## `TraceContext`

Passed to the `trace()` callback.

| Method                 | Purpose                         |
| ---------------------- | ------------------------------- |
| `setInput(value)`      | Trace input                     |
| `setOutput(value)`     | Trace output                    |
| `setMetadata(obj)`     | Merge key-value metadata        |
| `setError(err)`        | Mark errored                    |
| `span(name, type, fn)` | Create a child span (see below) |
| `id` (getter)          | Trace UUID                      |
| `sessionId` (getter)   | Session ID if set               |

### `span()`

```typescript theme={null}
await trace.span(
  name: string,
  type: "llm" | "retrieval" | "tool" | "other",
  fn: (span: SpanContext) => Promise<T> | T,
): Promise<T>
```

## `SpanContext`

| Method                            | Purpose                                      |
| --------------------------------- | -------------------------------------------- |
| `setInput(value)`                 | Span input                                   |
| `setOutput(value)`                | Span output                                  |
| `setMetadata(obj)`                | Metadata                                     |
| `setModel(name)`                  | Model name (for `llm` spans)                 |
| `setTokens(prompt?, completion?)` | Token counts (positional numbers)            |
| `setCost(usd)`                    | Cost of this span in USD (number), chainable |
| `setError(err)`                   | Mark errored                                 |
| `id` (getter)                     | Span UUID                                    |

## Instrumentation helpers

### `instrumentOpenAI(client, tl?)`

```typescript theme={null}
import OpenAI from "openai";
import { instrumentOpenAI } from "@trulayer/sdk";

const openai = instrumentOpenAI(new OpenAI(), tl);
```

Returns a Proxy-wrapped client; every `chat.completions.create` and `embeddings.create` call becomes a span automatically.

### `instrumentAnthropic(client, tl?)`

```typescript theme={null}
import Anthropic from "@anthropic-ai/sdk";
import { instrumentAnthropic } from "@trulayer/sdk";

const anthropic = instrumentAnthropic(new Anthropic(), tl);
```

### `instrumentVercelAI(tl?)`

```typescript theme={null}
import { instrumentVercelAI } from "@trulayer/sdk";

instrumentVercelAI(tl);
// every generateText/streamText/generateObject/streamObject from "ai" is now traced
```

## Module-level helpers

### `init()` / `getClient()`

If you prefer a global pattern over passing `tl` explicitly:

```typescript theme={null}
import { init, getClient } from "@trulayer/sdk";

init({ apiKey: "...", projectName: "..." });

const tl = getClient();
```

## Types

All of the following are exported type-only (no runtime cost):

```typescript theme={null}
import type {
  TruLayerConfig,
  TraceData,
  SpanData,
  SpanType,       // "llm" | "retrieval" | "tool" | "other"
  FeedbackData,
  EvalResult,
  Metrics,
} from "@trulayer/sdk";
```

## Error handling

SDK errors are logged, not thrown to your code — a failed flush drops traces but never interrupts your app. Subscribe to errors with:

```typescript theme={null}
tl.onError((err) => {
  console.error("trulayer:", err);
});
```

Exception types (re-exported for narrowing):

| Class                 | Reason                 |
| --------------------- | ---------------------- |
| `TruLayerError`       | Base class             |
| `AuthenticationError` | Invalid API key        |
| `RateLimitError`      | Plan limit hit         |
| `ValidationError`     | Bad trace/span payload |