@magnetonlabs/catdb-client

Typed TypeScript client for the CatDB platform HTTP API. Every type in this package is generated from the committed OpenAPI document (catdb/proto/openapi.json), and a test in this package fails if the checked-in bindings drift from that spec — so the types describe the server that exists, not the server someone remembers.

npm install @magnetonlabs/catdb-client

What CatDB is, in one paragraph

CatDB is a semantic layer that federates queries across databases that cannot be joined by any one warehouse, and refuses rather than guessing when it cannot answer honestly. The types in this package exist to make those refusals legible to a caller, which is why several of them look unusual for an API client.

Usage

The block below is examples/quickstart.ts verbatim — the compiler checks it and a test asserts this README quotes it, because the first draft of this file named a class and a method that do not exist.

import { createCatdbClient, CatdbApiError } from '@magnetonlabs/catdb-client';

/**
 * Read a required setting, or fail saying which one is missing.
 *
 * Not `?? ''`. An absent token becomes the literal string `Bearer undefined`
 * and an absent workspace id becomes an empty string where a UUID belongs —
 * both reach the server as a malformed request whose error names the field,
 * not the misconfiguration. That is the defect this whole client is built to
 * make impossible in an answer; the example should not commit it in a config.
 *
 * The value is trimmed before the check. A variable set to whitespace — an
 * empty line in a .env file, a trailing space in a CI secret — is not
 * configured either, and an untrimmed guard would pass ` ` through as a UUID.
 */
function required(name: string): string {
  const value = process.env[name]?.trim();
  if (value === undefined || value === '') {
    throw new Error(`${name} is not set; refusing to send a request that cannot succeed`);
  }
  return value;
}

const catdb = createCatdbClient({
  baseUrl: required('CATDB_URL'),
  headers: { authorization: `Bearer ${required('CATDB_TOKEN')}` },
});

const answer = await catdb.entityQuery({
  workspace_id: required('CATDB_WORKSPACE_ID'),
  entity: 'customer_360.Customer',
  select: ['email', 'region'],
  filters: [{ field: 'region', operator: 'eq', value: 'EU' }],
  order_by: [{ field: 'email', direction: 'ascending' }],
  page_size: 100,
  limit: 1000,
});

// An empty `rows` is not one fact. `reason` is present only when nothing came
// back, and says which of three things happened.
if (answer.rows.length === 0 && answer.reason) {
  switch (answer.reason.reason) {
    case 'nothing_examined':
      // No source ran. This says nothing about the data.
      break;
    case 'examined_none_admitted':
      // Sources looked and rejected every candidate at the source.
      break;
    case 'admitted_none_survived_final_evaluation':
      // Sources admitted rows; CatDB's own predicate or precedence removed them.
      break;
  }
}

// Per-source accounting. A source that never ran carries a cause and no count,
// so it can never be mistaken for a source that looked and found nothing.
for (const source of answer.sources) {
  switch (source.accounting.state) {
    case 'examined':
      source.accounting.examined;
      source.accounting.admitted;
      source.accounting.rejected;
      break;
    case 'abandoned':
      // Started and cut off. Its work is not evidence about the data.
      source.accounting.examined;
      break;
    case 'unexamined':
      source.accounting.cause;
      break;
  }
}

// `closed_over_authorized` or `open` — there is deliberately no state named
// `complete`, because a source you cannot see was never in the denominator.
answer.completeness.state;

try {
  await catdb.entityQuery({
    workspace_id: required('CATDB_WORKSPACE_ID'),
    entity: 'customer_360.Customer',
    select: ['email'],
    filters: [],
    order_by: [],
    page_size: 10,
    limit: 10,
  });
} catch (error) {
  if (error instanceof CatdbApiError) {
    error.status;
    error.body?.error;
  }
}

Read-only subpath

@magnetonlabs/catdb-client/read-only exposes only the public read surface, for callers that must not be able to reach control-plane operations.

Versioning

0.x — the wire contract is still moving. Breaking changes land in minor versions until 1.0.0.

Licence

Apache-2.0 OR MIT