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

# Migrate from @honeyhive/logger

> Move from the @honeyhive/logger package to @honeyhive/api-client

This guide walks through migrating from the [`@honeyhive/logger`](https://www.npmjs.com/package/@honeyhive/logger) package to [`@honeyhive/api-client`](https://www.npmjs.com/package/@honeyhive/api-client).

## What changes for you

`@honeyhive/logger` targets HoneyHive v1 and is being replaced by `@honeyhive/api-client`, the typed v2 SDK. The two are not drop-in compatible, but you get a lot more in return:

* **Full typed access to the v2 API.** Beyond logging events, you can manage datasets, datapoints, experiments, metrics, and event search from the same client.
* **One `Client` instance, not per-call config.** Set your API key once via `HH_API_KEY` instead of passing `apiKey` (and `project`) on every call.
* **Project scope is automatic.** v2 API keys are scoped to a single project, so the SDK no longer needs a `project` parameter. If you write to multiple projects, construct one `Client` per key.
* **Errors surface instead of being swallowed.** Failed calls throw typed errors you can catch, rather than logging to `console.error` and returning `undefined`.

Logger's three functions (`start`, `log`, `update`) map onto two namespaces on the new client: [`client.sessions`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#sessions) and [`client.events`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#events).

## Install and import

```bash theme={null}
npm uninstall @honeyhive/logger
npm install @honeyhive/api-client
```

Old:

```ts theme={null}
import { start, log, update } from "@honeyhive/logger";
```

New:

```ts theme={null}
import { Client } from "@honeyhive/api-client";

const client = new Client(); // reads HH_API_KEY from env
```

## Configuration

See the full [`ClientConfig` reference](https://honeyhiveai.github.io/typescript-api-client/interfaces/ClientConfig.html) for every option. The most common settings and mechanism for setting them are below.

| Concept                          | Logger (`@honeyhive/logger`)                           | API client (`@honeyhive/api-client`)                                                                                                                                                    |
| -------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key                          | `apiKey` param on every call.                          | Set the `HH_API_KEY` environment variable.                                                                                                                                              |
| Project                          | `project` param on every call.                         | Determined by the API key's project scope. **No `project` parameter exists.**                                                                                                           |
| Data Plane URL (was `serverUrl`) | `serverUrl` param, default `https://api.honeyhive.ai`. | `dataPlaneUrl` in the `Client` constructor or `HH_DATA_PLANE_URL` environment variable, default `https://api.dp1.us.honeyhive.ai`. `serverUrl` and `HH_API_URL` are deprecated aliases. |
| Source / environment             | `source` param, default `"dev"`.                       | `source` on the session/event body. Both sessions and events default to `"unknown"` if omitted. Set it explicitly (e.g. `"prod"`, `"staging"`) if you want to filter by environment.    |
| Verbose                          | `verbose` per-call.                                    | `HH_VERBOSE=true` env var (or `ClientConfig.verbose`). One-shot startup log of resolved URL and masked key.                                                                             |

### TLS / certificate verification

Logger exposed a per-call `verify` flag (Node-only). The new SDK is isomorphic - it runs in Node and the browser - and TLS verification isn't something you can flip from JavaScript in the browser, so the SDK doesn't expose a flag.

In Node, if you genuinely need to disable verification (for example, to talk to an internal HoneyHive deployment with a self-signed cert), use the standard Node environment variables: prefer `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` to register the internal CA, or `NODE_TLS_REJECT_UNAUTHORIZED=0` as a last resort. Do not disable verification against the public HoneyHive endpoint.

In the browser, certificate trust is browser-managed - trust the cert at the OS or browser level.

### Retry behavior changed

<Warning>
  Logger had built-in retry (3 attempts, exponential backoff with jitter, retrying on 5xx / 408 / 429 / network errors). **The new SDK does not retry.** If you relied on logger's retry behavior in production, you'll need to add it yourself - wrap calls in a small retry helper or use a library like [`p-retry`](https://www.npmjs.com/package/p-retry).
</Warning>

## Function-by-function migration

### `start(...)` → `client.sessions.create(...)`

See the [`sessions` namespace](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#sessions) for the full method reference.

Before:

```ts theme={null}
const sessionId = await start({
  apiKey: "hh_...",
  project: "my-project",
  sessionName: "my-session",
  source: "dev",
  config: {
    /* ... */
  },
  inputs: {
    /* ... */
  },
  metadata: {
    /* ... */
  },
  userProperties: {
    /* ... */
  },
});
```

After:

```ts theme={null}
const { session_id } = await client.sessions.create({
  session_name: "my-session",
  source: "dev",
  config: {
    /* ... */
  },
  inputs: {
    /* ... */
  },
  metadata: {
    /* ... */
  },
  user_properties: {
    /* ... */
  },
});
```

| Logger           | New SDK                                                          | Notes                                                                              |
| ---------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `apiKey`         | `Client` constructor / `HH_API_KEY`                              | Once per client, not per call                                                      |
| `project`        | -                                                                | Determined by API key                                                              |
| `sessionName`    | `session_name`                                                   |                                                                                    |
| `source`         | `source`                                                         |                                                                                    |
| `sessionId`      | `session_id`                                                     | UUID still optional; auto-generated if omitted                                     |
| `config`         | `config`                                                         |                                                                                    |
| `inputs`         | `inputs`                                                         |                                                                                    |
| `metadata`       | `metadata`                                                       |                                                                                    |
| `userProperties` | `user_properties`                                                |                                                                                    |
| `serverUrl`      | `dataPlaneUrl` in the `Client` constructor / `HH_DATA_PLANE_URL` | Once per client, not per call. `serverUrl` and `HH_API_URL` are deprecated aliases |
| `verbose`        | `Client` constructor / `HH_VERBOSE`                              | One-shot startup log, not per-call verbosity                                       |

The new SDK returns the full [`CreateSessionResponse`](https://honeyhiveai.github.io/typescript-api-client/types/CreateSessionResponse.html) (which includes both `session_id` and a separate `event_id` - see [Updating a session](#updating-a-session) below) and **throws** on failure rather than swallowing the error. See [Error handling](#error-handling) below.

### `log(...)` → `client.events.create(...)`

See the [`events` namespace](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#events) for the full method reference.

Before:

```ts theme={null}
const eventId = await log({
  apiKey: "hh_...",
  project: "my-project",
  sessionId,
  eventName: "model_inference",
  eventType: "model",
  durationMs: 120,
  inputs: { prompt: "..." },
  outputs: { response: "..." },
  config: {
    /* ... */
  },
  metadata: {
    /* ... */
  },
});
```

After:

```ts theme={null}
const { event_id } = await client.events.create({
  session_id,
  event_name: "model_inference",
  event_type: "model",
  duration: 120,
  inputs: { prompt: "..." },
  outputs: { response: "..." },
  config: {
    /* ... */
  },
  metadata: {
    /* ... */
  },
});
```

| Logger                                    | New SDK                                                                                                  | Notes                                                                                 |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `apiKey` / `project`                      | -                                                                                                        | Set on the client / API key, not per call                                             |
| `sessionId`                               | `session_id`                                                                                             |                                                                                       |
| `eventName`                               | `event_name`                                                                                             |                                                                                       |
| `eventType`                               | `event_type`                                                                                             | Same union: `'model' \| 'tool' \| 'chain'`. New SDK additionally accepts `'session'`. |
| `durationMs`                              | `duration`                                                                                               | **Renamed**: still milliseconds.                                                      |
| `source`                                  | `source`                                                                                                 |                                                                                       |
| `config`, `inputs`, `outputs`, `metadata` | same names                                                                                               |                                                                                       |
| -                                         | `parent_id`, `children_ids`, `error`, `start_time`, `end_time`, `feedback`, `metrics`, `user_properties` | New optional fields you didn't have before                                            |

If you log many events back-to-back, take a look at `client.events.createBatch({ events: [...] })` - it submits them in a single request.

### `update(...)` → `client.events.update(...)`

Before:

```ts theme={null}
await update({
  apiKey: "hh_...",
  eventId, // logger accepted either an event_id OR a session_id
  metadata: {
    /* ... */
  },
  feedback: { rating: 5 },
  metrics: { latency: 100 },
  outputs: {
    /* ... */
  },
  config: {
    /* ... */
  },
  userProperties: {
    /* ... */
  },
  durationMs: 120,
});
```

After:

```ts theme={null}
await client.events.update({
  event_id,
  metadata: {
    /* ... */
  },
  feedback: { rating: 5 },
  metrics: { latency: 100 },
  outputs: {
    /* ... */
  },
  config: {
    /* ... */
  },
  user_properties: {
    /* ... */
  },
  duration: 120,
});
```

Same renames as above: `durationMs` → `duration`, `userProperties` → `user_properties`.

### Updating a session

This is a meaningful behavior change. In v1, the legacy server treated `session_id` and `event_id` interchangeably for updates, so logger's `update({ eventId })` would accept either. **In v2 it does not** - passing a `session_id` to `events.update` returns a `400 Bad Request` with the message `no event with event_id - <id> found`.

A session is itself an event with `event_type: 'session'`. `client.sessions.create` returns **both** identifiers:

* `session_id` - the session correlation ID. Use this as the `session_id` on child events to associate them with the session.
* `event_id` - the row ID of the session-typed event itself. Use this when you want to update the session row.

```ts theme={null}
const { session_id, event_id: session_event_id } = await client.sessions.create(
  {
    session_name: "my-session",
  },
);

// Use session_id as the parent on child events
await client.events.create({
  session_id,
  event_type: "model",
  event_name: "chat",
  /* ... */
});

// Use session_event_id when you want to update the session row itself
await client.events.update({
  event_id: session_event_id,
  metadata: {
    /* ... */
  },
  outputs: {
    /* ... */
  },
});
```

[`events.update`](https://honeyhiveai.github.io/typescript-api-client/interfaces/UpdateEventRequest.html) only merges nine specific fields: `metadata`, `feedback`, `metrics`, `outputs`, `config`, `user_properties`, `duration`, `end_time`, `children_ids`. Other fields are accepted by the server but silently ignored.

## End-to-end example

A complete flow - start a session, log a model event, update it with the response - looks like this:

```ts theme={null}
import { Client } from "@honeyhive/api-client";
import OpenAI from "openai";

const client = new Client();
const openai = new OpenAI();

const { session_id } = await client.sessions.create({
  session_name: "openai-example",
  source: "dev",
});

const startTime = Date.now();
const { event_id } = await client.events.create({
  session_id,
  event_type: "model",
  event_name: "chat-completion",
  config: { model: "gpt-4o-mini" },
  inputs: {
    messages: [{ role: "user", content: "What is the meaning of life?" }],
  },
});

const completion = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "What is the meaning of life?" }],
});
const { content } = completion.choices[0].message;

if (content) {
  await client.events.update({
    event_id,
    outputs: { content },
    duration: Date.now() - startTime,
    metadata: { model: completion.model, usage: completion.usage },
  });
}
```

The [`@honeyhive/api-client` README](https://github.com/honeyhiveai/typescript-api-client#readme) has the same example with more commentary.

## Error handling

Logger swallowed errors by default - when a call failed, it logged to `console.error` and returned `null` (set `verbose: true` to make it throw instead). The new SDK **throws** on failure:

* [`ApiError`](https://honeyhiveai.github.io/typescript-api-client/classes/ApiError.html) - the server returned a non-2xx response. Carries `.status`, `.response`, `.error`, and a `.parseError()` helper that returns a typed [`ErrorResponse`](https://honeyhiveai.github.io/typescript-api-client/interfaces/ErrorResponse.html) when the body matches.
* [`NetworkError`](https://honeyhiveai.github.io/typescript-api-client/classes/NetworkError.html) - the request never made it to the server (DNS, connection reset, TLS failure, etc.). Carries `.error` with the underlying cause.

Both extend [`HoneyHiveError`](https://honeyhiveai.github.io/typescript-api-client/classes/HoneyHiveError.html), so a single `catch (err) { if (err instanceof HoneyHiveError) ... }` handles both:

```ts theme={null}
import { Client, ApiError, NetworkError } from "@honeyhive/api-client";

try {
  await client.sessions.create({ session_name: "my-session" });
} catch (err) {
  if (err instanceof ApiError) {
    console.error(`HoneyHive API error ${err.status}:`, err.parseError());
  } else if (err instanceof NetworkError) {
    console.error("HoneyHive network error:", err.error);
  } else {
    throw err;
  }
}
```

If you previously relied on logger's silent-failure behavior (your code expected `null` on failure and kept going), you'll need to add a `try`/`catch` to preserve that behavior - or, better, decide whether failing loud is what you actually want.

## What else you get

Migrating opens up a much larger API surface. None of these have a logger equivalent:

* [`client.events.search`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#events) - query events by filter, date range, or evaluation\_id
* [`client.events.createBatch`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#events) - bulk-create events in one request
* [`client.datasets`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#datasets) - create, list, update, delete datasets and add/remove datapoints
* [`client.datapoints`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#datapoints) - CRUD on datapoints
* [`client.experiments`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#experiments) - manage runs, fetch run schemas, compare runs
* [`client.metrics`](https://honeyhiveai.github.io/typescript-api-client/classes/Client.html#metrics) - create, list, run server-side metrics

For worked examples see the [`@honeyhive/api-client` README](https://github.com/honeyhiveai/typescript-api-client#readme). For the full reference, see [the API SDK reference site](https://honeyhiveai.github.io/typescript-api-client/).