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

package/dist/index.d.ts

@@ -1849,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);
@@ -4305,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>;
     /**