Client

Client is the entry point of the CyborgDB JS/TS SDK. It connects to a running CyborgDB service and creates, loads, and lists encrypted indexes. Operations on an index, such as upsert and query, are methods of the EncryptedIndex it returns.

Constructor

new Client({
    baseUrl: string,
    apiKey?: string,
    verifySsl?: boolean,
})

Parameters

Parameter	Type	Default	Description
`baseUrl`	`string`	-	Base URL of the CyborgDB service, e.g. `'http://localhost:8000'`. Must use `http://` or `https://`.
`apiKey`	`string`	`undefined`	(Optional) Service authentication credential, sent as the `X-API-Key` header. Required only when the service has authentication enabled.
`verifySsl`	`boolean`	`undefined` (auto-detect)	(Optional) TLS certificate verification. See TLS verification.

apiKey is the service authentication credential: the root key or a per-user cdbk_ token. It is required only when the service runs with CYBORGDB_SERVICE_ROOT_KEY set; against an unauthenticated service (the default), omit it. This is distinct from the service’s CYBORGDB_API_KEY license key. See Managing Keys.

The constructor throws CyborgDBValidationError if baseUrl can’t be parsed or doesn’t use http:// or https://.

Example Usage

import { Client } from 'cyborgdb';

const client = new Client({ baseUrl: 'http://localhost:8000', apiKey: 'your-api-key' });

TLS verification

verifySsl decides whether the SDK checks the service’s TLS certificate:

`baseUrl`	`verifySsl` unset	`true`	`false`
`http://…`	No TLS	No TLS	No TLS
`https://` with host `localhost`, `127.0.0.1`, or `::1`	Verification off	Verification on	Verification off
Any other `https://` URL	Verification on	Verification on	Verification off

Turning verification off works on Node.js, where requests then go through the node:https module instead of fetch. It follows redirects and honors AbortSignal, and it times out a connection after 300 seconds of inactivity. Browsers and Edge runtimes can’t turn verification off; verifySsl: false has no effect there. When verification is off, the SDK logs console.warn messages: on Node, one saying verification is disabled and a second saying the insecure transport is in use. The loopback auto-detect case logs its first message with console.info. A plain http:// URL also logs “SSL verification is disabled”, although there is no TLS to disable.

Errors

Failed requests throw a subclass of CyborgDBError chosen by HTTP status, such as CyborgDBNotFoundError for 404 or CyborgDBAuthenticationError for 401. Arguments rejected inside the SDK, before a request is sent, throw CyborgDBValidationError. See Errors for the full list.

import { Client, CyborgDBAuthenticationError } from 'cyborgdb';

try {
    await new Client({ baseUrl: 'http://localhost:8000', apiKey: 'wrong-key' }).listIndexes();
} catch (error) {
    console.log(error instanceof CyborgDBAuthenticationError);
}
// Output: true

Supported runtimes

The package has no runtime dependencies and needs only fetch and Web Crypto, so it runs on:

Runtime	Notes
Node.js 18+	Full functionality, including the on-disk sample dataset cache.
Bun, Deno	Same as Node.
Modern browsers	No sample-dataset cache.
Vercel Edge Runtime, Cloudflare Workers	No sample-dataset cache.

Introduction

Encrypted Index

Types & Helpers

Client

Constructor

Parameters

Example Usage

TLS verification

Errors

Supported runtimes

​Constructor

​Parameters

​Example Usage

​TLS verification

​Errors

​Supported runtimes

Constructor

Parameters

Example Usage

TLS verification

Errors

Supported runtimes