@geoly-ai/social-hub-sdk 0.0.52 → 0.0.53

package/dist/index.d.ts

@@ -190,6 +190,17 @@ export type UpdateContentDraftBody = {
     title?: string;
     body?: string;
     status?: string;
+    /**
+     * 目标板块(迁移 0136)。省略 = 不改;`null` = 清空;字符串 = 设置(服务端规范化)。
+     * 属内容身份 → **会** bump 草稿版本(旧内部审核 / 客户批准因此失效)。
+     */
+    subreddit?: string | null;
+    /**
+     * 写作参考 / 归因备注 URL(迁移 0136,原前端字段名 `targetUrl`)。
+     * ⚠️ **不参与发布执行** —— 系统没有 Reddit link post 概念,执行只冻结 title+body。
+     * 不属内容身份 → 单独改它**不** bump 版本、不使既有审核/批准失效。
+     */
+    referenceUrl?: string | null;
     /** Optimistic concurrency: last-loaded version; a mismatch is rejected 409. */
     expectedVersion?: number;
 };
@@ -364,12 +375,28 @@ export type ScheduleCommentDraftBody = {
 };
 export type DeliveryBundleStatusLike = "open" | "closed" | "cancelled";
 /** 客户面列 bundle:brandId 服务端**必填**(客户按 brand 收窄);SDK 类型强制。 */
+/**
+ * `cursor` 与 `offset` **互斥**,用可辨识联合在**编译期**就拒掉错误组合 —— 服务端也会
+ * 400,但把它留到运行时等于让调用方先发一次注定失败的请求。
+ */
 export type ListClientDeliveryBundlesParams = {
     brandId: string;
     status?: DeliveryBundleStatusLike;
     limit?: number;
+} & ({
+    /**
+     * keyset 游标 —— 上一次响应的 `nextCursor` 原样回传。对调用方是**不透明字符串**:
+     * 不要解析或构造,也不要换了 brandId/status 之后复用(游标绑定过滤条件指纹,会 400)。
+     */
+    cursor: string;
+    offset?: never;
+} | {
+    cursor?: undefined;
+    /**
+     * @deprecated 用 `cursor`。offset 分页在并发写入下会重复/跳条(服务端已改 keyset)。
+     */
     offset?: number;
-};
+});
 /** staff 建 bundle。 */
 export type CreateClientDeliveryBundleBody = {
     brandId: string;
@@ -472,6 +499,77 @@ export type ListSubredditWatchlistsParams = {
     /** 按板块名精确查归属(r/ 前缀可省,大小写不敏感)。 */
     subreddit?: string;
 };
+export type ListSubredditMonitorsParams = {
+    limit?: number;
+    offset?: number;
+    /** 缺省 = 全部(含已停止的);服务端只认 "true"/"false" 字符串,方法内负责转换。 */
+    enabled?: boolean;
+    watchlistId?: string;
+};
+/**
+ * 监听配置行(POST 启用的返回)。时间字段一律 `string`(HTTP JSON 里是 ISO 串,
+ * SDK 不代为 `new Date()`,免得调用方拿到「有时 Date 有时 string」的混合类型)。
+ */
+export type SubredditMonitorConfig = {
+    id: string;
+    watchlistId: string;
+    subreddit: string;
+    enabled: boolean;
+    sort: string;
+    fetchLimit: number;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * 监听列表的一行 = 配置行 + 三个派生水位字段。
+ * ⚠️ 这三个字段**只在列表读口有**,POST 启用返回的是裸配置行(见 SubredditMonitorConfig)。
+ */
+export type SubredditMonitorItem = SubredditMonitorConfig & {
+    /** 该监听最近一次观察到帖子的时间;从未观察到 → null。 */
+    lastObservedAt: string | null;
+    /** 最近一轮 run 中该监听**首次观察**到的帖子数。 */
+    newPostsInLatestRun: number;
+    /** 已观察但尚未进入任何送达报告的积压数(报告水位落后的信号)。 */
+    unreportedCount: number;
+};
+export type SubredditMonitorRunStatus = "pending" | "claimed" | "collecting" | "reporting" | "completed" | "degraded" | "failed";
+/** run 列表/摘要读口的形状:**不含** fetchDiagnostics / reportPayload 两个大字段。 */
+export type SubredditMonitorRunSummary = {
+    id: string;
+    scheduleKey: "cron" | "manual";
+    windowStart: string;
+    windowEnd: string;
+    status: SubredditMonitorRunStatus;
+    attempts: number;
+    monitorCount: number;
+    succeededMonitorCount: number;
+    failedMonitorCount: number;
+    observedPostCount: number;
+    newPostCount: number;
+    errorCode: string | null;
+    createdAt: string;
+    completedAt: string | null;
+};
+/** run 详情:摘要 + 只有单条读口才投影的 jsonb 大字段与各阶段时间戳。 */
+export type SubredditMonitorRunDetail = SubredditMonitorRunSummary & {
+    fetchDiagnostics: Record<string, unknown> | null;
+    reportPayload: Record<string, unknown> | null;
+    error: string | null;
+    fetchStartedAt: string | null;
+    fetchCompletedAt: string | null;
+    reportCompletedAt: string | null;
+};
+/** run 列表是 **keyset 分页**(无 offset):游标 = 上一页最后一行的 windowStart + id。 */
+export type ListSubredditMonitorRunsParams = {
+    limit?: number;
+    status?: SubredditMonitorRunStatus;
+    beforeWindowStart?: string;
+    beforeId?: string;
+};
+export type EnableSubredditMonitorBody = {
+    watchlistId: string;
+    fetchLimit?: number;
+};
 export type ListHotPostsParams = {
     limit?: number;
     offset?: number;
@@ -885,16 +983,31 @@ export declare class SocialHubClient {
     cancelScheduledJob(teamId: string, jobId: string): Promise<unknown>;
     listContentDrafts(teamId: string, params?: {
         limit?: number;
+        offset?: number;
         brandId?: string;
         campaignId?: string;
+        status?: string | string[];
+        /** 目标板块过滤(单值或数组;数组按逗号拼,同字段内 OR)。 */
+        subreddit?: string | string[];
+        search?: string;
     } | number): Promise<{
         items: unknown[];
+        total: number;
+        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<{
         id: string;
     }>;
@@ -955,9 +1068,13 @@ export declare class SocialHubClient {
         warning?: string;
     }>;
     private clientDeliveryBase;
-    /** GET client-delivery/bundles?brandId=(必填)&status=&limit=&offset= — 客户面 bundle 列表。 */
+    /**
+     * GET client-delivery/bundles?brandId=(必填)&status=&limit=&cursor= — 客户面 bundle 列表。
+     * `nextCursor === null` 表示已到末页;非 null 时原样回传到下次调用的 `cursor`。
+     */
     clientDeliveryListBundles(teamId: string, params: ListClientDeliveryBundlesParams): Promise<{
         items: unknown[];
+        nextCursor?: string | null;
     }>;
     /** GET client-delivery/bundles/:id — 单个 bundle(client 视图脱敏 / staff 完整)。 */
     clientDeliveryGetBundle(teamId: string, bundleId: string): Promise<unknown>;
@@ -1578,7 +1695,36 @@ export declare class SocialHubClient {
         offset?: number;
     }): Promise<{
         items: unknown[];
-        total: number;
+        /**
+         * ⚠️ 0140 起**不再恒为精确值**,必须连着 `totalRelation` 一起读。
+         * `null` = 未计算(keyword 路径)。想判断"还有没有下一页"请用 `hasMore`,
+         * 不要写 `offset + limit >= total` —— 封顶/未知时它会误判成没有下一页。
+         */
+        total: number | null;
+        /** "eq"=精确;"gte"=实际 ≥ total(封顶 10000);"unavailable"=未计算(total 为 null)。 */
+        totalRelation: "eq" | "gte" | "unavailable";
+        /** 权威分页信号:由服务端多取一行得出,与 total 精度无关。 */
+        hasMore: boolean;
+    }>;
+    /**
+     * 评论样本行的**精确 count**(与 list 同一组过滤谓词,无分页、不封顶)。
+     * ⚠️ 故意**不接受 keyword**:keyword 走全文 ILIKE,精确 count 要全表扫
+     * (服务端契约 strict,传了直接 400);keyword 口径请用 listRedditCommentSamples
+     * (totalRelation=unavailable)。
+     * ⚠️ 无过滤时是全表精确 count,属昂贵读——基线用途,**禁止轮询**。
+     * 口径是库内 reddit_comment_samples 行数,不是 Reddit 线程真实评论总数。
+     */
+    countRedditCommentSamples(params?: {
+        postId?: string;
+        subreddit?: string;
+        intent?: string;
+        sentiment?: string;
+        origin?: "hub_collector" | "import";
+    }): Promise<{
+        /** 精确匹配数(不封顶;恒精确,故无 relation 字段)。 */
+        count: number;
+        /** 采样口径恒为部分样本。 */
+        sampleMode: "partial_sample";
     }>;
     dispatchRedditCommentCapture(body: {
         permalinks: string[];
@@ -1714,6 +1860,52 @@ export declare class SocialHubClient {
         ok: boolean;
     }>;
     deleteSubredditWatchlist(watchlistId: string): Promise<void>;
+    listSubredditMonitors(params?: ListSubredditMonitorsParams): Promise<{
+        items: SubredditMonitorItem[];
+        total: number;
+        /** 最近一轮 run(全局,一轮覆盖所有监听);从未跑过 → null。 */
+        latestRun: SubredditMonitorRunSummary | null;
+        limit: number;
+        offset: number;
+    }>;
+    /**
+     * 加入监听(**幂等**):同一 watchlist 已停止的会被重新启用,不新建行 ——
+     * observation ledger 因此保留,重启后已报告过的帖子不会重复报告。
+     */
+    enableSubredditMonitor(body: EnableSubredditMonitorBody): Promise<SubredditMonitorConfig>;
+    /**
+     * 停止监听:DELETE 语义但服务端做**软停**(enabled=false),不删 observation ledger。
+     * 幂等 —— 本来就没在监听时返回 `{ ok: true, updated: false }`,不是 404。
+     */
+    /**
+     * 停止监听。默认是**软停**(`enabled=false`):保留观察 ledger,重新启用后已经报告过的
+     * 帖子不会被再报一遍。
+     *
+     * `purge: true` 是另一个动作 —— **连历史观察一起硬删**。只有在要删掉整个 watchlist 时
+     * 才需要:monitor 配置对 watchlist 的外键是 `ON DELETE RESTRICT`,不先 purge 就删不掉
+     * watchlist(服务端会返回 409 并提示走这条路)。
+     */
+    disableSubredditMonitor(watchlistId: string, options?: {
+        purge?: boolean;
+    }): Promise<{
+        ok: boolean;
+        updated: boolean;
+        purged?: boolean;
+    }>;
+    /** run 列表:keyset 分页,翻页用上一页最后一行的 windowStart + id 当游标。 */
+    listSubredditMonitorRuns(params?: ListSubredditMonitorRunsParams): Promise<{
+        items: SubredditMonitorRunSummary[];
+        hasMore: boolean;
+    }>;
+    /** run 详情:唯一会带回 fetchDiagnostics / reportPayload 两个大字段的读口。 */
+    getSubredditMonitorRun(runId: string): Promise<SubredditMonitorRunDetail>;
+    /** 手工触发一轮(202 入队)。没有任何启用中的监听时服务端返回 400,不制造空跑 run。 */
+    runSubredditMonitors(): Promise<{
+        status: string;
+        monitors: number;
+        jobId?: string;
+        warning?: string;
+    }>;
     listHotPosts(params?: ListHotPostsParams): Promise<{
         items: HotPostListItem[];
         total: number;
@@ -1851,9 +2043,16 @@ export declare class SocialHubClient {
     sessionActiveTeam(body: {
         teamId: string;
     }): Promise<unknown>;
+    /**
+     * 管理员替他人重置密码。需要**不受限的交互式 admin 会话**(role=admin 的 api_key
+     * 不行),且不能重置自己(自助改密走 `PUT /v1/auth/password`,它校验旧密码)。
+     *
+     * `userId` / `email` **恰好给一个**。原来的 `teamId` 参数已删除:密码是用户级全局
+     * 凭证,团队参数从来没有限制过影响范围,只是误导。
+     */
     sessionSetPassword(body: {
-        email: string;
-        teamId?: string;
+        userId?: string;
+        email?: string;
         password: string;
     }): Promise<unknown>;
     sessionUpdateProfile(body: {