@onehorizon/sdk-js

Node.js SDK for One Horizon. 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

npm install @onehorizon/sdk-js

yarn add @onehorizon/sdk-js

pnpm add @onehorizon/sdk-js

Quick start

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 for details.

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

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

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:

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
• Docs
• Support

License

MIT — see LICENSE