# @telemio/sdk

`@telemio/sdk` is the published first-party JavaScript/TypeScript SDK for trusted application runtimes that need explicit Telemio context in addition to standard OpenTelemetry instrumentation.

Install it from npm:

```bash
npm i @telemio/sdk
```

Package: https://www.npmjs.com/package/@telemio/sdk

## Create a client

```ts
import { createTelemio } from "@telemio/sdk"

const telemio = createTelemio({
  apiKey: process.env.TELEMIO_API_KEY,
  serviceName: "checkout-api",
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION
})
```

The default endpoint is `https://api.telemio.sh`.

## Available surfaces

- `telemio.tracer`: explicit spans and `withSpan` helpers
- `telemio.logger`: structured log records
- `telemio.metrics`: counters and timings
- `telemio.track`: product and custom events
- `telemio.agent`: agent, workflow, tool, usage, and fingerprint helpers
- `telemio.context`: context load/reuse metadata
- `telemio.flags`: feature flag evaluation
- `telemio.experiments`: experiment event tracking

The package also exports `createTelemioOpenFeatureProvider()`.

## Where to use it

Use the SDK on trusted JavaScript/TypeScript runtimes such as backend services, workers, serverless functions, edge processes with protected server-side configuration, CLIs, and agent runtimes.

Do not embed privileged Telemio API keys in browser bundles, iOS/Swift apps, Android/Kotlin apps, React Native bundles, Electron-style distributed clients, or other binaries delivered to end users. Those runtimes should use browser/mobile OpenTelemetry instrumentation and a client-safe collection path or trusted telemetry gateway.

For Java/JVM, Python, Go, .NET, Swift/iOS, Android/Kotlin, and other languages, use their standard OpenTelemetry instrumentation. Telemio does not require every runtime to use a Telemio-specific SDK.

## Agent example

```ts
const run = telemio.agent.startAgent("support-agent", {
  "gen_ai.provider.name": "openai",
  "gen_ai.request.model": "gpt-5"
})

const tool = telemio.agent.startTool("lookup_customer", {
  "gen_ai.tool.type": "datastore"
}, run)

await tool.end()
await telemio.agent.recordUsage({
  agentName: "support-agent",
  provider: "openai",
  model: "gpt-5",
  inputTokens: 820,
  outputTokens: 142
})

run.setStatus("ok")
await run.end()
```

Agent helpers do not automatically export prompt or completion bodies.

## Relationship to OpenTelemetry

Use standard OpenTelemetry auto-instrumentation before adding manual SDK calls. The SDK is for application-specific meaning: business operations, product events, agent metadata, context fingerprints, flags, and experiments.