@geoly-ai/social-hub-sdk 0.1.17 → 0.1.19

package/dist/index.d.ts

@@ -198,6 +198,8 @@ export type ListRedditPostSnapshotsParams = {
     draftStatus?: string;
     postType?: string;
     repostType?: string;
+    /** 账号类型:`internal` / `external`,可逗号分隔;proxy / 海外兼职 / 未知 / 空值在选了任一项时不命中。 */
+    accountType?: string;
     containsBrandKeyword?: "true" | "false" | "unset";
     primaryProduct?: string;
     /**
@@ -223,6 +225,8 @@ export type RedditPostSnapshotStatsParams = {
     draftStatus?: string;
     postType?: string;
     repostType?: string;
+    /** 账号类型:`internal` / `external`,可逗号分隔;proxy / 海外兼职 / 未知 / 空值在选了任一项时不命中。 */
+    accountType?: string;
     containsBrandKeyword?: "true" | "false" | "unset";
     primaryProduct?: string;
     /** 序列号闭区间(与列表同口径)。 */
@@ -1208,6 +1212,170 @@ export type UpdateSubredditMonitorConfigBody = {
      */
     fetchLimit: number;
 };
+/** 公开库端点前缀(供应商无关)。 */
+export declare const PUBLIC_REDDIT_BASE_PATH = "/v1/system/public-reddit";
+export declare const PUBLIC_REDDIT_PATHS: {
+    readonly communities: "/v1/system/public-reddit/communities";
+    readonly posts: "/v1/system/public-reddit/posts";
+    readonly postCounts: "/v1/system/public-reddit/post-counts";
+    readonly status: "/v1/system/public-reddit/status";
+};
+/**
+ * 公开库错误码(服务端 `error.code`)。🔴 `DISABLED` / `POLICY_DENIED` / `AUTH_FAILED` 等
+ * 都是「读不到」而**不是**「没有数据」,调用方绝不能把它们当成空结果。
+ */
+export declare const PUBLIC_REDDIT_ERROR_CODES: {
+    readonly DISABLED: "PUBLIC_REDDIT_DISABLED";
+    readonly BUDGET_EXHAUSTED: "PUBLIC_REDDIT_BUDGET_EXHAUSTED";
+    readonly DEGRADED: "PUBLIC_REDDIT_DEGRADED";
+    readonly COUNT_TIMEOUT: "PUBLIC_REDDIT_COUNT_TIMEOUT";
+    readonly RATE_LIMITED: "PUBLIC_REDDIT_RATE_LIMITED";
+    readonly AUTH_FAILED: "PUBLIC_REDDIT_AUTH_FAILED";
+    readonly POLICY_DENIED: "PUBLIC_REDDIT_POLICY_DENIED";
+    readonly COMMUNITY_NOT_AVAILABLE: "PUBLIC_REDDIT_COMMUNITY_NOT_AVAILABLE";
+    readonly SCOPE_TOO_LARGE: "PUBLIC_REDDIT_SCOPE_TOO_LARGE";
+    readonly QUERY_REQUIRED: "PUBLIC_REDDIT_QUERY_REQUIRED";
+    readonly INVALID_REQUEST: "PUBLIC_REDDIT_INVALID_REQUEST";
+    readonly INVALID_WINDOW: "PUBLIC_REDDIT_INVALID_WINDOW";
+    readonly INVALID_COMMUNITY: "PUBLIC_REDDIT_INVALID_COMMUNITY";
+    readonly CURSOR_MISMATCH: "PUBLIC_REDDIT_CURSOR_MISMATCH";
+    readonly CURSOR_RESET: "PUBLIC_REDDIT_CURSOR_RESET";
+    readonly UNAVAILABLE: "PUBLIC_REDDIT_UNAVAILABLE";
+    readonly BAD_UPSTREAM_RESPONSE: "PUBLIC_REDDIT_BAD_UPSTREAM_RESPONSE";
+};
+export type PublicRedditNamedWindow = "day" | "week" | "month" | "last_90d" | "last_360d" | "last_full_week";
+/** 窗口:命名窗口与显式 [from,to) 二选一(服务端校验互斥)。 */
+export type PublicRedditWindowParams = {
+    window?: PublicRedditNamedWindow;
+    from?: string;
+    to?: string;
+};
+export type ListPublicRedditCommunitiesParams = {
+    /** 数组按逗号拼接(与服务端 csv 形状一致)。 */
+    industryKey?: string | string[];
+    tierKey?: string | string[];
+    poolKind?: string | string[];
+    hasProfile?: boolean;
+    limit?: number;
+    /** Hub 令牌:原样回传上一页的 nextCursor。 */
+    cursor?: string;
+};
+export type SearchPublicRedditPostsParams = PublicRedditWindowParams & {
+    /** 必填、≤20 个;数组按逗号拼接。 */
+    subreddit: string | string[];
+    /** ⚠️ 会发往外部数据服务。 */
+    query?: string;
+    sort?: "created_at_desc";
+    limit?: number;
+    cursor?: string;
+    includeBody?: boolean;
+};
+export type CountPublicRedditPostsBody = PublicRedditWindowParams & {
+    subreddits: string[];
+    /** 必填;⚠️ 会发往外部数据服务。 */
+    query: string;
+    artifactType?: "post" | "comment";
+};
+export type PublicRedditSourceMeta = {
+    provider: "cyberredd";
+    mode: "off" | "shadow" | "on";
+    dataCutoff: string | null;
+    resolvedWindow: {
+        from: string;
+        to: string;
+        name: string | null;
+    } | null;
+    fetchedAt: string;
+    cached: boolean;
+    excludedCommunities: Array<{
+        communityId: string;
+        reason: string;
+    }>;
+    warnings: Array<{
+        code: string;
+        message?: string;
+    }>;
+};
+export type PublicRedditCommunity = {
+    communityId: string;
+    name: string | null;
+    url: string | null;
+    industryKeys: string[] | null;
+    tierKey: string | null;
+    poolKind: string | null;
+    hasProfile: boolean | null;
+    dataCutoff: string | null;
+};
+export type PublicRedditPost = {
+    upstreamId: string;
+    redditPostId: string | null;
+    communityId: string;
+    title: string | null;
+    bodyExcerpt: string | null;
+    body?: string | null;
+    authorName: string | null;
+    createdAt: string | null;
+    url: string | null;
+    contentState: string | null;
+    observationStatus: string | null;
+    intent: string | null;
+    sentiment: string | null;
+    labelVocabulary: "cyberredd_v1";
+};
+export type ListPublicRedditCommunitiesResponse = {
+    items: PublicRedditCommunity[];
+    nextCursor: string | null;
+    source: PublicRedditSourceMeta;
+};
+export type SearchPublicRedditPostsResponse = {
+    items: PublicRedditPost[];
+    nextCursor: string | null;
+    source: PublicRedditSourceMeta;
+};
+export type CountPublicRedditPostsResponse = {
+    artifactType: "post" | "comment";
+    window: {
+        from: string;
+        to: string;
+        name: string | null;
+    };
+    exact: boolean;
+    /** exact=false 时为 null,绝不是部分和。 */
+    total: number | null;
+    communities: Array<{
+        communityId: string;
+        status: string;
+        count: number | null;
+        dataCutoff: string | null;
+        windowCovered: boolean | null;
+    }>;
+    source: PublicRedditSourceMeta;
+};
+export type PublicRedditStatus = {
+    mode: "off" | "shadow" | "on";
+    capabilities: Array<"catalog" | "post_search" | "post_count">;
+    configured: boolean;
+    keyFingerprint: string | null;
+    keyExpiresAt: string | null;
+    credential: Record<string, unknown>;
+    breaker: {
+        state: string;
+        openedAt: string | null;
+    };
+    budget: {
+        windowSeconds: number;
+        limit: number;
+        used: number;
+    };
+    catalogIndex: {
+        size: number | null;
+        refreshedAt: string | null;
+    };
+    lastError: {
+        code: string;
+        at: string;
+    } | null;
+};
 export type ListHotPostsParams = {
     limit?: number;
     offset?: number;
@@ -1681,6 +1849,57 @@ export type ScrapeUrlResponse = (ScrapeResponseCommon & {
 export declare const CONTENT_REVIEW_AUTHOR_RELATION_MISMATCH: "AUTHOR_RELATION_MISMATCH";
 /** 该错误是否为 {@link CONTENT_REVIEW_AUTHOR_RELATION_MISMATCH}(422 + 稳定 code)。 */
 export declare function isAuthorRelationMismatchError(error: unknown): error is SocialHubHttpError;
+/**
+ * 页面周指标(周访客 / 周贡献)—— 与 contracts `OwnedSubredditWeeklyStats*` 同形。
+ * SDK 不能 import contracts(private 包),所以这里手写镜像;改契约时同步这里。
+ */
+export type OwnedSubredditWeeklyMetric = {
+    /** 页面原文,如 "1.2K";从未命中为 null。 */
+    text: string | null;
+    /** 解析后的整数;原文解析不了为 null(此时 text 仍在)。 */
+    num: number | null;
+    observedAt: string | null;
+    status: "ok" | "missing" | "stale";
+    /** 与相邻上一 UTC 周的环比(%);前值缺失 / 为 0 / 不可解析为 null(⛔ 不是 0)。 */
+    deltaPct: number | null;
+};
+export type OwnedSubredditWeeklyLastAttempt = {
+    at: string;
+    outcome: "ok" | "failed" | "not_visible" | "quota_skipped";
+    reason: string | null;
+};
+export type OwnedSubredditWeeklyStats = {
+    weekStart: string | null;
+    visitors: OwnedSubredditWeeklyMetric;
+    contributions: OwnedSubredditWeeklyMetric;
+    lastAttempt: OwnedSubredditWeeklyLastAttempt | null;
+};
+export type OwnedSubredditWeeklyTrendMetricPoint = {
+    text: string;
+    num: number | null;
+    observedAt: string;
+};
+export type OwnedSubredditWeeklyTrend = {
+    ownedSubredditId: string;
+    name: string;
+    weeks: number;
+    /** 长度恒为 weeks,旧 → 新;缺周的指标为 null(不压缩、不补 0)。 */
+    points: Array<{
+        weekStart: string;
+        visitors: OwnedSubredditWeeklyTrendMetricPoint | null;
+        contributions: OwnedSubredditWeeklyTrendMetricPoint | null;
+    }>;
+    lastAttempt: OwnedSubredditWeeklyLastAttempt | null;
+};
+export type OwnedSubredditWeeklyRefreshAccepted = {
+    status: "queued";
+    ownedSubredditId: string;
+    subreddit: string;
+    runId: string;
+    businessDate: string;
+    /** 下一业务日起点(同一板块下次允许再手动刷新的最早时刻)。 */
+    nextAllowedAt: string;
+};
 export declare class SocialHubClient {
     private readonly opts;
     constructor(opts: SocialHubClientOptions);
@@ -2732,6 +2951,9 @@ export declare class SocialHubClient {
         items: unknown[];
         total: number;
     }>;
+    /**
+     * 评论样本列表。⚠️ 只含 Hub 内现有评论样本(非归档,约 5.7 万条);历史/归档评论已迁至 CyberRedd。
+     */
     listRedditCommentSamples(params?: {
         postId?: string;
         subreddit?: string;
@@ -2761,6 +2983,7 @@ export declare class SocialHubClient {
      * (totalRelation=unavailable)。
      * ⚠️ 无过滤时是全表精确 count,属昂贵读——基线用途,**禁止轮询**。
      * 口径是库内 reddit_comment_samples 行数,不是 Reddit 线程真实评论总数。
+     * ⚠️ 只含 Hub 内现有评论样本(非归档,约 5.7 万条);历史/归档评论已迁至 CyberRedd。
      */
     countRedditCommentSamples(params?: {
         postId?: string;
@@ -3191,6 +3414,17 @@ export declare class SocialHubClient {
         }>;
     }>;
     exportHotPostsCsv(params?: ListHotPostsParams): Promise<string>;
+    /** GET /v1/system/public-reddit/communities — 公开库社区目录(只读;系统级,无 team 前缀)。 */
+    listPublicRedditCommunities(params?: ListPublicRedditCommunitiesParams): Promise<ListPublicRedditCommunitiesResponse>;
+    /** GET /v1/system/public-reddit/posts — 公开库帖子检索(必须带板块;query 会发往外部数据服务)。 */
+    searchPublicRedditPosts(params: SearchPublicRedditPostsParams): Promise<SearchPublicRedditPostsResponse>;
+    /**
+     * POST /v1/system/public-reddit/post-counts — 公开库计数。
+     * ⚠️ 昂贵读,禁止轮询;必须带 query;query 会发往外部数据服务。
+     */
+    countPublicRedditPosts(body: CountPublicRedditPostsBody): Promise<CountPublicRedditPostsResponse>;
+    /** GET /v1/system/public-reddit/status — 开关/熔断/预算(仅 unrestricted admin)。 */
+    getPublicRedditStatus(): Promise<PublicRedditStatus>;
     listKolIntents(params?: ListKolIntentsParams): Promise<{
         items: unknown[];
         total: number;
@@ -4122,6 +4356,24 @@ export declare class SocialHubClient {
     }): Promise<{
         items: unknown[];
     }>;
+    /**
+     * GET :id/weekly-stats — 板块页面周指标趋势(周访客 / 周贡献,默认 12 周,最多 52)。
+     *
+     * 返回长度恒为 `weeks` 的按周序列(旧 → 新);缺周的指标为 null —— ⛔ 不是 0。
+     * 列表接口 `listOwnedSubreddits` 的每行另带 `weeklyStats`(当前值 + 环比)。
+     */
+    getOwnedSubredditWeeklyStats(ownedSubredditId: string, params?: {
+        weeks?: number;
+    }): Promise<OwnedSubredditWeeklyTrend>;
+    /**
+     * POST :id/weekly-stats/refresh — 手动刷新该板块的页面周指标(202 入队)。
+     *
+     * 每板块每业务日最多真实抓一次:当日已抓/已入队 → 409,`error.details.code` 为
+     * `refresh_already_charged_today`,`details.nextAllowedAt` 是下一业务日起点;
+     * 其余稳定码见 contracts `WEEKLY_STATS_REFRESH_REJECT_CODES`。
+     * 仅 active 资产;写权限同其它写端点(真实登录 admin,拒 API Key)。
+     */
+    refreshOwnedSubredditWeeklyStats(ownedSubredditId: string): Promise<OwnedSubredditWeeklyRefreshAccepted>;
     /** GET :id — 单条资产详情（不可见时返 404，不返 403：避免变成枚举面）。 */
     getOwnedSubreddit(ownedSubredditId: string): Promise<unknown>;
     /**