@geoly-ai/social-hub-sdk 0.0.55 → 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;
 };
@@ -867,6 +873,113 @@ export declare class SocialHubHttpError extends Error {
         body?: string;
     });
 }
+/**
+ * 抓取结果状态。`reauth_required`/`human_required` 属立项 F（授权连接器），
+ * 当前 Hub 永不产出，仅预留以免将来扩枚举变成破坏性变更。
+ */
+export type ScrapeOutcome = "content" | "login_wall" | "captcha" | "blocked" | "timeout" | "rate_limited" | "upstream_error" | "empty_content" | "unknown" | "unsupported" | "cancelled" | "reauth_required" | "human_required";
+export type ScrapeFailureStage = "queued" | "dns" | "connect" | "proxy" | "navigate" | "render" | "wait" | "extract" | "parse" | "classify" | "transport" | "unknown";
+export type ScrapeClassificationEvidence = {
+    ruleId: string;
+    ruleVersion: number;
+    strength: "strong" | "weak";
+    location: string;
+    signal: string;
+    excerpt: string | null;
+};
+/** 两层事实：provider 原样事实 + Hub 执行观测。未知一律 null。 */
+export type ScrapeDiagnostics = {
+    provider: {
+        provider: "firecrawl" | "reddit_direct";
+        captureMethod: "firecrawl"
+        /** Hub 既有的 Reddit 直连（curl_cffi + TLS 指纹）通道。 */
+         | "direct_http" | "official_api" | "authorized_browser";
+        providerStatusCode: number | null;
+        providerErrorCode: string | null;
+        providerErrorType: string | null;
+        providerRequestId: string | null;
+        providerScrapeId: string | null;
+        targetStatusCode: number | null;
+        providerFinalUrl: string | null;
+        /** `[]` = 确认无重定向；`null` = provider 未提供该事实。 */
+        redirectChain: string[] | null;
+    };
+    execution: {
+        attemptCount: number;
+        attemptHistory: Array<{
+            attempt: number;
+            outcome: ScrapeOutcome;
+            providerStatusCode: number | null;
+            failureStage: ScrapeFailureStage | null;
+            durationMs: number;
+            waitedMs: number;
+        }>;
+        failureStage: ScrapeFailureStage | null;
+        retryAfterMs: number | null;
+        timings: {
+            totalMs: number;
+            providerMs: number;
+            backoffMs: number;
+            classifyMs: number;
+        };
+        errorSummary: string | null;
+    };
+};
+type ScrapeResponseCommon = {
+    url: string;
+    finalUrl: string;
+    /** 目标站点状态码（语义未变）。 */
+    statusCode: number | null;
+    metadata?: Record<string, unknown>;
+    requestId: string | null;
+    diagnostics: ScrapeDiagnostics;
+    classification: {
+        outcome: ScrapeOutcome;
+        classifierVersion: string;
+        classificationEvidence: ScrapeClassificationEvidence[];
+    };
+    provider: "firecrawl" | "reddit_direct";
+    providerRequestId: string | null;
+    providerStatusCode: number | null;
+    targetStatusCode: number | null;
+    attempts: number;
+    retryAfterMs: number | null;
+    failureStage: ScrapeFailureStage | null;
+    classifierVersion: string;
+    classificationEvidence: ScrapeClassificationEvidence[];
+    warnings: string[];
+};
+/**
+ * `ok` 是判别字段。被判定为「确定不是目标正文」的 outcome（login_wall / captcha /
+ * blocked / rate_limited / upstream_error / empty_content …）运行时不会带正文字段，
+ * 只有 `suppressedContent` 记录被抑制的格式与字符数；`outcome:"unknown"`（证据不足）
+ * 仍可能带正文，但 `warnings` 里会标明它未经确认——**不要**当成已验证的正文使用。
+ */
+export type ScrapeUrlResponse = (ScrapeResponseCommon & {
+    ok: true;
+    outcome: "content";
+    markdown?: string;
+    html?: string;
+    rawHtml?: string;
+    links?: string[];
+    json?: unknown;
+}) | (ScrapeResponseCommon & {
+    ok: false;
+    outcome: Exclude<ScrapeOutcome, "content">;
+    /**
+     * 被抑制的正文格式与字符数（`outcome` 属于「确定不是正文」那一类时出现）。
+     * `outcome:"unknown"` 不抑制正文，正文字段仍可能存在——**但它未经确认**。
+     */
+    suppressedContent?: Array<{
+        format: string;
+        chars: number;
+    }>;
+    markdown?: string;
+    html?: string;
+    rawHtml?: string;
+    links?: string[];
+    json?: unknown;
+});
 /**
  * POST /content-review 的 422 稳定错误码:调用方显式声称 `authorRelationHint:"post_author"`,
  * 但 Hub 侧帖子快照证明发布账号不是该帖作者。
@@ -941,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[];
     }>;
@@ -948,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,
@@ -2664,28 +2818,33 @@ export declare class SocialHubClient {
      * 通用网页抓取。Reddit .json（mode "reddit-json" 或 .json URL）走 API 内直连
      * curl_cffi+住宅代理返回结构化 JSON；HTML/普通网页经自托管 Firecrawl 返回
      * markdown/html/rawHtml/links。
+     *
+     * **务必先看 `ok`/`outcome`,不要只看 HTTP 状态**（立项 A）：Firecrawl 返回 200
+     * 但正文是登录页/验证码页时，Hub 会回 HTTP 200 + `ok:false` + `outcome`
+     * （`login_wall`/`captcha`/`empty_content` 等）并**不回传正文字段**，同时给出
+     * `classificationEvidence` 说明凭什么这么判。`outcome:"unknown"`（证据不足）仍会
+     * 带正文，但它**未经确认**，`warnings` 里有显式提示——不要当成已验证正文使用。
+     *
+     * 技术层失败（provider 非 2xx / Hub 等待超时 / 网络错误）抛 `SocialHubHttpError`
+     * （429/502/504），`code` 为 `SCRAPE_RATE_LIMITED`/`SCRAPE_TIMEOUT`/
+     * `SCRAPE_UPSTREAM_ERROR`，`details` 里带 provider typed code/error/request id、
+     * 失败阶段与尝试次数。
      */
     scrapeUrl(body: {
         url: string;
         formats?: Array<"markdown" | "html" | "rawHtml" | "links">;
         mode?: "raw" | "reddit-json";
         timeoutMs?: number;
-    }): Promise<{
-        url: string;
-        finalUrl: string;
-        statusCode: number | null;
-        markdown?: string;
-        html?: string;
-        rawHtml?: string;
-        links?: string[];
-        json?: unknown;
-        metadata?: Record<string, unknown>;
-    }>;
+    }): Promise<ScrapeUrlResponse>;
     getScrapeStatus(): Promise<{
         configured: boolean;
         firecrawl?: boolean;
         redditDirect?: boolean;
         inFlight: number;
+        /** 立项 A 新增：当前 2xx 页面分类器版本。 */
+        classifierVersion?: string;
+        /** 立项 A 新增：生效的尝试次数上限（含首次）。 */
+        maxAttempts?: number;
     }>;
     /** GET subjects/:hotPostId — active spec 下该 hot_post 的 current proposed 分类(proposed|missing)。 */
     getContentClassificationSubject(hotPostId: string, params?: {
@@ -3485,4 +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