<!-- Canonical: https://nitrozen.io/docs/node-sdk -->

> Official Node.js SDK for the Nitrozen.io changelog API. Full TypeScript support, Promise/callback API, and structured error handling.

[Docs](https://nitrozen.io/docs) / Node.js SDK

# Node.js SDK

Official Node.js client for the Nitrozen.io changelog API.

 [ npm: nitrozenio ](https://www.npmjs.com/package/nitrozenio) [ GitHub ](https://github.com/nitrozenio/nitrozen-node)

## Installation

Requires Node.js 18 or later.

shell

```
npm install nitrozenio
```

## Quick Start

javascript

```
const { ApiClient, ProjectsApi, EntriesApi } = require('nitrozenio');

// Create a client with your API token
const client = ApiClient.create('YOUR_API_TOKEN');

// List your projects
const projects = new ProjectsApi(client);
const { data } = await projects.projectsGet();
console.log(data); // Project[]

// Create a changelog entry
const entries = new EntriesApi(client);
const { data: entry } = await entries.projectsProjectEntriesPost(
  data[0].id,
  { title: 'New feature', content: 'We shipped something great.', category: 'new' }
);
console.log(entry);
```

## Authentication

Create an API token on the [API Tokens](https://nitrozen.io/api-tokens) page, then pass it to `ApiClient.create()`:

javascript

```
const { ApiClient } = require('nitrozenio');

// Static token
const client = ApiClient.create('YOUR_API_TOKEN');

// Dynamic token (e.g. from a secrets manager)
const client = ApiClient.create(() => getTokenFromVault());
```

## Error Handling

API errors reject with a `NitrozenError` that carries the HTTP status code and any validation details:

javascript

```
const { ApiClient, ProjectsApi, NitrozenError } = require('nitrozenio');

const client = ApiClient.create('YOUR_API_TOKEN');
const projects = new ProjectsApi(client);

try {
  const { data } = await projects.projectsProjectGet(999);
} catch (err) {
  if (err instanceof NitrozenError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.message);    // e.g. "Not found"
    console.error(err.errors);     // validation errors map, if any
  }
}
```

## Pagination

List endpoints accept `page` and `perPage` options and return a `meta` object:

javascript

```
const { data: entries, meta } = await entriesApi.projectsProjectEntriesGet(
  projectId,
  { page: 2, perPage: 20 }
);
console.log(meta.total, meta.last_page);
```

## Callback Style

Pass a callback as the last argument if you prefer the Node.js callback pattern:

javascript

```
projects.projectsGet(function(error, data) {
  if (error) throw error;
  console.log(data);
});
```

## TypeScript

The package ships with full TypeScript declarations. No `@types` package needed.

typescript

```
import { ApiClient, ProjectsApi, NitrozenError } from 'nitrozenio';

const client = ApiClient.create('YOUR_API_TOKEN');
const api = new ProjectsApi(client);

const { data } = await api.projectsGet();
// data is typed as Project[]
```

## API Reference

All methods return a `Promise` when called without a callback. All URIs are relative to `https://nitrozen.io/api/v1`.

### Authentication

 | Method | HTTP | Description |
|---|---|---|
| tokensGet() | GET /tokens | List API tokens |
| tokensPost(body) | POST /tokens | Create an API token |
| tokensTokenDelete(id) | DELETE /tokens/{token} | Revoke an API token |

### Projects

 | Method | HTTP | Description |
|---|---|---|
| projectsGet() | GET /projects | List projects |
| projectsPost(body) | POST /projects | Create a project |
| projectsProjectGet(id) | GET /projects/{project} | Get a project |
| projectsProjectPut(id, body) | PUT /projects/{project} | Update a project |
| projectsProjectDelete(id) | DELETE /projects/{project} | Delete a project |

### Entries

 | Method | HTTP | Description |
|---|---|---|
| projectsProjectEntriesGet(id, opts?) | GET /projects/{project}/entries | List entries |
| projectsProjectEntriesPost(id, body) | POST /projects/{project}/entries | Create an entry |
| projectsProjectEntriesEntryGet(pid, eid) | GET …/entries/{entry} | Get an entry |
| projectsProjectEntriesEntryPut(pid, eid, body) | PUT …/entries/{entry} | Update an entry |
| projectsProjectEntriesEntryDelete(pid, eid) | DELETE …/entries/{entry} | Delete an entry |

### Users

 | Method | HTTP | Description |
|---|---|---|
| userGet() | GET /user | Get current user |
| userUsageGet() | GET /user/usage | Get usage statistics |

### Public

 | Method | HTTP | Description |
|---|---|---|
| publicProjectsSlugEntriesGet(slug) | GET /public/projects/{slug}/entries | List published entries (no auth) |

 Every project starts with these built-in `category` values: `new` `improvement` `fix` `announcement` Projects on a plan with custom categories enabled can define additional category slugs from the dashboard — any of those slugs are valid here too.