@geoly-ai/social-hub-cli 0.3.4 → 0.3.6

package/dist/register-notify.d.ts

@@ -0,0 +1,172 @@
+import type { Command } from "commander";
+import { type NotificationPullReceiptDto, type NotificationPullResponseDto, type NotificationSubscriptionDto, type SocialHubClient } from "@geoly-ai/social-hub-sdk";
+/**
+ * `social-hub notify …` —— 事件订阅通知的消费面（设计见
+ * `docs/notification-event-subscription-design.md`，契约见
+ * `packages/contracts/src/notifications.ts`）。
+ *
+ * 使用场景：用户自己机器上的 agent 从 Hub 拉「帖子发布后 2h/6h/24h/2d/7d」这类节点事件，
+ * 拿到后自己去开浏览器截图、发飞书群。**Hub 只通知，完全不管执行**。因此本命令组的设计
+ * 目标是「AI agent 的工具调用」：机器友好 + 崩溃可恢复。
+ *
+ * ## 五条不可协商的形态约束
+ *
+ * 1. **默认 `--limit 1`**（不是 20）。没有 delivery 表，ack 是**连续 watermark** 而不是
+ *    单条确认：`cursorSeq = N` 表示该订阅所有匹配事件中 `seq ≤ N` 的**均已完成**。
+ *    一次拉 20 条、第 5 条失败，后面 15 条就再也无法安全 ack。
+ * 2. **`--follow` 的背压固定为 maxUnacked=1**：输出一条后轮询自己的 subscription，
+ *    等 `cursorSeq >= pendingSeq` 才拉下一条。`--follow` 是便利模式，**不是新的消费协议**。
+ * 3. **不提供 `--auto-ack`**。CLI 写完 stdout 不代表下游 agent 已经截完图、发完飞书；
+ *    此时崩溃事件就丢了。ack 必须由真正完成副作用的一方显式发起。
+ * 4. **只原样输出，绝不「补齐」缺失字段**。envelope 带四层版本 + `includedFields`，
+ *    形状随配置变化是设计不是 bug。
+ * 5. **`seq` 全程字符串**（bigint）。任何 `Number(seq)` 都是精度炸弹；比较走
+ *    {@link compareNotificationSeqStrings}（BigInt）。
+ *
+ * ## 退出码矩阵（脚本/supervisor 据此分流）
+ *
+ * | 码 | 含义 |
+ * | -- | ---- |
+ * | 0 | 成功（含「无消息」、`--follow` 被 SIGINT/SIGTERM 正常中断） |
+ * | 1 | 参数 / 鉴权 / 权限 / 协议错误，或服务端**非重试**错误（含 pull 的 410 stale） |
+ * | 2 | 可重试的网络 / 服务不可用；或 `--fail-if-empty` 且无消息 |
+ * | 3 | ack 的 cursor / receipt 冲突（409 CAS 冲突、410 游标过期） |
+ * | 4 | **保留**：未来批量操作部分成功。Phase 1 不产生该退出码 |
+ */
+export declare const NOTIFY_EXIT: {
+    readonly OK: 0;
+    /** 参数/鉴权/权限/协议或服务端非重试错误。 */
+    readonly FATAL: 1;
+    /** 可重试的网络/服务不可用，或 --fail-if-empty 且无消息。 */
+    readonly RETRYABLE: 2;
+    /** ack 的 cursor/receipt 冲突（409/410）。 */
+    readonly CURSOR_CONFLICT: 3;
+    /** 保留：批量操作部分成功（Phase 1 不产生）。 */
+    readonly PARTIAL: 4;
+};
+export type NotifyExitCode = (typeof NOTIFY_EXIT)[keyof typeof NOTIFY_EXIT];
+/**
+ * 可重试的 HTTP 状态：超时/过早/限流/服务端故障。
+ * 4xx 里只有 408 / 425 / 429 是「等一会儿再来」，其余都是调用方自己的问题。
+ */
+export declare function isRetryableStatus(status: number): boolean;
+/** 传输层失败（DNS / 连接拒绝 / socket 断开 / TLS）——一律当可重试。 */
+export declare function isNetworkError(e: unknown): boolean;
+export type NotifyPhase = "pull" | "ack" | "admin";
+export type NotifyErrorClassification = {
+    exitCode: NotifyExitCode;
+    /** true = `--follow` 应退避重试而不是退出。 */
+    retryable: boolean;
+    status?: number;
+    code?: string;
+    message: string;
+    details?: unknown;
+    retryAfterSeconds?: number;
+    /** 给 agent 的下一步动作提示（stderr 上打印）。 */
+    hint?: string;
+};
+/**
+ * 把任意错误映射成退出码。
+ *
+ * 关键取舍：
+ *   - **pull 的 410（`SUBSCRIPTION_CURSOR_EXPIRED`）判 1 而不是 2**。它需要人工确认后
+ *     `notify subscriptions reset`；若判成「可重试」，supervisor 会对同一个 stale 订阅
+ *     无限重启。
+ *   - **ack 的 409 与 410 都判 3**，方便调用方统一进入「游标恢复分支」；具体动作靠
+ *     stderr 里的 `code` 区分（409 → 重读订阅/重新 pull 拿新 receipt；410 → 人工 reset）。
+ *   - **`PULL_RECEIPT_INVALID` 判 1**：签名/epoch/filterVersion 已变，重试同一 receipt
+ *     永远不会成功，必须重新 pull。
+ */
+export declare function classifyNotifyError(e: unknown, phase: NotifyPhase): NotifyErrorClassification;
+/**
+ * receipt sidecar 的形状。
+ *
+ * **为什么必须有它**：JSON Lines 模式下 stdout 只能出 envelope，而 envelope 里**没有**
+ * receipt；ack 又要求回传**整个 receipt 对象**（不只是 signature）。没有 sidecar，
+ * `--format jsonl` 拉到的事件就是永远无法 ack 的死事件。
+ */
+export type NotifyReceiptSidecar = {
+    subscriptionId: string;
+    /** ack 时的 `expectedCursorSeq`（= receipt.fromCursorSeq）。 */
+    cursorSeq: string;
+    /** ack 时的 `throughSeq`（= 本批最后一条事件的 seq）。 */
+    throughSeq: string;
+    /** 本批事件的 eventId（便于 agent 对账；不参与 ack 校验）。 */
+    eventIds: string[];
+    receipt: NotificationPullReceiptDto;
+};
+export declare function buildReceiptSidecar(res: NotificationPullResponseDto): NotifyReceiptSidecar | null;
+/**
+ * 原子落盘：先写临时文件再 rename，避免 agent 读到半截 JSON。
+ * 权限 0600 —— receipt 是签名凭据，虽有 TTL 但不该对同机其它用户可读。
+ */
+export declare function writeReceiptSidecarAtomically(path: string, sidecar: NotifyReceiptSidecar): void;
+/** 指数退避 + ±20% 抖动，封顶 maxMs。 */
+export declare function nextBackoffMs(attempt: number, baseMs: number, maxMs: number, rand?: () => number): number;
+/**
+ * `--subscription` 收 name 或 uuid。
+ *
+ * SDK 侧**只认 uuid**（pull/ack 是消费热路径，不该藏一次隐式 list）；name 解析是 CLI
+ * 的便利层，且 `--follow` 只在启动时解析一次。
+ */
+export declare function resolveSubscription(client: SocialHubClient, teamId: string, ref: string, 
+/** `--follow` 启动期解析也必须能被 Ctrl-C 打断，否则要一直等到网络超时。 */
+signal?: AbortSignal): Promise<NotificationSubscriptionDto>;
+export type CursorWaitDecision = {
+    kind: "advanced";
+} | {
+    kind: "wait";
+} | {
+    kind: "abort";
+    reason: string;
+    hint: string;
+};
+/**
+ * `--follow` 每轮 GET subscription 后的判定。
+ *
+ * 只比 cursor 是不够的 —— 下列情形会让「等 cursor 推进」永久挂死，必须当场退出：
+ *   - `paused` / `stale` / `deleted`：这些状态下 ack 根本不会成功；
+ *   - `receiptEpoch` / `filterVersion` 变了而 cursor 还没越过 pendingSeq：
+ *     在途 receipt 已作废（reset / 改 filter / 权限变化），这条事件再也 ack 不上去。
+ *
+ * cursor 已越过 pendingSeq 视为**已被别处推进**，直接继续下一轮，**不重复输出**该事件。
+ */
+export declare function evaluateCursorWait(args: {
+    subscription: NotificationSubscriptionDto;
+    pendingSeq: string;
+    receiptEpoch: number;
+    filterVersion: number;
+}): CursorWaitDecision;
+/** 逗号分隔列表 → 去重 + ASCII 升序（契约要求 sourceIds / 字段路径升序去重）。 */
+export declare function parseSortedList(raw: string | undefined): string[] | undefined;
+export declare function registerNotifyCommands(program: Command): void;
+/** 组装 create 请求体：`-j/--json` 整体覆盖，否则由扁平参数拼（并做升序去重规范化）。 */
+export declare function buildCreateSubscriptionBody(opts: {
+    name?: string;
+    source?: string[];
+    start?: string;
+    requireFields?: string;
+    filterBrand?: string;
+    filterAccount?: string;
+    filterSubreddit?: string;
+    json?: string;
+    jsonFile?: string;
+}): {
+    name: string;
+    sourceIds: string[];
+    filters?: Record<string, string[]>;
+    requiredFields?: string[];
+    startPosition?: "now" | "earliest";
+};
+/**
+ * `--receipt` / `--receipt-file` 收两种形状：
+ *   - sidecar（`{subscriptionId, cursorSeq, throughSeq, receipt}`，`notify pull --receipt-file` 产出）
+ *   - 裸 receipt（`{subscriptionId, fromCursorSeq, …, signature}`）
+ * 两者都接受，agent 不必自己拆包。
+ */
+export declare function extractAckInput(raw: unknown): {
+    receipt: NotificationPullReceiptDto;
+    cursorSeq?: string;
+    throughSeq?: string;
+};
+//# sourceMappingURL=register-notify.d.ts.map

package/dist/register-notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-notify.d.ts","sourceRoot":"","sources":["../src/register-notify.ts"],"names":[],"mappings":"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"}