# TypeScript SDK

Send spans from Node.js / TypeScript agents to a local tj serve over HTTP.

---

The TypeScript SDK is a thin client that builds spans and POSTs them to a running `tj serve`. It's the fastest path to instrument a JS/TS agent.

## Install

```bash
npm install @tokenjam/sdk
```

Start the local server alongside your agent:

```bash
tj serve
```

## Usage

```typescript
import { TjClient, SpanBuilder } from "@tokenjam/sdk";

const client = new TjClient({
  baseUrl:      "http://127.0.0.1:7391",
  ingestSecret: process.env.TJ_INGEST_SECRET ?? "",
});

const span = new SpanBuilder("invoke_agent")
  .agentId("my-ts-agent")
  .model("gpt-4o-mini")
  .provider("openai")
  .inputTokens(450)
  .outputTokens(120)
  .build();

await client.send([span]);
```

The `TJ_INGEST_SECRET` is generated by `tj init` and stored in your config. `tj doctor` will print it.

## Span fields

`SpanBuilder` supports the OTel GenAI SemConv attributes plus TokenJam extensions:

- `.agentId(string)`: required. Maps to `service.name`.
- `.model(string)`: required for cost calculation.
- `.provider(string)`: `openai`, `anthropic`, `google`, `bedrock`, etc.
- `.inputTokens(number)` / `.outputTokens(number)`
- `.toolName(string)`: for tool-call spans.
- `.parentSpanId(string)`: link to a parent span.
- `.sessionId(string)`: group spans into a session.
- `.error(string)`: record a failure.

Spans are validated against the GenAI SemConv schema on ingest. Malformed spans surface as warnings in `tj doctor`.

## Coming soon

Framework patches for LangChain JS, OpenAI Agents SDK (TypeScript), Vercel AI SDK, and Mastra are tracked in the [OSS issue tracker](https://github.com/Metabuilder-Labs/tokenjam/issues).