Consuming Bus Types

Everything here happens in your frontend repo. It's one config block and the fetch you already run.

Configure

[bus]
endpoint = "https://staging.example.com/.well-known/chowbea.json"

That's the whole configuration. No [bus] block means the feature is completely inert — no requests, no files, no behaviour change.

Your existing [fetch.auth] and [fetch.headers] apply to bus requests too, so a bus endpoint behind Basic auth or a custom header needs nothing extra:

[fetch]
endpoint = "https://staging.example.com/openapi.json"
headers = { "X-Env" = "$STAGING_KEY" }

[fetch.auth]
type = "basic"
username = "$SWAGGER_USER"
password = "$SWAGGER_PASS"

[bus]
endpoint = "https://staging.example.com/.well-known/chowbea.json"

Sync

chowbea-axios fetch

The bus syncs alongside the spec. watch syncs it every cycle too — including cycles where the OpenAPI spec is unchanged, which matters because bus types change on their own schedule.

✓ done Type bus: 14 type(s) synced

or, when nothing moved:

Type bus: unchanged

What a sync actually does

1. Sends If-None-Match with the cached manifest hash. A 304 ends it there.
2. Parses and validates the manifest — version gate, hash integrity, declaration safety.
3. Diffs against the cached manifest and logs what changed:

   bus: + StudentId
   bus: ~ GradeMap
   bus: - LegacyGrade (removed)

4. Emits the .ts files, then writes the cache.

If the bus endpoint is unreachable, fetch warns and continues; your OpenAPI client still generates. Bus types are only regenerated when the endpoint answers.

What lands on disk

src/api/
├── _internal/
│   └── chowbea.bus.json        # cached manifest — don't edit, don't hand-resolve
└── _generated/bus/
    ├── exams.grade.ts          # from barrel key exams/grade
    ├── _marked.billing.ts      # from @chowbea-export types in src/billing/
    └── index.ts                # re-exports every barrel

Backend barrel keys map to filenames with / flattened to ., so your frontend layout mirrors the backend's domain structure instead of collapsing into one giant file. A backend file that declares chowbea-name picks its own filename instead.

/**
 * Auto-generated by chowbea-axios Type Bus.
 * DO NOT EDIT MANUALLY - your changes will be overwritten.
 */

/** From src/exams/grade.chowbea.ts:1 */
export type Grade = "A" | "B";

/** From src/exams/grade.chowbea.ts:3 */
export type GradeMap = Map<StudentId, Grade>;

Each declaration cites its backend origin, so "where does this come from?" is answerable without leaving the file.

Import

From the barrel:

import type { GradeMap, Plan } from '@/api/_generated/bus';

…or per-domain, if you prefer narrower imports:

import type { GradeMap } from '@/api/_generated/bus/exams.grade';

Enums arrive as runtime values, not just types — so you can iterate them:

import { Level } from '@/api/_generated/bus';

Object.values(Level);   // real array at runtime
Level.Low;              // "low"

Offline

generate re-emits bus files from the cached manifest without hitting the network, so a cold checkout with a warm cache still produces types. If there's no cached manifest yet it warns and tells you to run fetch — it doesn't fail your generation.

Version mismatches

The manifest carries a format version. A CLI meeting an unknown one fails loudly:

Unsupported chowbea bus manifest version "2" (this CLI supports "1"). Upgrade chowbea-axios.

That's deliberate — a newer backend can't silently feed a stale frontend CLI a format it will mis-parse. Upgrade the CLI; don't edit the manifest.