@morehao/trendradar-contract 0.7.1 → 0.8.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/CHANGELOG.md CHANGED
@@ -3,6 +3,29 @@
3
3
  All notable changes to `@morehao/trendradar-contract` are documented here.
4
4
  This project adheres to a `contract/vX.Y.Z` tag per release (npm + Go submodule).
5
5
 
6
+ ## 0.8.0
7
+
8
+ Additive, non-breaking. `RunResult` gains an optional `notify` report so the
9
+ plugin can surface the notification stage (what was sent, to which channels, and
10
+ how each fared) without re-deriving it. Wire integers unchanged
11
+ (`ipcSchema=4`, `digestSchema=3`).
12
+
13
+ ### Added
14
+ - `RunResult.notify?: NotifyReport` — present when a run went through the
15
+ notification stage; consumers that do not know it simply ignore it. Optional
16
+ and additive.
17
+ - `NotifyReport` (`$defs`) — `{ enabled, attempted, skipReason?, messages[], usage? }`.
18
+ `enabled`/`attempted`/`messages` are required; `skipReason` (string) explains
19
+ why an enabled stage did not attempt delivery; `usage?` carries
20
+ `{ calls?, totalTokens?, usageKnown? }` for the notification span when known.
21
+ - `NotifyMessage` (`$defs`) — `{ kind, period?, bodyChars, summarySource, channels[] }`.
22
+ `kind` is `trending` / `releases`; `period` is `daily` / `weekly` / `monthly`;
23
+ `bodyChars` is the rendered body length; `summarySource` is `model` / `fallback`;
24
+ `channels` holds one `NotifyChannelResult` per channel.
25
+ - `NotifyChannelResult` (`$defs`) — `{ channel, status, durationMs?, error? }`.
26
+ `status` is `sent` / `failed` / `disabled`; `durationMs` and `error` are
27
+ present only when relevant.
28
+
6
29
  ## 0.7.1
7
30
 
8
31
  Additive, non-breaking. `Usage` gains two optional fields so the plugin can
package/gen/ts/index.d.ts CHANGED
@@ -74,6 +74,7 @@ export interface RunResult {
74
74
  "error"?: ErrorInfo;
75
75
  "warnings"?: Array<string>;
76
76
  "usage"?: Usage;
77
+ "notify"?: NotifyReport;
77
78
  "releases"?: ReleasesReport;
78
79
  "subscriptions"?: SubscriptionList;
79
80
  "subscriptionDoc"?: SubscriptionDoc;
@@ -95,6 +96,32 @@ export interface Usage {
95
96
  [k: string]: unknown;
96
97
  }
97
98
 
99
+ export interface NotifyChannelResult {
100
+ "channel": string;
101
+ "status": "sent" | "failed" | "disabled";
102
+ "durationMs"?: number;
103
+ "error"?: string;
104
+ [k: string]: unknown;
105
+ }
106
+
107
+ export interface NotifyMessage {
108
+ "kind": "trending" | "releases";
109
+ "period"?: "daily" | "weekly" | "monthly";
110
+ "bodyChars": number;
111
+ "summarySource": "model" | "fallback";
112
+ "channels": Array<NotifyChannelResult>;
113
+ [k: string]: unknown;
114
+ }
115
+
116
+ export interface NotifyReport {
117
+ "enabled": boolean;
118
+ "attempted": boolean;
119
+ "skipReason"?: string;
120
+ "messages": Array<NotifyMessage>;
121
+ "usage"?: { [k: string]: unknown };
122
+ [k: string]: unknown;
123
+ }
124
+
98
125
  export interface StateRun {
99
126
  "date": string;
100
127
  "contentHash": string;
package/gen/ts/index.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import Ajv from 'ajv/dist/2020.js'
3
3
  import addFormats from 'ajv-formats'
4
4
 
5
- export const contractVersion = "0.7.1"
5
+ export const contractVersion = "0.8.0"
6
6
 
7
7
  export const errorCatalog = {
8
8
  "INTERNAL": {
@@ -1566,6 +1566,9 @@ const ipc = {
1566
1566
  "usage": {
1567
1567
  "$ref": "#/$defs/Usage"
1568
1568
  },
1569
+ "notify": {
1570
+ "$ref": "#/$defs/NotifyReport"
1571
+ },
1569
1572
  "releases": {
1570
1573
  "$ref": "releases.v3.json#/$defs/ReleasesReport"
1571
1574
  },
@@ -1637,6 +1640,125 @@ const ipc = {
1637
1640
  }
1638
1641
  }
1639
1642
  },
1643
+ "NotifyChannelResult": {
1644
+ "type": "object",
1645
+ "additionalProperties": true,
1646
+ "description": "The delivery outcome for one notification channel of one message.",
1647
+ "required": [
1648
+ "channel",
1649
+ "status"
1650
+ ],
1651
+ "properties": {
1652
+ "channel": {
1653
+ "type": "string"
1654
+ },
1655
+ "status": {
1656
+ "type": "string",
1657
+ "enum": [
1658
+ "sent",
1659
+ "failed",
1660
+ "disabled"
1661
+ ]
1662
+ },
1663
+ "durationMs": {
1664
+ "type": "integer",
1665
+ "minimum": 0
1666
+ },
1667
+ "error": {
1668
+ "type": "string"
1669
+ }
1670
+ }
1671
+ },
1672
+ "NotifyMessage": {
1673
+ "type": "object",
1674
+ "additionalProperties": true,
1675
+ "description": "One rendered notification message and how each of its channels fared.",
1676
+ "required": [
1677
+ "kind",
1678
+ "bodyChars",
1679
+ "summarySource",
1680
+ "channels"
1681
+ ],
1682
+ "properties": {
1683
+ "kind": {
1684
+ "type": "string",
1685
+ "enum": [
1686
+ "trending",
1687
+ "releases"
1688
+ ]
1689
+ },
1690
+ "period": {
1691
+ "type": "string",
1692
+ "enum": [
1693
+ "daily",
1694
+ "weekly",
1695
+ "monthly"
1696
+ ]
1697
+ },
1698
+ "bodyChars": {
1699
+ "type": "integer",
1700
+ "minimum": 0
1701
+ },
1702
+ "summarySource": {
1703
+ "type": "string",
1704
+ "enum": [
1705
+ "model",
1706
+ "fallback"
1707
+ ]
1708
+ },
1709
+ "channels": {
1710
+ "type": "array",
1711
+ "items": {
1712
+ "$ref": "#/$defs/NotifyChannelResult"
1713
+ }
1714
+ }
1715
+ }
1716
+ },
1717
+ "NotifyReport": {
1718
+ "type": "object",
1719
+ "additionalProperties": true,
1720
+ "description": "Summary of the notification stage of a run: whether it ran, which messages it produced, and the per-channel delivery outcomes. Optional and additive on RunResult.",
1721
+ "required": [
1722
+ "enabled",
1723
+ "attempted",
1724
+ "messages"
1725
+ ],
1726
+ "properties": {
1727
+ "enabled": {
1728
+ "type": "boolean"
1729
+ },
1730
+ "attempted": {
1731
+ "type": "boolean"
1732
+ },
1733
+ "skipReason": {
1734
+ "type": "string"
1735
+ },
1736
+ "messages": {
1737
+ "type": "array",
1738
+ "items": {
1739
+ "$ref": "#/$defs/NotifyMessage"
1740
+ }
1741
+ },
1742
+ "usage": {
1743
+ "type": "object",
1744
+ "additionalProperties": true,
1745
+ "description": "Model usage attributable to the notification stage, when known.",
1746
+ "properties": {
1747
+ "calls": {
1748
+ "type": "integer",
1749
+ "minimum": 0
1750
+ },
1751
+ "totalTokens": {
1752
+ "type": "integer",
1753
+ "minimum": 0
1754
+ },
1755
+ "usageKnown": {
1756
+ "type": "boolean"
1757
+ }
1758
+ }
1759
+ }
1760
+ }
1761
+ },
1640
1762
  "StateRun": {
1641
1763
  "type": "object",
1642
1764
  "additionalProperties": true,
@@ -2557,7 +2679,7 @@ const errors = {
2557
2679
  }
2558
2680
  }
2559
2681
  }
2560
- const api = "openapi: 3.1.0\ninfo:\n title: trendradar serve API\n version: 0.7.1\n description: |\n Read-only HTTP surface exposed by `trendradar serve`. All payloads reuse the\n contract schemas, so the plugin and any web UI consume the same shapes\n whether data comes from the filesystem or over HTTP. Historical v1 digests\n read from disk are normalized to the v2 shape with\n contentHashAlgo=legacy-struct-marshal-v1.\n\n Release endpoints are read-only. Token cost for a releases run is NOT part of\n a stored document (it describes one run and cannot be reproduced); it is\n reported in `releases.usage` of `trendradar run --json` and appended to\n `<repo>/.git/trendradar-usage.jsonl` with stage=\"releases\".\nservers:\n - url: http://127.0.0.1:8787\npaths:\n /api/v2/digests/{date}:\n get:\n operationId: getDigest\n summary: Fetch one day's digest\n parameters:\n - name: date\n in: path\n required: true\n schema:\n type: string\n format: date\n responses:\n \"200\":\n description: The digest document\n content:\n application/json:\n schema:\n $ref: \"./digest.v2.json\"\n \"404\":\n description: No digest for that date\n /api/v2/manifest:\n get:\n operationId: getManifest\n summary: List available dates and their content identity\n responses:\n \"200\":\n description: Manifest of available digests\n content:\n application/json:\n schema:\n type: object\n required: [entries]\n properties:\n coreVersion:\n type: string\n entries:\n type: array\n items:\n type: object\n required: [date, contentHash, schema, contentHashAlgo]\n properties:\n date:\n type: string\n format: date\n contentHash:\n type: string\n schema:\n type: integer\n contentHashAlgo:\n type: string\n enum: [jcs-sha256-v1, legacy-struct-marshal-v1]\n degraded:\n type: boolean\n /api/v2/releases:\n get:\n operationId: listReleases\n summary: List available release digests (newest first)\n description: |\n Returns an empty array (not 404) when no release digest exists yet.\n Entries carry no token cost because stored documents do not record it.\n parameters:\n - name: period\n in: query\n required: false\n schema:\n type: string\n enum: [daily, weekly, monthly]\n responses:\n \"200\":\n description: Manifest of release digests\n content:\n application/json:\n schema:\n type: array\n items:\n $ref: \"./releases.v2.json#/$defs/ReleaseManifestEntry\"\n /api/v2/releases/{date}:\n get:\n operationId: getReleases\n summary: Fetch one period's release digest\n parameters:\n - name: date\n in: path\n required: true\n schema:\n type: string\n format: date\n - name: period\n in: query\n required: false\n schema:\n type: string\n enum: [daily, weekly, monthly]\n responses:\n \"200\":\n description: The release digest document\n content:\n application/json:\n schema:\n $ref: \"./releases.v2.json\"\n \"404\":\n description: No release digest for that date\n /api/v2/subscriptions:\n get:\n operationId: listSubscriptions\n summary: List the repo subscriptions the core will poll\n description: |\n Read-only mirror of the IPC `subscribe list` command: both return the\n same SubscriptionList. `repos` is the legacy field; `items` adds the\n per-repo row detail (latest tag, last summary date, check status) and is\n optional, so an older core still satisfies this schema. Writing\n subscriptions stays on the CLI / IPC subscribe command and is never\n exposed over HTTP.\n responses:\n \"200\":\n description: Current subscription list\n content:\n application/json:\n schema:\n $ref: \"./releases.v2.json#/$defs/SubscriptionList\"\n /api/v2/repos/{owner}/{repo}/releases:\n get:\n operationId: getSubscriptionDoc\n summary: Read one repo's release document\n description: |\n Read-only mirror of the IPC `subscribe releases` command. Returns the\n exact markdown file content (plus the volume index) so a client renders\n what the data repo stores instead of re-summarizing it. `volume`\n defaults to the newest volume. Only repos matching\n ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ are served: the path is resolved\n inside the releases document root and never escapes it.\n parameters:\n - name: owner\n in: path\n required: true\n schema:\n type: string\n pattern: \"^[A-Za-z0-9_.-]+$\"\n - name: repo\n in: path\n required: true\n schema:\n type: string\n pattern: \"^[A-Za-z0-9_.-]+$\"\n - name: volume\n in: query\n required: false\n schema:\n type: integer\n minimum: 1\n responses:\n \"200\":\n description: The repo's release document\n content:\n application/json:\n schema:\n $ref: \"./releases.v2.json#/$defs/SubscriptionDoc\"\n \"400\":\n description: Malformed owner/repo or non-positive volume\n \"404\":\n description: The repo has no release document, or that volume is absent\n /feed.xml:\n get:\n operationId: getFeed\n summary: RSS feed of the most recent digests\n responses:\n \"200\":\n description: RSS 2.0 feed\n content:\n application/rss+xml:\n schema:\n type: string\n"
2682
+ const api = "openapi: 3.1.0\ninfo:\n title: trendradar serve API\n version: 0.8.0\n description: |\n Read-only HTTP surface exposed by `trendradar serve`. All payloads reuse the\n contract schemas, so the plugin and any web UI consume the same shapes\n whether data comes from the filesystem or over HTTP. Historical v1 digests\n read from disk are normalized to the v2 shape with\n contentHashAlgo=legacy-struct-marshal-v1.\n\n Release endpoints are read-only. Token cost for a releases run is NOT part of\n a stored document (it describes one run and cannot be reproduced); it is\n reported in `releases.usage` of `trendradar run --json` and appended to\n `<repo>/.git/trendradar-usage.jsonl` with stage=\"releases\".\nservers:\n - url: http://127.0.0.1:8787\npaths:\n /api/v2/digests/{date}:\n get:\n operationId: getDigest\n summary: Fetch one day's digest\n parameters:\n - name: date\n in: path\n required: true\n schema:\n type: string\n format: date\n responses:\n \"200\":\n description: The digest document\n content:\n application/json:\n schema:\n $ref: \"./digest.v2.json\"\n \"404\":\n description: No digest for that date\n /api/v2/manifest:\n get:\n operationId: getManifest\n summary: List available dates and their content identity\n responses:\n \"200\":\n description: Manifest of available digests\n content:\n application/json:\n schema:\n type: object\n required: [entries]\n properties:\n coreVersion:\n type: string\n entries:\n type: array\n items:\n type: object\n required: [date, contentHash, schema, contentHashAlgo]\n properties:\n date:\n type: string\n format: date\n contentHash:\n type: string\n schema:\n type: integer\n contentHashAlgo:\n type: string\n enum: [jcs-sha256-v1, legacy-struct-marshal-v1]\n degraded:\n type: boolean\n /api/v2/releases:\n get:\n operationId: listReleases\n summary: List available release digests (newest first)\n description: |\n Returns an empty array (not 404) when no release digest exists yet.\n Entries carry no token cost because stored documents do not record it.\n parameters:\n - name: period\n in: query\n required: false\n schema:\n type: string\n enum: [daily, weekly, monthly]\n responses:\n \"200\":\n description: Manifest of release digests\n content:\n application/json:\n schema:\n type: array\n items:\n $ref: \"./releases.v2.json#/$defs/ReleaseManifestEntry\"\n /api/v2/releases/{date}:\n get:\n operationId: getReleases\n summary: Fetch one period's release digest\n parameters:\n - name: date\n in: path\n required: true\n schema:\n type: string\n format: date\n - name: period\n in: query\n required: false\n schema:\n type: string\n enum: [daily, weekly, monthly]\n responses:\n \"200\":\n description: The release digest document\n content:\n application/json:\n schema:\n $ref: \"./releases.v2.json\"\n \"404\":\n description: No release digest for that date\n /api/v2/subscriptions:\n get:\n operationId: listSubscriptions\n summary: List the repo subscriptions the core will poll\n description: |\n Read-only mirror of the IPC `subscribe list` command: both return the\n same SubscriptionList. `repos` is the legacy field; `items` adds the\n per-repo row detail (latest tag, last summary date, check status) and is\n optional, so an older core still satisfies this schema. Writing\n subscriptions stays on the CLI / IPC subscribe command and is never\n exposed over HTTP.\n responses:\n \"200\":\n description: Current subscription list\n content:\n application/json:\n schema:\n $ref: \"./releases.v2.json#/$defs/SubscriptionList\"\n /api/v2/repos/{owner}/{repo}/releases:\n get:\n operationId: getSubscriptionDoc\n summary: Read one repo's release document\n description: |\n Read-only mirror of the IPC `subscribe releases` command. Returns the\n exact markdown file content (plus the volume index) so a client renders\n what the data repo stores instead of re-summarizing it. `volume`\n defaults to the newest volume. Only repos matching\n ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ are served: the path is resolved\n inside the releases document root and never escapes it.\n parameters:\n - name: owner\n in: path\n required: true\n schema:\n type: string\n pattern: \"^[A-Za-z0-9_.-]+$\"\n - name: repo\n in: path\n required: true\n schema:\n type: string\n pattern: \"^[A-Za-z0-9_.-]+$\"\n - name: volume\n in: query\n required: false\n schema:\n type: integer\n minimum: 1\n responses:\n \"200\":\n description: The repo's release document\n content:\n application/json:\n schema:\n $ref: \"./releases.v2.json#/$defs/SubscriptionDoc\"\n \"400\":\n description: Malformed owner/repo or non-positive volume\n \"404\":\n description: The repo has no release document, or that volume is absent\n /feed.xml:\n get:\n operationId: getFeed\n summary: RSS feed of the most recent digests\n responses:\n \"200\":\n description: RSS 2.0 feed\n content:\n application/rss+xml:\n schema:\n type: string\n"
2561
2683
 
2562
2684
  export const rawSchema = { model, ipc, digest, releases, errors, versionInfo, api }
2563
2685
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@morehao/trendradar-contract",
3
- "version": "0.7.1",
3
+ "version": "0.8.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",
@@ -1,7 +1,7 @@
1
1
  openapi: 3.1.0
2
2
  info:
3
3
  title: trendradar serve API
4
- version: 0.7.1
4
+ version: 0.8.0
5
5
  description: |
6
6
  Read-only HTTP surface exposed by `trendradar serve`. All payloads reuse the
7
7
  contract schemas, so the plugin and any web UI consume the same shapes
@@ -464,6 +464,9 @@
464
464
  "usage": {
465
465
  "$ref": "#/$defs/Usage"
466
466
  },
467
+ "notify": {
468
+ "$ref": "#/$defs/NotifyReport"
469
+ },
467
470
  "releases": {
468
471
  "$ref": "releases.v3.json#/$defs/ReleasesReport"
469
472
  },
@@ -535,6 +538,125 @@
535
538
  }
536
539
  }
537
540
  },
541
+ "NotifyChannelResult": {
542
+ "type": "object",
543
+ "additionalProperties": true,
544
+ "description": "The delivery outcome for one notification channel of one message.",
545
+ "required": [
546
+ "channel",
547
+ "status"
548
+ ],
549
+ "properties": {
550
+ "channel": {
551
+ "type": "string"
552
+ },
553
+ "status": {
554
+ "type": "string",
555
+ "enum": [
556
+ "sent",
557
+ "failed",
558
+ "disabled"
559
+ ]
560
+ },
561
+ "durationMs": {
562
+ "type": "integer",
563
+ "minimum": 0
564
+ },
565
+ "error": {
566
+ "type": "string"
567
+ }
568
+ }
569
+ },
570
+ "NotifyMessage": {
571
+ "type": "object",
572
+ "additionalProperties": true,
573
+ "description": "One rendered notification message and how each of its channels fared.",
574
+ "required": [
575
+ "kind",
576
+ "bodyChars",
577
+ "summarySource",
578
+ "channels"
579
+ ],
580
+ "properties": {
581
+ "kind": {
582
+ "type": "string",
583
+ "enum": [
584
+ "trending",
585
+ "releases"
586
+ ]
587
+ },
588
+ "period": {
589
+ "type": "string",
590
+ "enum": [
591
+ "daily",
592
+ "weekly",
593
+ "monthly"
594
+ ]
595
+ },
596
+ "bodyChars": {
597
+ "type": "integer",
598
+ "minimum": 0
599
+ },
600
+ "summarySource": {
601
+ "type": "string",
602
+ "enum": [
603
+ "model",
604
+ "fallback"
605
+ ]
606
+ },
607
+ "channels": {
608
+ "type": "array",
609
+ "items": {
610
+ "$ref": "#/$defs/NotifyChannelResult"
611
+ }
612
+ }
613
+ }
614
+ },
615
+ "NotifyReport": {
616
+ "type": "object",
617
+ "additionalProperties": true,
618
+ "description": "Summary of the notification stage of a run: whether it ran, which messages it produced, and the per-channel delivery outcomes. Optional and additive on RunResult.",
619
+ "required": [
620
+ "enabled",
621
+ "attempted",
622
+ "messages"
623
+ ],
624
+ "properties": {
625
+ "enabled": {
626
+ "type": "boolean"
627
+ },
628
+ "attempted": {
629
+ "type": "boolean"
630
+ },
631
+ "skipReason": {
632
+ "type": "string"
633
+ },
634
+ "messages": {
635
+ "type": "array",
636
+ "items": {
637
+ "$ref": "#/$defs/NotifyMessage"
638
+ }
639
+ },
640
+ "usage": {
641
+ "type": "object",
642
+ "additionalProperties": true,
643
+ "description": "Model usage attributable to the notification stage, when known.",
644
+ "properties": {
645
+ "calls": {
646
+ "type": "integer",
647
+ "minimum": 0
648
+ },
649
+ "totalTokens": {
650
+ "type": "integer",
651
+ "minimum": 0
652
+ },
653
+ "usageKnown": {
654
+ "type": "boolean"
655
+ }
656
+ }
657
+ }
658
+ }
659
+ },
538
660
  "StateRun": {
539
661
  "type": "object",
540
662
  "additionalProperties": true,
package/version-map.json CHANGED
@@ -26,14 +26,14 @@
26
26
  },
27
27
  "version-info.v2.json": {
28
28
  "wireKey": "contractVersion",
29
- "current": "0.7.1",
29
+ "current": "0.8.0",
30
30
  "breakingBump": [
31
31
  "packageMajor"
32
32
  ]
33
33
  },
34
34
  "api.v2.yaml": {
35
35
  "wireKey": "info.version",
36
- "current": "0.7.1",
36
+ "current": "0.8.0",
37
37
  "breakingBump": [
38
38
  "packageMajor"
39
39
  ]