@t0.labs/daxta 0.5.1 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,31 @@
1
- # DAxTA
1
+ <p align="center">
2
+ <img src="https://cdn.jsdelivr.net/npm/@t0.labs/daxta@0.5.3/assets/logo.png" width="88" alt="DAxTA" />
3
+ </p>
2
4
 
3
- **Tested behavior. Trusted API docs.**
5
+ <h1 align="center">DAxTA</h1>
4
6
 
5
- DAxTA generates and publishes API documentation from API behavior observed during automated tests.
7
+ <p align="center"><strong>API Test → API Documentation</strong></p>
8
+
9
+ <p align="center">
10
+ You already wrote the tests.<br />
11
+ Don't document the same thing twice.
12
+ </p>
13
+
14
+ <p align="center">
15
+ <a href="https://www.npmjs.com/package/@t0.labs/daxta"><img alt="npm" src="https://img.shields.io/npm/v/@t0.labs/daxta?color=111111&label=npm&logo=npm" /></a>
16
+ <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/@t0.labs/daxta?color=111111&label=node" /></a>
17
+ <a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@t0.labs/daxta?color=111111" /></a>
18
+ </p>
19
+
20
+ ---
21
+
22
+ DAxTA turns your existing **NestJS API integration tests** into living API documentation.
23
+
24
+ Your tests already know the requests, responses, status codes, headers, validation failures, authentication scenarios, omitted fields, and edge cases of your API.
25
+
26
+ DAxTA captures that real traffic while your tests run and turns it into interactive **OpenAPI documentation** on your application at `/api-docs`.
27
+
28
+ **No duplicate API definitions. No manually maintained examples. No documentation-specific decorators.**
6
29
 
7
30
  ```ts
8
31
  import { apiDocs, generateApiDocs } from '@t0.labs/daxta';
@@ -11,262 +34,367 @@ await generateApiDocs();
11
34
  apiDocs(app);
12
35
  ```
13
36
 
14
- Swagger asks you to decorate controllers. DAxTA records what your tests actually call.
15
-
16
- ```text
17
- Tests
18
- ↓
19
- Observed API Behavior
20
- ↓
21
- DAxTA
22
- ↓
23
- Verified API Docs
24
- ↓
25
- Hosted Documentation
26
- ```
37
+ ---
27
38
 
28
- The documentation shows what tests really exercise — not what the code claims to do.
39
+ ## Why DAxTA?
29
40
 
30
- ## Install
41
+ When you build an API, you already describe its behavior in your tests.
31
42
 
32
- One command — dependency, `apiDocs(app)`, Jest plugin, `daxta.config.ts`, and sidebar preferences:
43
+ Your integration tests know:
33
44
 
34
- ```bash
35
- pnpm dlx @t0.labs/daxta install
36
- # or
37
- npx @t0.labs/daxta install
38
- ```
45
+ - what request is sent
46
+ - what response should be returned
47
+ - which status code is expected
48
+ - which headers are required
49
+ - positive scenarios
50
+ - negative scenarios
51
+ - invalid inputs
52
+ - omitted fields
53
+ - authentication failures
54
+ - edge cases
39
55
 
40
- Install asks for the Nest entry, test script, sidebar folder order (`role-resource` / `resource-role`), `{id}` fold, and example label style.
41
- `DAXTA_DOCS=true` is written to `.env` (created if missing).
56
+ Then we often define much of the same information **again** for Swagger, Postman, or another API documentation tool.
42
57
 
43
- Then:
58
+ DAxTA removes that duplication.
44
59
 
45
- ```bash
46
- pnpm run test:integration # generates API docs when Jest finishes
47
- pnpm start:dev # API docs on the app port at /api-docs
60
+ ```text
61
+ Write API
62
+ ↓
63
+ Write tests
64
+ ↓
65
+ Run tests
66
+ ↓
67
+ DAxTA captures real API behavior
68
+ ↓
69
+ Interactive /api-docs
70
+ ↓
71
+ OpenAPI → Postman / other tools
48
72
  ```
49
73
 
50
- ```ts
51
- import { apiDocs } from '@t0.labs/daxta';
74
+ ---
52
75
 
53
- apiDocs(app); // DAXTA_DOCS is required (true | false)
54
- ```
76
+ ## What you get
55
77
 
56
- Flags: `--yes` · `--dry-run` · `--skip-main` · `--skip-dep` · `--main <path>` · `--fast`
78
+ | From your tests | In DAxTA |
79
+ | --- | --- |
80
+ | Real request / response pairs | Interactive `/api-docs` UI |
81
+ | Positive scenarios | Success examples |
82
+ | Negative scenarios | Error examples |
83
+ | Validation failures | Invalid cases |
84
+ | Authentication scenarios | Recorded headers |
85
+ | Omitted / optional fields | DTO field metadata |
86
+ | Status codes | Executable API calls |
87
+ | Multiple test cases | Multiple examples per operation |
88
+ | Recorded API set | OpenAPI + Postman export |
89
+
90
+ Different tests for the same endpoint automatically become different API examples.
57
91
 
58
- ## Uninstall
92
+ ```text
93
+ POST /v1/users
59
94
 
60
- ```bash
61
- pnpm dlx @t0.labs/daxta uninstall
62
- # or
63
- npx @t0.labs/daxta uninstall
95
+ ├── 201 User created
96
+ ├── 400 Invalid email
97
+ ├── 400 Missing required field
98
+ ├── 401 Missing authentication
99
+ └── 409 User already exists
64
100
  ```
65
101
 
66
- Removes:
67
-
68
- - `apiDocs` + `@t0.labs/daxta` import (`main.ts`)
69
- - Jest `setup` + `jest-reporter` (+ `globalSetup` when DAxTA added it)
70
- - `daxta.config.*` and `.daxta/` output
71
- - DAxTA lines in `.gitignore` / `.env`
72
- - `@t0.labs/daxta` package
102
+ These examples come from **actual test executions**, not manually maintained documentation.
73
103
 
74
- Flags: `--yes` · `--dry-run` · `--keep-dep` (leave the package, unwind wiring only) · `--fast`
104
+ ---
75
105
 
76
106
  ## How it works
77
107
 
78
108
  ```text
79
109
  your Jest suite
80
- │ supertest / superagent hits
110
+ │
111
+ │ supertest / superagent
112
+ ▼
113
+ your real NestJS endpoints
114
+ │
115
+ │ DAxTA records traffic
116
+ ▼
117
+ recorded API scenarios
118
+ │
119
+ │ no OpenAPI rebuild mid-run
81
120
  ▼
82
- DAxTA records hits to disk
83
- │ (no OpenAPI rebuild mid-run)
121
+ onRunComplete
122
+ │
123
+ │ one full build
84
124
  ▼
85
- onRunComplete → generate API docs
125
+ OpenAPI + DAxTA UI
86
126
  │
87
127
  ▼
88
- API docs ready → http://localhost:3000/api-docs
128
+ http://localhost:3000/api-docs
129
+ ```
130
+
131
+ 1. **Install** attaches DAxTA to Jest using `setupFilesAfterEnv` and a reporter.
132
+
133
+ Your existing `test:integration` command remains the entrypoint. DAxTA does not wrap your test process.
134
+
135
+ 2. **Run your tests normally.**
136
+
137
+ DAxTA records the real HTTP traffic generated by your tests.
138
+
139
+ 3. **When Jest finishes**, DAxTA performs a single documentation build.
140
+
141
+ 4. `apiDocs(app)` mounts the generated documentation on your NestJS application when `DAXTA_DOCS=true`.
142
+
143
+ ---
144
+
145
+ ## What DAxTA covers
146
+
147
+ DAxTA records **real HTTP traffic** from NestJS API integration tests.
148
+
149
+ That is the point. Documentation is generated from the same requests your tests already send against the running application — not from controller decorators, and not from unit tests that never hit HTTP.
150
+
151
+ **Covered** — Nest e2e / integration tests that go through **supertest** or **superagent**:
152
+
153
+ ```ts
154
+ request(app.getHttpServer())
155
+ .post('/v1/users')
156
+ .set('authorization', token)
157
+ .send({ email: 'ada@example.com' })
158
+ .expect(201);
89
159
  ```
90
160
 
91
- 1. **Install** attaches DAxTA as a Jest plugin (`setupFilesAfterEnv` + reporter, and `globalSetup` when you don’t already have one). Your existing `test:integration` stays the entrypoint — DAxTA does not wrap the process.
92
- 2. **During the run** only traffic is recorded. The API spec and HTML are generated once when Jest finishes, from **this run’s hits only**.
93
- 3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
161
+ If Jest is wired (`setupFilesAfterEnv` + reporter), those hits become `/api-docs` when the suite finishes.
162
+
163
+ **Not covered** — anything that never passes through that HTTP client:
94
164
 
95
- | After tests | On the app |
165
+ | Test style | Recorded? |
96
166
  | --- | --- |
97
- | OpenAPI + HTML from real hits | `/api-docs` on the same port as Nest |
98
- | POSITIVE / INVALID / SEMANTIC / AUTH scenarios | Example picker uses the `when` clause only |
99
- | DTO field map (required vs optional) | `DAXTA_DOCS=true\|false` gate |
167
+ | Nest e2e with `request(app.getHttpServer())` | Yes |
168
+ | Service / unit tests (`TestingModule`, no HTTP) | No |
169
+ | `axios`, `fetch`, `got` | No |
170
+ | Playwright / Cypress | No |
171
+ | GraphQL or WebSocket (unless over superagent HTTP) | No |
100
172
 
101
- ## `DAXTA_DOCS` (required)
173
+ If the test does not hit the API over HTTP the way your clients do, DAxTA has nothing to document. That is intentional: the source of truth is **observed API behavior**, not mocked internals.
102
174
 
103
- Same idea as Nest Swagger’s “don’t call `setup` in prod”:
175
+ ---
176
+
177
+ ## Install
104
178
 
105
179
  ```bash
106
- DAXTA_DOCS=true # mount /api-docs (install writes this)
107
- DAXTA_DOCS=false # no-op (must still be set)
108
- # unset / empty → throws — make the choice explicit
180
+ pnpm dlx @t0.labs/daxta install
109
181
  ```
110
182
 
111
- `false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting API docs.
183
+ or:
112
184
 
113
- ## Config
185
+ ```bash
186
+ npx @t0.labs/daxta install
187
+ ```
114
188
 
115
- `daxta.config.ts`:
189
+ The installer wires `apiDocs(app)` into your NestJS entrypoint, hooks DAxTA into Jest, and writes `daxta.config.ts`.
116
190
 
117
- ```ts
118
- import { defineConfig } from '@t0.labs/daxta';
119
-
120
- export default defineConfig({
121
- specInfo: () => ({
122
- title: 'Merchant API',
123
- version: '1.0.0',
124
- }),
125
- baseUrl: 'http://localhost:3000',
126
- docsPath: '/api-docs',
127
- outDir: '.daxta/out',
128
- viewerStoreFile: '.daxta/viewer-store.json',
129
- envPresets: {
130
- local: { baseUrl: 'http://localhost:3000' },
131
- staging: { baseUrl: 'https://api.staging.example.com' },
132
- production: { baseUrl: 'https://api.example.com' },
133
- },
134
- });
191
+ Then run your existing integration tests:
192
+
193
+ ```bash
194
+ pnpm run test:integration
135
195
  ```
136
196
 
137
- Generated artifacts live under `.daxta/`:
197
+ When Jest finishes, your documentation is ready.
198
+
199
+ Start your application with DAxTA enabled:
200
+
201
+ ```bash
202
+ DAXTA_DOCS=true pnpm start:dev
203
+ ```
204
+
205
+ Open:
138
206
 
139
207
  ```text
140
- .daxta/
141
- ├── out/
142
- │ ├── openapi.json
143
- │ └── openapi.html
144
- └── viewer-store.json
208
+ http://localhost:3000/api-docs
145
209
  ```
146
210
 
147
- DAxTA is the tool. The artifact is **API docs** (`openapi.json` + the HTML viewer). The hosted page title is your API title; the footer is a small **Generated by DAxTA**.
211
+ That's it.
148
212
 
149
- ## CLI
213
+ **Your tests are now your API documentation source.**
150
214
 
151
- ```text
152
- daxta generate
153
- Generate API documentation from test execution.
215
+ Flags: `--yes` · `--dry-run` · `--skip-main` · `--skip-dep` · `--main <path>` · `--fast`
154
216
 
155
- daxta serve
156
- Serve API documentation locally.
217
+ ---
157
218
 
158
- daxta install
159
- Install DAxTA in this project.
219
+ ## Docs UI
160
220
 
161
- daxta uninstall
162
- Remove DAxTA from this project.
221
+ DAxTA provides an interactive API workbench directly on your application.
163
222
 
164
- daxta migrate
165
- Upgrade project wiring after a package bump.
223
+ From `/api-docs` you can:
166
224
 
167
- daxta tree
168
- Configure API docs sidebar layout.
225
+ - browse recorded API operations
226
+ - switch between scenarios generated by different tests
227
+ - inspect real requests and responses
228
+ - inspect status codes and headers
229
+ - inspect required / optional DTO fields
230
+ - send API requests
231
+ - copy requests as cURL
232
+ - work with different environments and header groups
233
+ - select APIs and examples for export
169
234
 
170
- daxta titles
171
- Align test titles with API docs examples.
235
+ Think of it as an API exploration layer generated from the tests you already wrote.
172
236
 
173
- daxta fields
174
- Export API field map.
237
+ ### Recorded scenarios
175
238
 
176
- daxta call
177
- Send a Try-it request from the CLI.
178
- ```
239
+ Scenarios stay tied to the exact request that produced them — including headers.
179
240
 
180
- `daxta build` is an alias of `daxta generate`.
241
+ For example, an empty authorization header from a `401` test remains empty in that scenario.
181
242
 
182
- ### API docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
243
+ Environment tokens only override keys that were actually recorded.
183
244
 
184
- Company-wide choices (saved in `daxta.config.ts`):
245
+ ---
185
246
 
186
- | Option | Meaning |
187
- | --- | --- |
188
- | `treeLayout` | `role-resource` (`v1 › admin › baskets`) or `resource-role` (`v1 › baskets › admin`) — sidebar **and** Postman export folders |
189
- | `treeSkipParams` | Don’t nest folders under `{id}` (recommended `true`) |
190
- | `envPresets` | Multi-base Try-it presets (`local` / `staging` / `production` + optional variables) |
191
- | `exampleLabelStyle` | OpenAPI example labels: `status-title-case` / `status-case` / `full` |
247
+ ## DTO fields
192
248
 
193
- OpenAPI path keys in the generated spec still follow the sidebar tree. Real URLs stay on `x-daxta-url-path` when the layout differs (e.g. `/v1/admin/baskets` → tree `/v1/baskets/admin`).
249
+ Field metadata is derived from `class-validator` / `class-transformer` DTO metadata together with observed traffic.
194
250
 
195
- ### Try-it env / headers (persisted)
251
+ ```text
252
+ email required
253
+ password required
254
+ firstName optional
255
+ lastName optional
256
+ ```
196
257
 
197
- Env **presets** (multi-base) + header groups are editable in the API docs UI.
258
+ This allows DAxTA to understand required and optional fields without another documentation-specific definition of the same contract.
198
259
 
199
- - The picker shows each preset with its own `baseUrl` + variables + header groups
200
- - Serving the app only auto-fills **local** (or sole) preset — staging/production URLs are not overwritten
201
- - First `daxta generate` seeds `.daxta/viewer-store.json` from `envPresets` if the file is missing
202
- - Runtime edits still persist via `GET/PUT {docsPath}/env.json`
260
+ ---
203
261
 
204
- Sidebar: expand the chevron on an endpoint to list recorded examples underneath; click one to open it in the workbench.
262
+ ## OpenAPI export
205
263
 
206
- Export: download is **Postman Collection** (nested folders like the sidebar) plus, by default, the active Try-it **environment + header group** as a `.postman_environment.json`. Pick All / None / Success only for which examples to include.
264
+ DAxTA is not limited to `/api-docs`.
207
265
 
208
- Example label (`status-title-case`):
266
+ You can select the **APIs and examples** you want, combine them with the appropriate **environment and header groups**, and export using the **OpenAPI** spec plus a **Postman Collection**.
209
267
 
210
268
  ```text
211
- 200 — Admin Find One Basket By Id API — returns basket with items when found by id
269
+ Tests
270
+ ↓
271
+ DAxTA
272
+ ↓
273
+ Select APIs + Examples
274
+ ↓
275
+ Environment + Header Groups
276
+ ↓
277
+ OpenAPI / Postman
278
+ ↓
279
+ Other tools
212
280
  ```
213
281
 
214
- Then `daxta generate` to refresh `/api-docs` and export.
282
+ This also allows you to create customized API sets without exposing the entire `/api-docs` interface from your service.
215
283
 
216
- ## Test titles (API docs / Postman names)
284
+ Your tests remain the source of truth.
217
285
 
218
- Readable `TEST_TITLE` (path stays after the em dash so DAxTA can still bind the route):
286
+ **OpenAPI becomes the portable output.**
219
287
 
220
- ```ts
221
- static TEST_TITLE = () => `Create Mock Tbs — POST /v1/admin/mock-tbs`;
222
- describe(`${TEST_TITLE()} POSITIVE CASES`, () => { /* … */ });
288
+ ---
289
+
290
+ ## `DAXTA_DOCS`
291
+
292
+ DAxTA requires an explicit decision about whether `/api-docs` should be mounted.
293
+
294
+ ```bash
295
+ DAXTA_DOCS=true # mount /api-docs
296
+ DAXTA_DOCS=false # do not mount /api-docs
297
+
298
+ # unset / empty → throws
223
299
  ```
224
300
 
225
- Format: `{Title} — {METHOD} {path}`
301
+ This makes exposing API documentation an explicit application decision.
226
302
 
227
- Suggested titles (method + path, never `:id` as a name):
303
+ `DAXTA_DOCS=false` does not remove `@t0.labs/daxta` from your Node image. It only prevents `/api-docs` from being mounted.
228
304
 
229
- | Call | Title |
230
- | --- | --- |
231
- | `GET /…/mock-tbs` | Find All Mock Tbs |
232
- | `GET /…/mock-tbs/:id` | Find One Mock Tbs By Id |
233
- | `POST /…/mock-tbs` | Create Mock Tbs |
234
- | `PATCH /…/mock-tbs/:id` | Update Mock Tbs By Id |
235
- | `POST /…/products/bulk` | Create Bulk Products |
236
- | `POST /…/validator/tax-id/validate` | Validate Tax Id |
305
+ The path is configurable via `docsPath` in `daxta.config.ts` (default `/api-docs`).
237
306
 
238
- `--yes` / `a` only rewrite **known** patterns (CRUD + bulk + validate/approve/…). Unknown routes are **not skipped**: they stay listed until you type a custom title (`c`).
307
+ ---
239
308
 
240
- Old `{path} [METHOD] (integration)` still parses. `daxta titles --yes` rewrites to the new form.
309
+ ## Commands
241
310
 
242
- `it()` keeps a unique sentence; `/api-docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
311
+ ```bash
312
+ daxta install # one-shot project setup, including sidebar layout
313
+ daxta uninstall # remove DAxTA wiring from the project
314
+ daxta migrate # upgrade integration after a package bump
315
+ daxta generate # rebuild OpenAPI + UI from recorded traffic
316
+ daxta serve # optional standalone viewer
317
+ daxta tree # reconfigure the /api-docs sidebar
318
+ daxta titles # align test titles with API docs examples
319
+ daxta fields … # export the field map for an operation
320
+ daxta call … # execute an API operation from the CLI
321
+ ```
243
322
 
244
- | Layer | Rule | Example |
245
- | --- | --- | --- |
246
- | Positive `it()` | `{creates\|returns\|updates\|…} … when {diff}` | `creates mock tbs TRNC record when cyprus payload shape` |
247
- | Error `it()` | `returns error when {diff}` | `returns error when tax id already exists in mock TBS` |
248
- | Invalid fields | leave interpolated | `` `${property} - should not be ${description}` `` |
249
- | API docs / Postman | `{status} — {after when}` | `201 — cyprus payload shape` |
323
+ `daxta build` is an alias of `daxta generate`.
324
+
325
+ For most NestJS applications, `apiDocs(app)` is preferred over `daxta serve`.
250
326
 
251
- `--yes` / `a` rewrite **this case’s own text**, not one shared template. Interpolated `it(\`${…}\`)` is never rewritten.
327
+ ---
328
+
329
+ ## Sidebar order
252
330
 
253
331
  ```bash
254
- daxta titles # interactive (y = this recommended, a = all remaining)
255
- daxta titles --yes # rewrite every hit with the recommended name
256
- daxta titles --check # report only
332
+ daxta tree
257
333
  ```
258
334
 
335
+ controls how API paths are organized inside `/api-docs`.
336
+
337
+ ```text
338
+ /v1/admin/baskets
339
+
340
+ 1) URL order
341
+ v1 › admin › baskets
342
+
343
+ 2) Resource-first
344
+ v1 › baskets › admin
345
+
346
+ 3) Custom
347
+ …
348
+ ```
349
+
350
+ The selected structure is stored in `daxta.config.ts` as `treeLayout` and `treePathOverrides`.
351
+
352
+ Then rebuild:
353
+
354
+ ```bash
355
+ daxta generate
356
+ ```
357
+
358
+ ---
359
+
259
360
  ## API
260
361
 
261
362
  ```ts
262
- import { apiDocs, apiDocsHandler, generateApiDocs, getApiDocUrl, getApiDocs, serveApiDocs } from '@t0.labs/daxta';
363
+ import {
364
+ apiDocs,
365
+ apiDocsHandler,
366
+ generateApiDocs,
367
+ serveApiDocs,
368
+ } from '@t0.labs/daxta';
263
369
 
264
370
  await generateApiDocs(); // OpenAPI spec + HTML from recorded test hits
265
- apiDocs(app); // preferred — same origin as the API
371
+ apiDocs(app); // preferred — same origin as your API
266
372
  app.use(apiDocsHandler()); // Express-style mount
267
- serveApiDocs({ port: 5199 }); // standalone (CLI / rare)
268
- getApiDocUrl(); // e.g. http://localhost:3000/api-docs
269
- getApiDocs(); // { url, specPath, htmlPath }
373
+ serveApiDocs({ port: 5199 }); // standalone viewer
374
+ ```
375
+
376
+ ---
377
+
378
+ ## The idea behind DAxTA
379
+
380
+ The idea is simple.
381
+
382
+ If your integration test already proves that:
383
+
384
+ ```text
385
+ this request
386
+ ↓
387
+ produces this response
388
+ ↓
389
+ with this status code
270
390
  ```
271
391
 
272
- Capture during tests is an implementation detail. The public surface is generate, then mount or serve.
392
+ then the documentation already exists.
393
+
394
+ It is just trapped inside your tests.
395
+
396
+ **DAxTA turns it into something you can explore, execute, export, and share.**
397
+
398
+ <p align="center"><strong>API Test → API Documentation</strong></p>
399
+
400
+ <p align="center">You already wrote the tests. Let DAxTA write the docs.</p>
@@ -79,16 +79,29 @@
79
79
  text-overflow: ellipsis;
80
80
  color: var(--obsidian);
81
81
  }
82
- .ver-select {
83
- height: 24px;
84
- border: 1px solid var(--hairline);
82
+ .prefix-bar {
83
+ display: flex;
84
+ flex-wrap: wrap;
85
+ gap: 4px;
86
+ margin: 0 0 8px;
87
+ flex: none;
88
+ }
89
+ .prefix-bar[hidden] { display: none; }
90
+ .prefix-chip {
91
+ height: 22px;
92
+ padding: 0 8px;
93
+ border: 0;
85
94
  border-radius: 4px;
86
- background: var(--white);
87
- font: 500 11px/1 var(--mono);
88
- color: var(--obsidian);
89
- padding: 0 6px;
95
+ background: transparent;
96
+ color: var(--stone);
97
+ font: 500 11px/22px var(--mono);
90
98
  cursor: pointer;
91
99
  }
100
+ .prefix-chip:hover { color: var(--obsidian); background: var(--inset); }
101
+ .prefix-chip.on {
102
+ background: var(--inset);
103
+ color: var(--obsidian);
104
+ }
92
105
  .nav-tools { display: flex; align-items: center; gap: 8px; justify-self: end; }
93
106
  .nav-tools .btn {
94
107
  height: 28px;
@@ -1239,7 +1252,6 @@
1239
1252
  <header class="topnav">
1240
1253
  <div class="brand-wrap">
1241
1254
  <div class="brand" id="brand">API</div>
1242
- <select class="ver-select" id="ver-select" aria-label="API version"></select>
1243
1255
  </div>
1244
1256
  <div class="ep-nav" id="ep-nav">
1245
1257
  <span class="ep-name" id="ep-name"></span>
@@ -1287,6 +1299,7 @@
1287
1299
  <span class="search-kbd">/</span>
1288
1300
  <div class="search-panel" id="search-panel" role="listbox"></div>
1289
1301
  </div>
1302
+ <div class="prefix-bar" id="prefix-bar" hidden></div>
1290
1303
  <div class="tree-scroll" id="nav"></div>
1291
1304
  <div class="nav-foot"><span>Generated by DAxTA</span><span id="nav-version"></span></div>
1292
1305
  </aside>
@@ -1295,209 +1308,7 @@
1295
1308
  <div class="ex-dock" id="ex-dock"></div>
1296
1309
  </div>
1297
1310
  <script>
1298
- window.__SPEC__ = {
1299
- "openapi": "3.0.3",
1300
- "info": {
1301
- "title": "Token X Onboarding Service",
1302
- "version": "v1",
1303
- "x-workspace": "token-x"
1304
- },
1305
- "x-viewer": {
1306
- "workspace": "token-x",
1307
- "baseUrl": "http://localhost:3000",
1308
- "docsPath": "/api-docs",
1309
- "envPresets": {
1310
- "local": { "baseUrl": "http://localhost:3000" }
1311
- }
1312
- },
1313
- "servers": [{ "url": "http://localhost:3000" }],
1314
- "components": {
1315
- "securitySchemes": {
1316
- "adminId": { "type": "apiKey", "in": "header", "name": "x-admin-id" }
1317
- }
1318
- },
1319
- "paths": {
1320
- "/v1/admin/mock-tbs": {
1321
- "post": {
1322
- "summary": "Create Mock Tbs",
1323
- "security": [{ "adminId": [] }],
1324
- "x-tree-segments": ["v1", "mock-tbs", "admin"],
1325
- "x-docs": {
1326
- "title": "Create Mock Tbs",
1327
- "fields": [
1328
- { "name": "taxId", "in": "body", "type": "string", "required": true },
1329
- { "name": "terminals", "in": "body", "type": "array<object>", "required": false },
1330
- { "name": "terminals[].count", "in": "body", "type": "integer", "required": false }
1331
- ]
1332
- },
1333
- "x-scenarios": [
1334
- {
1335
- "name": "Creates mock TBS record with counted random model",
1336
- "group": "POSITIVE CASES",
1337
- "status": 201,
1338
- "headers": {
1339
- "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba",
1340
- "content-type": "application/json"
1341
- },
1342
- "reqBody": { "taxId": "7128961871", "terminals": [{ "count": 2 }] },
1343
- "resBody": {
1344
- "statusCode": 201,
1345
- "success": true,
1346
- "timestamp": "2026-08-22T23:24:16.571Z",
1347
- "path": "/v1/admin/mock-tbs",
1348
- "error": null
1349
- }
1350
- },
1351
- {
1352
- "name": "Creates mock TBS record with terminal model specs",
1353
- "group": "POSITIVE CASES",
1354
- "status": 201,
1355
- "headers": {
1356
- "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba",
1357
- "content-type": "application/json"
1358
- },
1359
- "reqBody": { "taxId": "7128961872", "terminals": [{ "count": 1, "model": "PAX-A920" }] },
1360
- "resBody": {
1361
- "statusCode": 201,
1362
- "success": true,
1363
- "timestamp": "2026-08-22T23:24:18.120Z",
1364
- "path": "/v1/admin/mock-tbs",
1365
- "error": null
1366
- }
1367
- },
1368
- {
1369
- "name": "Tax id already exists",
1370
- "group": "SEMANTIC ERROR CASES",
1371
- "status": 409,
1372
- "headers": {
1373
- "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba",
1374
- "content-type": "application/json"
1375
- },
1376
- "reqBody": { "taxId": "7128961871" },
1377
- "resBody": {
1378
- "statusCode": 409,
1379
- "success": false,
1380
- "path": "/v1/admin/mock-tbs",
1381
- "error": "Tax id already exists"
1382
- }
1383
- },
1384
- {
1385
- "name": "Fiscal id does not exist",
1386
- "group": "SEMANTIC ERROR CASES",
1387
- "status": 404,
1388
- "headers": {
1389
- "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba",
1390
- "content-type": "application/json"
1391
- },
1392
- "reqBody": { "taxId": "0000000000" },
1393
- "resBody": {
1394
- "statusCode": 404,
1395
- "success": false,
1396
- "path": "/v1/admin/mock-tbs",
1397
- "error": "Fiscal id does not exist"
1398
- }
1399
- },
1400
- {
1401
- "name": "taxId should not be array",
1402
- "group": "INVALID CASES",
1403
- "status": 400,
1404
- "headers": {
1405
- "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba",
1406
- "content-type": "application/json"
1407
- },
1408
- "reqBody": { "taxId": ["7128961871"] },
1409
- "resBody": {
1410
- "statusCode": 400,
1411
- "success": false,
1412
- "path": "/v1/admin/mock-tbs",
1413
- "error": "taxId should not be array"
1414
- }
1415
- },
1416
- {
1417
- "name": "taxId has invalid format",
1418
- "group": "INVALID CASES",
1419
- "status": 400,
1420
- "headers": {
1421
- "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba",
1422
- "content-type": "application/json"
1423
- },
1424
- "reqBody": { "taxId": "abc" },
1425
- "resBody": {
1426
- "statusCode": 400,
1427
- "success": false,
1428
- "path": "/v1/admin/mock-tbs",
1429
- "error": "taxId has invalid format"
1430
- }
1431
- },
1432
- {
1433
- "name": "terminals is omitted",
1434
- "group": "OMITTED CASES",
1435
- "status": 201,
1436
- "headers": {
1437
- "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba",
1438
- "content-type": "application/json"
1439
- },
1440
- "reqBody": { "taxId": "7128961873" },
1441
- "resBody": {
1442
- "statusCode": 201,
1443
- "success": true,
1444
- "timestamp": "2026-08-22T23:25:01.000Z",
1445
- "path": "/v1/admin/mock-tbs",
1446
- "error": null
1447
- }
1448
- },
1449
- {
1450
- "name": "Headers are missing",
1451
- "group": "SEMANTIC ERROR CASES - AUTH",
1452
- "status": 401,
1453
- "headers": { "content-type": "application/json" },
1454
- "reqBody": { "taxId": "7128961871" },
1455
- "resBody": {
1456
- "statusCode": 401,
1457
- "success": false,
1458
- "path": "/v1/admin/mock-tbs",
1459
- "error": "Unauthorized"
1460
- }
1461
- }
1462
- ]
1463
- }
1464
- },
1465
- "/v1/admin/terminals": {
1466
- "get": {
1467
- "summary": "List Terminals",
1468
- "security": [{ "adminId": [] }],
1469
- "x-tree-segments": ["v1", "terminal", "admin"],
1470
- "x-docs": { "title": "List Terminals", "fields": [] },
1471
- "x-scenarios": [
1472
- {
1473
- "name": "Returns terminals for admin",
1474
- "group": "POSITIVE CASES",
1475
- "status": 200,
1476
- "headers": { "x-admin-id": "28c82ecd-645e-4df3-96fe-f45b8adbc5ba" },
1477
- "resBody": { "statusCode": 200, "success": true, "data": [] }
1478
- }
1479
- ]
1480
- }
1481
- },
1482
- "/v1/payments": {
1483
- "post": {
1484
- "summary": "Create Payment",
1485
- "x-tree-segments": ["v1", "payments"],
1486
- "x-docs": { "title": "Create Payment", "fields": [{ "name": "amount", "in": "body", "type": "number", "required": true }] },
1487
- "x-scenarios": [
1488
- {
1489
- "name": "Creates a payment",
1490
- "group": "POSITIVE CASES",
1491
- "status": 201,
1492
- "headers": { "content-type": "application/json" },
1493
- "reqBody": { "amount": 1200 },
1494
- "resBody": { "statusCode": 201, "success": true }
1495
- }
1496
- ]
1497
- }
1498
- }
1499
- }
1500
- };
1311
+ window.__SPEC__ = {"openapi":"3.0.3","info":{"title":"Lumen Library API","version":"2.1.0","description":"Generated from observed test execution","x-workspace":"lumen"},"x-viewer":{"workspace":"lumen","baseUrl":"http://localhost:3000","docsPath":"/api-docs","treeLayout":"role-resource","treeSkipParams":true,"exampleLabelStyle":"status-title-case","envPresets":{"local":{"baseUrl":"http://localhost:3000"},"staging":{"baseUrl":"https://api.staging.lumen.example"},"production":{"baseUrl":"https://api.lumen.example"}}},"servers":[{"url":"http://localhost:3000"}],"tags":[{"name":"titles"},{"name":"copies"},{"name":"holds"},{"name":"loans"},{"name":"rooms"}],"components":{"securitySchemes":{"staffId":{"type":"apiKey","in":"header","name":"x-staff-id"},"patronId":{"type":"apiKey","in":"header","name":"x-patron-id"},"authorization":{"type":"apiKey","in":"header","name":"authorization"}}},"paths":{"/v1/staff/titles":{"post":{"tags":["titles"],"summary":"Create Title","security":[{"staffId":[]}],"x-tree-segments":["v1","titles","staff"],"x-docs":{"title":"Create Title","fields":[{"name":"x-staff-id","in":"header","type":"string","required":true},{"name":"isbn","in":"body","type":"string","required":true},{"name":"name","in":"body","type":"string","required":true},{"name":"copies","in":"body","type":"array\u003cobject>","required":false},{"name":"copies[].count","in":"body","type":"integer","required":false},{"name":"copies[].binding","in":"body","type":"string","required":false}]},"x-scenarios":[{"name":"Creates title when counted paperback copies are provided","group":"POSITIVE CASES","status":201,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"isbn":"9780141439518","name":"Pride and Prejudice","copies":[{"count":4}]},"resBody":{"statusCode":201,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":null,"data":{"id":"ttl_01PP","isbn":"9780141439518","copyCount":4}}},{"name":"Creates title when hardcover binding specs are provided","group":"POSITIVE CASES","status":201,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"isbn":"9780141439518","name":"Pride and Prejudice","copies":[{"count":2,"binding":"hardcover"}]},"resBody":{"statusCode":201,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":null,"data":{"id":"ttl_01PP","bindings":["hardcover"]}}},{"name":"Returns error when isbn already exists","group":"SEMANTIC ERROR CASES","status":409,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"isbn":"9780141439518","name":"Pride and Prejudice"},"resBody":{"statusCode":409,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":"ISBN already exists"}},{"name":"Returns error when publisher catalog has no match","group":"SEMANTIC ERROR CASES","status":404,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"isbn":"0000000000000","name":"Unknown Volume"},"resBody":{"statusCode":404,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":"Publisher catalog has no match"}},{"name":"Returns error when isbn is an array","group":"INVALID CASES","status":400,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"isbn":["9780141439518"],"name":"Pride and Prejudice"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":"isbn should not be array"}},{"name":"Returns error when isbn has invalid format","group":"INVALID CASES","status":400,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"isbn":"abc","name":"Pride and Prejudice"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":"isbn has invalid format"}},{"name":"Creates title when copies are omitted","group":"OMITTED CASES","status":201,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"isbn":"9780061120084","name":"To Kill a Mockingbird"},"resBody":{"statusCode":201,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":null,"data":{"id":"ttl_01MK","copyCount":0}}},{"name":"Returns error when x-staff-id is missing","group":"SEMANTIC ERROR CASES - AUTH","status":401,"pathParams":{},"query":{},"headers":{"content-type":"application/json"},"reqBody":{"isbn":"9780141439518","name":"Pride and Prejudice"},"resBody":{"statusCode":401,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","path":"/v1/staff/titles","error":"Unauthorized"}}]}},"/v1/staff/copies":{"get":{"tags":["copies"],"summary":"List Copies","security":[{"staffId":[]}],"x-tree-segments":["v1","copies","staff"],"x-docs":{"title":"List Copies","fields":[{"name":"x-staff-id","in":"header","type":"string","required":true},{"name":"status","in":"query","type":"string","required":false},{"name":"page","in":"query","type":"integer","required":false},{"name":"limit","in":"query","type":"integer","required":false}]},"x-scenarios":[{"name":"Lists copies when query is valid","group":"POSITIVE CASES","status":200,"pathParams":{},"query":{"status":"SHELVED","page":"1","limit":"20"},"headers":{"x-staff-id":"stf_7c91e2a4"},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":[{"id":"cpy_01AA","barcode":"LUM-1001","binding":"paperback","status":"SHELVED"},{"id":"cpy_01AB","barcode":"LUM-1002","binding":"hardcover","status":"SHELVED"}],"meta":{"page":1,"limit":20,"total":2}}},{"name":"Lists copies when filters are omitted","group":"OMITTED CASES","status":200,"pathParams":{},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4"},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":[],"meta":{"page":1,"limit":20,"total":0}}},{"name":"Returns error when page is not a number","group":"INVALID CASES","status":400,"pathParams":{},"query":{"page":"first"},"headers":{"x-staff-id":"stf_7c91e2a4"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"page must be an integer"}},{"name":"Returns error when x-staff-id is missing","group":"SEMANTIC ERROR CASES - AUTH","status":401,"pathParams":{},"query":{},"headers":{},"resBody":{"statusCode":401,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Unauthorized"}}]}},"/v1/staff/copies/{copyId}":{"get":{"tags":["copies"],"summary":"Get Copy","security":[{"staffId":[]}],"x-tree-segments":["v1","copies","staff"],"x-docs":{"title":"Get Copy","fields":[{"name":"x-staff-id","in":"header","type":"string","required":true},{"name":"copyId","in":"path","type":"string","required":true}]},"x-scenarios":[{"name":"Returns copy when id exists","group":"POSITIVE CASES","status":200,"pathParams":{"copyId":"cpy_01AA"},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4"},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"cpy_01AA","barcode":"LUM-1001","binding":"paperback","status":"SHELVED","branch":"river-north"}}},{"name":"Returns error when copy does not exist","group":"SEMANTIC ERROR CASES","status":404,"pathParams":{"copyId":"cpy_missing"},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4"},"resBody":{"statusCode":404,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Copy not found"}},{"name":"Returns error when x-staff-id is missing","group":"SEMANTIC ERROR CASES - AUTH","status":401,"pathParams":{"copyId":"cpy_01AA"},"query":{},"headers":{},"resBody":{"statusCode":401,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Unauthorized"}}]},"patch":{"tags":["copies"],"summary":"Update Copy","security":[{"staffId":[]}],"x-tree-segments":["v1","copies","staff"],"x-docs":{"title":"Update Copy","fields":[{"name":"x-staff-id","in":"header","type":"string","required":true},{"name":"copyId","in":"path","type":"string","required":true},{"name":"status","in":"body","type":"string","required":false},{"name":"shelf","in":"body","type":"string","required":false},{"name":"condition.notes","in":"body","type":"string","required":false}]},"x-scenarios":[{"name":"Updates copy when status is valid","group":"POSITIVE CASES","status":200,"pathParams":{"copyId":"cpy_01AA"},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"status":"REPAIR","shelf":"B-14","condition":{"notes":"loose spine"}},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"cpy_01AA","status":"REPAIR","shelf":"B-14"}}},{"name":"Returns error when status is unknown","group":"INVALID CASES","status":400,"pathParams":{"copyId":"cpy_01AA"},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"status":"LOST-IN-SPACE"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"status must be one of SHELVED, LOANED, REPAIR, WITHDRAWN"}},{"name":"Returns error when copy is already withdrawn","group":"SEMANTIC ERROR CASES","status":409,"pathParams":{"copyId":"cpy_withdrawn"},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4","content-type":"application/json"},"reqBody":{"status":"SHELVED"},"resBody":{"statusCode":409,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Withdrawn copies cannot be reshelved"}}]},"delete":{"tags":["copies"],"summary":"Delete Copy","security":[{"staffId":[]}],"x-tree-segments":["v1","copies","staff"],"x-docs":{"title":"Delete Copy","fields":[{"name":"x-staff-id","in":"header","type":"string","required":true},{"name":"copyId","in":"path","type":"string","required":true}]},"x-scenarios":[{"name":"Deletes copy when it is unused","group":"POSITIVE CASES","status":204,"pathParams":{"copyId":"cpy_01AB"},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4"}},{"name":"Returns error when copy is on loan","group":"SEMANTIC ERROR CASES","status":409,"pathParams":{"copyId":"cpy_01AA"},"query":{},"headers":{"x-staff-id":"stf_7c91e2a4"},"resBody":{"statusCode":409,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Copy is on loan"}},{"name":"Returns error when x-staff-id is missing","group":"SEMANTIC ERROR CASES - AUTH","status":401,"pathParams":{"copyId":"cpy_01AB"},"query":{},"headers":{},"resBody":{"statusCode":401,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Unauthorized"}}]}},"/v1/patron/holds":{"post":{"tags":["holds"],"summary":"Create Hold","security":[{"patronId":[]}],"x-tree-segments":["v1","holds","patron"],"x-docs":{"title":"Create Hold","fields":[{"name":"x-patron-id","in":"header","type":"string","required":true},{"name":"titleId","in":"body","type":"string","required":true},{"name":"pickup.branch","in":"body","type":"string","required":true},{"name":"pickup.by","in":"body","type":"string","required":false},{"name":"notes","in":"body","type":"string","required":false}]},"x-scenarios":[{"name":"Creates hold when pickup branch is open","group":"POSITIVE CASES","status":201,"pathParams":{},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6","content-type":"application/json"},"reqBody":{"titleId":"ttl_01PP","pickup":{"branch":"river-north","by":"2026-09-01"},"notes":"large print if available"},"resBody":{"statusCode":201,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"hld_01PP","status":"QUEUED","position":2}}},{"name":"Returns error when patron already holds this title","group":"SEMANTIC ERROR CASES","status":409,"pathParams":{},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6","content-type":"application/json"},"reqBody":{"titleId":"ttl_01PP","pickup":{"branch":"river-north"}},"resBody":{"statusCode":409,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"A hold already exists for this title"}},{"name":"Returns error when branch code is invalid","group":"INVALID CASES","status":400,"pathParams":{},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6","content-type":"application/json"},"reqBody":{"titleId":"ttl_01PP","pickup":{"branch":"moon-base"}},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"pickup.branch must be a known branch"}},{"name":"Returns error when titleId is omitted","group":"OMITTED CASES","status":400,"pathParams":{},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6","content-type":"application/json"},"reqBody":{"pickup":{"branch":"river-north"}},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"titleId should not be empty"}},{"name":"Returns error when x-patron-id is missing","group":"SEMANTIC ERROR CASES - AUTH","status":401,"pathParams":{},"query":{},"headers":{"content-type":"application/json"},"reqBody":{"titleId":"ttl_01PP","pickup":{"branch":"river-north"}},"resBody":{"statusCode":401,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Unauthorized"}}]}},"/v1/patron/holds/{holdId}":{"get":{"tags":["holds"],"summary":"Get Hold","security":[{"patronId":[]}],"x-tree-segments":["v1","holds","patron"],"x-docs":{"title":"Get Hold","fields":[{"name":"x-patron-id","in":"header","type":"string","required":true},{"name":"holdId","in":"path","type":"string","required":true}]},"x-scenarios":[{"name":"Returns hold when it belongs to patron","group":"POSITIVE CASES","status":200,"pathParams":{"holdId":"hld_01PP"},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6"},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"hld_01PP","status":"QUEUED","titleId":"ttl_01PP"}}},{"name":"Returns error when hold belongs to another patron","group":"SEMANTIC ERROR CASES","status":403,"pathParams":{"holdId":"hld_other"},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6"},"resBody":{"statusCode":403,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Forbidden"}}]},"put":{"tags":["holds"],"summary":"Replace Hold","security":[{"patronId":[]}],"x-tree-segments":["v1","holds","patron"],"x-docs":{"title":"Replace Hold","fields":[{"name":"x-patron-id","in":"header","type":"string","required":true},{"name":"holdId","in":"path","type":"string","required":true},{"name":"titleId","in":"body","type":"string","required":true},{"name":"pickup.branch","in":"body","type":"string","required":true},{"name":"pickup.by","in":"body","type":"string","required":false}]},"x-scenarios":[{"name":"Replaces hold when pickup branch is valid","group":"POSITIVE CASES","status":200,"pathParams":{"holdId":"hld_01PP"},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6","content-type":"application/json"},"reqBody":{"titleId":"ttl_01PP","pickup":{"branch":"west-end","by":"2026-09-08"}},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"hld_01PP","pickup":{"branch":"west-end"},"status":"QUEUED"}}},{"name":"Returns error when hold is already ready","group":"SEMANTIC ERROR CASES","status":409,"pathParams":{"holdId":"hld_ready"},"query":{},"headers":{"x-patron-id":"ptr_3b18d0f6","content-type":"application/json"},"reqBody":{"titleId":"ttl_01PP","pickup":{"branch":"west-end"}},"resBody":{"statusCode":409,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Ready holds cannot be replaced"}}]}},"/v1/loans":{"get":{"tags":["loans"],"summary":"List Loans","security":[{"authorization":[]}],"x-tree-segments":["v1","loans"],"x-docs":{"title":"List Loans","fields":[{"name":"authorization","in":"header","type":"string","required":true},{"name":"from","in":"query","type":"string","required":false},{"name":"to","in":"query","type":"string","required":false},{"name":"status","in":"query","type":"string","required":false},{"name":"cursor","in":"query","type":"string","required":false}]},"x-scenarios":[{"name":"Lists loans when date range is valid","group":"POSITIVE CASES","status":200,"pathParams":{},"query":{"from":"2026-08-01","to":"2026-08-22","status":"OPEN"},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":[{"id":"lon_9f2a","copyId":"cpy_01AA","dueOn":"2026-09-05","status":"OPEN"}],"nextCursor":null}},{"name":"Returns error when from is after to","group":"INVALID CASES","status":400,"pathParams":{},"query":{"from":"2026-08-22","to":"2026-08-01"},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"from must be before to"}},{"name":"Returns error when authorization is missing","group":"SEMANTIC ERROR CASES - AUTH","status":401,"pathParams":{},"query":{"from":"2026-08-01","to":"2026-08-22"},"headers":{},"resBody":{"statusCode":401,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Unauthorized"}}]},"post":{"tags":["loans"],"summary":"Create Loan","security":[{"authorization":[]}],"x-tree-segments":["v1","loans"],"x-docs":{"title":"Create Loan","fields":[{"name":"authorization","in":"header","type":"string","required":true},{"name":"copyId","in":"body","type":"string","required":true},{"name":"patronId","in":"body","type":"string","required":true},{"name":"days","in":"body","type":"integer","required":true},{"name":"idempotencyKey","in":"body","type":"string","required":true},{"name":"notice.email","in":"body","type":"string","required":false}]},"x-scenarios":[{"name":"Creates loan when copy is shelved","group":"POSITIVE CASES","status":201,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"copyId":"cpy_01AA","patronId":"ptr_3b18d0f6","days":21,"idempotencyKey":"chk_88","notice":{"email":"reader@example.com"}},"resBody":{"statusCode":201,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"lon_9f2a","status":"OPEN","dueOn":"2026-09-12"}}},{"name":"Returns open loan when idempotency key is reused","group":"POSITIVE CASES","status":200,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"copyId":"cpy_01AA","patronId":"ptr_3b18d0f6","days":21,"idempotencyKey":"chk_88"},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"lon_9f2a","status":"OPEN","dueOn":"2026-09-12"}}},{"name":"Returns error when copy is in repair","group":"SEMANTIC ERROR CASES","status":422,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"copyId":"cpy_repair","patronId":"ptr_3b18d0f6","days":14,"idempotencyKey":"chk_89"},"resBody":{"statusCode":422,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Copy is not available for loan"}},{"name":"Returns error when days is negative","group":"INVALID CASES","status":400,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"copyId":"cpy_01AA","patronId":"ptr_3b18d0f6","days":-1,"idempotencyKey":"chk_90"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"days must be a positive integer"}},{"name":"Returns error when patronId is omitted","group":"OMITTED CASES","status":400,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"copyId":"cpy_01AA","days":21,"idempotencyKey":"chk_91"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"patronId should not be empty"}},{"name":"Returns error when authorization is expired","group":"SEMANTIC ERROR CASES - AUTH","status":401,"pathParams":{},"query":{},"headers":{"authorization":"Bearer expired","content-type":"application/json"},"reqBody":{"copyId":"cpy_01AA","patronId":"ptr_3b18d0f6","days":21,"idempotencyKey":"chk_92"},"resBody":{"statusCode":401,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Unauthorized"}}]}},"/v1/loans/{loanId}":{"get":{"tags":["loans"],"summary":"Get Loan","security":[{"authorization":[]}],"x-tree-segments":["v1","loans"],"x-docs":{"title":"Get Loan","fields":[{"name":"authorization","in":"header","type":"string","required":true},{"name":"loanId","in":"path","type":"string","required":true}]},"x-scenarios":[{"name":"Returns loan when it exists","group":"POSITIVE CASES","status":200,"pathParams":{"loanId":"lon_9f2a"},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"},"resBody":{"statusCode":200,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"lon_9f2a","copyId":"cpy_01AA","patronId":"ptr_3b18d0f6","status":"OPEN","dueOn":"2026-09-12"}}},{"name":"Returns error when loan does not exist","group":"SEMANTIC ERROR CASES","status":404,"pathParams":{"loanId":"lon_missing"},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"},"resBody":{"statusCode":404,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Loan not found"}}]}},"/v1/rooms/bookings":{"post":{"tags":["rooms"],"summary":"Create Booking","security":[{"authorization":[]}],"x-tree-segments":["v1","rooms","bookings"],"x-docs":{"title":"Create Booking","fields":[{"name":"authorization","in":"header","type":"string","required":true},{"name":"roomId","in":"body","type":"string","required":true},{"name":"slot","in":"body","type":"string","required":true},{"name":"seats","in":"body","type":"integer","required":false}]},"x-scenarios":[{"name":"Creates booking when room is free","group":"POSITIVE CASES","status":201,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"roomId":"rm_quiet","slot":"2026-08-24T10:00:00Z","seats":4},"resBody":{"statusCode":201,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"bkg_9f2a","roomId":"rm_quiet","status":"CONFIRMED"}}},{"name":"Returns error when slot overlaps an existing booking","group":"SEMANTIC ERROR CASES","status":409,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"roomId":"rm_quiet","slot":"2026-08-24T10:00:00Z"},"resBody":{"statusCode":409,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"Room is already booked for this slot"}},{"name":"Returns error when slot is not ISO-8601","group":"INVALID CASES","status":400,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"roomId":"rm_quiet","slot":"tomorrow-morning"},"resBody":{"statusCode":400,"success":false,"timestamp":"2026-08-22T14:08:03.120Z","error":"slot must be an ISO-8601 datetime"}},{"name":"Creates booking when seats are omitted","group":"OMITTED CASES","status":201,"pathParams":{},"query":{},"headers":{"authorization":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…","content-type":"application/json"},"reqBody":{"roomId":"rm_map","slot":"2026-08-24T15:00:00Z"},"resBody":{"statusCode":201,"success":true,"timestamp":"2026-08-22T14:08:03.120Z","data":{"id":"bkg_map","roomId":"rm_map","seats":1,"status":"CONFIRMED"}}}]}}}};
1501
1312
  </script>
1502
1313
  <script>
1503
1314
  const spec = window.__SPEC__ || {};
@@ -3603,6 +3414,7 @@
3603
3414
  if (version) activeVersion = version;
3604
3415
  expandedExampleOps.add(id);
3605
3416
  }
3417
+ renderPrefixBar();
3606
3418
  renderNav();
3607
3419
  renderMain();
3608
3420
  history.replaceState(null, "", "#" + encodeURIComponent(id));
@@ -3665,23 +3477,35 @@
3665
3477
  }
3666
3478
  });
3667
3479
 
3668
- const verSelect = document.getElementById("ver-select");
3669
- if (verSelect) {
3670
- if (!apiVersions.length) verSelect.hidden = true;
3671
- else {
3672
- verSelect.innerHTML = apiVersions.map((name) => `<option value="${escapeAttr(name)}">${escapeHtml(name)}</option>`).join("");
3673
- verSelect.value = activeVersion;
3674
- verSelect.onchange = () => {
3675
- activeVersion = verSelect.value;
3480
+ const prefixLabel = (name) => (String(name).startsWith("/") ? name : "/" + name);
3481
+ const renderPrefixBar = () => {
3482
+ const bar = document.getElementById("prefix-bar");
3483
+ if (!bar) return;
3484
+ if (apiVersions.length < 2) {
3485
+ bar.hidden = true;
3486
+ bar.innerHTML = "";
3487
+ return;
3488
+ }
3489
+ bar.hidden = false;
3490
+ bar.innerHTML = apiVersions
3491
+ .map(
3492
+ (name) =>
3493
+ `<button type="button" class="prefix-chip ${name === activeVersion ? "on" : ""}" data-prefix="${escapeAttr(name)}" aria-pressed="${name === activeVersion ? "true" : "false"}">${escapeHtml(prefixLabel(name))}</button>`,
3494
+ )
3495
+ .join("");
3496
+ bar.querySelectorAll(".prefix-chip").forEach((button) => {
3497
+ button.onclick = () => {
3498
+ activeVersion = button.dataset.prefix;
3676
3499
  const first = visibleOps()[0];
3677
3500
  if (first) select(first.id);
3678
3501
  else {
3502
+ renderPrefixBar();
3679
3503
  renderNav();
3680
3504
  renderMain();
3681
3505
  }
3682
3506
  };
3683
- }
3684
- }
3507
+ });
3508
+ };
3685
3509
 
3686
3510
  const initial = decodeURIComponent(location.hash.replace(/^#/, "")) || ops[0]?.id;
3687
3511
  select(ops.some((item) => item.id === initial) ? initial : ops[0]?.id);
@@ -79,16 +79,29 @@
79
79
  text-overflow: ellipsis;
80
80
  color: var(--obsidian);
81
81
  }
82
- .ver-select {
83
- height: 24px;
84
- border: 1px solid var(--hairline);
82
+ .prefix-bar {
83
+ display: flex;
84
+ flex-wrap: wrap;
85
+ gap: 4px;
86
+ margin: 0 0 8px;
87
+ flex: none;
88
+ }
89
+ .prefix-bar[hidden] { display: none; }
90
+ .prefix-chip {
91
+ height: 22px;
92
+ padding: 0 8px;
93
+ border: 0;
85
94
  border-radius: 4px;
86
- background: var(--white);
87
- font: 500 11px/1 var(--mono);
88
- color: var(--obsidian);
89
- padding: 0 6px;
95
+ background: transparent;
96
+ color: var(--stone);
97
+ font: 500 11px/22px var(--mono);
90
98
  cursor: pointer;
91
99
  }
100
+ .prefix-chip:hover { color: var(--obsidian); background: var(--inset); }
101
+ .prefix-chip.on {
102
+ background: var(--inset);
103
+ color: var(--obsidian);
104
+ }
92
105
  .nav-tools { display: flex; align-items: center; gap: 8px; justify-self: end; }
93
106
  .nav-tools .btn {
94
107
  height: 28px;
@@ -1239,7 +1252,6 @@
1239
1252
  <header class="topnav">
1240
1253
  <div class="brand-wrap">
1241
1254
  <div class="brand" id="brand">API</div>
1242
- <select class="ver-select" id="ver-select" aria-label="API version"></select>
1243
1255
  </div>
1244
1256
  <div class="ep-nav" id="ep-nav">
1245
1257
  <span class="ep-name" id="ep-name"></span>
@@ -1287,6 +1299,7 @@
1287
1299
  <span class="search-kbd">/</span>
1288
1300
  <div class="search-panel" id="search-panel" role="listbox"></div>
1289
1301
  </div>
1302
+ <div class="prefix-bar" id="prefix-bar" hidden></div>
1290
1303
  <div class="tree-scroll" id="nav"></div>
1291
1304
  <div class="nav-foot"><span>Generated by DAxTA</span><span id="nav-version"></span></div>
1292
1305
  </aside>
@@ -3401,6 +3414,7 @@
3401
3414
  if (version) activeVersion = version;
3402
3415
  expandedExampleOps.add(id);
3403
3416
  }
3417
+ renderPrefixBar();
3404
3418
  renderNav();
3405
3419
  renderMain();
3406
3420
  history.replaceState(null, "", "#" + encodeURIComponent(id));
@@ -3463,23 +3477,35 @@
3463
3477
  }
3464
3478
  });
3465
3479
 
3466
- const verSelect = document.getElementById("ver-select");
3467
- if (verSelect) {
3468
- if (!apiVersions.length) verSelect.hidden = true;
3469
- else {
3470
- verSelect.innerHTML = apiVersions.map((name) => `<option value="${escapeAttr(name)}">${escapeHtml(name)}</option>`).join("");
3471
- verSelect.value = activeVersion;
3472
- verSelect.onchange = () => {
3473
- activeVersion = verSelect.value;
3480
+ const prefixLabel = (name) => (String(name).startsWith("/") ? name : "/" + name);
3481
+ const renderPrefixBar = () => {
3482
+ const bar = document.getElementById("prefix-bar");
3483
+ if (!bar) return;
3484
+ if (apiVersions.length < 2) {
3485
+ bar.hidden = true;
3486
+ bar.innerHTML = "";
3487
+ return;
3488
+ }
3489
+ bar.hidden = false;
3490
+ bar.innerHTML = apiVersions
3491
+ .map(
3492
+ (name) =>
3493
+ `<button type="button" class="prefix-chip ${name === activeVersion ? "on" : ""}" data-prefix="${escapeAttr(name)}" aria-pressed="${name === activeVersion ? "true" : "false"}">${escapeHtml(prefixLabel(name))}</button>`,
3494
+ )
3495
+ .join("");
3496
+ bar.querySelectorAll(".prefix-chip").forEach((button) => {
3497
+ button.onclick = () => {
3498
+ activeVersion = button.dataset.prefix;
3474
3499
  const first = visibleOps()[0];
3475
3500
  if (first) select(first.id);
3476
3501
  else {
3502
+ renderPrefixBar();
3477
3503
  renderNav();
3478
3504
  renderMain();
3479
3505
  }
3480
3506
  };
3481
- }
3482
- }
3507
+ });
3508
+ };
3483
3509
 
3484
3510
  const initial = decodeURIComponent(location.hash.replace(/^#/, "")) || ops[0]?.id;
3485
3511
  select(ops.some((item) => item.id === initial) ? initial : ops[0]?.id);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@t0.labs/daxta",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
4
4
  "description": "DAxTA — Tested behavior. Trusted API docs. Generate API documentation from observed test execution.",
5
5
  "license": "MIT",
6
6
  "repository": {