# @o11y-one/sdk

> Hand-written client wrapper over @o11y-one/api-agentic: transport construction, credential injection, and the O11y One error taxonomy.

Latest version **0.1.3** (published 2026-09-24) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @o11y-one/sdk
pnpm add @o11y-one/sdk
yarn add @o11y-one/sdk
bun add @o11y-one/sdk
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.3 |
| Published | 2026-09-24 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 5 |
| Unpacked size | 92 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Maintainers | o11y-one-admin |

## Links

- npm: https://www.npmjs.com/package/@o11y-one/sdk
- Repository: https://github.com/o11y-one/o11y-one-sdk
- Homepage: https://github.com/o11y-one/o11y-one-sdk#readme
- Issues: https://github.com/o11y-one/o11y-one-sdk/issues
- npm.io page: https://npm.io/package/@o11y-one/sdk

## Dependencies (5)

- [@bufbuild/protobuf](https://npm.io/package/@bufbuild/protobuf.md) ^2.15.0
- [@connectrpc/connect](https://npm.io/package/@connectrpc/connect.md) ^2.2.0
- [@o11y-one/api-agentic](https://npm.io/package/@o11y-one/api-agentic.md) 0.1.3
- [@connectrpc/connect-web](https://npm.io/package/@connectrpc/connect-web.md) ^2.2.0
- [@connectrpc/connect-node](https://npm.io/package/@connectrpc/connect-node.md) ^2.2.0

## Recent versions

- 0.1.3 (latest) — 2026-09-24
- 0.1.2 — 2026-09-24
- 0.1.1 — 2026-09-24
- 0.1.0 — 2026-09-24
- 0.0.0 — 2026-09-23

## README

# `@o11y-one/sdk`

The TypeScript client for the O11y One API. A thin, hand-written layer over the
generated [`@o11y-one/api-agentic`](../gen-ts-agentic) package.

## Install

```sh
pnpm add @o11y-one/sdk
```

## Use

```ts
import { O11yClient, classify } from "@o11y-one/sdk";
import { AgenticEvaluationService } from "@o11y-one/api-agentic/o11y_one/agentic/v1/evaluation_pb";

const o11y = new O11yClient({
  baseUrl: "https://grpc.o11y.one",
  credential: process.env.O11Y_API_KEY, // o11y_mach.<selector>.<secret>
  orgId: process.env.O11Y_ORG_ID,
});

const evals = o11y.service(AgenticEvaluationService);

try {
  const defs = await evals.listEvaluationDefinitions({});
} catch (err) {
  const failure = classify(err);
  if (failure.disposition === "insufficient-scope") {
    throw new Error(`credential is missing scope ${failure.missingScope}`);
  }
  throw err;
}
```

## What is here, and what deliberately is not

Three modules and nothing else:

| module | responsibility |
|---|---|
| `client.ts` | transport construction, credential and scoping header injection |
| `auth.ts`   | the credential wire format and local structural validation |
| `errors.ts` | the failure taxonomy: reauthenticate / insufficient-scope / version-skew / retry / unclassified |

Service methods are **not** wrapped. connect-es turns any generated descriptor
into a fully typed client; a hand-written facade over every service would be a
second API surface to keep in sync with the proto, and it would rot the first
time a field is added upstream.

## The distinction this package exists to preserve

`UNAUTHENTICATED` and `PERMISSION_DENIED` are different problems:

* **`UNAUTHENTICATED`** — the credential is absent, malformed, unknown, expired,
  or revoked. Re-auth. Retrying cannot change the answer.
* **`PERMISSION_DENIED`** — the credential is fine; it lacks a scope (the server
  names which one) or it was presented to a non-machine surface.

`classify()` keeps them apart, along with `UNAVAILABLE` (auth backend down —
retry with backoff) and `INVALID_ARGUMENT` (SDK/server version skew). Collapsing
these into a single "auth error" is the failure mode this module exists to
prevent.

## Credentials

A machine credential is `o11y_mach.<selector>.<secret>`, presented in the
`x-o11y-key` header. It is returned exactly once at creation (no read-back RPC,
no recovery path), rotated create-then-revoke rather than atomically, revoked
effective on the next request, and expires at +365 days by default with a
three-year cap.

Never send it as `authorization: Bearer` — that path carries the browser session
JWT and a machine credential presented there is rejected.

## Runtime support

The default transport is gRPC-web via `@connectrpc/connect-web`, which needs
only a spec-compatible `fetch`. That covers browsers, Node 26, Deno, Bun and
Cloudflare Workers. `@connectrpc/connect-node` is a dependency for callers who
want the Node-specific HTTP/2 transport and construct it themselves; pass the
resulting transport's options through `ClientOptions` or build your own
transport and install `credentialInterceptor()` on it. The API serves gRPC and
gRPC-web only, so a transport you build must speak one of those, not the
Connect protocol.

---
_Source: https://npm.io/package/@o11y-one/sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._