@geoly-ai/social-hub-sdk 0.0.58 → 0.1.1

package/dist/index.d.ts

@@ -75,6 +75,43 @@ export type UpdateCalendarEntryBody = {
     deliveryMode?: CalendarEntryDeliveryMode;
     permalink?: string;
     failureReason?: string;
+    /**
+     * R7 · 抢占执行权时的乐观版本钉子（只对 `scheduled → running` 有效）。
+     * 🔴 终态回写**不要带**：抢占那一次自己会把 revision 推到 N+1，终态再带 N 必然失败
+     * （得到 `expected_revision_not_applicable`）。
+     */
+    expectedRevision?: number;
+    /**
+     * R7 · 服务端签发的执行 capability token。终态回写必带（只要条目有在途授权）；
+     * 初次抢占**不得**带。⚠️ bearer 凭据，别打日志。
+     */
+    executionToken?: string;
+    /**
+     * R7 · 抢占的幂等键（客户端生成，建议 UUID）。
+     * **强烈建议每次抢占都带** —— 它是「claim 已提交但响应丢失」的唯一补救。
+     */
+    claimRequestId?: string;
+    /**
+     * R7 · 强制终结：宿主机死在 `running` 中途时的逃生口。
+     * 仅 manager/admin、仅 `failed`/`cancelled`、必须同时给 `failureReason`。
+     * ⚠️ 不是把执行权让给下一台机 —— 条目就此终结。
+     */
+    forceTerminalize?: boolean;
+};
+/**
+ * R7 · 抢占成功时服务端回的执行授权。
+ * 🔴 `token` 是 bearer 凭据：存本机 state 文件，别打日志、别回显。
+ */
+export type CalendarEntryExecutionGrant = {
+    /** 单调递增的执行代数，仅供审计对账；授权判据是 `token`。 */
+    epoch: number;
+    token: string;
+    /**
+     * 抢占**之后**的 directiveRevision（= 抢占前 + 1）。
+     * ⚠️ 抢占会 append 一条 `cancel` 指令并广播给**包括赢家在内**的全部机器 ——
+     * 协议规定它只删**未来的** cron，**绝不中止已持 token 的在途执行**。
+     */
+    directiveRevision: number;
 };
 export type ListRedditPostSnapshotsParams = {
     limit?: number;
@@ -352,6 +389,84 @@ export type ListCommentDraftsParams = {
     /** 把聚合收窄到指定可见团队(逗号拼);空数组=不收窄。 */
     scopeTeamIds?: string[];
 };
+/**
+ * R12(迁移 0153)——「**显式**声明这条内容不做品牌提及」。
+ *
+ * 只有 `"none"` 一个值,对应契约的 `brandMentionDeclarationSchema`
+ * (`packages/contracts/src/brand-mention-declaration.ts`)。
+ *
+ * 🔴 **缺失 ≠ 无意图**:省略 `brandId` 而不带这个声明,服务端按「忘了传」判 400,
+ * 不会静默降级成无品牌。判定规则全在服务端(`refineBrandMentionDeclaration` +
+ * 路由的四值比较 + db 层兜底),**SDK 只表达类型、不复刻校验** —— 复刻必然两边漂移。
+ */
+export type BrandMentionDeclaration = "none";
+/**
+ * `POST /content-drafts` 的 body。
+ *
+ * ⚠️ `brandId` 与 `brandMention` 的互斥/必填关系**故意不用类型联合表达**:
+ * 服务端的 `superRefine` 是唯一判定处,在 SDK 里再写一遍会漂移(见
+ * {@link BrandMentionDeclaration})。类型只负责让「无品牌草稿」可以被表达出来。
+ */
+export type CreateContentDraftBody = {
+    /** R12:可选。省略时**必须**同时显式给 `brandMention: "none"`(服务端校验)。 */
+    brandId?: string;
+    /** R12:显式声明本草稿不做品牌提及。见 {@link BrandMentionDeclaration}。 */
+    brandMention?: BrandMentionDeclaration;
+    /** @deprecated legacy 归因;新草稿只用 brandId。 */
+    campaignId?: string;
+    title: string;
+    body: string;
+    /** 目标板块(内容语义真源);服务端规范化后落库。省略/null → NULL。 */
+    subreddit?: string | null;
+    /**
+     * 写作参考 / 归因备注 URL:「这篇内容围绕哪个落地页写的」。
+     * ⚠️ **不参与发布执行** —— 系统没有 Reddit link post 概念,执行只冻结 title+body。
+     */
+    referenceUrl?: string | null;
+    /**
+     * R2:**创建幂等键**(可选)。同一个 `(team, sourceRef)` 重复创建会复用首次那篇,
+     * 返回 `{ reused: true }` 而不是再造一篇。
+     *
+     * 用它包住会重试的调用(cron 重跑、超时重发、回执丢失后补发)。key 由调用方拥有,
+     * 服务端只做 NFKC + trim + 长度 1..200 + 拒控制字符,**不限制字符集** ——
+     * `agent:reports/2026-08.json#3` 这类带 `#` 的键是合法的。
+     *
+     * 🔴 唯一例外:**`openclaw:` 前缀是导入器专用的保留命名空间,写入面直接 400**
+     * (导入器有权用源文件覆盖同 key 的草稿;你占用它,你的草稿会在下次 ingest 被覆盖)。
+     * 换个自己的前缀即可。按 `openclaw:` 反查**不受限制**。
+     *
+     * ⚠️ **同 key 换内容 = 409**(`CONTENT_DRAFT_SOURCE_REF_CONFLICT`),不是静默覆盖。
+     * 改稿走 `PATCH`,或换一个新 key。删除会释放 key。
+     */
+    sourceRef?: string;
+};
+/** `POST /publishing-plans` 里的单条待排期条目。 */
+export type CreatePublishingPlanEntryInput = {
+    contentDraftId?: string;
+    socialAccountId: string;
+    subreddit: string;
+    /** ISO-8601 datetime。 */
+    plannedAt: string;
+    /** 缺省 = `hub_managed`。见 {@link CalendarEntryDeliveryMode}。 */
+    deliveryMode?: CalendarEntryDeliveryMode;
+};
+/**
+ * `POST /publishing-plans` 的 body(此前是 `Record<string, unknown>`,运行时不挡、
+ * 类型也表达不出 R12 的无品牌计划)。
+ *
+ * ⚠️ 与 {@link CreateContentDraftBody} 同理:brandId / brandMention 的四条 fail-closed
+ * 规则**只在服务端**判,SDK 不复刻。
+ */
+export type CreatePublishingPlanBody = {
+    /** R12:可选。省略时**必须**同时显式给 `brandMention: "none"`(服务端校验)。 */
+    brandId?: string;
+    /** R12:显式声明本计划不做品牌提及。见 {@link BrandMentionDeclaration}。 */
+    brandMention?: BrandMentionDeclaration;
+    /** @deprecated legacy 归因。 */
+    campaignId?: string;
+    name: string;
+    entries: CreatePublishingPlanEntryInput[];
+};
 export type CreateCommentDraftBody = {
     brandId: string;
     campaignId?: string;
@@ -1084,9 +1199,31 @@ export declare class SocialHubClient {
     listCalendarEntries(teamId: string, params?: ListCalendarEntriesParams): Promise<{
         items: unknown[];
     }>;
+    /**
+     * PATCH 一条日历条目。
+     *
+     * ## R7 · 执行权排他（只对 `external_agent` 条目）
+     * 协议是四步，**顺序不能换**：
+     *   1. `calendar preflight`（可以两台都拿到 ok，它是纯读）；
+     *   2. **抢 `status:"running"`** —— 这一步才是排他。赢家在响应里拿到
+     *      `execution.token`；输的那台拿 **409 `EXECUTION_NOT_ACQUIRED`**，
+     *      `details.reason = "execution_already_acquired"`，应当安静退出并删本机 cron；
+     *   3. 提交到 Reddit；
+     *   4. 带 `executionToken` 回写 `succeeded` / `failed`。
+     *
+     * ⛔ **绝不能先提交再抢 running** —— 那样排他就完全失效了。
+     *
+     * 🔴 抢占时**务必带 `claimRequestId`**（客户端生成的幂等键）。没有它，
+     * 「claim 已提交但 HTTP 响应丢失」会留下一条永久卡 `running`、
+     * 却没有任何人握着 token 的条目，只能人工强制终结。带上它重试即可拿回原 token。
+     *
+     * ⚠️ `execution.token` 是 **bearer 凭据**：写进本机 state 文件，别打日志、别回显。
+     */
     updateCalendarEntry(teamId: string, entryId: string, body: UpdateCalendarEntryBody): Promise<{
         ok: boolean;
         warning?: string;
+        /** 仅在本次真正取得（或幂等重取）执行权时出现。老服务端不会回这个字段。 */
+        execution?: CalendarEntryExecutionGrant;
     }>;
     /**
      * 与 {@link SocialHubClient.listCalendarEntries} **同一个端点**，只是把返回体
@@ -1246,6 +1383,11 @@ export declare class SocialHubClient {
         status?: string | string[];
         /** 目标板块过滤(单值或数组;数组按逗号拼,同字段内 OR)。 */
         subreddit?: string | string[];
+        /**
+         * R2:按创建幂等键反查(单值或数组;数组按逗号拼,同字段内 OR)。
+         * 迁移期用它把本地 legacy key 映射到 Hub 草稿,不必靠标题去猜。
+         */
+        sourceRef?: string | string[];
         search?: string;
     } | number): Promise<{
         items: unknown[];
@@ -1253,20 +1395,19 @@ export declare class SocialHubClient {
         limit: number;
         offset: number;
     }>;
-    createContentDraft(teamId: string, body: {
-        brandId: string;
-        campaignId?: string;
-        title: string;
-        body: string;
-        /** 目标板块(内容语义真源);服务端规范化后落库。省略/null → NULL。 */
-        subreddit?: string | null;
-        /**
-         * 写作参考 / 归因备注 URL:「这篇内容围绕哪个落地页写的」。
-         * ⚠️ **不参与发布执行** —— 系统没有 Reddit link post 概念,执行只冻结 title+body。
-         */
-        referenceUrl?: string | null;
-    }): Promise<{
+    /**
+     * `POST /content-drafts`。
+     *
+     * R2:传了 `body.sourceRef` 时,`reused` 表示这次是**复用**了既有草稿(HTTP 200)
+     * 而不是新建(HTTP 201)。
+     *
+     * ⚠️ 没传 `sourceRef` 时服务端**不返回** `reused`(响应保持 R2 之前的 `{ id }`),
+     * 所以这里的类型是可选的 —— 别写 `if (!res.reused)` 当作「新建」的判据,
+     * 那在没传 key 时恒真但毫无意义;要判复用请先确认自己传了 key。
+     */
+    createContentDraft(teamId: string, body: CreateContentDraftBody): Promise<{
         id: string;
+        reused?: boolean;
     }>;
     /**
      * GET /content-review-targets — team-scoped 审核目标列表(status/contentType 过滤 +
@@ -1630,7 +1771,7 @@ export declare class SocialHubClient {
     listPublishingPlans(teamId: string, params?: ListPublishingPlansParams): Promise<{
         items: unknown[];
     }>;
-    createPublishingPlan(teamId: string, body: Record<string, unknown>): Promise<unknown>;
+    createPublishingPlan(teamId: string, body: CreatePublishingPlanBody): Promise<unknown>;
     listAuditLogs(teamId: string, params?: ListAuditLogsParams): Promise<{
         items: unknown[];
     }>;
@@ -3787,7 +3928,15 @@ export type CalendarEntryListItemDto = {
     id: string;
     teamId: string;
     publishingPlanId: string;
-    brandId: string;
+    /**
+     * R12(迁移 0153):**可为 null** —— `null` 表示这条条目所属计划显式声明了
+     * 无品牌提及(`plan.brandId` 与 `campaign.brandId` 都是 NULL)。
+     *
+     * 读侧对 `brands` 已由 innerJoin 改成 **leftJoin**,无品牌行不再被静默丢掉,
+     * 所以服务端**确实会**在这里回 null。契约真源:
+     * `packages/contracts/src/publishing-plans.ts` 的 `calendarEntryListItemSchema`。
+     */
+    brandId: string | null;
     /** legacy；brand-first 建的计划为 null。 */
     campaignId: string | null;
     contentDraftId: string | null;
@@ -3808,7 +3957,11 @@ export type CalendarEntryListItemDto = {
     createdAt: string;
     /** 迁移 0149 起维护；更早的真实修改时间已不可考。 */
     updatedAt?: string;
-    brandName: string;
+    /**
+     * R12:无品牌条目没有 `brands` 行可 join → **null**(不是空串)。
+     * ⚠️ 直接 `.toUpperCase()` / `.slice()` 会在运行时炸;先判空再用。
+     */
+    brandName: string | null;
     campaignName: string | null;
     socialAccountHandle: string | null;
     socialAccountPlatform: string;