@jxdltd/onyx-client

@jxdltd/onyx-client is the published npm client for the Onyx public API. Its types come straight from the oRPC contract that the server implements, so every call and response is fully typed end to end. Under the hood it is plain REST against /api/v1, the same API described by the generated OpenAPI document.

Installation

npm install @jxdltd/onyx-client

Authentication

The client authenticates with organization-scoped API keys, sent as the x-api-key header. An organization member creates a key through the Better Auth api-key endpoints (POST /api/auth/api-key/create with an organizationId), and every call made with that key is scoped to that organization.

import { createOnyxClient } from '@jxdltd/onyx-client';

const client = createOnyxClient({
  apiKey: process.env.ONYX_API_KEY, // organization API key (onyx_...)
});

Usage

import { createOnyxClient, safe } from '@jxdltd/onyx-client';

const client = createOnyxClient({ apiKey: process.env.ONYX_API_KEY });

// Unauthenticated health check.
const health = await client.health();

// Fetch the organization the API key is scoped to.
const { data: organization, error } = await safe(client.org());
if (error === null) {
  console.log(organization.name);
}

safe wraps a call and returns { data, error } instead of throwing. Use isDefinedError (also re-exported) to narrow errors that are defined in the contract, such as UNAUTHORIZED:

import { safe, isDefinedError } from '@jxdltd/onyx-client';

const { data, error } = await safe(client.org());
if (isDefinedError(error) && error.code === 'UNAUTHORIZED') {
  console.error('Invalid or revoked API key.');
}

Options

createOnyxClient(options) accepts:

const client = createOnyxClient({
  origin: 'http://localhost:3000',
  apiKey: process.env.ONYX_API_KEY,
});

Types

The package exports helper types inferred from the contract:

• OnyxClient: the client type returned by createOnyxClient.
• ApiInputs and ApiOutputs: input and output types for every procedure.
• Organization: the organization shape returned by client.org().
• DEFAULT_ORIGIN: the hosted deployment origin used when origin is omitted.

import type { ApiOutputs } from '@jxdltd/onyx-client';

type Org = ApiOutputs['org'];