npm package: @onehorizon/sdk-js
Description: Node.js SDK for One Horizon
Author: One Horizon
Latest version: 0.0.5

# @onehorizon/sdk-js

[![npm version](https://img.shields.io/npm/v/@onehorizon/sdk-js.svg)](https://www.npmjs.com/package/@onehorizon/sdk-js)
[![license](https://img.shields.io/npm/l/@onehorizon/sdk-js.svg)](./LICENSE)

Node.js SDK for [One Horizon](https://onehorizon.ai). Provides fully-typed API clients for managing tasks, workspaces, and teams — generated from the One Horizon OpenAPI spec. Works in Node.js and in bundlers (Webpack, Browserify), with CommonJS and ES module support.

## Install

```bash
npm install @onehorizon/sdk-js
```

```bash
yarn add @onehorizon/sdk-js
```

```bash
pnpm add @onehorizon/sdk-js
```

## Quick start

```ts
import { Configuration, GatewayApi } from '@onehorizon/sdk-js'

const config = new Configuration({
  basePath: 'https://api.onehorizon.ai',
  accessToken: '<your-access-token>'
})

const gateway = new GatewayApi(config)

// List workspaces
const { workspaces } = await gateway.listWorkspaces()
const workspaceId = workspaces[0].workspaceId

// List your active tasks
const { tasks } = await gateway.listPlannedTasks({ workspaceId })

// Fetch a single task
const task = await gateway.fetchTask({ workspaceId, taskId: 'tsk_...' })

// Create a task
const created = await gateway.createTask({
  workspaceId,
  task: { title: 'New task', kind: 'task' }
})

// Update a task
await gateway.updateTask({
  workspaceId,
  taskId: created.taskId,
  task: { status: 'in_progress' }
})
```

## Authentication

The `accessToken` in `Configuration` must be a valid One Horizon OAuth access token. Obtain one through the One Horizon auth flow — see the [authentication docs](https://onehorizon.ai/docs) for details.

Token refresh is the caller's responsibility. Pass an async function if you need dynamic token resolution:

```ts
const config = new Configuration({
  basePath: 'https://api.onehorizon.ai',
  accessToken: async () => await getAccessToken() // called per request
})
```

## API reference

### GatewayApi

Main API for tasks, workspaces, teams, and users.

| Method | Description |
| --- | --- |
| `listWorkspaces()` | List workspaces the authenticated user can access |
| `listTasks({ workspaceId, ... })` | List tasks with optional status, type, and team filters |
| `listPlannedTasks({ workspaceId })` | Active planned and in-progress tasks |
| `listBlockedTasks({ workspaceId })` | Blocked tasks |
| `listCompletedTasks({ workspaceId })` | Completed tasks in a date range |
| `fetchTask({ workspaceId, taskId })` | Fetch a single task by ID |
| `createTask({ workspaceId, task })` | Create a task |
| `updateTask({ workspaceId, taskId, task })` | Update a task |
| `deleteTask({ workspaceId, taskId })` | Delete a task |
| `fetchDocument({ workspaceId, documentId })` | Fetch a task's rich-text document body |
| `listTeams({ workspaceId })` | List teams in a workspace |
| `listWorkspaceUsers({ workspaceId })` | List users in a workspace |
| `listTeamUsers({ workspaceId, teamId })` | List users that are members of a team (includes role) |
| `fetchUserMe({ workspaceId })` | Get the current authenticated user |
| `updateUserMeSettings({ workspaceId, userSettingsPatch })` | Update current user settings |

### AuthApi

```ts
import { Configuration, AuthApi } from '@onehorizon/sdk-js'

const auth = new AuthApi(config)
const user = await auth.getUser() // AuthUser — id, email, user metadata
```

| Method | Description |
| --- | --- |
| `getUser()` | Get the authenticated user from the auth service |

## TypeScript

Types are bundled with the package — no separate `@types` package needed.

Key types:

```ts
import type {
  Task,
  TaskStatus,
  TaskKind,
  Workspace,
  Team,
  User,
  TeamRole,
  UserSettings,
  Pagination
} from '@onehorizon/sdk-js'
```

`TaskStatus` values: `open` · `planned` · `in_progress` · `in_review` · `blocked` · `completed` · `cancelled` · `merged` · `idea`

`TaskKind` values: `task` · `bug` · `initiative`

## Requirements

- Node.js 20 or newer

## Links

- [Website](https://onehorizon.ai)
- [Docs](https://onehorizon.ai/docs)
- [Support](https://join.slack.com/t/onecommunitycrew/shared_invite/zt-3pfndy2wy-IMkk146kt4Zw72kLp6R~6g)

## License

MIT — see [LICENSE](./LICENSE)