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

package/dist/index.d.ts

@@ -283,6 +283,103 @@ export type ScheduleCommentDraftBody = {
     runAt: string;
     windowMinutes?: number;
 };
+export type DeliveryBundleStatusLike = "open" | "closed" | "cancelled";
+/** 客户面列 bundle:brandId 服务端**必填**(客户按 brand 收窄);SDK 类型强制。 */
+export type ListClientDeliveryBundlesParams = {
+    brandId: string;
+    status?: DeliveryBundleStatusLike;
+    limit?: number;
+    offset?: number;
+};
+/** staff 建 bundle。 */
+export type CreateClientDeliveryBundleBody = {
+    brandId: string;
+    bundleCode: string;
+    name: string;
+    clientDueAt?: string | null;
+};
+/** staff upsert item(帖/评 + 矩阵规划字段)。 */
+export type UpsertClientDeliveryItemBody = {
+    kind: "post" | "comment";
+    itemCode: string;
+    contentDraftId?: string | null;
+    commentDraftId?: string | null;
+    ordinal?: number;
+    boundProductId?: string | null;
+    primaryPostType?: string[] | null;
+    writingVariant?: string | null;
+    structureFamily?: string | null;
+    contentFunction?: string | null;
+    functionDetail?: string | null;
+    brandEntryMode?: string | null;
+    anchorSlot?: string | null;
+    mappingRuleId?: string | null;
+    vocabularyVersion?: string | null;
+};
+/** staff 送审 revision(note 可选)。 */
+export type SubmitClientDeliveryRevisionBody = {
+    note?: string;
+};
+export type ClientDeliveryInventoryStatus = "in_stock" | "low_stock" | "out_of_stock" | "preorder" | "discontinued" | "unknown";
+/** 产品事实版本 body(客户面:正文/draft 字段物理不接受;仅事实)。 */
+export type ClientDeliveryFactVersionBody = {
+    positioning?: string | null;
+    materials?: string | null;
+    priceAmount?: string | null;
+    priceCurrency?: string | null;
+    inventoryStatus?: ClientDeliveryInventoryStatus | null;
+    inventoryAsOf?: string | null;
+    shippingDaysMin?: number | null;
+    shippingDaysMax?: number | null;
+    factsJson?: Record<string, string | number | boolean | null>;
+    effectiveAt?: string | null;
+    expiresAt?: string | null;
+    sourceRef?: string | null;
+};
+/** staff 事实版本 body:额外可指定 provenance(默认 staff)。 */
+export type StaffClientDeliveryFactVersionBody = ClientDeliveryFactVersionBody & {
+    provenance?: "client" | "staff" | "import";
+};
+/** staff 建产品身份。 */
+export type CreateClientDeliveryProductBody = {
+    brandId: string;
+    sku: string;
+    brandRegistryId?: string | null;
+    modelName?: string | null;
+    market?: string | null;
+    status?: string;
+};
+/** staff 建品牌内容政策版本。 */
+export type CreateClientDeliveryPolicyVersionBody = {
+    brandId: string;
+    market?: string | null;
+    provenance?: "client" | "staff" | "import";
+    policyJson?: Record<string, unknown>;
+    effectiveAt?: string | null;
+};
+/** 字段级评论(request-changes 内嵌 / 独立讨论)。 */
+export type ClientDeliveryDecisionComment = {
+    fieldKey: string;
+    quotedText?: string;
+    body: string;
+};
+/** 客户批准(CAS:expectedRevisionHash)。 */
+export type ApproveClientDeliveryRevisionBody = {
+    expectedRevisionHash: string;
+    note?: string;
+};
+/** 客户请求修改(CAS + 字段级评论,至少一条)。 */
+export type RequestChangesClientDeliveryRevisionBody = {
+    expectedRevisionHash: string;
+    comments: ClientDeliveryDecisionComment[];
+    note?: string;
+};
+/** 客户字段级讨论评论。 */
+export type AddClientDeliveryCommentBody = {
+    fieldKey: string;
+    quotedText?: string;
+    body: string;
+};
 export type UpdateNotificationChannelBody = {
     provider?: string;
     externalId?: string;
@@ -416,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);
@@ -487,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;
@@ -650,6 +784,101 @@ export declare class SocialHubClient {
         /** BullMQ 入队失败时的告警(job 仍 scheduled,可被 ops 领)。 */
         warning?: string;
     }>;
+    private clientDeliveryBase;
+    /** GET client-delivery/bundles?brandId=(必填)&status=&limit=&offset= — 客户面 bundle 列表。 */
+    clientDeliveryListBundles(teamId: string, params: ListClientDeliveryBundlesParams): Promise<{
+        items: unknown[];
+    }>;
+    /** GET client-delivery/bundles/:id — 单个 bundle(client 视图脱敏 / staff 完整)。 */
+    clientDeliveryGetBundle(teamId: string, bundleId: string): Promise<unknown>;
+    /** GET client-delivery/bundles/:id/items — bundle 下条目列表。 */
+    clientDeliveryListItems(teamId: string, bundleId: string): Promise<{
+        items: unknown[];
+    }>;
+    /** GET client-delivery/items/:id — 单个条目。 */
+    clientDeliveryGetItem(teamId: string, itemId: string): Promise<unknown>;
+    /** GET client-delivery/items/:id/revisions — 条目下 revision 列表。 */
+    clientDeliveryListRevisions(teamId: string, itemId: string): Promise<{
+        items: unknown[];
+    }>;
+    /** GET client-delivery/revisions/:id — 单个 revision(含 sourceContentHash 作 CAS 凭证)。 */
+    clientDeliveryGetRevision(teamId: string, revisionId: string): Promise<unknown>;
+    /** GET client-delivery/revisions/:id/comments — revision 字段级评论列表。 */
+    clientDeliveryListComments(teamId: string, revisionId: string): Promise<{
+        items: unknown[];
+    }>;
+    /** GET client-delivery/revisions/:id/events — revision 决策事件链(append-only)。 */
+    clientDeliveryListEvents(teamId: string, revisionId: string): Promise<{
+        items: unknown[];
+    }>;
+    /**
+     * POST client-delivery/revisions/:id/approve — 客户批准(CAS)。expectedRevisionHash 与服务端
+     * 当前 revision hash 不符 → 409(SDK 透传为 `HTTP 409:` Error);须 user 凭证(拒 api_key)。
+     */
+    clientDeliveryApproveRevision(teamId: string, revisionId: string, body: ApproveClientDeliveryRevisionBody): Promise<{
+        revision: unknown;
+    }>;
+    /**
+     * POST client-delivery/revisions/:id/request-changes — 客户请求修改 + 字段级评论(CAS)。
+     * hash 不符 → 409;须 user 凭证。
+     */
+    clientDeliveryRequestChanges(teamId: string, revisionId: string, body: RequestChangesClientDeliveryRevisionBody): Promise<{
+        revision: unknown;
+    }>;
+    /** POST client-delivery/revisions/:id/comments — 客户字段级讨论(非决策);须 user 凭证。 */
+    clientDeliveryAddComment(teamId: string, revisionId: string, body: AddClientDeliveryCommentBody): Promise<{
+        comment: unknown;
+    }>;
+    /** POST client-delivery/comments/:id/resolve — 客户关闭讨论(幂等);须 user 凭证。 */
+    clientDeliveryResolveComment(teamId: string, commentId: string): Promise<{
+        comment: unknown;
+    }>;
+    /**
+     * POST client-delivery/products/:productId/fact-versions（**客户面**）— 客户提交产品事实版本。
+     * provenance 服务端强制 'client';正文/draft 字段物理不接受。须 user 凭证。
+     */
+    clientDeliveryCreateClientFactVersion(teamId: string, productId: string, body: ClientDeliveryFactVersionBody): Promise<{
+        factVersion: unknown;
+    }>;
+    /** POST client-delivery/bundles — staff 建 bundle。 */
+    clientDeliveryCreateBundle(teamId: string, body: CreateClientDeliveryBundleBody): Promise<{
+        bundle: unknown;
+    }>;
+    /** POST client-delivery/bundles/:id/items — staff upsert 条目(帖/评 + 矩阵字段)。 */
+    clientDeliveryUpsertItem(teamId: string, bundleId: string, body: UpsertClientDeliveryItemBody): Promise<{
+        item: unknown;
+    }>;
+    /** POST client-delivery/items/:id/revisions — staff 建不可变送审快照(无 body)。 */
+    clientDeliveryCreateRevision(teamId: string, itemId: string): Promise<{
+        revision: unknown;
+    }>;
+    /** POST client-delivery/revisions/:id/submit — staff 送审(not_submitted|withdrawn → pending)。 */
+    clientDeliverySubmitRevision(teamId: string, revisionId: string, body?: SubmitClientDeliveryRevisionBody): Promise<{
+        revision: unknown;
+    }>;
+    /** POST client-delivery/products — staff 建产品身份。 */
+    clientDeliveryCreateProduct(teamId: string, body: CreateClientDeliveryProductBody): Promise<{
+        product: unknown;
+    }>;
+    /**
+     * POST client-delivery/products/:productId/fact-versions（**staff 面**）— staff 提交事实版本。
+     * provenance 由 body 决定(默认 staff)。须 user 凭证。
+     */
+    clientDeliveryCreateFactVersion(teamId: string, productId: string, body: StaffClientDeliveryFactVersionBody): Promise<{
+        factVersion: unknown;
+    }>;
+    /** POST client-delivery/products/:productId/fact-versions/:fvId/activate — staff 激活 + stale 传播。 */
+    clientDeliveryActivateFactVersion(teamId: string, productId: string, factVersionId: string): Promise<{
+        factVersion: unknown;
+    }>;
+    /** POST client-delivery/policy-versions — staff 建品牌内容政策版本。 */
+    clientDeliveryCreatePolicyVersion(teamId: string, body: CreateClientDeliveryPolicyVersionBody): Promise<{
+        policyVersion: unknown;
+    }>;
+    /** POST client-delivery/policy-versions/:id/activate — staff 激活政策版本。 */
+    clientDeliveryActivatePolicyVersion(teamId: string, policyVersionId: string): Promise<{
+        policyVersion: unknown;
+    }>;
     listReports(teamId: string, options?: ListReportsParams | number): Promise<{
         items: unknown[];
     }>;
@@ -1991,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