@morehao/trendradar-contract 0.0.0-stage → 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.
package/package.json CHANGED
@@ -1,6 +1,47 @@
1
1
  {
2
2
  "name": "@morehao/trendradar-contract",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.0",
4
+ "description": "Language-neutral contract (JSON Schema, fixtures, generated Go & TypeScript types) shared by the trendradar Go core and its DSH plugin.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/morehao/trendradar.git",
10
+ "directory": "contract"
11
+ },
12
+ "files": [
13
+ "schema",
14
+ "fixtures",
15
+ "gen/ts",
16
+ "version-map.json",
17
+ "README.md",
18
+ "CHANGELOG.md"
19
+ ],
20
+ "exports": {
21
+ ".": {
22
+ "types": "./gen/ts/index.d.ts",
23
+ "import": "./gen/ts/index.js"
24
+ },
25
+ "./schema/*": "./schema/*",
26
+ "./fixtures/*": "./fixtures/*"
27
+ },
28
+ "types": "./gen/ts/index.d.ts",
29
+ "scripts": {
30
+ "generate": "node scripts/generate.mjs",
31
+ "verify": "node scripts/generate.mjs && git diff --exit-code -- gen contract.gen.go schema",
32
+ "verify-versions": "node scripts/check-versions.mjs",
33
+ "test": "node --test test/*.test.mjs",
34
+ "prepack": "npm run verify-versions"
35
+ },
36
+ "devDependencies": {
37
+ "canonicalize": "5.1.0"
38
+ },
39
+ "dependencies": {
40
+ "ajv": "8.20.0",
41
+ "ajv-formats": "3.0.1"
42
+ },
43
+ "publishConfig": {
44
+ "access": "public",
45
+ "registry": "https://registry.npmjs.org"
46
+ }
47
+ }
@@ -0,0 +1,145 @@
1
+ openapi: 3.1.0
2
+ info:
3
+ title: trendradar serve API
4
+ version: 0.3.0
5
+ description: |
6
+ Read-only HTTP surface exposed by `trendradar serve`. All payloads reuse the
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".
16
+ servers:
17
+ - url: http://127.0.0.1:8787
18
+ paths:
19
+ /api/v2/digests/{date}:
20
+ get:
21
+ operationId: getDigest
22
+ summary: Fetch one day's digest
23
+ parameters:
24
+ - name: date
25
+ in: path
26
+ required: true
27
+ schema:
28
+ type: string
29
+ format: date
30
+ responses:
31
+ "200":
32
+ description: The digest document
33
+ content:
34
+ application/json:
35
+ schema:
36
+ $ref: "./digest.v2.json"
37
+ "404":
38
+ description: No digest for that date
39
+ /api/v2/manifest:
40
+ get:
41
+ operationId: getManifest
42
+ summary: List available dates and their content identity
43
+ responses:
44
+ "200":
45
+ description: Manifest of available digests
46
+ content:
47
+ application/json:
48
+ schema:
49
+ type: object
50
+ required: [entries]
51
+ properties:
52
+ coreVersion:
53
+ type: string
54
+ entries:
55
+ type: array
56
+ items:
57
+ type: object
58
+ required: [date, contentHash, schema, contentHashAlgo]
59
+ properties:
60
+ date:
61
+ type: string
62
+ format: date
63
+ contentHash:
64
+ type: string
65
+ schema:
66
+ type: integer
67
+ contentHashAlgo:
68
+ type: string
69
+ enum: [jcs-sha256-v1, legacy-struct-marshal-v1]
70
+ degraded:
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"
135
+ /feed.xml:
136
+ get:
137
+ operationId: getFeed
138
+ summary: RSS feed of the most recent digests
139
+ responses:
140
+ "200":
141
+ description: RSS 2.0 feed
142
+ content:
143
+ application/rss+xml:
144
+ schema:
145
+ type: string
@@ -0,0 +1,25 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/morehao/trendradar/contract/schema/digest.v2.json",
4
+ "title": "trendradar digest v2",
5
+ "description": "One day's rendered digest document. contentHash is stable across runs (generatedAt/coreVersion excluded); contentHashAlgo records which algorithm produced it.",
6
+ "type": "object",
7
+ "additionalProperties": true,
8
+ "required": ["schema", "date", "period", "languages", "count", "degraded", "contentHash", "contentHashAlgo", "repos"],
9
+ "properties": {
10
+ "schema": { "const": 2 },
11
+ "date": { "type": "string", "format": "date" },
12
+ "period": { "type": "string", "enum": ["daily", "weekly", "monthly"] },
13
+ "languages": { "type": "array", "minItems": 1, "items": { "type": "string" } },
14
+ "count": { "type": "integer", "minimum": 0 },
15
+ "degraded": { "type": "boolean" },
16
+ "contentHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
17
+ "contentHashAlgo": { "type": "string", "enum": ["jcs-sha256-v1", "legacy-struct-marshal-v1"] },
18
+ "coreVersion": { "type": "string" },
19
+ "generatedAt": { "type": "string", "format": "date-time" },
20
+ "repos": {
21
+ "type": "array",
22
+ "items": { "$ref": "model.v2.json#/$defs/RepoDigest" }
23
+ }
24
+ }
25
+ }
@@ -0,0 +1,341 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/morehao/trendradar/contract/schema/errors.v2.json",
4
+ "title": "trendradar errors v2",
5
+ "description": "Canonical error-code catalog. Each property is one error code whose retriable/description are consts, so this file is the single source of truth for retriability. ipc.v2.json ErrorCode enum must match these keys exactly.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "INTERNAL",
10
+ "CONFIG_INVALID",
11
+ "PAYLOAD_TOO_LARGE",
12
+ "FETCH_FAILED",
13
+ "FETCH_RATE_LIMITED",
14
+ "PARSE_FAILED",
15
+ "MODEL_UNAUTHORIZED",
16
+ "MODEL_RATE_LIMITED",
17
+ "MODEL_TIMEOUT",
18
+ "MODEL_FAILED",
19
+ "MODEL_BAD_OUTPUT",
20
+ "GIT_NOT_INSTALLED",
21
+ "REPO_NOT_GIT",
22
+ "REPO_DIRTY",
23
+ "GIT_OPERATION_FAILED",
24
+ "PR_FAILED",
25
+ "NOT_MERGEABLE"
26
+ ],
27
+ "properties": {
28
+ "INTERNAL": {
29
+ "type": "object",
30
+ "additionalProperties": false,
31
+ "required": [
32
+ "retriable",
33
+ "description"
34
+ ],
35
+ "properties": {
36
+ "retriable": {
37
+ "const": true
38
+ },
39
+ "description": {
40
+ "const": "Unexpected internal error (transient panic/IO); retry may succeed."
41
+ }
42
+ }
43
+ },
44
+ "CONFIG_INVALID": {
45
+ "type": "object",
46
+ "additionalProperties": false,
47
+ "required": [
48
+ "retriable",
49
+ "description"
50
+ ],
51
+ "properties": {
52
+ "retriable": {
53
+ "const": false
54
+ },
55
+ "description": {
56
+ "const": "Configuration is invalid or unreadable."
57
+ }
58
+ }
59
+ },
60
+ "PAYLOAD_TOO_LARGE": {
61
+ "type": "object",
62
+ "additionalProperties": false,
63
+ "required": [
64
+ "retriable",
65
+ "description"
66
+ ],
67
+ "properties": {
68
+ "retriable": {
69
+ "const": false
70
+ },
71
+ "description": {
72
+ "const": "Input payload exceeds the allowed size."
73
+ }
74
+ }
75
+ },
76
+ "FETCH_FAILED": {
77
+ "type": "object",
78
+ "additionalProperties": false,
79
+ "required": [
80
+ "retriable",
81
+ "description"
82
+ ],
83
+ "properties": {
84
+ "retriable": {
85
+ "const": false
86
+ },
87
+ "description": {
88
+ "const": "Fetching trending data failed terminally (retries exhausted)."
89
+ }
90
+ }
91
+ },
92
+ "FETCH_RATE_LIMITED": {
93
+ "type": "object",
94
+ "additionalProperties": false,
95
+ "required": [
96
+ "retriable",
97
+ "description"
98
+ ],
99
+ "properties": {
100
+ "retriable": {
101
+ "const": true
102
+ },
103
+ "description": {
104
+ "const": "Fetching was rate limited; retry later."
105
+ }
106
+ }
107
+ },
108
+ "PARSE_FAILED": {
109
+ "type": "object",
110
+ "additionalProperties": false,
111
+ "required": [
112
+ "retriable",
113
+ "description"
114
+ ],
115
+ "properties": {
116
+ "retriable": {
117
+ "const": false
118
+ },
119
+ "description": {
120
+ "const": "Parsing fetched HTML/JSON failed."
121
+ }
122
+ }
123
+ },
124
+ "MODEL_UNAUTHORIZED": {
125
+ "type": "object",
126
+ "additionalProperties": false,
127
+ "required": [
128
+ "retriable",
129
+ "description"
130
+ ],
131
+ "properties": {
132
+ "retriable": {
133
+ "const": false
134
+ },
135
+ "description": {
136
+ "const": "Model provider rejected the credentials."
137
+ }
138
+ }
139
+ },
140
+ "MODEL_RATE_LIMITED": {
141
+ "type": "object",
142
+ "additionalProperties": false,
143
+ "required": [
144
+ "retriable",
145
+ "description"
146
+ ],
147
+ "properties": {
148
+ "retriable": {
149
+ "const": true
150
+ },
151
+ "description": {
152
+ "const": "Model provider rate limited the request."
153
+ }
154
+ }
155
+ },
156
+ "MODEL_TIMEOUT": {
157
+ "type": "object",
158
+ "additionalProperties": false,
159
+ "required": [
160
+ "retriable",
161
+ "description"
162
+ ],
163
+ "properties": {
164
+ "retriable": {
165
+ "const": true
166
+ },
167
+ "description": {
168
+ "const": "Model request timed out."
169
+ }
170
+ }
171
+ },
172
+ "MODEL_FAILED": {
173
+ "type": "object",
174
+ "additionalProperties": false,
175
+ "required": [
176
+ "retriable",
177
+ "description"
178
+ ],
179
+ "properties": {
180
+ "retriable": {
181
+ "const": true
182
+ },
183
+ "description": {
184
+ "const": "Model request failed."
185
+ }
186
+ }
187
+ },
188
+ "MODEL_BAD_OUTPUT": {
189
+ "type": "object",
190
+ "additionalProperties": false,
191
+ "required": [
192
+ "retriable",
193
+ "description"
194
+ ],
195
+ "properties": {
196
+ "retriable": {
197
+ "const": false
198
+ },
199
+ "description": {
200
+ "const": "Model returned output that violates the expected shape."
201
+ }
202
+ }
203
+ },
204
+ "GIT_NOT_INSTALLED": {
205
+ "type": "object",
206
+ "additionalProperties": false,
207
+ "required": [
208
+ "retriable",
209
+ "description"
210
+ ],
211
+ "properties": {
212
+ "retriable": {
213
+ "const": false
214
+ },
215
+ "description": {
216
+ "const": "git executable was not found."
217
+ }
218
+ }
219
+ },
220
+ "REPO_NOT_GIT": {
221
+ "type": "object",
222
+ "additionalProperties": false,
223
+ "required": [
224
+ "retriable",
225
+ "description"
226
+ ],
227
+ "properties": {
228
+ "retriable": {
229
+ "const": false
230
+ },
231
+ "description": {
232
+ "const": "Target directory is not a git repository."
233
+ }
234
+ }
235
+ },
236
+ "REPO_DIRTY": {
237
+ "type": "object",
238
+ "additionalProperties": false,
239
+ "required": [
240
+ "retriable",
241
+ "description"
242
+ ],
243
+ "properties": {
244
+ "retriable": {
245
+ "const": false
246
+ },
247
+ "description": {
248
+ "const": "Git working tree has uncommitted changes."
249
+ }
250
+ }
251
+ },
252
+ "GIT_OPERATION_FAILED": {
253
+ "type": "object",
254
+ "additionalProperties": false,
255
+ "required": [
256
+ "retriable",
257
+ "description"
258
+ ],
259
+ "properties": {
260
+ "retriable": {
261
+ "const": true
262
+ },
263
+ "description": {
264
+ "const": "A git operation (commit/push) failed."
265
+ }
266
+ }
267
+ },
268
+ "PR_FAILED": {
269
+ "type": "object",
270
+ "additionalProperties": false,
271
+ "required": [
272
+ "retriable",
273
+ "description"
274
+ ],
275
+ "properties": {
276
+ "retriable": {
277
+ "const": true
278
+ },
279
+ "description": {
280
+ "const": "Opening or updating the pull request failed."
281
+ }
282
+ }
283
+ },
284
+ "NOT_MERGEABLE": {
285
+ "type": "object",
286
+ "additionalProperties": false,
287
+ "required": [
288
+ "retriable",
289
+ "description"
290
+ ],
291
+ "properties": {
292
+ "retriable": {
293
+ "const": false
294
+ },
295
+ "description": {
296
+ "const": "Pull request is not mergeable."
297
+ }
298
+ }
299
+ }
300
+ },
301
+ "$defs": {
302
+ "ErrorCode": {
303
+ "type": "string",
304
+ "enum": [
305
+ "INTERNAL",
306
+ "CONFIG_INVALID",
307
+ "PAYLOAD_TOO_LARGE",
308
+ "FETCH_FAILED",
309
+ "FETCH_RATE_LIMITED",
310
+ "PARSE_FAILED",
311
+ "MODEL_UNAUTHORIZED",
312
+ "MODEL_RATE_LIMITED",
313
+ "MODEL_TIMEOUT",
314
+ "MODEL_FAILED",
315
+ "MODEL_BAD_OUTPUT",
316
+ "GIT_NOT_INSTALLED",
317
+ "REPO_NOT_GIT",
318
+ "REPO_DIRTY",
319
+ "GIT_OPERATION_FAILED",
320
+ "PR_FAILED",
321
+ "NOT_MERGEABLE"
322
+ ]
323
+ },
324
+ "ErrorMeta": {
325
+ "type": "object",
326
+ "additionalProperties": false,
327
+ "required": [
328
+ "retriable",
329
+ "description"
330
+ ],
331
+ "properties": {
332
+ "retriable": {
333
+ "type": "boolean"
334
+ },
335
+ "description": {
336
+ "type": "string"
337
+ }
338
+ }
339
+ }
340
+ }
341
+ }