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

# Installation

> Install and configure the server-only @nozle-js/node SDK.

`@nozle-js/node` requires Node.js 18 or later and uses the built-in Fetch API.

Entity subscription APIs are introduced in `0.5.0`.

```bash theme={null}
npm install @nozle-js/node
```

## Create a client

```ts theme={null}
import { Nozle } from '@nozle-js/node'

export const nozle = new Nozle({
  apiKey: process.env.NOZLE_SECRET_KEY!,
  baseUrl: 'https://api.nozle.app',
  eventsUrl: 'https://core.nozle.app',
  timeout: 10_000,
})
```

### Configuration

| Field       | Type     | Default                 | Description                                                                                                                                                            |
| ----------- | -------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`    | `string` | required                | Organization credential. Use a restricted `sk_` for server mutations.                                                                                                  |
| `baseUrl`   | `string` | `http://localhost:8080` | API origin used for entitlements, credits, entities, usage, and margin.                                                                                                |
| `eventsUrl` | `string` | `http://localhost:3000` | Core API origin used for customer writes, billing resources, `track()`, credit-system discovery, and Entity subscriptions. Use `https://core.nozle.app` in production. |
| `timeout`   | `number` | `10000`                 | Per-request timeout in milliseconds.                                                                                                                                   |

Set both URLs explicitly outside local development. Trailing slashes are removed automatically.

```mermaid theme={null}
flowchart LR
  App[Your backend] --> SDK[@nozle-js/node]
  SDK -->|baseUrl| API[Entitlements, credits, usage, margin]
  SDK -->|eventsUrl| Core[Customers, billing resources, metered events]
```

<Warning>
  This package is server-only. Never bundle an `sk_`, master key, or internal credential into browser code. Use `@nozle-js/react` with a publishable key for public catalog reads.
</Warning>

## Verify connectivity

```ts theme={null}
const health = await nozle.ping()

console.log(health.ok)
console.log(health.engine)
console.log(health.version)
```

## API surface

### API and billing

| Method                                  | Purpose                                                      |
| --------------------------------------- | ------------------------------------------------------------ |
| `nozle.ping()`                          | Check API health.                                            |
| `nozle.plans()`                         | List plans.                                                  |
| `nozle.checkout()`                      | Create a payment-aware checkout result.                      |
| `nozle.subscribe()`                     | Create a direct subscription where your workflow permits it. |
| `nozle.cancelSubscription()`            | Cancel immediately or at the renewal boundary.               |
| `nozle.previewSubscriptionTransition()` | Preview cancellation, downgrade, or uncancel settlement.     |
| `nozle.applySubscriptionTransition()`   | Apply an idempotent settlement transition.                   |
| `nozle.track()`                         | Send a metered event through the Events API.                 |
| `nozle.can()`                           | Check feature access, usage, and margin state.               |

### Namespaces

| Namespace             | Methods                                                                             |
| --------------------- | ----------------------------------------------------------------------------------- |
| `customers`           | `upsert()`                                                                          |
| `creditSystems`       | `list()`                                                                            |
| `entities`            | `get()`, `list()`, `upsert()`, `activate()`, `suspend()`, `bulkUpsert()`            |
| `entitySubscriptions` | `ensure()`, `get()`, `list()`, `checkout()`, `changePlan()`, `cancel()`, `remove()` |
| `credits`             | Customer and Entity balance/history reads, `allocate()`, `deallocate()`             |
| `usage`               | Advisory `check()` and atomic, idempotent `track()`                                 |
| `margin`              | `summary()`, `byCustomer()`, `byMetric()`, `byPlan()`, `byModel()`, `trend()`       |

The package also exports `wrapOpenAI()` and `wrapAnthropic()` for token metadata capture.

## Key behavior

* Billing mutations and settlement transitions require an API key beginning with `sk_`.
* Entity mutations, credit transfers, and `usage.track()` reject publishable `pk_` keys.
* Mutation idempotency keys are caller-supplied and limited to 255 bytes.
* Product-credit amounts are exact decimal strings, not JavaScript numbers.
* Failed HTTP responses reject with an `Error` containing the operation and HTTP status.
* Every request uses `AbortSignal.timeout(timeout)`.

## Production pattern

Create one client per process and reuse it:

```ts theme={null}
// billing/nozle.ts
import { Nozle } from '@nozle-js/node'

export const nozle = new Nozle({
  apiKey: process.env.NOZLE_SECRET_KEY!,
  baseUrl: process.env.NOZLE_API_URL!,
  eventsUrl: process.env.NOZLE_EVENTS_URL ?? 'https://core.nozle.app',
})
```

Do not accept authoritative `customerId`, Entity IDs, plan codes, return origins, or idempotency keys blindly from a browser. Derive or validate them in your trusted backend.

## Next steps

* [Billing and subscriptions](/sdks/node/billing)
* [Tracking events](/sdks/node/tracking-events)
* [Customers and Entities](/sdks/node/customers-entities)
* [Product credits](/sdks/node/credits)
* [Entitlements](/sdks/node/entitlements)
* [LLM auto-capture](/sdks/node/llm-auto-capture)