@x12i/catalox-client

HTTP client SDK for the Catalox API. Typed wrappers around /v1 routes with support for open context mode (internal) and Authix bearer token mode (public 6.0.0).

Part of the Catalox monorepo.

Role

Lets browsers, agents, and services call catalox-service without linking the engine. Uses @x12i/catalox-contracts for result types and error mapping.

Install

npm install @x12i/catalox-client @x12i/catalox-contracts

Usage

Authix mode (production)

import { createCataloxClient } from "@x12i/catalox-client";

const client = createCataloxClient({
  baseUrl: "https://catalox-api.example.com",
  getToken: async () => {
    const res = await fetch("/api/catalox-token");
    return res.text();
  },
});

const session = await getTokenFromBff();
const bound = client.withToken(session);

const { outcome, result } = await bound.listCatalogItems("skills", { limit: 50 });
if (outcome !== "ok") { /* handle */ }

// Structured errors (never throws):
const listed = await bound.listCatalogItemsResult("skills", { limit: 50 });
if (!listed.ok) console.error(listed.errorDetail);

Open mode (internal 5.9.x only)

const client = createCataloxClient({ baseUrl: "http://catalox-service:3200" });
const bound = client.withContext({ appId: "myApp", superAdmin: true });

await bound.getAppCatalogBootstrap("myApp");
await bound.getCatalogItem("signals", "core:S1");
await bound.getCatalogItemByFieldResult("signals", "data.code", "LOGICAL-1");

API surface (CataloxClientBound)

| Method | HTTP | |--------|------| | listAppCatalogs(appId) | GET /v1/apps/:appId/catalogs | | getAppCatalogBootstrap(appId) | GET /v1/apps/:appId/bootstrap | | listCatalogItems(catalogId, opts?) | GET /v1/catalogs/:id/items | | getCatalogItem(catalogId, itemId) | GET /v1/catalogs/:id/items/:itemId | | getCatalogItemByField(…) / …Result | GET …/items/by-field | | listCatalogItemsResult / getCatalogItemResult | Same + CataloxResult mapping |

See src/bound-client.ts for the full list.

Types

Re-exports: CataloxClientBound, OutcomeResponse, CataloxResult, CataloxClientError

Build & test

npm run build -w @x12i/catalox-client
npm test -w @x12i/catalox-client

Documentation

• OpenAPI package
• 6.0.0 public API
• Deployment

When to use client vs engine

| Scenario | Use | |----------|-----| | Low-latency BFF in Node | Embed @x12i/catalox-engine | | Browser / external service / other language via HTTP | This client | | Same process as engine | Engine directly — no HTTP hop |