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

# TypeScript SDK

> Instrument your TypeScript agents with ProvenLog

## Installation

```bash theme={null}
npm install provenlog
```

**Requirements:** Node.js 18+

## Basic usage

```typescript theme={null}
import { ProvenLogClient } from "provenlog";

const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "my-agent",
});

client.logEvent({
  action_type: "TOOL_CALL",
  action_name: "fetch_data",
  action_input: { query: "revenue Q4" },
  action_status: "success",
  action_output: { results: 42 },
});

await client.close();
```

## Client configuration

```typescript theme={null}
const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "my-agent",        // Default agent ID
  sessionId: "session-123",   // Default session ID
  metadata: { env: "prod" },  // Default metadata
  labels: { dept: "finance" },// Default labels
  context: {                  // Initial label context for dashboard enrichment
    dept: { displayName: "Finance", costCenter: "CC-100" },
  },
  batchSize: 100,             // Events per batch
  flushInterval: 1000,        // Milliseconds between flushes
  timeout: 30000,             // HTTP timeout in ms
  apiKey: "your-key",         // Bearer token for auth
});
```

<Note>
  The TypeScript SDK currently operates in server mode only. Start a `plog serve` instance and point the client at it.
</Note>

## Logging events

```typescript theme={null}
client.logEvent({
  action_type: "TOOL_CALL",
  action_name: "search_database",
  action_input: { query: "revenue Q4" },
  action_output: { results: 42 },
  action_status: "success",
  duration_ms: 150,
  metadata: { model: "claude-sonnet-4-5-20250929" },
  labels: { env: "prod" },
});
```

## Labels and context

### Default labels

Labels passed to the constructor are merged into every event. Event-level labels override defaults for matching keys.

```typescript theme={null}
const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "loan-processor",
  labels: { env: "prod", dept: "lending" },
});

// This event will have labels { env: "prod", dept: "lending", loan_id: "LN-2024-4821" }
client.logEvent({
  action_type: "TOOL_CALL",
  action_name: "pull_credit_report",
  action_status: "success",
  labels: { loan_id: "LN-2024-4821" },
});
```

### Label context

`setContext()` attaches business data to a label value for dashboard enrichment — for example, attaching a borrower name and loan amount to a `loan_id`.

```typescript theme={null}
const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "loan-processor",
  labels: { loan_id: "LN-2024-4821" },
});

await client.setContext("loan_id", {
  borrower: "Alice Rivera",
  amount: 420000,
  stage: "underwriting",
});
```

The label key must exist in the client's default labels — otherwise an `Error` is thrown. The data is sent as a fire-and-forget `PUT /v1/context/{key}/{value}` request. Transport errors are logged with `console.warn` and never throw.

You can also push context at construction time with the `context` option (fire-and-forget, promises are not awaited):

```typescript theme={null}
const client = new ProvenLogClient("http://localhost:7600", {
  agentId: "loan-processor",
  labels: { loan_id: "LN-2024-4821", env: "prod" },
  context: {
    loan_id: { borrower: "Alice Rivera", amount: 420000 },
    env: { displayName: "Production", region: "us-east-1" },
  },
});
```

## Lifecycle

```typescript theme={null}
// Flush pending events
await client.flush();

// Clean shutdown
await client.close();
```