@geoly-ai/social-hub-sdk 0.0.45 → 0.0.46

package/dist/index.d.ts

@@ -513,6 +513,30 @@ export declare class RegistryProposalSdkError extends Error {
     constructor(status: number, code: string | undefined, staleCode: string | undefined, message: string);
     get isStale(): boolean;
 }
+/**
+ * Hub API 的结构化 HTTP 错误。
+ *
+ * `message` 保持与历史一致(`HTTP <status>: <message>`),所以既有 `catch (e) { e.message }`
+ * 的调用方不受影响；新增的 `status` / `code` / `details` 让调用方(尤其是要把服务端错误
+ * 映射成**退出码**的 CLI)不必 regex 解析 message。
+ *
+ * `retryAfterSeconds` 取自 `Retry-After` 响应头(仅当其为整数秒时)。
+ */
+export declare class SocialHubHttpError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    readonly retryAfterSeconds?: number;
+    readonly body?: string;
+    constructor(args: {
+        status: number;
+        message: string;
+        code?: string;
+        details?: unknown;
+        retryAfterSeconds?: number;
+        body?: string;
+    });
+}
 export declare class SocialHubClient {
     private readonly opts;
     constructor(opts: SocialHubClientOptions);
@@ -584,6 +608,19 @@ export declare class SocialHubClient {
         ok: boolean;
         warning?: string;
     }>;
+    /**
+     * 归属桶(teams.kind='bucket':未配置/外部)。这些团队没有 membership、不出现
+     * 在 `listTeams()` 里,所以外部来源帖要回填进桶就只能先从这里拿到 UUID,
+     * 再把它当 `teamId` 传给 createRedditPostSnapshot / batchUpsertRedditPostSnapshots。
+     */
+    listRedditPostTeamBuckets(): Promise<{
+        items: Array<{
+            id: string;
+            slug: string;
+            name: string;
+            kind: string;
+        }>;
+    }>;
     listRedditPostSnapshots(teamId: string, params?: ListRedditPostSnapshotsParams): Promise<{
         items: unknown[];
         total?: number;
@@ -2183,5 +2220,308 @@ export declare class SocialHubClient {
         count: number;
         runs: unknown[];
     }>;
+    private subscriptionsBase;
+    private eventsBase;
+    private sourcesBase;
+    /**
+     * GET .../notification-subscriptions
+     * 非 manager/admin 只看得到自己拥有(`ownerUserId`)的订阅 —— 别人机器的消费位点
+     * 露出来只会诱发误 ack。
+     */
+    listNotificationSubscriptions(teamId: string, params?: {
+        status?: NotificationSubscriptionStatus;
+        sourceId?: string;
+        /** 常驻消费方解析订阅名时传入，便于 Ctrl-C 立即中断。 */
+        signal?: AbortSignal;
+    }): Promise<{
+        items: NotificationSubscriptionDto[];
+    }>;
+    /** GET .../notification-subscriptions/:id —— 返回**裸** subscription（无包装）。 */
+    getNotificationSubscription(teamId: string, subscriptionId: string, 
+    /** 常驻消费方轮询游标时传入，便于 Ctrl-C 立即中断。 */
+    opts?: {
+        signal?: AbortSignal;
+    }): Promise<NotificationSubscriptionDto>;
+    /** POST .../notification-subscriptions（201，裸 subscription）。 */
+    createNotificationSubscription(teamId: string, body: CreateNotificationSubscriptionSdkBody): Promise<NotificationSubscriptionDto>;
+    /**
+     * PATCH .../notification-subscriptions/:id —— 乐观锁 CAS(`expectedRowVersion` 必填)。
+     * `status` 只能是 active|paused；pause/resume 另有语义化捷径端点（走同一把锁）。
+     */
+    updateNotificationSubscription(teamId: string, subscriptionId: string, body: UpdateNotificationSubscriptionSdkBody): Promise<NotificationSubscriptionDto>;
+    /**
+     * POST .../notification-subscriptions/:id/pause|resume。
+     * `expectedRowVersion` 可省（服务端用当前值），显式传则是真 CAS。
+     */
+    setNotificationSubscriptionPaused(teamId: string, subscriptionId: string, paused: boolean, body?: {
+        expectedRowVersion?: number;
+    }): Promise<NotificationSubscriptionDto>;
+    /** DELETE .../notification-subscriptions/:id —— 软删（保留审计），**204 无响应体**。 */
+    deleteNotificationSubscription(teamId: string, subscriptionId: string): Promise<void>;
+    /**
+     * POST .../notification-subscriptions/:id/reset —— 重设游标起点（stale 恢复的唯一出口）。
+     * `startPosition` 与 `cursorSeq` **互斥**；后者是运维手工修复面，服务端会 clamp 在
+     * `[floor - 1, latestSeq]`。reset 会 bump `receiptEpoch`，作废全部在途 receipt。
+     *
+     * ⚠️ `expectedRowVersion` **必填**：reset 是破坏性写，服务端做真 CAS，冲突返回
+     * `409 SUBSCRIPTION_ROW_VERSION_CONFLICT`。调用前先 GET 订阅拿当前 `rowVersion`。
+     *
+     * ⚠️ reset **不是** resume：`paused` 订阅 reset 后**仍是** paused；只有 `stale`
+     * 会被恢复成 `active`。
+     */
+    resetNotificationSubscriptionCursor(teamId: string, subscriptionId: string, body: {
+        expectedRowVersion: number;
+        startPosition?: NotificationSubscriptionStartPosition;
+        cursorSeq?: string;
+    }): Promise<NotificationSubscriptionDto>;
+    /**
+     * POST .../notification-events/pull —— long-poll 拉事件。**幂等**:不推进游标。
+     *
+     * `limit` 默认 1:游标是**连续 watermark**(`cursorSeq = N` 表示 seq ≤ N 的匹配事件均已完成),
+     * 一次拉 N 条却只在中间某条失败,就无法安全 ack 其后的任何一条。
+     */
+    pullNotificationEvents(teamId: string, body: {
+        subscriptionId: string;
+        /** 1..50,默认 1。 */
+        limit?: number;
+        /** 0..30 秒;0 = 立即返回(可能空)。 */
+        waitSeconds?: number;
+    }, 
+    /** long-poll 可能挂满 30 秒；常驻消费方必须能被 Ctrl-C 立即中断。 */
+    opts?: {
+        signal?: AbortSignal;
+    }): Promise<NotificationPullResponseDto>;
+    /**
+     * POST .../notification-events/ack —— 推进连续 watermark。
+     * 语义是「本订阅所有匹配事件中 seq ≤ throughSeq 的**均已完成**」,**不是**执行回执。
+     * 409 `SUBSCRIPTION_CURSOR_CONFLICT` = CAS 冲突(含重放);410 = 游标已过保留 floor。
+     */
+    ackNotificationCursor(teamId: string, body: {
+        subscriptionId: string;
+        expectedCursorSeq: string;
+        throughSeq: string;
+        receipt: NotificationPullReceiptDto;
+    }): Promise<{
+        subscriptionId: string;
+        cursorSeq: string;
+    }>;
+    /** GET .../notification-events —— 运维列表（**元数据摘要**，不含 payload）。 */
+    listNotificationEvents(teamId: string, params?: {
+        afterSeq?: string;
+        sourceId?: string;
+        limit?: number;
+    }): Promise<{
+        items: NotificationEventSummaryDto[];
+        latestSeq: string;
+        earliestAvailableSeq: string;
+    }>;
+    /** GET .../notification-events/:seq —— 单条完整 envelope（按事件行冻结的权限重验）。 */
+    getNotificationEventBySeq(teamId: string, seq: string): Promise<NotificationEventEnvelopeDto>;
+    /** GET .../notification-sources —— registry 声明 + 本 team 的 active config 摘要。 */
+    listNotificationSources(teamId: string): Promise<{
+        items: {
+            definition: unknown;
+            activeConfig: NotificationSourceConfigDto | null;
+        }[];
+    }>;
+    /** GET .../notification-sources/:sourceId/configs —— 该 source 的历史 version 列表。 */
+    listNotificationSourceConfigs(teamId: string, sourceId: string, params?: {
+        limit?: number;
+    }): Promise<{
+        items: NotificationSourceConfigDto[];
+    }>;
+    /** GET .../notification-sources/:sourceId/configs/:configId（裸 config）。 */
+    getNotificationSourceConfig(teamId: string, sourceId: string, configId: string): Promise<NotificationSourceConfigDto>;
+    /**
+     * POST .../notification-sources/:sourceId/configs —— 创建**新的不可变 version**
+     * （`activate` 默认 true；除 enabled 外任何变更都是新 version，只影响新物化的 schedule）。
+     * 409 `SOURCE_CONFIG_REQUIRED_FIELDS_CONFLICT` = 会打掉某些 active 订阅的 requiredFields。
+     */
+    createNotificationSourceConfig(teamId: string, sourceId: string, body: UpsertNotificationSourceConfigSdkBody, params?: {
+        activate?: boolean;
+    }): Promise<NotificationSourceConfigDto>;
+    /** POST .../notification-sources/:sourceId/configs/:configId/activate。 */
+    activateNotificationSourceConfig(teamId: string, sourceId: string, configId: string): Promise<NotificationSourceConfigDto>;
+    /**
+     * PUT .../notification-sources/:sourceId/enabled —— 实时 kill switch。
+     *
+     * 🔴 按 **sourceId 身份**而不是 version id：DB 语义是改 `(teamId, sourceId)` 下
+     * **全部历史 version 行**（在途 schedule 引用的是物化时那一行，只改 active 行 =
+     * 开关形同虚设）。本操作**不** bump sourceConfigVersion。
+     * disabled 期间到点的 schedule 标 `missed`，重新 enable **不补发**。
+     */
+    setNotificationSourceEnabled(teamId: string, sourceId: string, enabled: boolean): Promise<{
+        totalVersions: number;
+        updatedVersions: number;
+        enabled: boolean;
+    }>;
 }
+export type NotificationSubscriptionStatus = "active" | "paused"
+/** 游标落后于保留 floor,已无法保证不漏；需人工确认后 reset。 */
+ | "stale" | "deleted";
+export type NotificationSubscriptionStartPosition = "now" | "earliest";
+/** 同字段内多值 = OR,跨字段 = AND；空数组 = 不过滤该维度。 */
+export type NotificationFiltersDto = {
+    brandIds?: string[];
+    socialAccountIds?: string[];
+    subreddits?: string[];
+};
+export type NotificationSubscriptionDto = {
+    id: string;
+    teamId: string;
+    name: string;
+    sourceIds: string[];
+    filters: NotificationFiltersDto;
+    requiredFields: string[];
+    /** 匹配面(sourceIds/filters/requiredFields)变化时 +1。 */
+    filterVersion: number;
+    /** 「哪一代 pull 结果仍可推进游标」的身份;变了 → 在途 receipt 全部作废。 */
+    receiptEpoch: number;
+    /** 连续 watermark,十进制字符串。 */
+    cursorSeq: string;
+    /** 乐观锁,update DTO 的 CAS 用;**不进** receipt。 */
+    rowVersion: number;
+    startPosition: NotificationSubscriptionStartPosition;
+    status: NotificationSubscriptionStatus;
+    lastPulledAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** 服务端附加的归属信息（不在冻结契约里，仅供展示/排障）。 */
+    ownerUserId?: string | null;
+    isOwner?: boolean;
+    lastAckedAt?: string | null;
+    staleAt?: string | null;
+};
+/** `GET .../notification-events` 的运维摘要行（**不含 payload / includedFields**）。 */
+export type NotificationEventSummaryDto = {
+    eventId: string;
+    seq: string;
+    teamId: string;
+    sourceId: string;
+    canonicalTopic: string;
+    dedupeKey: string;
+    sourceConfigVersion: number;
+    fieldSetVersion: string;
+    payloadStatus: "active" | "expired";
+    maxSensitivity: string;
+    requiredPermissions: string[];
+    brandId: string | null;
+    socialAccountId: string | null;
+    subreddit: string | null;
+    occurredAt: string;
+    emittedAt: string;
+};
+export type CreateNotificationSubscriptionSdkBody = {
+    name: string;
+    /** **升序去重**(进 filterVersion 计算,不规范化会误伤在途 receipt)。 */
+    sourceIds: string[];
+    filters?: NotificationFiltersDto;
+    /** 「没有这些字段就别发给我」;必须 ⊆ 当前生效 config 的 configuredFields。 */
+    requiredFields?: string[];
+    /** 默认 `now`,避免新机器一上线被历史事件淹没。 */
+    startPosition?: NotificationSubscriptionStartPosition;
+};
+export type UpdateNotificationSubscriptionSdkBody = {
+    /** 必填:并发改配置时的 CAS。 */
+    expectedRowVersion: number;
+    name?: string;
+    sourceIds?: string[];
+    filters?: NotificationFiltersDto;
+    requiredFields?: string[];
+    /** pause/resume 就走这里(不能改成 stale/deleted)。 */
+    status?: "active" | "paused";
+};
+export type NotificationNodeSpecDto = {
+    key: string;
+    offsetSeconds: number;
+    maxLatenessSeconds: number;
+};
+export type UpsertNotificationSourceConfigSdkBody = {
+    sourceId: string;
+    nodes: NotificationNodeSpecDto[];
+    filters?: NotificationFiltersDto;
+    /** 只能勾 registry `optionalFields`;required 不可勾也不可取消。 */
+    selectedFields?: string[];
+    retentionDays?: number;
+    displayName: string;
+    /** 展示用,**不参与**路由/过滤/去重。 */
+    displayTopicLabel?: string | null;
+};
+export type NotificationSourceConfigDto = {
+    id: string;
+    teamId: string;
+    sourceId: string;
+    version: number;
+    enabled: boolean;
+    nodes: NotificationNodeSpecDto[];
+    filters: NotificationFiltersDto;
+    selectedFields: string[];
+    fieldSetVersion: string;
+    retentionDays: number;
+    displayName: string;
+    displayTopicLabel: string | null;
+    activatedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** 以下是服务端在冻结契约之外附加的只读字段（后台展示/排障用）。 */
+    isActive?: boolean;
+    supersededAt?: string | null;
+    sourceDefinitionVersion?: number;
+    payloadSchemaVersion?: string;
+    /** 配置级暴露政策（= fieldSetVersion 的哈希输入）。 */
+    configuredFields?: string[];
+    /** registry 推导的字段级 authz 并集（AND 语义），只读。 */
+    requiredPermissions?: string[];
+};
+/**
+ * 事件信封。四层版本 + `includedFields` 决定形状,消费方按 `payloadSchemaVersion` 分支;
+ * **遇到未知版本应拒绝处理但不 ack**(并打印 eventId/sourceId/payloadSchemaVersion)。
+ *
+ * `payloadStatus === "expired"` 是 **tombstone**:`payload` 为 null、`includedFields` 为空。
+ * 收到它**不得**当业务事件处理,但**必须**照常 ack —— 否则一条过期事件会把游标永久卡死。
+ */
+export type NotificationEventEnvelopeDto = {
+    eventId: string;
+    /** 十进制字符串(bigint)。 */
+    seq: string;
+    teamId: string;
+    sourceId: string;
+    canonicalTopic: string;
+    /** agent 侧幂等键(**不是** seq —— seq 只表示顺序)。 */
+    dedupeKey: string;
+    envelopeVersion: number;
+    sourceDefinitionVersion: number;
+    payloadSchemaVersion: string;
+    sourceConfigVersion: number;
+    fieldSetVersion: string;
+    occurredAt: string;
+    emittedAt: string;
+    payloadStatus: "active" | "expired";
+    includedFields: string[];
+    payload: Record<string, unknown> | null;
+};
+/** 不落库的签名凭据;ack 必须原样回传**整个对象**(不只是 signature)。 */
+export type NotificationPullReceiptDto = {
+    subscriptionId: string;
+    fromCursorSeq: string;
+    maxDeliveredSeq: string;
+    filterVersion: number;
+    receiptEpoch: number;
+    expiresAt: string;
+    signature: string;
+};
+export type NotificationPullResponseDto = {
+    /** 严格按 seq 升序的 `seq > cursorSeq` 前 N 条匹配事件。 */
+    events: NotificationEventEnvelopeDto[];
+    receipt: NotificationPullReceiptDto;
+    /** = receipt.fromCursorSeq。 */
+    cursorSeq: string;
+    /** 流末尾,供 agent 估算落后量;不参与任何校验。 */
+    latestSeq: string;
+};
+/**
+ * 十进制 seq 字符串的数值比较(BigInt,不走 Number —— 53 bit 之后会静默丢精度)。
+ * 与 contracts `compareNotificationSeq` 同口径;SDK 侧复刻是因为不能引 contracts。
+ */
+export declare function compareNotificationSeqStrings(left: string, right: string): number;
 //# sourceMappingURL=index.d.ts.map