# `@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](../../README.md). Used by [catalox-service](../../packages/http/catalox-service/README.md).

---

## 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](../../docs/catalox-v6/6.0.0/README.md)

---

## Usage (embed in your server)

```ts
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](../../packages/http/catalox-service/README.md) and [environment.md](../../docs/environment.md).

Key vars: `CATALOX_AUTH_MODE`, `CATALOX_PRIVATE_MODE`, `CATALOX_DEFAULT_SUPER_ADMIN`, `AUTHIX_*`

---

## Build

```bash
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 |