@geoly-ai/social-hub-sdk 0.1.0 → 0.1.2

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;
@@ -386,6 +423,22 @@ export type CreateContentDraftBody = {
      * ⚠️ **不参与发布执行** —— 系统没有 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 = {
@@ -1146,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} **同一个端点**，只是把返回体
@@ -1308,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[];
@@ -1315,8 +1395,19 @@ export declare class SocialHubClient {
         limit: number;
         offset: number;
     }>;
+    /**
+     * `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 过滤 +
@@ -2986,6 +3077,121 @@ export declare class SocialHubClient {
         count: number;
         runs: unknown[];
     }>;
+    /**
+     * POST subreddits — 只登记 canonical 板块身份，**不建资产**（幂等）。
+     *
+     * 「r/foo 这个板块存在」与「r/foo 是我们的」是两件事：后者会让绑定到它的账号在
+     * enforce 档下被全面阻断。分开是为了能先把 20 个板块名录进来核对拼写，
+     * 再逐个确认所有权。
+     */
+    registerSubredditIdentity(body: {
+        name: string;
+        displayName?: string;
+    }): Promise<{
+        subredditId: string;
+        normalizedName: string;
+        created: boolean;
+    }>;
+    /** POST — 登记一条自建板块资产（幂等：同板块已有资产则返回 created=false）。 */
+    registerOwnedSubreddit(body: {
+        name: string;
+        displayName?: string;
+        /** 可为空：板块是公司资产，不必挂品牌（代价由行级授权承担）。 */
+        brandId?: string | null;
+        assetStatus?: "active" | "archived" | "lost";
+        notes?: string | null;
+    }): Promise<{
+        ownedSubredditId: string;
+        created: boolean;
+    }>;
+    /**
+     * GET — 列出自建板块资产（含版主绑定与只读风险投影）。
+     *
+     * `moderatorRisk=zero|single` 是**零/单版主的发现入口**：存量 20 条全是单版主，
+     * 这是查出「哪些板块只剩一个版主、而那个号刚被封」的地方。
+     * ⛔ 它只做发现，不做写入硬拒绝。
+     */
+    listOwnedSubreddits(params?: {
+        assetStatus?: "active" | "archived" | "lost";
+        moderatorRisk?: "zero" | "single" | "redundant";
+        brandId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: unknown[];
+    }>;
+    /** GET :id — 单条资产详情（不可见时返 404，不返 403：避免变成枚举面）。 */
+    getOwnedSubreddit(ownedSubredditId: string): Promise<unknown>;
+    /**
+     * PATCH :id/status — 改资产状态（CAS，rowVersion 漂移返 409）。
+     *
+     * ⚠️ `lost` **解除**该板块所有绑定账号的阻断并停止核验；`archived` **保留**阻断。
+     */
+    updateOwnedSubredditStatus(ownedSubredditId: string, body: {
+        assetStatus: "active" | "archived" | "lost";
+        rowVersion: number;
+        reason?: string | null;
+    }): Promise<{
+        rowVersion: number;
+    }>;
+    /**
+     * POST :id/moderators — 给板块加一个版主绑定。
+     *
+     * 🔴 返回的 `accountAtRisk=true` 表示**这个账号已经是 banned/restricted 了**。
+     * 建绑不构成状态转变，所以封禁告警那条链一条都不会发 —— 服务端另落了一条
+     * critical 风险事件，而这个返回值是人工录入 20 条存量时当场能看见的信号。
+     */
+    addSubredditModerator(ownedSubredditId: string, body: {
+        socialAccountId: string;
+        isPrimary?: boolean;
+        declaredPermissions?: string[];
+        notes?: string | null;
+    }): Promise<{
+        bindingId: string;
+        accountAtRisk: boolean;
+    }>;
+    /** POST moderators/:id/revoke — 撤销绑定（CAS）。行永久保留，历史不可抹。 */
+    revokeSubredditModerator(bindingId: string, body: {
+        rowVersion: number;
+        reason?: string | null;
+    }): Promise<{
+        rowVersion: number;
+    }>;
+    /** POST moderators/replace — 更替版主 = **关旧建新**（不是就地改 accountId）。 */
+    replaceSubredditModerator(body: {
+        bindingId: string;
+        rowVersion: number;
+        nextSocialAccountId: string;
+        declaredPermissions?: string[];
+        reason?: string | null;
+    }): Promise<{
+        revokedBindingId: string;
+        bindingId: string;
+    }>;
+    /** GET — 读全局版主保护档位（off / shadow / enforce）。 */
+    getModeratorProtection(): Promise<{
+        mode: "off" | "shadow" | "enforce";
+        rowVersion: number;
+        note: string | null;
+        updatedAt: string;
+        updatedByUserId: string | null;
+    }>;
+    /**
+     * PATCH — 改全局版主保护档位（CAS + 审计）。
+     *
+     * 🔴 这是**全局**开关，无个体 override：`enforce` 之下所有持有 active 绑定的账号，
+     * 四类自动化动作（publish_post / publish_comment / warmup / engage）一律阻断。
+     * 切档前请先跑完 `shadow` 的验证窗口，并暂停 dispatcher 与外部 agent cron
+     * （已在外部执行中的动作不可撤回，那是 cutover 前的已知风险）。
+     */
+    setModeratorProtection(body: {
+        mode: "off" | "shadow" | "enforce";
+        rowVersion: number;
+        note?: string | null;
+    }): Promise<{
+        mode: string;
+        rowVersion: number;
+    }>;
     private subscriptionsBase;
     private eventsBase;
     private sourcesBase;