@morehao/trendradar-contract 0.2.0 → 0.3.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.
@@ -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.3.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,69 @@ 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. Returns an empty array when the subscription file is missing
127
+ or empty. Writing subscriptions stays on the CLI / IPC subscribe command.
128
+ responses:
129
+ "200":
130
+ description: Current subscription list
131
+ content:
132
+ application/json:
133
+ schema:
134
+ $ref: "./releases.v2.json#/$defs/SubscriptionList"
66
135
  /feed.xml:
67
136
  get:
68
137
  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,369 @@
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
+ ]
123
+ },
124
+ "repo": {
125
+ "type": "string",
126
+ "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
127
+ }
128
+ },
129
+ "description": "Strict request envelope. command=subscribe manages the repo subscription list: action=list needs no repo; action=add/remove require exactly one repo.",
130
+ "allOf": [
131
+ {
132
+ "if": {
133
+ "properties": {
134
+ "command": {
135
+ "const": "subscribe"
136
+ }
137
+ },
138
+ "required": [
139
+ "command"
140
+ ]
141
+ },
142
+ "then": {
143
+ "required": [
144
+ "action"
145
+ ],
146
+ "properties": {
147
+ "action": {
148
+ "enum": [
149
+ "list",
150
+ "add",
151
+ "remove"
152
+ ]
153
+ }
154
+ },
155
+ "allOf": [
156
+ {
157
+ "if": {
158
+ "properties": {
159
+ "action": {
160
+ "const": "list"
161
+ }
162
+ },
163
+ "required": [
164
+ "action"
165
+ ]
166
+ },
167
+ "then": {
168
+ "not": {
169
+ "required": [
170
+ "repo"
171
+ ]
172
+ }
173
+ }
174
+ },
175
+ {
176
+ "if": {
177
+ "properties": {
178
+ "action": {
179
+ "enum": [
180
+ "add",
181
+ "remove"
182
+ ]
183
+ }
184
+ },
185
+ "required": [
186
+ "action"
187
+ ]
188
+ },
189
+ "then": {
190
+ "required": [
191
+ "repo"
192
+ ]
193
+ }
194
+ }
195
+ ]
196
+ }
197
+ },
198
+ {
199
+ "if": {
200
+ "properties": {
201
+ "command": {
202
+ "enum": [
203
+ "run",
204
+ "serve",
205
+ "config",
206
+ "version"
207
+ ]
208
+ }
209
+ },
210
+ "required": [
211
+ "command"
212
+ ]
213
+ },
214
+ "then": {
215
+ "not": {
216
+ "anyOf": [
217
+ {
218
+ "required": [
219
+ "action"
220
+ ]
221
+ },
222
+ {
223
+ "required": [
224
+ "repo"
225
+ ]
226
+ }
227
+ ]
228
+ }
229
+ }
230
+ }
231
+ ]
66
232
  },
67
233
  "RunResult": {
68
234
  "type": "object",
69
235
  "additionalProperties": true,
70
- "required": ["ipcSchema", "ok", "command", "startedAt", "finishedAt", "skipped", "files"],
236
+ "required": [
237
+ "ipcSchema",
238
+ "ok",
239
+ "command",
240
+ "startedAt",
241
+ "finishedAt",
242
+ "skipped",
243
+ "files"
244
+ ],
245
+ "properties": {
246
+ "ipcSchema": {
247
+ "const": 2
248
+ },
249
+ "ok": {
250
+ "type": "boolean"
251
+ },
252
+ "command": {
253
+ "type": "string",
254
+ "enum": [
255
+ "run",
256
+ "serve",
257
+ "config",
258
+ "version"
259
+ ]
260
+ },
261
+ "startedAt": {
262
+ "type": "string",
263
+ "format": "date-time"
264
+ },
265
+ "finishedAt": {
266
+ "type": "string",
267
+ "format": "date-time"
268
+ },
269
+ "skipped": {
270
+ "type": "boolean"
271
+ },
272
+ "files": {
273
+ "type": "array",
274
+ "items": {
275
+ "$ref": "#/$defs/FileArtifact"
276
+ }
277
+ },
278
+ "branch": {
279
+ "type": "string"
280
+ },
281
+ "commit": {
282
+ "type": "string"
283
+ },
284
+ "prUrl": {
285
+ "type": "string",
286
+ "format": "uri"
287
+ },
288
+ "contentHash": {
289
+ "type": "string",
290
+ "pattern": "^sha256:[0-9a-f]{64}$"
291
+ },
292
+ "error": {
293
+ "$ref": "#/$defs/ErrorInfo"
294
+ },
295
+ "warnings": {
296
+ "type": "array",
297
+ "items": {
298
+ "type": "string"
299
+ }
300
+ },
301
+ "usage": {
302
+ "$ref": "#/$defs/Usage"
303
+ },
304
+ "releases": {
305
+ "$ref": "releases.v2.json#/$defs/ReleasesReport"
306
+ }
307
+ }
308
+ },
309
+ "Usage": {
310
+ "type": "object",
311
+ "additionalProperties": true,
312
+ "required": [
313
+ "promptTokens",
314
+ "completionTokens",
315
+ "totalTokens",
316
+ "cachedTokens",
317
+ "usageKnown",
318
+ "calls",
319
+ "retries",
320
+ "batches",
321
+ "cacheHits"
322
+ ],
71
323
  "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" } }
324
+ "promptTokens": {
325
+ "type": "integer",
326
+ "minimum": 0
327
+ },
328
+ "completionTokens": {
329
+ "type": "integer",
330
+ "minimum": 0
331
+ },
332
+ "totalTokens": {
333
+ "type": "integer",
334
+ "minimum": 0
335
+ },
336
+ "cachedTokens": {
337
+ "type": "integer",
338
+ "minimum": 0
339
+ },
340
+ "usageKnown": {
341
+ "type": "boolean"
342
+ },
343
+ "calls": {
344
+ "type": "integer",
345
+ "minimum": 0
346
+ },
347
+ "retries": {
348
+ "type": "integer",
349
+ "minimum": 0
350
+ },
351
+ "batches": {
352
+ "type": "integer",
353
+ "minimum": 0
354
+ },
355
+ "cacheHits": {
356
+ "type": "integer",
357
+ "minimum": 0
358
+ }
85
359
  }
86
360
  },
87
361
  "StateRun": {
88
362
  "type": "object",
89
363
  "additionalProperties": true,
90
- "required": ["date", "contentHash", "runAt"],
364
+ "required": [
365
+ "date",
366
+ "contentHash",
367
+ "runAt"
368
+ ],
91
369
  "properties": {
92
- "date": { "type": "string", "format": "date" },
93
- "contentHash": { "type": "string" },
94
- "outputDir": { "type": "string" },
95
- "runAt": { "type": "string", "format": "date-time" }
370
+ "date": {
371
+ "type": "string",
372
+ "format": "date"
373
+ },
374
+ "contentHash": {
375
+ "type": "string"
376
+ },
377
+ "outputDir": {
378
+ "type": "string"
379
+ },
380
+ "runAt": {
381
+ "type": "string",
382
+ "format": "date-time"
383
+ }
96
384
  }
97
385
  },
98
386
  "State": {
99
387
  "type": "object",
100
388
  "additionalProperties": true,
101
- "required": ["ipcSchema", "stateSchema"],
389
+ "required": [
390
+ "ipcSchema",
391
+ "stateSchema"
392
+ ],
102
393
  "properties": {
103
- "ipcSchema": { "const": 2 },
104
- "stateSchema": { "const": 2 },
105
- "lastRun": { "$ref": "#/$defs/StateRun" }
394
+ "ipcSchema": {
395
+ "const": 2
396
+ },
397
+ "stateSchema": {
398
+ "const": 2
399
+ },
400
+ "lastRun": {
401
+ "$ref": "#/$defs/StateRun"
402
+ }
106
403
  }
107
404
  }
108
405
  }