@morehao/trendradar-contract 0.2.0 → 0.4.0

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@morehao/trendradar-contract",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Language-neutral contract (JSON Schema, fixtures, generated Go & TypeScript types) shared by the trendradar Go core and its DSH plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -30,9 +30,8 @@
30
30
  "generate": "node scripts/generate.mjs",
31
31
  "verify": "node scripts/generate.mjs && git diff --exit-code -- gen contract.gen.go schema",
32
32
  "verify-versions": "node scripts/check-versions.mjs",
33
- "verify-field-map": "node scripts/check-field-map.mjs",
34
33
  "test": "node --test test/*.test.mjs",
35
- "prepack": "npm run verify-versions && npm run verify-field-map"
34
+ "prepack": "npm run verify-versions"
36
35
  },
37
36
  "devDependencies": {
38
37
  "canonicalize": "5.1.0"
@@ -1,12 +1,18 @@
1
1
  openapi: 3.1.0
2
2
  info:
3
3
  title: trendradar serve API
4
- version: 0.2.0
4
+ version: 0.4.0
5
5
  description: |
6
6
  Read-only HTTP surface exposed by `trendradar serve`. All payloads reuse the
7
- digest.v2 schema, so the plugin can consume the same shape whether data comes
8
- from the filesystem or over HTTP. Historical v1 digests read from disk are
9
- normalized to this v2 shape with contentHashAlgo=legacy-struct-marshal-v1.
7
+ contract schemas, so the plugin and any web UI consume the same shapes
8
+ whether data comes from the filesystem or over HTTP. Historical v1 digests
9
+ read from disk are normalized to the v2 shape with
10
+ contentHashAlgo=legacy-struct-marshal-v1.
11
+
12
+ Release endpoints are read-only. Token cost for a releases run is NOT part of
13
+ a stored document (it describes one run and cannot be reproduced); it is
14
+ reported in `releases.usage` of `trendradar run --json` and appended to
15
+ `<repo>/.git/trendradar-usage.jsonl` with stage="releases".
10
16
  servers:
11
17
  - url: http://127.0.0.1:8787
12
18
  paths:
@@ -63,6 +69,114 @@ paths:
63
69
  enum: [jcs-sha256-v1, legacy-struct-marshal-v1]
64
70
  degraded:
65
71
  type: boolean
72
+ /api/v2/releases:
73
+ get:
74
+ operationId: listReleases
75
+ summary: List available release digests (newest first)
76
+ description: |
77
+ Returns an empty array (not 404) when no release digest exists yet.
78
+ Entries carry no token cost because stored documents do not record it.
79
+ parameters:
80
+ - name: period
81
+ in: query
82
+ required: false
83
+ schema:
84
+ type: string
85
+ enum: [daily, weekly, monthly]
86
+ responses:
87
+ "200":
88
+ description: Manifest of release digests
89
+ content:
90
+ application/json:
91
+ schema:
92
+ type: array
93
+ items:
94
+ $ref: "./releases.v2.json#/$defs/ReleaseManifestEntry"
95
+ /api/v2/releases/{date}:
96
+ get:
97
+ operationId: getReleases
98
+ summary: Fetch one period's release digest
99
+ parameters:
100
+ - name: date
101
+ in: path
102
+ required: true
103
+ schema:
104
+ type: string
105
+ format: date
106
+ - name: period
107
+ in: query
108
+ required: false
109
+ schema:
110
+ type: string
111
+ enum: [daily, weekly, monthly]
112
+ responses:
113
+ "200":
114
+ description: The release digest document
115
+ content:
116
+ application/json:
117
+ schema:
118
+ $ref: "./releases.v2.json"
119
+ "404":
120
+ description: No release digest for that date
121
+ /api/v2/subscriptions:
122
+ get:
123
+ operationId: listSubscriptions
124
+ summary: List the repo subscriptions the core will poll
125
+ description: |
126
+ Read-only mirror of the IPC `subscribe list` command: both return the
127
+ same SubscriptionList. `repos` is the legacy field; `items` adds the
128
+ per-repo row detail (latest tag, last summary date, check status) and is
129
+ optional, so an older core still satisfies this schema. Writing
130
+ subscriptions stays on the CLI / IPC subscribe command and is never
131
+ exposed over HTTP.
132
+ responses:
133
+ "200":
134
+ description: Current subscription list
135
+ content:
136
+ application/json:
137
+ schema:
138
+ $ref: "./releases.v2.json#/$defs/SubscriptionList"
139
+ /api/v2/repos/{owner}/{repo}/releases:
140
+ get:
141
+ operationId: getSubscriptionDoc
142
+ summary: Read one repo's release document
143
+ description: |
144
+ Read-only mirror of the IPC `subscribe releases` command. Returns the
145
+ exact markdown file content (plus the volume index) so a client renders
146
+ what the data repo stores instead of re-summarizing it. `volume`
147
+ defaults to the newest volume. Only repos matching
148
+ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ are served: the path is resolved
149
+ inside the releases document root and never escapes it.
150
+ parameters:
151
+ - name: owner
152
+ in: path
153
+ required: true
154
+ schema:
155
+ type: string
156
+ pattern: "^[A-Za-z0-9_.-]+$"
157
+ - name: repo
158
+ in: path
159
+ required: true
160
+ schema:
161
+ type: string
162
+ pattern: "^[A-Za-z0-9_.-]+$"
163
+ - name: volume
164
+ in: query
165
+ required: false
166
+ schema:
167
+ type: integer
168
+ minimum: 1
169
+ responses:
170
+ "200":
171
+ description: The repo's release document
172
+ content:
173
+ application/json:
174
+ schema:
175
+ $ref: "./releases.v2.json#/$defs/SubscriptionDoc"
176
+ "400":
177
+ description: Malformed owner/repo or non-positive volume
178
+ "404":
179
+ description: The repo has no release document, or that volume is absent
66
180
  /feed.xml:
67
181
  get:
68
182
  operationId: getFeed
@@ -4,8 +4,12 @@
4
4
  "title": "trendradar ipc v2",
5
5
  "description": "Envelope exchanged between the trendradar core binary and the DSH plugin. Only RunRequest forbids extra fields. ipcSchema is const 2.",
6
6
  "oneOf": [
7
- { "$ref": "#/$defs/RunRequest" },
8
- { "$ref": "#/$defs/RunResult" }
7
+ {
8
+ "$ref": "#/$defs/RunRequest"
9
+ },
10
+ {
11
+ "$ref": "#/$defs/RunResult"
12
+ }
9
13
  ],
10
14
  "$defs": {
11
15
  "ErrorCode": {
@@ -33,76 +37,455 @@
33
37
  "ErrorInfo": {
34
38
  "type": "object",
35
39
  "additionalProperties": true,
36
- "required": ["code", "message", "retriable"],
40
+ "required": [
41
+ "code",
42
+ "message",
43
+ "retriable"
44
+ ],
37
45
  "properties": {
38
- "code": { "$ref": "#/$defs/ErrorCode" },
39
- "message": { "type": "string" },
40
- "retriable": { "type": "boolean" },
41
- "details": { "type": "object", "additionalProperties": true }
46
+ "code": {
47
+ "$ref": "#/$defs/ErrorCode"
48
+ },
49
+ "message": {
50
+ "type": "string"
51
+ },
52
+ "retriable": {
53
+ "type": "boolean"
54
+ },
55
+ "details": {
56
+ "type": "object",
57
+ "additionalProperties": true
58
+ }
42
59
  }
43
60
  },
44
61
  "FileArtifact": {
45
62
  "type": "object",
46
63
  "additionalProperties": true,
47
- "required": ["path", "bytes", "sha256"],
64
+ "required": [
65
+ "path",
66
+ "bytes",
67
+ "sha256"
68
+ ],
48
69
  "properties": {
49
- "path": { "type": "string" },
50
- "bytes": { "type": "integer", "minimum": 0 },
51
- "sha256": { "type": "string" }
70
+ "path": {
71
+ "type": "string"
72
+ },
73
+ "bytes": {
74
+ "type": "integer",
75
+ "minimum": 0
76
+ },
77
+ "sha256": {
78
+ "type": "string"
79
+ }
52
80
  }
53
81
  },
54
82
  "RunRequest": {
55
83
  "type": "object",
56
84
  "additionalProperties": false,
57
- "required": ["ipcSchema", "command"],
85
+ "required": [
86
+ "ipcSchema",
87
+ "command"
88
+ ],
58
89
  "properties": {
59
- "ipcSchema": { "const": 2 },
60
- "command": { "type": "string", "enum": ["run", "serve", "config", "version"] },
61
- "configPath": { "type": "string" },
62
- "date": { "type": "string", "format": "date" },
63
- "dryRun": { "type": "boolean" },
64
- "outputDir": { "type": "string" }
65
- }
90
+ "ipcSchema": {
91
+ "const": 2
92
+ },
93
+ "command": {
94
+ "type": "string",
95
+ "enum": [
96
+ "run",
97
+ "serve",
98
+ "config",
99
+ "version",
100
+ "subscribe"
101
+ ]
102
+ },
103
+ "configPath": {
104
+ "type": "string"
105
+ },
106
+ "date": {
107
+ "type": "string",
108
+ "format": "date"
109
+ },
110
+ "dryRun": {
111
+ "type": "boolean"
112
+ },
113
+ "outputDir": {
114
+ "type": "string"
115
+ },
116
+ "action": {
117
+ "type": "string",
118
+ "enum": [
119
+ "list",
120
+ "add",
121
+ "remove",
122
+ "releases"
123
+ ]
124
+ },
125
+ "repo": {
126
+ "type": "string",
127
+ "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
128
+ },
129
+ "volume": {
130
+ "type": "integer",
131
+ "minimum": 1,
132
+ "description": "subscribe action=releases only: which volume of the repo's release document to read. Defaults to the newest volume."
133
+ },
134
+ "stages": {
135
+ "type": "array",
136
+ "description": "command=run only: which stages to execute. Absent means every enabled stage (backwards compatible); an explicit list narrows the run, e.g. ['releases'] for a release-only run.",
137
+ "items": {
138
+ "type": "string",
139
+ "enum": [
140
+ "trending",
141
+ "digest",
142
+ "releases"
143
+ ]
144
+ }
145
+ }
146
+ },
147
+ "description": "Strict request envelope. command=subscribe manages the repo subscription list: action=list needs no repo; action=add/remove require exactly one repo; action=releases requires a repo and may name a volume. command=run may narrow its work with stages.",
148
+ "allOf": [
149
+ {
150
+ "if": {
151
+ "properties": {
152
+ "command": {
153
+ "const": "subscribe"
154
+ }
155
+ },
156
+ "required": [
157
+ "command"
158
+ ]
159
+ },
160
+ "then": {
161
+ "required": [
162
+ "action"
163
+ ],
164
+ "properties": {
165
+ "action": {
166
+ "enum": [
167
+ "list",
168
+ "add",
169
+ "remove",
170
+ "releases"
171
+ ]
172
+ }
173
+ },
174
+ "allOf": [
175
+ {
176
+ "if": {
177
+ "properties": {
178
+ "action": {
179
+ "const": "list"
180
+ }
181
+ },
182
+ "required": [
183
+ "action"
184
+ ]
185
+ },
186
+ "then": {
187
+ "not": {
188
+ "anyOf": [
189
+ {
190
+ "required": [
191
+ "repo"
192
+ ]
193
+ },
194
+ {
195
+ "required": [
196
+ "volume"
197
+ ]
198
+ }
199
+ ]
200
+ }
201
+ }
202
+ },
203
+ {
204
+ "if": {
205
+ "properties": {
206
+ "action": {
207
+ "enum": [
208
+ "add",
209
+ "remove"
210
+ ]
211
+ }
212
+ },
213
+ "required": [
214
+ "action"
215
+ ]
216
+ },
217
+ "then": {
218
+ "required": [
219
+ "repo"
220
+ ],
221
+ "not": {
222
+ "required": [
223
+ "volume"
224
+ ]
225
+ }
226
+ }
227
+ },
228
+ {
229
+ "if": {
230
+ "properties": {
231
+ "action": {
232
+ "const": "releases"
233
+ }
234
+ },
235
+ "required": [
236
+ "action"
237
+ ]
238
+ },
239
+ "then": {
240
+ "required": [
241
+ "repo"
242
+ ]
243
+ }
244
+ }
245
+ ]
246
+ }
247
+ },
248
+ {
249
+ "if": {
250
+ "properties": {
251
+ "command": {
252
+ "enum": [
253
+ "run",
254
+ "serve",
255
+ "config",
256
+ "version"
257
+ ]
258
+ }
259
+ },
260
+ "required": [
261
+ "command"
262
+ ]
263
+ },
264
+ "then": {
265
+ "not": {
266
+ "anyOf": [
267
+ {
268
+ "required": [
269
+ "action"
270
+ ]
271
+ },
272
+ {
273
+ "required": [
274
+ "repo"
275
+ ]
276
+ },
277
+ {
278
+ "required": [
279
+ "volume"
280
+ ]
281
+ }
282
+ ]
283
+ }
284
+ }
285
+ },
286
+ {
287
+ "if": {
288
+ "properties": {
289
+ "command": {
290
+ "enum": [
291
+ "subscribe",
292
+ "serve",
293
+ "config",
294
+ "version"
295
+ ]
296
+ }
297
+ },
298
+ "required": [
299
+ "command"
300
+ ]
301
+ },
302
+ "then": {
303
+ "not": {
304
+ "required": [
305
+ "stages"
306
+ ]
307
+ }
308
+ }
309
+ }
310
+ ]
66
311
  },
67
312
  "RunResult": {
68
313
  "type": "object",
69
314
  "additionalProperties": true,
70
- "required": ["ipcSchema", "ok", "command", "startedAt", "finishedAt", "skipped", "files"],
315
+ "required": [
316
+ "ipcSchema",
317
+ "ok",
318
+ "command",
319
+ "startedAt",
320
+ "finishedAt",
321
+ "skipped",
322
+ "files"
323
+ ],
324
+ "properties": {
325
+ "ipcSchema": {
326
+ "const": 2
327
+ },
328
+ "ok": {
329
+ "type": "boolean"
330
+ },
331
+ "command": {
332
+ "type": "string",
333
+ "enum": [
334
+ "run",
335
+ "serve",
336
+ "config",
337
+ "version",
338
+ "subscribe"
339
+ ]
340
+ },
341
+ "startedAt": {
342
+ "type": "string",
343
+ "format": "date-time"
344
+ },
345
+ "finishedAt": {
346
+ "type": "string",
347
+ "format": "date-time"
348
+ },
349
+ "skipped": {
350
+ "type": "boolean"
351
+ },
352
+ "files": {
353
+ "type": "array",
354
+ "items": {
355
+ "$ref": "#/$defs/FileArtifact"
356
+ }
357
+ },
358
+ "branch": {
359
+ "type": "string"
360
+ },
361
+ "commit": {
362
+ "type": "string"
363
+ },
364
+ "prUrl": {
365
+ "type": "string",
366
+ "format": "uri"
367
+ },
368
+ "contentHash": {
369
+ "type": "string",
370
+ "pattern": "^sha256:[0-9a-f]{64}$"
371
+ },
372
+ "error": {
373
+ "$ref": "#/$defs/ErrorInfo"
374
+ },
375
+ "warnings": {
376
+ "type": "array",
377
+ "items": {
378
+ "type": "string"
379
+ }
380
+ },
381
+ "usage": {
382
+ "$ref": "#/$defs/Usage"
383
+ },
384
+ "releases": {
385
+ "$ref": "releases.v2.json#/$defs/ReleasesReport"
386
+ },
387
+ "subscriptions": {
388
+ "$ref": "releases.v2.json#/$defs/SubscriptionList"
389
+ },
390
+ "subscriptionDoc": {
391
+ "$ref": "releases.v2.json#/$defs/SubscriptionDoc"
392
+ }
393
+ }
394
+ },
395
+ "Usage": {
396
+ "type": "object",
397
+ "additionalProperties": true,
398
+ "required": [
399
+ "promptTokens",
400
+ "completionTokens",
401
+ "totalTokens",
402
+ "cachedTokens",
403
+ "usageKnown",
404
+ "calls",
405
+ "retries",
406
+ "batches",
407
+ "cacheHits"
408
+ ],
71
409
  "properties": {
72
- "ipcSchema": { "const": 2 },
73
- "ok": { "type": "boolean" },
74
- "command": { "type": "string", "enum": ["run", "serve", "config", "version"] },
75
- "startedAt": { "type": "string", "format": "date-time" },
76
- "finishedAt": { "type": "string", "format": "date-time" },
77
- "skipped": { "type": "boolean" },
78
- "files": { "type": "array", "items": { "$ref": "#/$defs/FileArtifact" } },
79
- "branch": { "type": "string" },
80
- "commit": { "type": "string" },
81
- "prUrl": { "type": "string", "format": "uri" },
82
- "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
83
- "error": { "$ref": "#/$defs/ErrorInfo" },
84
- "warnings": { "type": "array", "items": { "type": "string" } }
410
+ "promptTokens": {
411
+ "type": "integer",
412
+ "minimum": 0
413
+ },
414
+ "completionTokens": {
415
+ "type": "integer",
416
+ "minimum": 0
417
+ },
418
+ "totalTokens": {
419
+ "type": "integer",
420
+ "minimum": 0
421
+ },
422
+ "cachedTokens": {
423
+ "type": "integer",
424
+ "minimum": 0
425
+ },
426
+ "usageKnown": {
427
+ "type": "boolean"
428
+ },
429
+ "calls": {
430
+ "type": "integer",
431
+ "minimum": 0
432
+ },
433
+ "retries": {
434
+ "type": "integer",
435
+ "minimum": 0
436
+ },
437
+ "batches": {
438
+ "type": "integer",
439
+ "minimum": 0
440
+ },
441
+ "cacheHits": {
442
+ "type": "integer",
443
+ "minimum": 0
444
+ }
85
445
  }
86
446
  },
87
447
  "StateRun": {
88
448
  "type": "object",
89
449
  "additionalProperties": true,
90
- "required": ["date", "contentHash", "runAt"],
450
+ "required": [
451
+ "date",
452
+ "contentHash",
453
+ "runAt"
454
+ ],
91
455
  "properties": {
92
- "date": { "type": "string", "format": "date" },
93
- "contentHash": { "type": "string" },
94
- "outputDir": { "type": "string" },
95
- "runAt": { "type": "string", "format": "date-time" }
456
+ "date": {
457
+ "type": "string",
458
+ "format": "date"
459
+ },
460
+ "contentHash": {
461
+ "type": "string"
462
+ },
463
+ "outputDir": {
464
+ "type": "string"
465
+ },
466
+ "runAt": {
467
+ "type": "string",
468
+ "format": "date-time"
469
+ }
96
470
  }
97
471
  },
98
472
  "State": {
99
473
  "type": "object",
100
474
  "additionalProperties": true,
101
- "required": ["ipcSchema", "stateSchema"],
475
+ "required": [
476
+ "ipcSchema",
477
+ "stateSchema"
478
+ ],
102
479
  "properties": {
103
- "ipcSchema": { "const": 2 },
104
- "stateSchema": { "const": 2 },
105
- "lastRun": { "$ref": "#/$defs/StateRun" }
480
+ "ipcSchema": {
481
+ "const": 2
482
+ },
483
+ "stateSchema": {
484
+ "const": 2
485
+ },
486
+ "lastRun": {
487
+ "$ref": "#/$defs/StateRun"
488
+ }
106
489
  }
107
490
  }
108
491
  }