@geoly-ai/social-hub-sdk 0.0.57 → 0.1.0

package/dist/index.d.ts

@@ -352,6 +352,68 @@ export type ListCommentDraftsParams = {
     /** 把聚合收窄到指定可见团队(逗号拼);空数组=不收窄。 */
     scopeTeamIds?: string[];
 };
+/**
+ * R12(迁移 0153)——「**显式**声明这条内容不做品牌提及」。
+ *
+ * 只有 `"none"` 一个值,对应契约的 `brandMentionDeclarationSchema`
+ * (`packages/contracts/src/brand-mention-declaration.ts`)。
+ *
+ * 🔴 **缺失 ≠ 无意图**:省略 `brandId` 而不带这个声明,服务端按「忘了传」判 400,
+ * 不会静默降级成无品牌。判定规则全在服务端(`refineBrandMentionDeclaration` +
+ * 路由的四值比较 + db 层兜底),**SDK 只表达类型、不复刻校验** —— 复刻必然两边漂移。
+ */
+export type BrandMentionDeclaration = "none";
+/**
+ * `POST /content-drafts` 的 body。
+ *
+ * ⚠️ `brandId` 与 `brandMention` 的互斥/必填关系**故意不用类型联合表达**:
+ * 服务端的 `superRefine` 是唯一判定处,在 SDK 里再写一遍会漂移(见
+ * {@link BrandMentionDeclaration})。类型只负责让「无品牌草稿」可以被表达出来。
+ */
+export type CreateContentDraftBody = {
+    /** R12:可选。省略时**必须**同时显式给 `brandMention: "none"`(服务端校验)。 */
+    brandId?: string;
+    /** R12:显式声明本草稿不做品牌提及。见 {@link BrandMentionDeclaration}。 */
+    brandMention?: BrandMentionDeclaration;
+    /** @deprecated legacy 归因;新草稿只用 brandId。 */
+    campaignId?: string;
+    title: string;
+    body: string;
+    /** 目标板块(内容语义真源);服务端规范化后落库。省略/null → NULL。 */
+    subreddit?: string | null;
+    /**
+     * 写作参考 / 归因备注 URL:「这篇内容围绕哪个落地页写的」。
+     * ⚠️ **不参与发布执行** —— 系统没有 Reddit link post 概念,执行只冻结 title+body。
+     */
+    referenceUrl?: string | null;
+};
+/** `POST /publishing-plans` 里的单条待排期条目。 */
+export type CreatePublishingPlanEntryInput = {
+    contentDraftId?: string;
+    socialAccountId: string;
+    subreddit: string;
+    /** ISO-8601 datetime。 */
+    plannedAt: string;
+    /** 缺省 = `hub_managed`。见 {@link CalendarEntryDeliveryMode}。 */
+    deliveryMode?: CalendarEntryDeliveryMode;
+};
+/**
+ * `POST /publishing-plans` 的 body(此前是 `Record<string, unknown>`,运行时不挡、
+ * 类型也表达不出 R12 的无品牌计划)。
+ *
+ * ⚠️ 与 {@link CreateContentDraftBody} 同理:brandId / brandMention 的四条 fail-closed
+ * 规则**只在服务端**判,SDK 不复刻。
+ */
+export type CreatePublishingPlanBody = {
+    /** R12:可选。省略时**必须**同时显式给 `brandMention: "none"`(服务端校验)。 */
+    brandId?: string;
+    /** R12:显式声明本计划不做品牌提及。见 {@link BrandMentionDeclaration}。 */
+    brandMention?: BrandMentionDeclaration;
+    /** @deprecated legacy 归因。 */
+    campaignId?: string;
+    name: string;
+    entries: CreatePublishingPlanEntryInput[];
+};
 export type CreateCommentDraftBody = {
     brandId: string;
     campaignId?: string;
@@ -636,6 +698,13 @@ export type ListScheduledJobsParams = {
     from?: string;
     to?: string;
 };
+export type ListAccountRiskProfilesParams = {
+    /** 服务端上限 200;缺省 100。 */
+    limit?: number;
+    /** 翻页起始偏移量(offset,不是 cursor):每次 += limit。 */
+    offset?: number;
+    search?: string;
+};
 export type ListAccountsParams = {
     limit?: number;
     offset?: number;
@@ -996,7 +1065,19 @@ export declare class SocialHubClient {
     private teamBase;
     /** GET /health — no API key required. */
     getHealth(): Promise<HealthCheckJson>;
+    /**
+     * 绝对 URL 拼接的**唯一**入口:`path` 一律是站内相对路径(如 `/v1/teams/x/events`)。
+     * 直接把相对路径交给 `fetch()` 在 Node 下会抛
+     * `TypeError: Failed to parse URL from /v1/...`,所以新增请求方法必须走这里。
+     */
+    private buildUrl;
+    /** 鉴权 + 默认 Content-Type;调用方 headers 覆盖默认值(与历史行为一致)。 */
+    private buildHeaders;
+    /** 共享请求管线:统一 base-url 拼接、鉴权头与错误体解析,返回原始响应文本。 */
+    private requestText;
     private fetchJson;
+    /** 与 `fetchJson` 同一条 base-url/鉴权/错误处理路径,但返回文本(CSV 等非 JSON 响应)。 */
+    private fetchText;
     appendEvent(teamId: string, body: {
         type: string;
         socialAccountId?: string;
@@ -1234,19 +1315,7 @@ export declare class SocialHubClient {
         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<{
+    createContentDraft(teamId: string, body: CreateContentDraftBody): Promise<{
         id: string;
     }>;
     /**
@@ -1414,6 +1483,10 @@ export declare class SocialHubClient {
     }): Promise<unknown>;
     listAccounts(teamId: string, params?: ListAccountsParams): Promise<{
         items: unknown[];
+        /** 满足过滤条件的总数(与 limit/offset 无关);翻页终止判据。 */
+        total?: number;
+        limit?: number;
+        offset?: number;
     }>;
     createAccount(teamId: string, body: Record<string, unknown>): Promise<{
         id: string;
@@ -1607,7 +1680,7 @@ export declare class SocialHubClient {
     listPublishingPlans(teamId: string, params?: ListPublishingPlansParams): Promise<{
         items: unknown[];
     }>;
-    createPublishingPlan(teamId: string, body: Record<string, unknown>): Promise<unknown>;
+    createPublishingPlan(teamId: string, body: CreatePublishingPlanBody): Promise<unknown>;
     listAuditLogs(teamId: string, params?: ListAuditLogsParams): Promise<{
         items: unknown[];
     }>;
@@ -1797,8 +1870,23 @@ export declare class SocialHubClient {
     deleteSubredditSanction(teamId: string, id: string): Promise<{
         ok: boolean;
     }>;
-    listAccountRiskProfiles(teamId: string, limit?: number): Promise<{
+    /**
+     * 列出团队下账号的风险画像。
+     *
+     * `limit` 上限 200(contracts `listAccountRiskProfilesQuerySchema`),所以账号数
+     * 超过 200 的 team 必须用 `offset` 翻页,否则会**静默截断**。第二参数保留
+     * `number` 形式只为兼容已发布包的老调用方(等价于 `{ limit }`)。
+     */
+    listAccountRiskProfiles(teamId: string, paramsOrLimit?: number | ListAccountRiskProfilesParams): Promise<{
         items: unknown[];
+        /**
+         * 满足过滤条件的总数(与 limit/offset 无关)。集合在翻页期间不变时可用作
+         * 翻页终止判据;offset 分页不是快照分页,并发写入下 total 会漂移,
+         * 同一行也可能重复出现或被跳过。
+         */
+        total?: number;
+        limit?: number;
+        offset?: number;
     }>;
     getAccountRiskProfile(teamId: string, socialAccountId: string): Promise<unknown>;
     upsertAccountRiskProfile(teamId: string, socialAccountId: string, body: Record<string, unknown>): Promise<unknown>;
@@ -3160,6 +3248,8 @@ export declare class SocialHubClient {
         items: {
             sourceId: string;
             canonicalTopic: string;
+            /** source **类型**展示名的 i18n key（registry 真源；不是模板的 displayName）。 */
+            labelKey: string;
             sourceDefinitionVersion: number;
             payloadSchemaVersion: string;
             activeTemplate: NotificationSourceTemplateDto | null;
@@ -3685,7 +3775,13 @@ export type PublishingCalendarPreflightRejectionReason =
 /** 条目没绑草稿,或草稿行已不在。 */
  | "draft_detached"
 /** 当前草稿的 canonical review target 不存在、身份漂移,或状态不是 `passed`。 */
- | "review_not_passed";
+ | "review_not_passed"
+/**
+ * 发布护栏判定当前不可发布(账号被封/受限、cluster 暂停等)。
+ * **与其余 reason 不同:这条通常是暂时的,不要删 cron**,按原节奏重试即可。
+ * 护栏评估本身失败不走这条(那是 5xx 系统故障)。
+ */
+ | "guardrail_blocked";
 /** preflight 放行：**唯一**能拿到正文的分支。 */
 export type PublishingCalendarPreflightOkDto = {
     decision: "ok";
@@ -3741,7 +3837,15 @@ export type CalendarEntryListItemDto = {
     id: string;
     teamId: string;
     publishingPlanId: string;
-    brandId: string;
+    /**
+     * R12(迁移 0153):**可为 null** —— `null` 表示这条条目所属计划显式声明了
+     * 无品牌提及(`plan.brandId` 与 `campaign.brandId` 都是 NULL)。
+     *
+     * 读侧对 `brands` 已由 innerJoin 改成 **leftJoin**,无品牌行不再被静默丢掉,
+     * 所以服务端**确实会**在这里回 null。契约真源:
+     * `packages/contracts/src/publishing-plans.ts` 的 `calendarEntryListItemSchema`。
+     */
+    brandId: string | null;
     /** legacy；brand-first 建的计划为 null。 */
     campaignId: string | null;
     contentDraftId: string | null;
@@ -3762,7 +3866,11 @@ export type CalendarEntryListItemDto = {
     createdAt: string;
     /** 迁移 0149 起维护；更早的真实修改时间已不可考。 */
     updatedAt?: string;
-    brandName: string;
+    /**
+     * R12:无品牌条目没有 `brands` 行可 join → **null**(不是空串)。
+     * ⚠️ 直接 `.toUpperCase()` / `.slice()` 会在运行时炸;先判空再用。
+     */
+    brandName: string | null;
     campaignName: string | null;
     socialAccountHandle: string | null;
     socialAccountPlatform: string;