@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 +88 -151
- package/dist/db/models/api_settings.model.d.ts +1 -0
- package/dist/db/models/request_log.model.d.ts +1 -0
- package/dist/db/models/routes.model.d.ts +1 -0
- package/dist/db/models/routes_statistics.model.d.ts +1 -0
- package/frontend-vue/package.json +1 -1
- package/package.json +29 -13
- package/skills/dms-api/SKILL.md +31 -0
package/README.md
CHANGED
|
@@ -1,157 +1,94 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# @antelopejs/dms-api
|
|
2
4
|
|
|
3
|
-
<
|
|
4
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/
|
|
5
|
-
<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"
|
|
6
|
-
<a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
+

|
|
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
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,19 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/dms-api",
|
|
3
|
-
"version": "0.4.
|
|
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.
|
|
35
|
-
"@antelopejs/interface-api-util": ">=0.1.
|
|
36
|
-
"@antelopejs/interface-core": ">=0.
|
|
37
|
-
"@antelopejs/interface-database": ">=0.1.
|
|
38
|
-
"@antelopejs/interface-database-decorators": ">=0.1.
|
|
39
|
-
"@antelopejs/interface-dms": ">=0.7.
|
|
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.
|
|
45
|
-
"@antelopejs/tooling-configs": ">=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.
|
|
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.
|