@geoly-ai/social-hub-sdk 0.0.56 → 0.0.57

package/dist/index.d.ts

@@ -67,6 +67,12 @@ export type ListCalendarEntriesParams = {
 export type UpdateCalendarEntryBody = {
     plannedAt?: string;
     status?: string;
+    /**
+     * 「谁来发这条内容」——防重复发帖的唯一闸门（方案 Block 0 · D1）。
+     * 改它会让服务端在同一事务里撤销/创建内部 job 并 append directive 指令，
+     * 因此这是**高风险写**，CLI 侧带 `--apply` 门。见 {@link CalendarEntryDeliveryMode}。
+     */
+    deliveryMode?: CalendarEntryDeliveryMode;
     permalink?: string;
     failureReason?: string;
 };
@@ -1048,6 +1054,14 @@ export declare class SocialHubClient {
     }): Promise<{
         metrics?: Record<string, number | undefined>;
     }>;
+    /**
+     * `GET .../calendar-entries` 的 URL —— {@link SocialHubClient.listCalendarEntries}
+     * 与 {@link SocialHubClient.listCalendarEntriesTyped} 共用。
+     *
+     * 抽出来是为了让两个方法**不可能**漂移：将来加一个过滤参数只改一处，
+     * 否则 typed 变体会静默少一个过滤条件，表现为「同样的参数却多返回了行」。
+     */
+    private calendarEntriesUrl;
     listCalendarEntries(teamId: string, params?: ListCalendarEntriesParams): Promise<{
         items: unknown[];
     }>;
@@ -1055,6 +1069,39 @@ export declare class SocialHubClient {
         ok: boolean;
         warning?: string;
     }>;
+    /**
+     * 与 {@link SocialHubClient.listCalendarEntries} **同一个端点**，只是把返回体
+     * 标成 {@link CalendarEntryListItemDto}。
+     *
+     * 为什么另开一个方法而不是收紧旧方法的返回类型：旧方法返回 `unknown[]`，既有调用方
+     * 普遍在外面自己 `as` 成本地形状；把它改成具名类型会让那些断言从「无操作」变成
+     * 「类型不兼容」，是一次纯粹为了好看的破坏性变更。新方法零风险，想要
+     * `deliveryMode` / `directiveRevision` 的调用方直接用它。
+     *
+     * ⚠️ 运行时**不做校验**（SDK 不引 zod）：老服务端不会回这两个字段，所以它们在
+     * DTO 里是可选的——读到 `undefined` 一律按 `hub_managed` / 未知 revision 处理，
+     * 不要当成 0。
+     */
+    listCalendarEntriesTyped(teamId: string, params?: ListCalendarEntriesParams): Promise<{
+        items: CalendarEntryListItemDto[];
+    }>;
+    /**
+     * GET .../publishing-calendar-directives/:calendarEntryId/preflight?revision=N
+     * —— 外部 agent 的 cron 到点后、**真正发帖前**必须调的只读校验（方案 §8 D5）。
+     *
+     * 这是整条链路上正文的**唯一出口**：directive 事件 payload 里只有身份 + 版本号。
+     * 服务端在同一个只读快照里确认「条目仍 scheduled / 仍 external_agent / revision 仍是
+     * 你手上那条 / 审核仍 passed」，四条全成立才把内容交出来。
+     *
+     * ⚠️ **业务拒绝是 HTTP 200 + `decision: "rejected"`，不是 4xx**——本方法不会为
+     * `rejected` 抛错。调用方必须显式判 `decision`；`if (await preflight(...))` 这种写法
+     * 会把每一次拒绝都当成放行。4xx/5xx 只留给请求本身或系统的错误。
+     *
+     * `revision` 必须是调用方手上那条 directive 的版本号，**不能省、不能猜**：服务端
+     * 拒绝空值与非数字，而 revision 0 是每条条目的合法初始值，任何「默认值」都会放行
+     * 真实条目。这里先在客户端挡一道，免得把明显非法的值打到网络上。
+     */
+    preflightPublishingCalendarDirective(teamId: string, calendarEntryId: string, revision: number): Promise<PublishingCalendarPreflightResultDto>;
     /**
      * 归属桶(teams.kind='bucket':未配置/外部)。这些团队没有 membership、不出现
      * 在 `listTeams()` 里,所以外部来源帖要回填进桶就只能先从这里拿到 UUID,
@@ -3597,5 +3644,145 @@ export type NotificationPullResponseDto = {
  * 与 contracts `compareNotificationSeq` 同口径;SDK 侧复刻是因为不能引 contracts。
  */
 export declare function compareNotificationSeqStrings(left: string, right: string): number;
+/**
+ * 这条日历条目由谁发布 —— **防重复发帖的唯一闸门**（方案 D1）。
+ *   - `hub_managed`（默认）：Hub 同事务建内部 `publish_post` job,自己发；**不**产生指令事件。
+ *   - `external_agent`：**不**建内部 job,改由 `publishing-calendar-directive.v1` 事件
+ *     驱动用户自己机器上的 agent 建 UTC 一次性 cron 去发。
+ *
+ * 两者互斥。老服务端不回这个字段 —— 读到 `undefined` 按 `hub_managed` 处理。
+ */
+export type CalendarEntryDeliveryMode = "hub_managed" | "external_agent";
+/** 指令变体：期望状态是「该有一个 cron」还是「不该有」。 */
+export type PublishingCalendarDirectiveKind = "upsert" | "cancel";
+/** cancel 的原因（枚举而非自由文本：agent 按它分流告警 vs 正常运营动作）。 */
+export type PublishingCalendarDirectiveCancelReason = 
+/** 运营主动取消这条日历条目。 */
+"entry_cancelled"
+/** 条目行被删除（含 plan/account 级联）。 */
+ | "entry_deleted"
+/** 审核由 passed 回退,内容不再允许发布。 */
+ | "review_revoked"
+/** 条目改回 `hub_managed`,改由 Hub 内部发布。 */
+ | "delivery_mode_changed"
+/** 关联草稿被解绑（`content_draft_id SET NULL`）。 */
+ | "draft_detached";
+/**
+ * preflight 的拒绝原因。**每一条都必须有本地处置动作**,不能笼统当成「失败重试」——
+ * 其中大部分是终态（该删 cron）,轮询重试只会把一条已经不该发的内容一直挂着。
+ */
+export type PublishingCalendarPreflightRejectionReason = 
+/** 条目不存在、不属于本 team,或调用方品牌作用域看不到它。此时 `currentRevision` 恒为 null。 */
+"entry_not_found"
+/** 条目已不是 `scheduled`（取消/发布中/已发/失败）。删 cron。 */
+ | "entry_not_scheduled"
+/** 条目已改回 `hub_managed`,Hub 自己发。删 cron。 */
+ | "delivery_mode_not_external"
+/** 手上的 revision 比 Hub 当前的旧 —— 还有一条更新的指令在路上。 */
+ | "revision_stale"
+/** 手上的 revision 比 Hub 当前的**新**。正常不该发生,一律不给内容。 */
+ | "revision_unknown"
+/** 条目没绑草稿,或草稿行已不在。 */
+ | "draft_detached"
+/** 当前草稿的 canonical review target 不存在、身份漂移,或状态不是 `passed`。 */
+ | "review_not_passed";
+/** preflight 放行：**唯一**能拿到正文的分支。 */
+export type PublishingCalendarPreflightOkDto = {
+    decision: "ok";
+    calendarEntryId: string;
+    publishingPlanId: string;
+    /** 服务端当前 revision（ok 时必然 === 请求里那个）。 */
+    revision: number;
+    socialAccountId: string;
+    subreddit: string;
+    /** **Z 结尾的 UTC**；直接拿去建 UTC one-shot cron,不要先转本地时区。 */
+    plannedAt: string;
+    content: {
+        contentDraftId: string;
+        contentDraftVersion: number;
+        title: string;
+        body: string;
+    };
+    review: {
+        targetId: string;
+        /** 恒为 `passed` —— 没有第二种 ok。 */
+        status: "passed";
+        /** 服务端 canonical 内容 hash,可留痕对账。 */
+        contentHash: string;
+    };
+};
+export type PublishingCalendarPreflightRejectedDto = {
+    decision: "rejected";
+    calendarEntryId: string;
+    reason: PublishingCalendarPreflightRejectionReason;
+    /**
+     * Hub 当前的 revision,**仅供诊断对账**。
+     *
+     * 🔴 绝不能拿它推进本地的「已见最高 revision」：收到 rev 5 的 cron 被判
+     * `revision_stale/currentRevision=6` 后若把本地状态升到 6,随后真正到达的 rev 6
+     * `upsert` 会被当成旧消息忽略 —— 结果是**一个 cron 都没有**。只等真实的指令。
+     *
+     * `entry_not_found` 时恒为 null（那个 reason 同时覆盖「真不存在」与「作用域看不到」）。
+     */
+    currentRevision: number | null;
+};
+/**
+ * preflight 判定结果。**业务拒绝走 200 + 本判别联合,不用 404/409**：
+ * cron 路径要能无歧义分流每个 reason。判 `decision` 之前不要碰任何字段。
+ */
+export type PublishingCalendarPreflightResultDto = PublishingCalendarPreflightOkDto | PublishingCalendarPreflightRejectedDto;
+/**
+ * `GET .../calendar-entries` 的行形状（含 joined labels）。
+ *
+ * 只被 {@link SocialHubClient.listCalendarEntriesTyped} 使用；旧的
+ * `listCalendarEntries` 仍返回 `unknown[]`,故意不动。
+ */
+export type CalendarEntryListItemDto = {
+    id: string;
+    teamId: string;
+    publishingPlanId: string;
+    brandId: string;
+    /** legacy；brand-first 建的计划为 null。 */
+    campaignId: string | null;
+    contentDraftId: string | null;
+    socialAccountId: string;
+    subreddit: string;
+    plannedAt: string;
+    status: CalendarEntryStatus;
+    /** 见 {@link CalendarEntryDeliveryMode}；老数据/老服务端缺省视为 `hub_managed`。 */
+    deliveryMode?: CalendarEntryDeliveryMode;
+    /**
+     * 单调递增的指令版本,**高版本覆盖低版本**。只对 `external_agent` 有业务意义,
+     * 但 `hub_managed` 也照常递增（改回外部时不会倒退）。缺省 = 老服务端,不是 0。
+     */
+    directiveRevision?: number;
+    publishedAt: string | null;
+    permalink: string | null;
+    failureReason: string | null;
+    createdAt: string;
+    /** 迁移 0149 起维护；更早的真实修改时间已不可考。 */
+    updatedAt?: string;
+    brandName: string;
+    campaignName: string | null;
+    socialAccountHandle: string | null;
+    socialAccountPlatform: string;
+    draftTitle: string | null;
+    draftExcerpt: string | null;
+    reviewGate?: {
+        targetId: string | null;
+        status: ReviewTargetStatus | null;
+        contentVersion: number | null;
+        /** target 是否对应当前草稿版本（canonical 全校验）。 */
+        isCurrent: boolean;
+        gateState: ReviewGateState;
+        lastError: string | null;
+    } | null;
+};
+/** 契约 `calendarEntryStatusSchema` 的镜像。 */
+export type CalendarEntryStatus = "draft" | "scheduled" | "exported" | "running" | "succeeded" | "failed" | "cancelled";
+/** 契约 `reviewTargetStatusSchema` 的镜像（审核 target 的原生状态）。 */
+export type ReviewTargetStatus = "pending" | "running" | "passed" | "needs_revision" | "blocked" | "degraded" | "superseded";
+/** 契约 `reviewGateStateSchema` 的镜像（日历条目上的审核门投影）。 */
+export type ReviewGateState = "passed" | "waiting" | "revision_required" | "blocked" | "stale" | "untracked";
 export {};
 //# sourceMappingURL=index.d.ts.map