@antelopejs/dms-api 0.4.0 → 0.4.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,157 +1,94 @@
1
+ <div align="center">
2
+
1
3
  # @antelopejs/dms-api
2
4
 
3
- <div align="center">
4
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge&labelColor=000000"></a>
5
- <a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
6
- <a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
5
+ <a href="https://www.npmjs.com/package/@antelopejs/dms-api"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/dms-api?style=for-the-badge&labelColor=000000&color=000000"></a>
6
+ <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/dms-api?style=for-the-badge&labelColor=000000&color=000000"></a>
7
+ <a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
8
+ <a href="https://dms.antelopejs.com/docs/modules/api"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
9
+
10
+ The API console of the AntelopeJS DMS: health, request logs, route statistics and a tester.
11
+
7
12
  </div>
8
13
 
9
- `@antelopejs/dms-api` adds an API console to the AntelopeJS DMS. Open
10
- **Modules → API** (`/modules/api`):
11
-
12
- - **Overview**: is the API healthy, since when and why not, with traffic,
13
- errors, the routes needing attention and the slowest ones.
14
- - **Request logs**: every captured request, filtered by status class, method,
15
- slowness or period; a request opens with its error, timing, headers and
16
- bodies, and can be replayed in the tester.
17
- - **Routes**: every registered route with its statistics, its contract
18
- (inferred from its code and its traffic) and a tester.
19
- - **API settings**: the routes the console watches, retention, captured
20
- headers and the slow threshold.
21
-
22
- It requires `@antelopejs/dms` `>=0.9.0 <1.0.0` (`@antelopejs/interface-dms`
23
- 0.7.0) and `@antelopejs/dms-frontend` `>=0.6.0 <0.7.0`. The frontend server
24
- serves no tester route of its own: this module's `dms.server.ts` serves
25
- `POST /api/_dms-api/tester`. These DMS releases
26
- bring the pieces the console is built on: the row side panel, the page's
27
- Live / Pause state and its holds, the refresh the console's own blocks share
28
- with the DMS blocks, the period kept in the URL, the column tones, the
29
- `Guard` block, the form API its settings fields use, the redirect of
30
- `/modules/api` to the Overview, and `useApiData`, which renders the console's
31
- data on the server.
32
-
33
- The Overview, the Request logs and Routes have the DMS **Live / Pause**
34
- toggle (the L key). Live, the default, the page follows new requests as the
35
- DMS realtime channel announces them, each block, the console's own included,
36
- read again at most every 5 s (Request logs), 10 s (Overview) or 15 s
37
- (Routes), every minute once the Overview or Routes show a week or more, and
38
- on that clock while the realtime channel is down. Paused, nothing is read:
39
- the toggle says what was missed ("Paused · 40 new requests · 2 in 5xx"), the
40
- request tables keep their rows, search, sort and "Load more" included, and
41
- offer "40 new requests · 2 in 5xx · Show"; resuming reads each block once.
42
- The page also pauses by itself while its browser tab is hidden and while you
43
- type in the Tester, and a request table holds its rows while one of them is
44
- open in the side panel (and, in the Request logs, while you read further
45
- down, search or sort otherwise than newest first), saying why ("Table on
46
- hold · search active"). The choice is one for the three pages, and
47
- `?live=0` opens a page paused.
48
-
49
- A request opens in a side panel on the right, on a single click on its row,
50
- from every request table: the panel is titled with its method and path, J / K
51
- step through the rows shown, and the URL names it (`?record=`), so a link or a
52
- reload opens it again. In the Request logs, `/` opens the search and `?` the
53
- list of shortcuts; in Routes, `/` opens the route filter. The DMS Shortcuts
54
- page lists them. The period of a page is its period selector's (1H, 24H, 7D,
55
- 30D, and "All time" in the Request logs), kept in the URL
56
- (`?api.period=last-24h`); without one, the page opens on the last period
57
- picked on any of the three pages, else the last 24 hours. An incident of the
58
- Overview opens the Request logs narrowed to its own range
59
- (`?since=&until=`), a linked filter within the page's period. The tabs of a
60
- route are named in the URL by their slot (`?tab=tester`).
61
- Dates and times follow the user's Language & region preferences (time zone,
62
- clock, date format), on a 24-hour clock by default.
63
-
64
- This module is the dashboard for your API, not the HTTP server implementation.
65
- Your application still needs an API provider such as `@antelopejs/api`, the
66
- DMS runtime, and a database.
67
-
68
- ## Start with the demo
69
-
70
- [template-dms-demo](https://github.com/AntelopeJS/template-dms-demo) already
71
- loads this module and its supporting infrastructure. Follow its README to
72
- install the project, start both backend and frontend processes, and create
73
- the first administrator.
74
-
75
- For an existing DMS project, add a package module entry to the `modules` map
76
- in `antelope.config.ts`:
77
-
78
- ```ts
79
- "dms-api": {
80
- source: {
81
- type: "package",
82
- package: "@antelopejs/dms-api",
83
- version: ">=0.0.1 <1.0.0",
84
- },
85
- },
14
+ ![The API Overview: health verdict, routes needing attention, slowest routes and error share](./docs/images/overview.png)
15
+
16
+ ## What it does
17
+
18
+ - Tells whether your API is healthy, since when and why not, with traffic, errors and the slowest routes.
19
+ - Captures every request of your project's routes with its error, timing, headers and bodies (size-capped and redacted).
20
+ - Lists every registered route with its statistics and a contract inferred from code and traffic.
21
+ - Sends test requests from a built-in tester, logged apart from real traffic.
22
+ - Applies its settings (watched routes, retention, captured headers, slow threshold) without a restart.
23
+
24
+ It is the dashboard for your API, not the HTTP server: the project still needs an API provider such as `@antelopejs/api`.
25
+
26
+ ## Install
27
+
28
+ Run the AntelopeJS CLI from the root of a project that already loads `@antelopejs/dms`:
29
+
30
+ ```bash
31
+ ajs project modules add @antelopejs/dms-api
32
+ ```
33
+
34
+ ## Quick start
35
+
36
+ The module works without configuration. Restart the backend, then the frontend, and open **Modules → API** (`/modules/api`). Review the [configuration](https://dms.antelopejs.com/docs/modules/api/configuration) before capturing real traffic: request logs can hold application data.
37
+
38
+ To try it with sample traffic, clone this repository and run its playground:
39
+
40
+ ```bash
41
+ pnpm install && pnpm dev # backend
42
+ pnpm frontend:dev # dashboard, in a second terminal
43
+ pnpm --dir playground traffic # a few hundred demo requests
86
44
  ```
87
45
 
88
- Install the declared modules with `pnpm exec ajs project modules install`,
89
- then restart the backend before restarting the frontend. The module registers
90
- its Vue 3 Inertia frontend module automatically through
91
- `frontend-vue/dms.frontend.ts`.
92
-
93
- ## Configuration and data handling
94
-
95
- [src/config.ts](src/config.ts) defines the supported settings, including
96
- statistics and request-log retention, the slow-request threshold, body-size
97
- limits, and the header capture allowlist. Retention uses milliseconds; body
98
- limits use bytes. Settings saved through the dashboard override the module
99
- configuration at runtime. A field set back to its module default ("Use
100
- default") holds no override; the retentions have no such button, since
101
- lowering one deletes data. An empty list of captured headers is an override
102
- of its own: no header is captured.
103
-
104
- The cURL and fetch snippets of a route and a request are written against the
105
- DMS's public API origin, its `apiBaseUrl` (read through `GetApiBaseUrl()`):
106
- set it to the URL clients reach the API at, such as `https://api.example.com`.
107
- Under `ajs dms dev` it follows the dev server.
108
-
109
- Statistics are kept 90 days by default, and the dashboard offers 30, 60 or
110
- 90 days. The 30D period compares itself with the 30 days before it, so it
111
- needs 60 days or more: with 30 days, the 30D comparison is unavailable.
112
- Request logs, which hold full requests, are kept 30 days by default,
113
- independently of the statistics. Lowering a retention from the dashboard shows how much the
114
- next hourly prune deletes and asks to confirm it.
115
-
116
- The module configuration follows the dashboard's rules: the module does not
117
- start with a value the Settings page would refuse (statistics kept other than
118
- 30, 60 or 90 days, a slow threshold off its 50 ms step, a body cap or a log
119
- retention out of bounds, a secret header to capture).
120
-
121
- The console only counts your API's traffic. Its own calls (`/api/monitoring`),
122
- the DMS's (`/dms`, the realtime channel, the page layouts, the session check,
123
- its Settings pages and their tables) and the DMS console's pages are neither
124
- logged nor counted. Requests sent from the Tester are logged, marked as such,
125
- but left out of the statistics, the health and the incidents. The Tester marks
126
- its calls with a short-lived token the module signs
127
- (`x-antelopejs-api-source`), which only a user allowed to use the Tester
128
- obtains: a client cannot leave the statistics by declaring itself the Tester.
129
- Behind several instances, give them the same `testerSourceSecret` so each one
130
- accepts the tokens of the others.
131
-
132
- ### Upgrading from 0.1
133
-
134
- The stored data of earlier versions is not migrated. Drop the
135
- `request_log`, `routes_statistics` and `migrations` tables of the `dms-api`
136
- schema when upgrading; the module creates them again. The API settings answer
137
- the error-rate thresholds as ratios (`0.05`), and the `api.get-api-health`
138
- automation answers `failingRoutes` instead of `routesWithErrors24h`.
139
-
140
- Request logs can contain application data. Review the capture and retention
141
- settings before collecting real traffic, and use synthetic requests for
142
- screenshots or shared demos. The module prunes logs and statistics hourly.
143
-
144
- ## Development
145
-
146
- Use the pnpm version declared in `package.json`. The repository's `dev` script
147
- starts its playground backend; `frontend:dev` starts the published Inertia
148
- dashboard loader. The playground connects to MongoDB at
149
- `mongodb://localhost:27017` unless `MONGO_URL` points it elsewhere. Run `pnpm --dir playground traffic` while the playground runs to send
150
- its demo storefront routes a few hundred requests (healthy, slow, failing and
151
- client errors), so every page has something to show. `pnpm build`
152
- compiles the backend, and `pnpm test` runs the backend unit tests (`tests/`)
153
- followed by the frontend test suite, and `pnpm knip` checks the dependencies
154
- of both. To build and typecheck the frontend module against the installed
155
- DMS, run `pnpm exec ajs dms verify-source -m ../frontend-vue` from
156
- `playground/`; or set `DMS_FRONTEND_WORKSPACE` to the workspace generated by
157
- `ajs dms prepare`, then run `pnpm --dir frontend-vue typecheck`.
46
+ [template-dms-demo](https://github.com/AntelopeJS/template-dms-demo) also loads the module.
47
+
48
+ ## Compatibility
49
+
50
+ | Package | Version |
51
+ | --- | --- |
52
+ | `@antelopejs/dms` | `>=0.9.0 <1.0.0` |
53
+ | `@antelopejs/interface-dms` | `>=0.7.0 <1.0.0` |
54
+ | `@antelopejs/dms-frontend` (renderer) | `>=0.6.0 <0.7.0` |
55
+ | API provider | `@antelopejs/api` |
56
+ | Database | an `@antelopejs/interface-database` implementation, such as `@antelopejs/mongodb` |
57
+
58
+ On DMS 0.8, use `@antelopejs/dms-api` 0.3. Upgrading from 0.1? Read the [FAQ](https://dms.antelopejs.com/docs/modules/api/faq#upgrading-from-01).
59
+
60
+ ## Documentation
61
+
62
+ - [Introduction](https://dms.antelopejs.com/docs/modules/api/introduction)
63
+ - [Installation](https://dms.antelopejs.com/docs/modules/api/installation)
64
+ - [Configuration](https://dms.antelopejs.com/docs/modules/api/configuration)
65
+ - [Usage](https://dms.antelopejs.com/docs/modules/api/usage/overview)
66
+ - [Extending](https://dms.antelopejs.com/docs/modules/api/extending)
67
+ - [FAQ](https://dms.antelopejs.com/docs/modules/api/faq)
68
+
69
+ The guide's sources live in [`docs/`](./docs). The package also ships the `dms-api` Claude Code skill in [`skills/`](./skills), declared under `antelopeJs.skills`.
70
+
71
+ ## Contributing
72
+
73
+ Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. Use the pnpm version declared in `package.json`. The playground connects to MongoDB at `mongodb://localhost:27017` unless `MONGO_URL` points elsewhere.
74
+
75
+ ```bash
76
+ pnpm install
77
+ pnpm dev # playground backend
78
+ pnpm frontend:dev # dashboard, in a second terminal
79
+ pnpm lint
80
+ pnpm typecheck
81
+ pnpm test # backend unit tests (tests/), then the frontend suite
82
+ pnpm knip
83
+ ```
84
+
85
+ <details>
86
+ <summary>Repository notes</summary>
87
+
88
+ - To build and typecheck the frontend module against the installed DMS, run `pnpm exec ajs dms verify-source -m ../frontend-vue` from `playground/`, or set `DMS_FRONTEND_WORKSPACE` to the workspace generated by `ajs dms prepare` and run `pnpm --dir frontend-vue typecheck`.
89
+
90
+ </details>
91
+
92
+ ## License
93
+
94
+ [Apache-2.0](./LICENSE)
@@ -12,6 +12,7 @@ declare const ApiSettingsModel_base: {
12
12
  delete(id: string): Promise<number>;
13
13
  };
14
14
  readonly schemaName: string;
15
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<ApiSettings>;
15
16
  fromPlainData(obj: any): ApiSettings;
16
17
  fromDatabase(obj: any): ApiSettings | undefined;
17
18
  toDatabase(obj: any): Record<string, any>;
@@ -64,6 +64,7 @@ declare const RequestLogModel_base: {
64
64
  delete(id: string): Promise<number>;
65
65
  };
66
66
  readonly schemaName: string;
67
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<RequestLog>;
67
68
  fromPlainData(obj: any): RequestLog;
68
69
  fromDatabase(obj: any): RequestLog | undefined;
69
70
  toDatabase(obj: any): Record<string, any>;
@@ -12,6 +12,7 @@ declare const RouteModel_base: {
12
12
  delete(id: string): Promise<number>;
13
13
  };
14
14
  readonly schemaName: string;
15
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Route>;
15
16
  fromPlainData(obj: any): Route;
16
17
  fromDatabase(obj: any): Route | undefined;
17
18
  toDatabase(obj: any): Record<string, any>;
@@ -13,6 +13,7 @@ declare const RouteStatisticsModel_base: {
13
13
  delete(id: string): Promise<number>;
14
14
  };
15
15
  readonly schemaName: string;
16
+ readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<RouteStatistics>;
16
17
  fromPlainData(obj: any): RouteStatistics;
17
18
  fromDatabase(obj: any): RouteStatistics | undefined;
18
19
  toDatabase(obj: any): Record<string, any>;
@@ -6,7 +6,7 @@
6
6
  "main": "./dms.frontend.ts",
7
7
  "packageManager": "pnpm@10.6.5",
8
8
  "engines": {
9
- "@antelopejs/dms-frontend": ">=0.6.0 <0.7.0"
9
+ "@antelopejs/dms-frontend": ">=0.6.3 <0.7.0"
10
10
  },
11
11
  "scripts": {
12
12
  "dev": "pnpm --dir ../playground frontend:dev",
package/package.json CHANGED
@@ -1,6 +1,19 @@
1
1
  {
2
2
  "name": "@antelopejs/dms-api",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
+ "description": "API console for the AntelopeJS DMS: API health, request logs, per-route statistics, inferred contracts and a request tester.",
5
+ "keywords": [
6
+ "antelopejs",
7
+ "api",
8
+ "dms",
9
+ "dms-module",
10
+ "monitoring",
11
+ "request-logs"
12
+ ],
13
+ "homepage": "https://dms.antelopejs.com/docs/modules/api",
14
+ "bugs": {
15
+ "url": "https://github.com/AntelopeJS/dms-api/issues"
16
+ },
4
17
  "license": "Apache-2.0",
5
18
  "repository": {
6
19
  "type": "git",
@@ -8,7 +21,8 @@
8
21
  },
9
22
  "files": [
10
23
  "dist",
11
- "frontend-vue"
24
+ "frontend-vue",
25
+ "skills"
12
26
  ],
13
27
  "main": "dist/index.js",
14
28
  "publishConfig": {
@@ -31,20 +45,19 @@
31
45
  "knip:all": "knip"
32
46
  },
33
47
  "dependencies": {
34
- "@antelopejs/interface-api": ">=0.0.14 <1.0.0",
35
- "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
36
- "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
37
- "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
38
- "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
39
- "@antelopejs/interface-dms": ">=0.7.0 <1.0.0",
48
+ "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
49
+ "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
50
+ "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
51
+ "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
52
+ "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
53
+ "@antelopejs/interface-dms": ">=0.7.2 <1.0.0",
40
54
  "node-cron": "^4.2.1",
41
55
  "zod": "^3.24.2"
42
56
  },
43
57
  "devDependencies": {
44
- "@antelopejs/core": "1.13.5",
45
- "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
58
+ "@antelopejs/core": "1.16.0",
59
+ "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
46
60
  "@types/node": "^24.0.0",
47
- "@types/node-cron": "^3.0.11",
48
61
  "knip": "^6.34.0",
49
62
  "oxfmt": "^0.66.0",
50
63
  "oxlint": "1.81.0",
@@ -56,7 +69,7 @@
56
69
  "vitest": "^3.2.4"
57
70
  },
58
71
  "optionalDependencies": {
59
- "@antelopejs/interface-dms-automation": ">=0.1.1 <1.0.0"
72
+ "@antelopejs/interface-dms-automation": ">=0.2.1 <1.0.0"
60
73
  },
61
74
  "packageManager": "pnpm@10.6.5",
62
75
  "antelopeJs": {
@@ -65,6 +78,9 @@
65
78
  "@/*": [
66
79
  "*"
67
80
  ]
68
- }
81
+ },
82
+ "skills": [
83
+ "./skills"
84
+ ]
69
85
  }
70
86
  }
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: dms-api
3
+ description: Uses the @antelopejs/dms-api console of the AntelopeJS DMS (API health, request logs, per-route statistics, inferred route docs and a tester under /modules/api). Use when installing or configuring dms-api (retention, slow threshold, captured headers, testerSourceSecret), debugging a failing or slow route from its request logs, wiring its automation nodes (api.route-unhealthy, api.get-api-health, api.query-request-logs), or when a route is missing from the console.
4
+ icon: i-lucide-webhook
5
+ category: monitoring
6
+ tags: [api, monitoring, request-logs, routes, tester, automation]
7
+ ---
8
+
9
+ # dms-api
10
+
11
+ Monitors the project's own HTTP API: it captures each request of the routes in scope, rolls them into per-route statistics, and infers each route's contract from its handler and traffic. It is a dashboard, not the HTTP server: the project still needs `@antelopejs/api`. User docs: https://dms.antelopejs.com/docs/modules/api (source: `docs/` of this package).
12
+
13
+ ## When to reach for it
14
+
15
+ - Debug a route: read its failed requests in `/modules/api/logs` (the side panel holds the error, stack, headers and bodies) or replay one in the route's Tester.
16
+ - Alert on a broken route: an automation procedure on `api.route-unhealthy` (`flags`: `broken`, `slow`, `warn`; default `broken` + `slow`).
17
+
18
+ ## Config (`antelope.config.ts`; the API settings page overrides it at runtime)
19
+
20
+ `statisticsLifetime` (ms, 30/60/90 days only), `requestLogRetention` (ms, 1–366 days), `requestSlownessThreshold` (ms, steps of 50), `requestLogMaxBodySize` (bytes), `requestLogCaptureHeaders` (lower case), `authMiddlewareNamePatterns`, `authMiddlewareCallbacks`, `testerSourceSecret` (same value on every instance). The module refuses to start with a value its settings page would refuse.
21
+
22
+ ## Gotchas
23
+
24
+ - Scope defaults to **Own routes**: routes a module registers show only under Module routes or All routes.
25
+ - Its own calls, the DMS's calls and Tester calls are never counted in statistics or health.
26
+ - cURL snippets use the DMS `apiBaseUrl`: set it to the public API origin.
27
+ - The Tester forwards calls through the module's own frontend server route `POST /api/_dms-api/tester` (`frontend-vue/dms.server.ts`); dms-frontend 0.6 has no built-in tester route.
28
+ - Version 0.4+ needs `@antelopejs/dms` 0.9 (`interface-dms` 0.7) and `@antelopejs/dms-frontend` 0.6; 0.3 is the DMS 0.8 line.
29
+ - A route reads "Auth unknown" when the check happens inside the handler; guard with the DMS auth decorators or name the middleware in `authMiddlewareCallbacks`.
30
+ - Each block is its own permission (`@AuthUserWithPermission(<block>)`): grant roles the blocks they need.
31
+ - Request logs can hold application data; secret-looking keys are always redacted.