@geoly-ai/social-hub-sdk 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -1056,6 +1056,58 @@ export type UpsertFeishuIdentitiesResponse = {
  * 四眼 registry proposal API 的结构化错误(D2):携带 HTTP status + 稳定 code + staleCode。
  * apply 的 409 + code PROPOSAL_STALE → isStale=true(消费方据此重新提案,保留 staleCode)。
  */
+/**
+ * `subreddit-candidates` 的候选耗尽诊断 —— 回答「`items` 为空到底是哪一类空」。
+ *
+ * ⛔ **这不是准入依据。** 它是诊断快照,可能因并发变更、查询上限或数据不完整而滞后。
+ * 实际可执行性**只由**服务端硬闸、`items` 与 `allowedActions` 决定。
+ * (`account_subreddit_affinities` 就曾差点被当成「可去板块」的依据 —— 别再踩一次。)
+ *
+ * 🔴 **`complete: false` 时任何 `all_*` 都不成立**,`reason` 会是 `resolution_incomplete`:
+ * 源集合没被完整枚举时,「没查到」和「查了但都被拦掉」长得一样,而处置方式完全相反。
+ *
+ * 判「要不要惊动人」的最小用法:
+ *   · `all_comment_cooldown` —— 良性,近 24h 已在这些板评论过,**不要**告警;
+ *   · `all_action_not_permitted` —— 结构性(系统共享池不作评论目标),**不要**告警;
+ *   · `all_sanctioned` / `all_blocklisted` —— 被闸拦光,**要**人工换板;
+ *   · `pool_empty` / `persona_unavailable` —— 配置问题,**要**修数据;
+ *   · `resolution_incomplete` / `mixed_exhausted` —— 说不清,按要惊动人处理。
+ */
+export type SubredditCandidatesExhaustion = {
+    reason: "not_exhausted" | "resolution_incomplete" | "pool_empty" | "persona_unavailable" | "all_blocklisted" | "all_sanctioned" | "all_tier_filtered" | "all_quota_truncated" | "all_affinity_blocked" | "all_comment_cooldown" | "all_action_not_permitted" | "all_limit_truncated" | "mixed_exhausted";
+    complete: boolean;
+    incompleteReasons: string[];
+    eligibleBeforeFilters: number;
+    returnedBoards: number;
+    returned: number;
+    /** 互斥且守恒:`Σ terminal + returnedBoards === eligibleBeforeFilters`。 */
+    terminal: Record<string, number>;
+    /** 各闸 raw 命中数,**允许重叠**,仅供排障 —— 不要用它选 reason。 */
+    filtered: Record<string, number>;
+};
+export type SubredditPostAnnotationType = "style_fit" | "brand_friendliness";
+export type SubredditPostAnnotationSource = "llm" | "human";
+/** `subreddit-style-profiles` 的行视图;写操作要回传 `rowVersion` 作 If-Match。 */
+export type SubredditStyleProfileView = {
+    id: string;
+    status: "proposed" | "approved" | "retired";
+    summary: string | null;
+    proposedByUserId: string | null;
+    /** If-Match 的值。状态每次合法迁移必变。 */
+    rowVersion: string;
+    [key: string]: unknown;
+};
+export type SubredditStyleProfileTransitionInput = {
+    id: string;
+    /** 来自 `getSubredditStyleProfile(id).profile.rowVersion`;**必传**,见方法说明。 */
+    rowVersion: string;
+};
+/**
+ * If-Match token 归一,**fail-closed**:只接受单个 strong token(可带成对引号)。
+ * 拒 `W/` 弱 ETag、`*` 通配、多值(含逗号)、引号不成对 —— 非法形状本地即拒,
+ * 不留给服务端猜。与 CLI 的 `normalizeRowVersionToken` 同一口径。
+ */
+export declare function normalizeStyleProfileRowVersion(raw: string | undefined): string | undefined;
 export declare class RegistryProposalSdkError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -2808,7 +2860,79 @@ export declare class SocialHubClient {
         personaPools?: unknown;
         systemPools?: unknown;
         fallback?: unknown;
+        exhaustion?: SubredditCandidatesExhaustion;
     }>;
+    listSubredditPostAnnotations(teamId: string, params?: {
+        subreddit?: string;
+        permalink?: string;
+        annotationType?: SubredditPostAnnotationType;
+        brandId?: string;
+        source?: SubredditPostAnnotationSource;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: unknown[];
+        total?: number;
+    }>;
+    upsertSubredditPostAnnotation(teamId: string, body: Record<string, unknown>): Promise<unknown>;
+    listSubredditStyleProfiles(params?: {
+        subreddit?: string;
+        scope?: string;
+        brandId?: string;
+        /** 逗号分隔多值,如 `proposed,approved`。 */
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: unknown[];
+        total?: number;
+    }>;
+    /** 响应里的 `profile.rowVersion` 就是写操作要回传的 If-Match 值。 */
+    getSubredditStyleProfile(id: string): Promise<{
+        profile: SubredditStyleProfileView;
+    }>;
+    getActiveSubredditStyleProfile(params: {
+        subreddit: string;
+        scope?: string;
+        brandId?: string;
+    }): Promise<unknown>;
+    proposeSubredditStyleProfile(body: Record<string, unknown>): Promise<{
+        profile: SubredditStyleProfileView;
+    }>;
+    /** 四眼审批 `proposed → approved`。提案人本人不可批(服务端 409 SELF_APPROVE)。 */
+    approveSubredditStyleProfile(input: SubredditStyleProfileTransitionInput): Promise<{
+        profile: SubredditStyleProfileView;
+    }>;
+    /** 审批人驳回 `proposed → retired`(`retire_reason=rejected:<reason>`)。 */
+    rejectSubredditStyleProfile(input: SubredditStyleProfileTransitionInput & {
+        reason: string;
+    }): Promise<{
+        profile: SubredditStyleProfileView;
+    }>;
+    /** 提案人本人撤回。worker/LLM 提案(proposedByUserId=NULL)不可 cancel,请用 reject。 */
+    cancelSubredditStyleProfile(input: SubredditStyleProfileTransitionInput & {
+        reason: string;
+    }): Promise<{
+        profile: SubredditStyleProfileView;
+    }>;
+    /** 停用已生效画像 `approved → retired`。 */
+    retireSubredditStyleProfile(input: SubredditStyleProfileTransitionInput & {
+        reason: string;
+    }): Promise<{
+        profile: SubredditStyleProfileView;
+    }>;
+    /**
+     * 四个 transition 的共同形状。
+     *
+     * 🔴 **`rowVersion` 是必传的,SDK 刻意不提供「缺省自动 GET 当前值」那种便利。**
+     * CLI 有这个便利(交互式使用,人就在现场),但库里自动 GET 会让一个**本意保护
+     * 特定版本**的写悄悄作用到最新版本 —— 乐观锁就此被架空,而且失败时毫无痕迹。
+     * 调用方要先 `getSubredditStyleProfile` 拿 `profile.rowVersion` 再传进来。
+     *
+     * 🔴 **409 PROFILE_STALE 一律原样抛出,绝不自动重取重试。** 自动重试等于替用户
+     * 认可了他没看过的那一版内容。
+     */
+    private styleProfileTransition;
     listSettings(): Promise<{
         items: Array<{
             key: string;