@geoly-ai/social-hub-sdk 0.0.54 → 0.0.56

package/dist/index.d.ts

@@ -759,6 +759,79 @@ export type ListReportsParams = {
     limit?: number;
     reportType?: "reddit-post-snapshot" | "account-status-snapshot" | "campaign-digest" | "agent-run-summary" | "style-curation-report" | "quota-violation-report" | "content-weekly";
 };
+/** `user_feishu_identities.resolve_status`（迁移 0144）。 */
+export type FeishuIdentityResolveStatus = "resolved" | "not_found" | "lookup_failed";
+/**
+ * 列表过滤值。比 {@link FeishuIdentityResolveStatus} 多一个 `unmapped` ——
+ * 那是「映射表里根本没有这一行」，在库里表示为 NULL 而不是某个状态值。
+ */
+export type FeishuIdentityListStatusFilter = FeishuIdentityResolveStatus | "unmapped";
+export type FeishuIdentityListItem = {
+    userId: string;
+    email: string;
+    name: string;
+    userStatus: string;
+    provider: string | null;
+    appId: string | null;
+    /** 未映射为 null；非 admin 读到的是脱敏值（见 `redacted`）。 */
+    openId: string | null;
+    unionId: string | null;
+    /** `null` = 从未同步过，与 `not_found` 不同。 */
+    resolveStatus: FeishuIdentityResolveStatus | null;
+    lastAttemptedAt: string | null;
+    lastResolvedAt: string | null;
+    lastErrorCode: string | null;
+};
+export type FeishuIdentityListResponse = {
+    items: FeishuIdentityListItem[];
+    /** true 表示 `openId`/`unionId` 已脱敏，不可回写。 */
+    redacted: boolean;
+    summary: {
+        total: number;
+        resolved: number;
+        notFound: number;
+        lookupFailed: number;
+        unmapped: number;
+    };
+};
+/**
+ * 写入条目。三个状态的字段集**互斥**（与契约的 discriminated union 同源）：
+ * 服务端 `.strict()`，多传字段是 400 而不是被忽略。
+ */
+export type FeishuIdentityUpsertEntry = {
+    userId: string;
+    resolveStatus: "resolved";
+    /** `^ou_[A-Za-z0-9]{1,128}$` —— 会被拼进飞书卡片的 `<at id=...>`。 */
+    openId: string;
+    unionId?: string | null;
+} | {
+    userId: string;
+    resolveStatus: "not_found";
+} | {
+    userId: string;
+    resolveStatus: "lookup_failed";
+    /** 必填 `^[a-z0-9_.-]{1,64}$`：没有错误码的失败无法排查。 */
+    lastErrorCode: string;
+};
+export type FeishuIdentityUpsertResult = {
+    userId: string;
+    requestedStatus: FeishuIdentityResolveStatus;
+    /** 实际落库状态：`lookup_failed` 撞上既有 `resolved` 时这里仍是 `resolved`。 */
+    storedStatus: FeishuIdentityResolveStatus;
+    mentionable: boolean;
+};
+export type UpsertFeishuIdentitiesResponse = {
+    provider: string;
+    appId: string;
+    results: FeishuIdentityUpsertResult[];
+    counts: {
+        resolved: number;
+        notFound: number;
+        lookupFailed: number;
+        /** `lookup_failed` 但保住了上次成功解析结果的条数。 */
+        preservedResolved: number;
+    };
+};
 /**
  * 四眼 registry proposal API 的结构化错误(D2):携带 HTTP status + 稳定 code + staleCode。
  * apply 的 409 + code PROPOSAL_STALE → isStale=true(消费方据此重新提案,保留 staleCode)。
@@ -794,6 +867,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 侧帖子快照证明发布账号不是该帖作者。
@@ -922,7 +1102,18 @@ export declare class SocialHubClient {
         queued: number;
         warning?: string;
     }>;
-    updateRedditPostSnapshot(teamId: string, snapshotId: string, body: Record<string, unknown>): Promise<{
+    /**
+     * 更新单条帖子快照。
+     *
+     * ⚠️ 把 `opsStatus` 改成 `deleted` / `banned` 时,**必须**同时带上必选项
+     * `repostRequired`(布尔:是否需补发),否则服务端 400 —— 这是刻意的 fail-closed,
+     * 「需补发」不会默认成 false。「需补发1 / 需补发2」的轮次由服务端按**原帖**的
+     * `repostType` 派生(首发→1、补发一次→2、补发二次→不问也不写),客户端传数字无效。
+     * 原帖 `repostType` 已是 `second` 时不需要带,带了也会被忽略。
+     */
+    updateRedditPostSnapshot(teamId: string, snapshotId: string, body: Record<string, unknown> & {
+        repostRequired?: boolean;
+    }): Promise<{
         ok: boolean;
     }>;
     deleteRedditPostSnapshot(teamId: string, snapshotId: string): Promise<{
@@ -2336,6 +2527,37 @@ export declare class SocialHubClient {
     listSystemUsers(): Promise<{
         items: unknown[];
     }>;
+    /**
+     * `GET /v1/system/feishu-identities` —— Hub 用户 ↔ 飞书 open_id 的映射现状。
+     *
+     * 返回**全体用户**（users LEFT JOIN 映射表），所以 `resolveStatus === null` 表示
+     * 「从未同步过」，与 `not_found`（查过、通讯录里没这人）是两回事。
+     *
+     * ⚠️ 非「不受限交互式 admin 登录」读到的 `openId`/`unionId` 是脱敏的 `ou_***`。
+     * 判据是响应里的 `redacted`，不要拿 `openId` 的字符串形态去猜 —— 脱敏值也以
+     * `ou_` 开头，直接透传会写出一个永远 @ 不到人的映射。
+     */
+    listFeishuIdentities(params?: {
+        provider?: string;
+        appId?: string;
+        status?: FeishuIdentityListStatusFilter;
+        includeInactiveUsers?: boolean;
+    }): Promise<FeishuIdentityListResponse>;
+    /**
+     * `PUT /v1/system/feishu-identities` —— 批量落库（幂等，同一批重放结果相同）。
+     *
+     * 写入面只认不受限的交互式 admin 登录：**API key 一律 403**，所以这个方法在
+     * 服务端到服务端的集成里不可用，它是给交互式运维工具（CLI/后台）用的。
+     *
+     * 语义上最贵的一条：`not_found` 会清空既有 `openId`（离职语义）。查询失败必须用
+     * `lookup_failed`（服务端会保住上次成功解析的值），把「没问出来」写成 `not_found`
+     * 等于静默注销一个本来能收到告警的人。
+     */
+    upsertFeishuIdentities(body: {
+        provider?: "feishu";
+        appId: string;
+        entries: FeishuIdentityUpsertEntry[];
+    }): Promise<UpsertFeishuIdentitiesResponse>;
     createSystemUser(body: {
         email: string;
         name: string;
@@ -2549,28 +2771,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?: {
@@ -3370,4 +3597,5 @@ export type NotificationPullResponseDto = {
  * 与 contracts `compareNotificationSeq` 同口径;SDK 侧复刻是因为不能引 contracts。
  */
 export declare function compareNotificationSeqStrings(left: string, right: string): number;
+export {};
 //# sourceMappingURL=index.d.ts.map