# Yonote SDK for JavaScript

## Installation

```
npm install @yonote/js-sdk
```

## Usage

Import and initialize a client using an **integration token** or an OAuth **access token**.

```js
import { Client } from "@yonote/js-sdk"

// Initializing a client
const client = new Client({
  token: process.env.YONOTE_TOKEN,
  baseUrl: "http://myCustomDomain.ru" // optional
})
```

Make a request to any Yonote API endpoint.

```js
;(async () => {
  const listUsersResponse = await client.users.list({});
})()
```

Each method returns a `Promise` which resolves the response.

```js
console.log(listUsersResponse)
```

```
{
  "id": "fbc2fc3e-87f0-4eb0-8225-cdb24497ee55",
  "email": "user@example.org",
  "name": "user",
  "avatarUrl": "https://i.yonote.ru/avatar/43f4563d166c0a78adcce6dc5a6caccz/i.png?c=9E5CF7",
  "color": "#9E5CF7",
  "isAdmin": false,
  "isSuspended": false,
  "isViewer": false,
  "createdAt": "2025-07-07T15:24:33.167Z",
  "updatedAt": "2025-08-05T13:01:47.892Z",
  "deletedAt": null,
  "lastActiveAt": "2025-08-05T13:01:47.892Z",
  "language": "ru_RU",
  "flags": {
    "inviteSent": 1
  }
}
```

The endpoint parameters are grouped into two objects - data and pagination. You don't need to remember which parameters are contained in the path, request, or body.

```js
const myPage = await client.documents.search_titles(
  {
    query: "my query",
    direction: "ASC",
    isPublished: true,
  },
  {
    offset: 0,
    limit: 2,
  },
)
```

### Handling errors

If the API returns an unsuccessful response, the returned `Promise` rejects with a `APIResponseError`.

The error contains properties from the response, and the most helpful is `code`. You can compare `code` to the values in the `APIErrorCode` object to avoid misspelling error codes.

```js
const { Client, APIErrorCode, APIError } = require("@yonote/js-sdk")

try {
  const client = new Client({ token: process.env.YONOTE_TOKEN })
  const myPage = await client.documents.get({
    id: "wrongId",
  })
} catch (error) {
  if (err instanceof APIError) {
    if (err.code === APIErrorCode.ResourceNotFound) {
      //
      // For example: There is no document with this id. Check the correctness of the id
      //
    } else {
      // Other error handling code
      console.error(err);
    }
  }
}
```

### Client options

The `Client` supports the following options on initialization. These options are all keys in the single constructor parameter.

| Option      | Default value         | Type         | Description                                                                                                                                                  |
|-------------|-----------------------| ------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `token`     | `undefined`           | `string`     | Bearer token for authentication.                                                                                                                             |
| `baseUrl`   | `"https://yonote.ru"` | `string`     | The root URL for sending API requests. This can be changed to test with a mock server.                                                                       |

## Requirements

This package supports the following minimum versions:

- Runtime: `node >= 18`
- Type definitions (optional): `typescript >= 5.9`

Earlier versions may still work, but we encourage people building new applications to upgrade to the current stable.