# SDK API reference

Call the correct API for the browser, Node, or edge runtime.


## Runtime entries

| Entry | Main exports |
| --- | --- |
| `@everock/sdk` | `init`, `capture`, `captureError`, `identify`, `getConsent`, `setConsent`, `flush`, `shutdown`, `getDiagnostics` |
| `@everock/sdk/node` | `init`, `capture`, `captureError`, `requestHandler`, `errorHandler`, `withRequest`, `withSpan`, `webhook`, `track`, `instrument`, `registerEndpoints`, `flush`, `shutdown`, `getDiagnostics` |
| `@everock/sdk/edge` | `init`, `captureError`, `withRequest`, `registerEndpoints`, `flush`, `getDiagnostics` |

Framework packages wrap selected exports. An edge worker does not gain browser identity, DOM replay, or Node database instrumentation by importing the generic package.

## Capture a handled error

The browser takes error options as its second argument:

```ts title="Browser"
import { captureError } from '@everock/sdk';
captureError(new Error('Checkout failed'), {
  handled: true,
  mechanism: 'business_failure',
  operation: 'checkout',
  extra: { orderType: 'subscription' },
});
```

Node and edge take extra context second and signal options third:

```ts title="Node or edge"
import { captureError } from '@everock/sdk/node';
captureError(new Error('Checkout failed'),
  { orderType: 'subscription' },
  { handled: true, mechanism: 'business_failure', operation: 'checkout' },
);
```

Use the edge import in a worker. These calls queue an event; they do not promise that detection will create a new incident or send a notification. See [errors and detection](/docs/features/errors).

## Custom events

Browser `capture(type, message?, payload?)` accepts `error`, `session`, `trace`, or `log`. Prefer `captureError` for an exception so its handled state and mechanism are explicit. Node's generic `capture` accepts `log` and `trace`.

```ts title="Custom trace"
import { capture } from '@everock/sdk';
capture('trace', 'checkout-step', { step: 'confirmation' });
```

Do not put credentials, request bodies, or private customer data in a custom payload. Local redaction cannot infer every sensitive application-specific value.

## Browser identity and consent

```ts title="Visitor identity"
import { identify, getConsent, setConsent } from '@everock/sdk';
identify({ id: 'user-42' });
const consent = getConsent();
// Use your own recorded consent choice, not this example as a consent UI.
setConsent({ analytics: true, replay: false });
identify(null); // Clear the user identity on logout.
```

`identify` sets a stable application user ID; it does not sign in the visitor. Identity and browser consent APIs are not exported by the Node or edge entry.

## Request wrappers and spans

Use Node `requestHandler()` before Express-style routes and `errorHandler()` after them. Node and edge `withRequest(handler, { route })` wrap a Fetch-style handler and keep its response/error behavior. `registerEndpoints` declares route metadata after SDK initialization; it does not make a health-check request.

Node `withSpan(name, operation)` measures the supplied operation and preserves its return value or rejection. See [tracing](/docs/features/tracing) and [requests](/docs/features/requests).

## Delivery and lifecycle

`flush()` attempts delivery of pending signals; it is asynchronous and bounded by transport policies. Browser `flush(true)` requests the beacon path. Await normal delivery where the runtime lifetime permits it. Browser and Node expose `shutdown()` for cleanup; edge uses its invocation context and `flush()`.

`getDiagnostics()` reports local queue, delivery, drop, and persistence counters. It does not return accepted event contents or prove end-to-end ingestion. See [delivery and diagnostics](/docs/features/reliability).

## Persistence adapters

The exported `EventStore` contract contains `load(): Promise<StoredEvent[]>`, `apply(put, remove): Promise<void>`, and `clear(): Promise<void>`. Each `StoredEvent` has an `id`, enqueue timestamp `at`, and sanitized `event`.

Use durable storage with the isolation, permissions, and lifetime appropriate for your runtime. An in-memory implementation is not durable storage. `maxEvents`, `maxBytes`, and `maxAgeMs` remain bounded by the SDK; a custom adapter does not remove those limits.