@t0.labs/daxta 0.4.24 → 0.5.1

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,128 +1,185 @@
1
1
  # DAxTA
2
2
 
3
- **Document API × Test API** — NestJS integration tests already hit your real endpoints. DAxTA records that traffic and turns it into living OpenAPI docs on your app port (`/docs`), with DTO required/optional fields and a Try-it workbench.
3
+ **Tested behavior. Trusted API docs.**
4
4
 
5
- Swagger asks you to decorate controllers. DAxTA learns from what your tests actually call.
6
-
7
- DAxTA docs — recorded request, response, Try-it
8
-
9
- ## What you get
10
-
11
-
12
- | After tests | On the app |
13
- | ------------------------------------- | -------------------------------------------------------- |
14
- | OpenAPI + HTML from real hits | `/docs` on the same port as Nest |
15
- | POSITIVE / INVALID / SEMANTIC / AUTH scenarios | Example picker uses the `when` clause only |
16
- | DTO field map (required vs optional) | `DAXTA_DOCS=true|false` gate (like Swagger’s prod check) |
5
+ DAxTA generates and publishes API documentation from API behavior observed during automated tests.
17
6
 
7
+ ```ts
8
+ import { apiDocs, generateApiDocs } from '@t0.labs/daxta';
18
9
 
19
- Jest finishes — Docs ready on /docs
10
+ await generateApiDocs();
11
+ apiDocs(app);
12
+ ```
20
13
 
21
- ## How it works
14
+ Swagger asks you to decorate controllers. DAxTA records what your tests actually call.
22
15
 
23
16
  ```text
24
- your Jest suite
25
- │ supertest / superagent hits
26
- ▼
27
- DAxTA records hits to disk
28
- │ (no OpenAPI rebuild mid-run)
29
- ▼
30
- onRunComplete → one full build
31
- │
32
- ▼
33
- Docs ready → http://localhost:3000/docs
17
+ Tests
18
+ ↓
19
+ Observed API Behavior
20
+ ↓
21
+ DAxTA
22
+ ↓
23
+ Verified API Docs
24
+ ↓
25
+ Hosted Documentation
34
26
  ```
35
27
 
36
- 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.
37
- 2. **During the run** only traffic is recorded (disk flush). OpenAPI/HTML is rebuilt once when Jest finishes, from **this run’s hits only** (previous worker shards are cleared so examples do not stack).
38
- 3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
39
-
28
+ The documentation shows what tests really exercise — not what the code claims to do.
40
29
 
30
+ ## Install
41
31
 
42
- ## CLI ile kurulum
43
-
44
- Tek komut — dependency, `apiDocs(app)`, Jest plugin, `daxta.config.ts` ve sidebar tercihler:
32
+ One command — dependency, `apiDocs(app)`, Jest plugin, `daxta.config.ts`, and sidebar preferences:
45
33
 
46
34
  ```bash
47
35
  pnpm dlx @t0.labs/daxta install
48
- # veya
36
+ # or
49
37
  npx @t0.labs/daxta install
50
38
  ```
51
39
 
52
- Kurulum sırasında sorulur: Nest entry, test script, docs folder order (`role-resource` / `resource-role`), `{id}` fold, example label stili.
53
- `DAXTA_DOCS=true` otomatik `.env`’e yazılır (yoksa oluşturulur).
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).
54
42
 
55
- Sonra:
43
+ Then:
56
44
 
57
45
  ```bash
58
- pnpm run test:integration # test bitince Docs ready
59
- pnpm start:dev # app portunda /docs (DAXTA_DOCS already set)
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
48
  ```
61
49
 
62
50
  ```ts
63
51
  import { apiDocs } from '@t0.labs/daxta';
64
52
 
65
- apiDocs(app); // DAXTA_DOCS zorunlu (true | false)
53
+ apiDocs(app); // DAXTA_DOCS is required (true | false)
66
54
  ```
67
55
 
68
56
  Flags: `--yes` · `--dry-run` · `--skip-main` · `--skip-dep` · `--main <path>` · `--fast`
69
57
 
70
- ## CLI ile kaldırma
58
+ ## Uninstall
71
59
 
72
60
  ```bash
73
61
  pnpm dlx @t0.labs/daxta uninstall
74
- # veya
62
+ # or
75
63
  npx @t0.labs/daxta uninstall
76
64
  ```
77
65
 
78
- Otomatik temizler:
66
+ Removes:
79
67
 
80
68
  - `apiDocs` + `@t0.labs/daxta` import (`main.ts`)
81
- - Jest `setup` + `jest-reporter` (+ `globalSetup` when missing)
82
- - `daxta.config.*` ve `daxta/` output
83
- - `.gitignore` / `.env` içindeki DAxTA satırları
84
- - `@t0.labs/daxta` paketi
85
-
86
- Flags: `--yes` · `--dry-run` · `--keep-dep` (paketi bırakıp sadece wiring’i sök) · `--fast`
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
87
73
 
74
+ Flags: `--yes` · `--dry-run` · `--keep-dep` (leave the package, unwind wiring only) · `--fast`
88
75
 
76
+ ## How it works
89
77
 
90
- ## Docs UI
91
-
92
- Recorded scenarios (success, validation, missing auth) stay tied to the request that produced them — headers included. Empty auth on a 401 scenario stays empty; env tokens only override keys that were actually recorded.
93
-
94
- Scenario picker — success, validation, auth
78
+ ```text
79
+ your Jest suite
80
+ │ supertest / superagent hits
81
+ ▼
82
+ DAxTA records hits to disk
83
+ │ (no OpenAPI rebuild mid-run)
84
+ ▼
85
+ onRunComplete → generate API docs
86
+ │
87
+ ▼
88
+ API docs ready → http://localhost:3000/api-docs
89
+ ```
95
90
 
96
- Field metadata comes from class-validator / class-transformer DTOs plus observed traffic:
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`.
97
94
 
98
- Required vs optional DTO fields
95
+ | After tests | On the app |
96
+ | --- | --- |
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 |
99
100
 
100
101
  ## `DAXTA_DOCS` (required)
101
102
 
102
103
  Same idea as Nest Swagger’s “don’t call `setup` in prod”:
103
104
 
104
105
  ```bash
105
- DAXTA_DOCS=true # mount /docs (install writes this)
106
+ DAXTA_DOCS=true # mount /api-docs (install writes this)
106
107
  DAXTA_DOCS=false # no-op (must still be set)
107
108
  # unset / empty → throws — make the choice explicit
108
109
  ```
109
110
 
110
- `false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting `/docs`.
111
+ `false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting API docs.
111
112
 
112
- ## Commands
113
+ ## Config
113
114
 
114
- ```bash
115
- daxta install # CLI kurulum (+ sidebar prompts)
116
- daxta uninstall # CLI kaldırma (komple)
117
- daxta migrate # paket bump sonrası upgrade (+ sidebar prompts)
118
- daxta build # OpenAPI/HTML rebuild
119
- daxta serve # standalone viewer (opsiyonel)
120
- daxta tree # sidebar / example tercihlerini yeniden sor
121
- daxta fields … # field map export
122
- daxta call … # CLI Try-it
115
+ `daxta.config.ts`:
116
+
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
+ });
123
135
  ```
124
136
 
125
- ### Docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
137
+ Generated artifacts live under `.daxta/`:
138
+
139
+ ```text
140
+ .daxta/
141
+ ├── out/
142
+ │ ├── openapi.json
143
+ │ └── openapi.html
144
+ └── viewer-store.json
145
+ ```
146
+
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**.
148
+
149
+ ## CLI
150
+
151
+ ```text
152
+ daxta generate
153
+ Generate API documentation from test execution.
154
+
155
+ daxta serve
156
+ Serve API documentation locally.
157
+
158
+ daxta install
159
+ Install DAxTA in this project.
160
+
161
+ daxta uninstall
162
+ Remove DAxTA from this project.
163
+
164
+ daxta migrate
165
+ Upgrade project wiring after a package bump.
166
+
167
+ daxta tree
168
+ Configure API docs sidebar layout.
169
+
170
+ daxta titles
171
+ Align test titles with API docs examples.
172
+
173
+ daxta fields
174
+ Export API field map.
175
+
176
+ daxta call
177
+ Send a Try-it request from the CLI.
178
+ ```
179
+
180
+ `daxta build` is an alias of `daxta generate`.
181
+
182
+ ### API docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
126
183
 
127
184
  Company-wide choices (saved in `daxta.config.ts`):
128
185
 
@@ -137,26 +194,16 @@ OpenAPI path keys in the generated spec still follow the sidebar tree. Real URLs
137
194
 
138
195
  ### Try-it env / headers (persisted)
139
196
 
140
- Env **presets** (multi-base) + header groups are editable in the docs UI.
141
-
142
- Define company defaults in `daxta.config.ts`:
143
-
144
- ```ts
145
- envPresets: {
146
- local: { baseUrl: 'http://localhost:3000' },
147
- staging: { baseUrl: 'https://api.staging.example.com' },
148
- production: { baseUrl: 'https://api.example.com', variables: { apiKey: '' } },
149
- },
150
- ```
197
+ Env **presets** (multi-base) + header groups are editable in the API docs UI.
151
198
 
152
- - Docs picker shows each preset with its own `baseUrl` + variables + header groups
153
- - Serving the app only auto-fills **local** (or sole) preset — staging/production URLs are not overwritten
154
- - First `daxta build` seeds `daxta/viewer-store.json` from `envPresets` if the file is missing
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
155
202
  - Runtime edits still persist via `GET/PUT {docsPath}/env.json`
156
203
 
157
204
  Sidebar: expand the chevron on an endpoint to list recorded examples underneath; click one to open it in the workbench.
158
205
 
159
- 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. Import the collection, then the environment, and select that env in Postman.
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.
160
207
 
161
208
  Example label (`status-title-case`):
162
209
 
@@ -164,9 +211,9 @@ Example label (`status-title-case`):
164
211
  200 — Admin Find One Basket By Id API — returns basket with items when found by id
165
212
  ```
166
213
 
167
- Then `daxta build` to refresh `/docs` and export.
214
+ Then `daxta generate` to refresh `/api-docs` and export.
168
215
 
169
- ## Test titles (docs / Postman names)
216
+ ## Test titles (API docs / Postman names)
170
217
 
171
218
  Readable `TEST_TITLE` (path stays after the em dash so DAxTA can still bind the route):
172
219
 
@@ -192,14 +239,14 @@ Suggested titles (method + path, never `:id` as a name):
192
239
 
193
240
  Old `{path} [METHOD] (integration)` still parses. `daxta titles --yes` rewrites to the new form.
194
241
 
195
- `it()` keeps a unique sentence; `/docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
242
+ `it()` keeps a unique sentence; `/api-docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
196
243
 
197
244
  | Layer | Rule | Example |
198
245
  | --- | --- | --- |
199
246
  | Positive `it()` | `{creates\|returns\|updates\|…} … when {diff}` | `creates mock tbs TRNC record when cyprus payload shape` |
200
247
  | Error `it()` | `returns error when {diff}` | `returns error when tax id already exists in mock TBS` |
201
248
  | Invalid fields | leave interpolated | `` `${property} - should not be ${description}` `` |
202
- | Docs / Postman | `{status} — {after when}` | `201 — cyprus payload shape` |
249
+ | API docs / Postman | `{status} — {after when}` | `201 — cyprus payload shape` |
203
250
 
204
251
  `--yes` / `a` rewrite **this case’s own text**, not one shared template. Interpolated `it(\`${…}\`)` is never rewritten.
205
252
 
@@ -209,16 +256,17 @@ daxta titles --yes # rewrite every hit with the recommended name
209
256
  daxta titles --check # report only
210
257
  ```
211
258
 
212
-
213
-
214
-
215
259
  ## API
216
260
 
217
261
  ```ts
218
- import { apiDocs, apiDocsHandler, serveApiDocs } from '@t0.labs/daxta';
262
+ import { apiDocs, apiDocsHandler, generateApiDocs, getApiDocUrl, getApiDocs, serveApiDocs } from '@t0.labs/daxta';
219
263
 
264
+ await generateApiDocs(); // OpenAPI spec + HTML from recorded test hits
220
265
  apiDocs(app); // preferred — same origin as the API
221
266
  app.use(apiDocsHandler()); // Express-style mount
222
267
  serveApiDocs({ port: 5199 }); // standalone (CLI / rare)
268
+ getApiDocUrl(); // e.g. http://localhost:3000/api-docs
269
+ getApiDocs(); // { url, specPath, htmlPath }
223
270
  ```
224
271
 
272
+ Capture during tests is an implementation detail. The public surface is generate, then mount or serve.
package/assets/empty.html CHANGED
@@ -3,7 +3,8 @@
3
3
  <head>
4
4
  <meta charset="utf-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1" />
6
- <title>Notary</title>
6
+ <title>API Documentation</title>
7
+ <link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMiAzMiI+CiAgPHN0eWxlPgogICAgLmJnIHsgZmlsbDogI2ZmZmZmZjsgfQogICAgLmZnIHsgZmlsbDogIzExMTExMTsgfQogICAgLnJpbmcgeyBmaWxsOiBub25lOyBzdHJva2U6ICMxMTExMTE7IHN0cm9rZS13aWR0aDogMS4yNTsgfQogICAgQG1lZGlhIChwcmVmZXJzLWNvbG9yLXNjaGVtZTogZGFyaykgewogICAgICAuYmcgeyBmaWxsOiAjMTExMTExOyB9CiAgICAgIC5mZyB7IGZpbGw6ICNmZmZmZmY7IH0KICAgICAgLnJpbmcgeyBzdHJva2U6ICNmZmZmZmY7IH0KICAgIH0KICA8L3N0eWxlPgogIDxyZWN0IGNsYXNzPSJiZyIgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiByeD0iNyIvPgogIDxyZWN0IGNsYXNzPSJyaW5nIiB4PSIwLjYiIHk9IjAuNiIgd2lkdGg9IjMwLjgiIGhlaWdodD0iMzAuOCIgcng9IjYuNCIvPgogIDxwYXRoIGNsYXNzPSJmZyIgZD0iTTQuMiA1LjIgMTQuMiA4Ljh2NC4yQTQuMiA0LjIgMCAwIDEgMTQuMiAyMS40djRMNC4yIDI2LjhaIi8+CiAgPHBhdGggY2xhc3M9ImZnIiBkPSJNMjcuOCA1LjIgMTcuOCA4Ljh2NC4yQTQuMiA0LjIgMCAwIDAgMTcuOCAyMS40djRMMjcuOCAyNi44WiIvPgo8L3N2Zz4K" />
7
8
  <link rel="preconnect" href="https://fonts.googleapis.com" />
8
9
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
9
10
  <link href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@400;500;600&family=Geist:wght@400;500;600&display=swap" rel="stylesheet" />
@@ -133,23 +134,23 @@
133
134
  </head>
134
135
  <body>
135
136
  <header class="topnav">
136
- <span class="nav-meta">/docs</span>
137
+ <span class="nav-meta">/api-docs</span>
137
138
  </header>
138
139
  <main class="stage">
139
140
  <div class="panel">
140
141
  <p class="kicker">Waiting</p>
141
- <h1>No documentation yet</h1>
142
+ <h1>No API documentation yet</h1>
142
143
  <p>This page publishes when API traffic has been recorded. Run your integration tests, then refresh.</p>
143
144
  <ol class="steps">
144
145
  <li><span class="n">1</span><span>Run the integration suite that hits your API.</span></li>
145
- <li><span class="n">2</span><span>Notary writes the docs from those requests and responses.</span></li>
146
+ <li><span class="n">2</span><span>DAxTA writes API docs from those requests and responses.</span></li>
146
147
  <li><span class="n">3</span><span>Reload this page to open the workbench.</span></li>
147
148
  </ol>
148
149
  <pre class="cmd">pnpm run test:integration</pre>
149
150
  <div class="actions">
150
151
  <button class="btn primary" type="button" id="reload">Refresh</button>
151
152
  </div>
152
- <div class="foot">Generated by Notary</div>
153
+ <div class="foot">Generated by DAxTA</div>
153
154
  </div>
154
155
  </main>
155
156
  <script>