@x12i/catalox-api

HTTP route layer for Catalox: Fastify registration, Authix verification hook, request context resolution, and outcome → HTTP status mapping.

Part of the Catalox monorepo. Used by catalox-service.

Role

Thin HTTP wrapper over @x12i/catalox-engine. The engine remains authoritative for bindings, scope, and catalog outcomes.

| Export | Purpose | |--------|---------| | registerCataloxRoutes(app, catalox, config) | Mount all routes on existing Fastify app | | createCataloxApiApp(catalox, config?) | Create configured Fastify instance | | loadCataloxApiConfig() | Read CATALOX_* and Authix env | | buildRequestContext | Build CataloxContext with normalized actor | | resolveRequestContext | Alias of buildRequestContext | | parseCatalogListQuery | Map HTTP query string → CatalogQueryOptions | | listOutcomeToHttp, getItemOutcomeToHttp | Map engine outcomes to HTTP status |

Routes (/v1)

| Method | Path | Purpose | |--------|------|---------| | GET | /health | Health check (unauthenticated) | | GET | /v1/apps/:appId/catalogs | List app catalogs | | GET | /v1/apps/:appId/bootstrap | App catalog bootstrap (descriptors) | | GET | /v1/catalogs | List all catalogs (operator) | | GET | /v1/catalogs/:catalogId/items | List items (?status=active, sort=field:desc, includeDeleted=1) | | GET | /v1/catalogs/:catalogId/items/:itemId | Get item | | GET | /v1/catalogs/:catalogId/items/by-field | Lookup by indexed field | | PUT/PATCH/DELETE | /v1/catalogs/:catalogId/items/:itemId | Item mutations (DELETE ?permanent=1 for hard delete) | | POST | /v1/catalogs/:catalogId/items/:itemId/restore | Restore soft-deleted item | | GET/PUT | …/native-record | Native envelope read/replace | | GET | /v1/catalogs/:catalogId/search | Text / AI search | | POST | /v1/apps/:appId/catalogs/:catalogId/bind | Bind catalog | | GET | /v1/catalogs/:catalogId/export | Export catalog items |

Exact handlers: src/routes/*.ts

Auth modes

| CATALOX_AUTH_MODE | Behavior | |---------------------|----------| | open | Trust network; context from headers/config (internal 5.9.x only) | | authix | Require Authorization: Bearer ax1…; verify via Authix |

→ 6.0.0 API docs

Usage (embed in your server)

import Fastify from "fastify";
import { createCataloxFromEnv } from "@x12i/catalox-engine/firebase";
import { registerCataloxRoutes, loadCataloxApiConfig } from "@x12i/catalox-api";

const { catalox } = createCataloxFromEnv();
const app = Fastify();
await registerCataloxRoutes(app, catalox, loadCataloxApiConfig());
await app.listen({ port: 3200 });

Configuration

See catalox-service README and environment.md.

Key vars: CATALOX_AUTH_MODE, CATALOX_PRIVATE_MODE, CATALOX_DEFAULT_SUPER_ADMIN, AUTHIX_*

Build

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

Related packages

| Package | Role | |---------|------| | @x12i/catalox-engine | Catalog runtime | | @x12i/catalox-authix-bridge | Token → context (used by route handlers) | | @x12i/catalox-openapi | OpenAPI spec for these routes | | @x12i/catalox-client | HTTP consumer SDK |