@appthen/sdk-core 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -273,8 +273,17 @@ export interface CreateMessageInput {
     status?: string;
     metadata?: Record<string, unknown>;
 }
+/** 入口客户端信号：网关只认白名单 kind 与短 deviceId，用于运行时路由。 */
+export interface ChatHubEntryClientSignal {
+    kind: 'web' | 'desktop' | 'mobile';
+    deviceId?: string;
+}
+/** 运行偏好：auto = 服务端按入口策略决定；cloud = 用户显式选择云端执行。 */
+export type ChatHubRuntimePreference = 'auto' | 'cloud';
 export interface CreateInternalMessageInput extends CreateMessageInput {
     tenantId: string;
+    client?: ChatHubEntryClientSignal;
+    runtimePreference?: ChatHubRuntimePreference;
 }
 export interface QueryMessagesInput {
     tenantId?: string;
@@ -298,7 +307,26 @@ export interface QueryConversationsInput {
     status?: string;
     createdBySubjectId?: string;
     subjectId?: string;
+    /** 分页（P1）：不传即全量（保持历史行为）。 */
+    limit?: number;
+    offset?: number;
+    /** keyset 游标（上一页最后一条的 encode 结果，见 encodeConversationListCursor）。 */
+    cursor?: string;
+    /** 服务端搜索：标题 / conversationId 纯文本匹配（不区分大小写）。 */
+    search?: string;
+}
+/**
+ * 会话列表游标（keyset 分页，P1）：与服务端 conversation-list-cursor.util 同构。
+ * 载荷 = base64url(JSON { u: updatedAt 毫秒, c: conversationId })。
+ * 客户端从「当前列表最后一条」构造；服务端按 (updatedAt desc, conversationId desc) 续页。
+ */
+export interface ConversationListCursorPayload {
+    updatedAt: number;
+    conversationId: string;
 }
+export declare function encodeConversationListCursor(payload: ConversationListCursorPayload): string;
+/** 从会话记录构造游标（读取 updatedAt；缺失/非法返回 null）。 */
+export declare function buildConversationListCursorFromRecord(record: Record<string, unknown> | null | undefined): string | null;
 export interface CreateInternalConversationInput extends CreateConversationInput {
     tenantId: string;
 }
@@ -421,6 +449,10 @@ export interface SendTextMessageOptions {
     mentionedSubjectIds?: string[];
     metadata?: Record<string, unknown>;
     status?: string;
+    /** 这条消息从哪种客户端发出（运行时路由信号）。 */
+    client?: ChatHubEntryClientSignal;
+    /** 仅显式选择云端执行时传 `cloud`；默认不传 = 服务端按 auto 处理。 */
+    runtimePreference?: ChatHubRuntimePreference;
 }
 export interface SendChatHubMessageOptions {
     conversationId: string;
@@ -431,6 +463,8 @@ export interface SendChatHubMessageOptions {
     mentionedSubjectIds?: string[];
     metadata?: Record<string, unknown>;
     status?: string;
+    client?: ChatHubEntryClientSignal;
+    runtimePreference?: ChatHubRuntimePreference;
 }
 export interface ListChatHubMessagesOptions {
     conversationId: string;
@@ -560,7 +594,14 @@ export declare class ChatHubAppRuntime {
     updateConversationRead(input: ConversationReadStateInput): Promise<void>;
     ensureAuthenticated(): Promise<void>;
     bootstrapConversation(): Promise<ChatHubBootstrapResult>;
-    listConversations(subjectId?: string): Promise<ConversationRecord[]>;
+    listConversations(subjectId?: string, options?: {
+        /** 分页（P1）：不传 limit 即全量（历史行为）。 */
+        limit?: number;
+        /** keyset 游标（上一页最后一条的 encode 结果）。 */
+        cursor?: string;
+        /** 服务端搜索：标题 / conversationId 纯文本匹配。 */
+        search?: string;
+    }): Promise<ConversationRecord[]>;
     listMessages(input: string | ListChatHubMessagesOptions): Promise<ConversationMessageRecord[]>;
     listMessagesPage(input: string | ListChatHubMessagesOptions): Promise<ListChatHubMessagesPageResult>;
     ensureParticipant(input: CreateParticipantInput): Promise<Record<string, unknown>>;
@@ -582,6 +623,12 @@ export interface PlatformProvisionTenantInput {
     externalCorrelationId: string;
     /** 该租户被授予的 platform scope，缺省 ['platform:subject:sync']。 */
     grantScopes?: string[];
+    adminIdentifiers?: PlatformAdminIdentifier[];
+    adminDisplayName?: string;
+}
+export interface PlatformAdminIdentifier {
+    type: 'phone' | 'email';
+    value: string;
 }
 export interface PlatformProvisionTenantResult {
     tenantId: string;
@@ -590,6 +637,8 @@ export interface PlatformProvisionTenantResult {
     grantId: string;
     /** 仅首次开通返回（7d 有效）；认领激活时提交。 */
     claimToken?: string;
+    inviteId?: string;
+    inviteUrl?: string;
     /** false = 幂等命中（同 platformId + externalCorrelationId 已开通过）。 */
     created: boolean;
     [key: string]: unknown;
@@ -600,6 +649,11 @@ export interface PlatformExternalIdentityInput {
     displayLabel?: string;
     metadata?: Record<string, unknown>;
 }
+export interface PlatformLoginIdentifierInput {
+    /** 登录渠道。v1 仅支持 `phone`（邮箱/工号等预留，新增渠道不改契约形状）。 */
+    provider: 'phone' | string;
+    value: string;
+}
 export interface PlatformSyncSubjectInput {
     classId: string;
     displayName: string;
@@ -611,6 +665,32 @@ export interface PlatformSyncSubjectInput {
     tags?: string[];
     /** 命中已存在主体时是否更新其可写字段，默认 false（纯幂等）。 */
     updateOnMatch?: boolean;
+    /**
+     * 登录标识（v1 = 手机号）。**带上才可登录**——平台据此把"这个成员"与
+     * "用该标识登录的人"对上；不带不算错，但该主体只作为通讯录/圈人对象存在，
+     * 登录时列不出来。
+     *
+     * 语义要点：
+     * - 与 `updateOnMatch` **正交**：传入即补绑（命中已存在主体时同样生效），
+     *   所以"先同步→后拿到手机号→再推一次"即可让身份变得可用；
+     * - **不传 ≠ 解绑**（缺席不代表移除）；
+     * - 同一标识可同时挂在多个主体上（例如第三方系统里同一手机号对应
+     *   「用户前台」「员工后台」两个账号空间）——平台按声明如实挂载，不自行归并；
+     * - 系统内**首次**挂载该标识的主体为「主身份」，用于登录时的默认选择。
+     */
+    loginIdentifiers?: PlatformLoginIdentifierInput[];
+    /**
+     * 身份标签：**由第三方声明的短标签**（如「用户前台」/「员工后台」），
+     * 用于在工作台的「切换身份」里区分同一个人的多个身份。
+     *
+     * 语义要点：
+     * - 平台**只提供字段，不发明语义**：值原样展示，不翻译、不判定、不造词；
+     *   不传时界面回退到角色（member / admin / owner）。
+     * - 属**内容字段**（与 `displayName` / `tags` 同规则）：建时落库；命中已存在
+     *   主体时**仅在 `updateOnMatch: true` 下覆盖**，不传不会被清空。
+     * - 建议 ≤ 4 个字（行内展示位有限）；接口上限 64 字符，超长返回 400。
+     */
+    identityLabel?: string;
     /** 幂等键：{source, externalKey}。重复推送只产生一个 Subject，可安全重试。 */
     externalIdentity: PlatformExternalIdentityInput;
 }
@@ -630,10 +710,21 @@ export interface PlatformResolveTenantResult {
         status: string;
     }>;
 }
+export interface PlatformAdminInviteInput {
+    adminIdentifiers: PlatformAdminIdentifier[];
+    adminDisplayName?: string;
+}
+export interface PlatformAdminInviteResult {
+    tenantId: string;
+    status: string;
+    inviteId: string;
+    inviteUrl: string;
+}
 export declare class PlatformApi extends BaseApi {
     provisionTenant(input: PlatformProvisionTenantInput): Promise<PlatformProvisionTenantResult>;
     syncSubject(targetTenantId: string, input: PlatformSyncSubjectInput): Promise<PlatformSyncSubjectResult>;
     resolveTenant(externalCorrelationId: string): Promise<PlatformResolveTenantResult>;
+    createAdminInvite(tenantId: string, input: PlatformAdminInviteInput): Promise<PlatformAdminInviteResult>;
     toggleGrant(grantId: string, status: 'active' | 'revoked'): Promise<Record<string, unknown>>;
     /**
      * 按标签/条件圈人并直接触达（声明式，调用方无 subjectId 概念）：
@@ -642,6 +733,21 @@ export declare class PlatformApi extends BaseApi {
      * 收件人二选一：标签圈人（selector）或单点声明（receive，如微信客服消息迁移）。
      */
     notify(targetTenantId: string, request: PlatformNotifyRequest, notify: PlatformNotifyInput): Promise<PlatformNotifyResult>;
+    /**
+     * 重发认领凭证（平台级）：租户 7 天内未认领时，服务商重新签发 claimToken。
+     * **重发即作废**——epoch 递增，旧 token 立即失效；仅 pending 租户可重发。
+     */
+    reissueClaimToken(tenantId: string): Promise<PlatformReissueClaimTokenResult>;
+}
+/** 重发认领凭证的返回（claimToken 有效期 7 天；重发后旧 token 立即失效）。 */
+export interface PlatformReissueClaimTokenResult {
+    tenantId: string;
+    status: string;
+    claimToken: string;
+    expiresIn: string;
+    /** 签发轮次：0 = 首次开通签发，>=1 = 第 N 次重发。 */
+    claimEpoch: number;
+    reissued: boolean;
 }
 /** 声明式主体引用：调用方只需本地维护 id/昵称/头像，服务端 lazily create-or-get。 */
 export interface PlatformLazySubject {

package/dist/index.js

@@ -10,6 +10,27 @@
  * - 内部 JWT 保护的查询接口（messages / conversations）
  */
 export const SDK_VERSION = '0.1.0';
+export function encodeConversationListCursor(payload) {
+    const json = JSON.stringify({ u: payload.updatedAt, c: payload.conversationId });
+    // 同时兼容浏览器（btoa，需先转 latin1）与 Node（Buffer）：base64url 无 padding。
+    const base64 = typeof Buffer !== 'undefined'
+        ? Buffer.from(json, 'utf8').toString('base64')
+        : btoa(unescape(encodeURIComponent(json)));
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+/** 从会话记录构造游标（读取 updatedAt；缺失/非法返回 null）。 */
+export function buildConversationListCursorFromRecord(record) {
+    const conversationId = typeof record?.conversationId === 'string' ? record.conversationId : '';
+    const rawUpdatedAt = record?.updatedAt;
+    const updatedAt = typeof rawUpdatedAt === 'number'
+        ? rawUpdatedAt
+        : typeof rawUpdatedAt === 'string'
+            ? Date.parse(rawUpdatedAt)
+            : NaN;
+    if (!conversationId || !Number.isFinite(updatedAt) || updatedAt <= 0)
+        return null;
+    return encodeConversationListCursor({ updatedAt, conversationId });
+}
 export function resolveChatHubMessagePolicy(value) {
     const policy = value && typeof value === 'object' ? value : {};
     return {
@@ -22,6 +43,12 @@ export function resolveChatHubMessagePolicy(value) {
         allowRevoke: policy.allowRevoke === true,
     };
 }
+/**
+ * 断线补齐时一次 refresh 最多向后续拉的页数（防单次同步打爆服务端）。
+ * 每页按 watch 的 limit（上限 100），20 页 = 最多 2000 条，
+ * 覆盖任何合理的断线积压；真超过这个量级应走历史分页而不是实时补齐。
+ */
+const MAX_CATCHUP_PAGES = 20;
 function withBearerToken(headers, token) {
     if (!token) {
         return headers || {};
@@ -384,13 +411,16 @@ export class ChatHubAppRuntime {
             conversation,
         };
     }
-    async listConversations(subjectId) {
+    async listConversations(subjectId, options) {
         await this.ensureAuthenticated();
         const resolvedSubjectId = subjectId || this.config.subjects?.[0]?.subjectId || undefined;
         const conversations = await this.client.conversations.list({
             tenantId: this.tenantId,
             typeId: this.config.conversationType?.typeId,
             subjectId: resolvedSubjectId,
+            ...(options?.limit ? { limit: options.limit } : {}),
+            ...(options?.cursor ? { cursor: options.cursor } : {}),
+            ...(options?.search ? { search: options.search } : {}),
         });
         // Participants are intentionally NOT fetched here: doing so would fan out
         // one `/conversation-runtime/participants` HTTP request per conversation
@@ -506,22 +536,41 @@ export class ChatHubAppRuntime {
             if (refreshPromise) {
                 return refreshPromise;
             }
-            const afterSequence = lastSequence;
             refreshPromise = (async () => {
                 try {
-                    const messages = await this.listMessages({
-                        conversationId: options.conversationId,
-                        limit,
-                        afterSequence,
-                    });
-                    const maxSequence = messages.reduce((current, message) => {
-                        const sequence = typeof message.sequence === 'number' && Number.isFinite(message.sequence)
-                            ? Math.floor(message.sequence)
-                            : current;
-                        return Math.max(current, sequence);
-                    }, lastSequence);
-                    lastSequence = Math.max(lastSequence, maxSequence);
-                    await options.onMessages({ reason, messages, afterSequence });
+                    let cursor = lastSequence;
+                    for (let page = 0; page < MAX_CATCHUP_PAGES; page += 1) {
+                        const pageAfterSequence = cursor;
+                        const messages = await this.listMessages({
+                            conversationId: options.conversationId,
+                            limit,
+                            afterSequence: pageAfterSequence,
+                        });
+                        const maxSequence = messages.reduce((current, message) => {
+                            const sequence = typeof message.sequence === 'number' && Number.isFinite(message.sequence)
+                                ? Math.floor(message.sequence)
+                                : current;
+                            return Math.max(current, sequence);
+                        }, cursor);
+                        const advanced = maxSequence > cursor;
+                        if (advanced) {
+                            cursor = maxSequence;
+                        }
+                        lastSequence = Math.max(lastSequence, maxSequence);
+                        await options.onMessages({
+                            reason,
+                            messages,
+                            afterSequence: pageAfterSequence,
+                        });
+                        // 收敛条件：不满页说明已追平；本页没有推进说明游标打转，必须停下
+                        // （否则服务端若回传不含 sequence 的消息会死循环）。
+                        if (messages.length < limit || !advanced) {
+                            if (page > 0) {
+                                console.info('[chat-hub-sdk] watch caught up', options.conversationId, 'pages=', page + 1, 'lastSequence=', lastSequence);
+                            }
+                            break;
+                        }
+                    }
                 }
                 catch (error) {
                     options.onError?.(error);
@@ -608,6 +657,8 @@ export class ChatHubAppRuntime {
             mentionedSubjectIds: input.mentionedSubjectIds,
             metadata: input.metadata,
             status: input.status,
+            client: input.client,
+            runtimePreference: input.runtimePreference,
         });
     }
     async sendMessage(input) {
@@ -622,6 +673,8 @@ export class ChatHubAppRuntime {
             content: input.content,
             mentionedSubjectIds: input.mentionedSubjectIds,
             metadata: input.metadata,
+            client: input.client,
+            runtimePreference: input.runtimePreference,
         });
     }
     async updateMessage(input) {
@@ -779,6 +832,13 @@ export class PlatformApi extends BaseApi {
             query: { externalCorrelationId },
         });
     }
+    async createAdminInvite(tenantId, input) {
+        return this.request({
+            method: 'POST',
+            path: `/open-platform/platform/tenants/${encodeURIComponent(tenantId)}/admin-invites`,
+            body: input,
+        });
+    }
     async toggleGrant(grantId, status) {
         return this.request({
             method: 'POST',
@@ -799,4 +859,14 @@ export class PlatformApi extends BaseApi {
             body: { ...notify, ...request, targetTenantId },
         });
     }
+    /**
+     * 重发认领凭证（平台级）：租户 7 天内未认领时，服务商重新签发 claimToken。
+     * **重发即作废**——epoch 递增，旧 token 立即失效；仅 pending 租户可重发。
+     */
+    async reissueClaimToken(tenantId) {
+        return this.request({
+            method: 'POST',
+            path: `/open-platform/platform/tenants/${encodeURIComponent(tenantId)}/claim-token`,
+        });
+    }
 }

package/dist-cjs/index.d.ts

@@ -273,8 +273,17 @@ export interface CreateMessageInput {
     status?: string;
     metadata?: Record<string, unknown>;
 }
+/** 入口客户端信号：网关只认白名单 kind 与短 deviceId，用于运行时路由。 */
+export interface ChatHubEntryClientSignal {
+    kind: 'web' | 'desktop' | 'mobile';
+    deviceId?: string;
+}
+/** 运行偏好：auto = 服务端按入口策略决定；cloud = 用户显式选择云端执行。 */
+export type ChatHubRuntimePreference = 'auto' | 'cloud';
 export interface CreateInternalMessageInput extends CreateMessageInput {
     tenantId: string;
+    client?: ChatHubEntryClientSignal;
+    runtimePreference?: ChatHubRuntimePreference;
 }
 export interface QueryMessagesInput {
     tenantId?: string;
@@ -298,7 +307,26 @@ export interface QueryConversationsInput {
     status?: string;
     createdBySubjectId?: string;
     subjectId?: string;
+    /** 分页（P1）：不传即全量（保持历史行为）。 */
+    limit?: number;
+    offset?: number;
+    /** keyset 游标（上一页最后一条的 encode 结果，见 encodeConversationListCursor）。 */
+    cursor?: string;
+    /** 服务端搜索：标题 / conversationId 纯文本匹配（不区分大小写）。 */
+    search?: string;
+}
+/**
+ * 会话列表游标（keyset 分页，P1）：与服务端 conversation-list-cursor.util 同构。
+ * 载荷 = base64url(JSON { u: updatedAt 毫秒, c: conversationId })。
+ * 客户端从「当前列表最后一条」构造；服务端按 (updatedAt desc, conversationId desc) 续页。
+ */
+export interface ConversationListCursorPayload {
+    updatedAt: number;
+    conversationId: string;
 }
+export declare function encodeConversationListCursor(payload: ConversationListCursorPayload): string;
+/** 从会话记录构造游标（读取 updatedAt；缺失/非法返回 null）。 */
+export declare function buildConversationListCursorFromRecord(record: Record<string, unknown> | null | undefined): string | null;
 export interface CreateInternalConversationInput extends CreateConversationInput {
     tenantId: string;
 }
@@ -421,6 +449,10 @@ export interface SendTextMessageOptions {
     mentionedSubjectIds?: string[];
     metadata?: Record<string, unknown>;
     status?: string;
+    /** 这条消息从哪种客户端发出（运行时路由信号）。 */
+    client?: ChatHubEntryClientSignal;
+    /** 仅显式选择云端执行时传 `cloud`；默认不传 = 服务端按 auto 处理。 */
+    runtimePreference?: ChatHubRuntimePreference;
 }
 export interface SendChatHubMessageOptions {
     conversationId: string;
@@ -431,6 +463,8 @@ export interface SendChatHubMessageOptions {
     mentionedSubjectIds?: string[];
     metadata?: Record<string, unknown>;
     status?: string;
+    client?: ChatHubEntryClientSignal;
+    runtimePreference?: ChatHubRuntimePreference;
 }
 export interface ListChatHubMessagesOptions {
     conversationId: string;
@@ -560,7 +594,14 @@ export declare class ChatHubAppRuntime {
     updateConversationRead(input: ConversationReadStateInput): Promise<void>;
     ensureAuthenticated(): Promise<void>;
     bootstrapConversation(): Promise<ChatHubBootstrapResult>;
-    listConversations(subjectId?: string): Promise<ConversationRecord[]>;
+    listConversations(subjectId?: string, options?: {
+        /** 分页（P1）：不传 limit 即全量（历史行为）。 */
+        limit?: number;
+        /** keyset 游标（上一页最后一条的 encode 结果）。 */
+        cursor?: string;
+        /** 服务端搜索：标题 / conversationId 纯文本匹配。 */
+        search?: string;
+    }): Promise<ConversationRecord[]>;
     listMessages(input: string | ListChatHubMessagesOptions): Promise<ConversationMessageRecord[]>;
     listMessagesPage(input: string | ListChatHubMessagesOptions): Promise<ListChatHubMessagesPageResult>;
     ensureParticipant(input: CreateParticipantInput): Promise<Record<string, unknown>>;
@@ -582,6 +623,12 @@ export interface PlatformProvisionTenantInput {
     externalCorrelationId: string;
     /** 该租户被授予的 platform scope，缺省 ['platform:subject:sync']。 */
     grantScopes?: string[];
+    adminIdentifiers?: PlatformAdminIdentifier[];
+    adminDisplayName?: string;
+}
+export interface PlatformAdminIdentifier {
+    type: 'phone' | 'email';
+    value: string;
 }
 export interface PlatformProvisionTenantResult {
     tenantId: string;
@@ -590,6 +637,8 @@ export interface PlatformProvisionTenantResult {
     grantId: string;
     /** 仅首次开通返回（7d 有效）；认领激活时提交。 */
     claimToken?: string;
+    inviteId?: string;
+    inviteUrl?: string;
     /** false = 幂等命中（同 platformId + externalCorrelationId 已开通过）。 */
     created: boolean;
     [key: string]: unknown;
@@ -600,6 +649,11 @@ export interface PlatformExternalIdentityInput {
     displayLabel?: string;
     metadata?: Record<string, unknown>;
 }
+export interface PlatformLoginIdentifierInput {
+    /** 登录渠道。v1 仅支持 `phone`（邮箱/工号等预留，新增渠道不改契约形状）。 */
+    provider: 'phone' | string;
+    value: string;
+}
 export interface PlatformSyncSubjectInput {
     classId: string;
     displayName: string;
@@ -611,6 +665,32 @@ export interface PlatformSyncSubjectInput {
     tags?: string[];
     /** 命中已存在主体时是否更新其可写字段，默认 false（纯幂等）。 */
     updateOnMatch?: boolean;
+    /**
+     * 登录标识（v1 = 手机号）。**带上才可登录**——平台据此把"这个成员"与
+     * "用该标识登录的人"对上；不带不算错，但该主体只作为通讯录/圈人对象存在，
+     * 登录时列不出来。
+     *
+     * 语义要点：
+     * - 与 `updateOnMatch` **正交**：传入即补绑（命中已存在主体时同样生效），
+     *   所以"先同步→后拿到手机号→再推一次"即可让身份变得可用；
+     * - **不传 ≠ 解绑**（缺席不代表移除）；
+     * - 同一标识可同时挂在多个主体上（例如第三方系统里同一手机号对应
+     *   「用户前台」「员工后台」两个账号空间）——平台按声明如实挂载，不自行归并；
+     * - 系统内**首次**挂载该标识的主体为「主身份」，用于登录时的默认选择。
+     */
+    loginIdentifiers?: PlatformLoginIdentifierInput[];
+    /**
+     * 身份标签：**由第三方声明的短标签**（如「用户前台」/「员工后台」），
+     * 用于在工作台的「切换身份」里区分同一个人的多个身份。
+     *
+     * 语义要点：
+     * - 平台**只提供字段，不发明语义**：值原样展示，不翻译、不判定、不造词；
+     *   不传时界面回退到角色（member / admin / owner）。
+     * - 属**内容字段**（与 `displayName` / `tags` 同规则）：建时落库；命中已存在
+     *   主体时**仅在 `updateOnMatch: true` 下覆盖**，不传不会被清空。
+     * - 建议 ≤ 4 个字（行内展示位有限）；接口上限 64 字符，超长返回 400。
+     */
+    identityLabel?: string;
     /** 幂等键：{source, externalKey}。重复推送只产生一个 Subject，可安全重试。 */
     externalIdentity: PlatformExternalIdentityInput;
 }
@@ -630,10 +710,21 @@ export interface PlatformResolveTenantResult {
         status: string;
     }>;
 }
+export interface PlatformAdminInviteInput {
+    adminIdentifiers: PlatformAdminIdentifier[];
+    adminDisplayName?: string;
+}
+export interface PlatformAdminInviteResult {
+    tenantId: string;
+    status: string;
+    inviteId: string;
+    inviteUrl: string;
+}
 export declare class PlatformApi extends BaseApi {
     provisionTenant(input: PlatformProvisionTenantInput): Promise<PlatformProvisionTenantResult>;
     syncSubject(targetTenantId: string, input: PlatformSyncSubjectInput): Promise<PlatformSyncSubjectResult>;
     resolveTenant(externalCorrelationId: string): Promise<PlatformResolveTenantResult>;
+    createAdminInvite(tenantId: string, input: PlatformAdminInviteInput): Promise<PlatformAdminInviteResult>;
     toggleGrant(grantId: string, status: 'active' | 'revoked'): Promise<Record<string, unknown>>;
     /**
      * 按标签/条件圈人并直接触达（声明式，调用方无 subjectId 概念）：
@@ -642,6 +733,21 @@ export declare class PlatformApi extends BaseApi {
      * 收件人二选一：标签圈人（selector）或单点声明（receive，如微信客服消息迁移）。
      */
     notify(targetTenantId: string, request: PlatformNotifyRequest, notify: PlatformNotifyInput): Promise<PlatformNotifyResult>;
+    /**
+     * 重发认领凭证（平台级）：租户 7 天内未认领时，服务商重新签发 claimToken。
+     * **重发即作废**——epoch 递增，旧 token 立即失效；仅 pending 租户可重发。
+     */
+    reissueClaimToken(tenantId: string): Promise<PlatformReissueClaimTokenResult>;
+}
+/** 重发认领凭证的返回（claimToken 有效期 7 天；重发后旧 token 立即失效）。 */
+export interface PlatformReissueClaimTokenResult {
+    tenantId: string;
+    status: string;
+    claimToken: string;
+    expiresIn: string;
+    /** 签发轮次：0 = 首次开通签发，>=1 = 第 N 次重发。 */
+    claimEpoch: number;
+    reissued: boolean;
 }
 /** 声明式主体引用：调用方只需本地维护 id/昵称/头像，服务端 lazily create-or-get。 */
 export interface PlatformLazySubject {

package/dist-cjs/index.js

@@ -12,9 +12,32 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlatformApi = exports.ChatHubAppRuntime = exports.ChatHubClient = exports.MessagesApi = exports.ConversationsApi = exports.ConversationTypesApi = exports.SubjectDirectoryApi = exports.OpenPlatformApi = exports.SDK_VERSION = void 0;
+exports.encodeConversationListCursor = encodeConversationListCursor;
+exports.buildConversationListCursorFromRecord = buildConversationListCursorFromRecord;
 exports.resolveChatHubMessagePolicy = resolveChatHubMessagePolicy;
 exports.createChatHubAppRuntime = createChatHubAppRuntime;
 exports.SDK_VERSION = '0.1.0';
+function encodeConversationListCursor(payload) {
+    const json = JSON.stringify({ u: payload.updatedAt, c: payload.conversationId });
+    // 同时兼容浏览器（btoa，需先转 latin1）与 Node（Buffer）：base64url 无 padding。
+    const base64 = typeof Buffer !== 'undefined'
+        ? Buffer.from(json, 'utf8').toString('base64')
+        : btoa(unescape(encodeURIComponent(json)));
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+/** 从会话记录构造游标（读取 updatedAt；缺失/非法返回 null）。 */
+function buildConversationListCursorFromRecord(record) {
+    const conversationId = typeof record?.conversationId === 'string' ? record.conversationId : '';
+    const rawUpdatedAt = record?.updatedAt;
+    const updatedAt = typeof rawUpdatedAt === 'number'
+        ? rawUpdatedAt
+        : typeof rawUpdatedAt === 'string'
+            ? Date.parse(rawUpdatedAt)
+            : NaN;
+    if (!conversationId || !Number.isFinite(updatedAt) || updatedAt <= 0)
+        return null;
+    return encodeConversationListCursor({ updatedAt, conversationId });
+}
 function resolveChatHubMessagePolicy(value) {
     const policy = value && typeof value === 'object' ? value : {};
     return {
@@ -27,6 +50,12 @@ function resolveChatHubMessagePolicy(value) {
         allowRevoke: policy.allowRevoke === true,
     };
 }
+/**
+ * 断线补齐时一次 refresh 最多向后续拉的页数（防单次同步打爆服务端）。
+ * 每页按 watch 的 limit（上限 100），20 页 = 最多 2000 条，
+ * 覆盖任何合理的断线积压；真超过这个量级应走历史分页而不是实时补齐。
+ */
+const MAX_CATCHUP_PAGES = 20;
 function withBearerToken(headers, token) {
     if (!token) {
         return headers || {};
@@ -395,13 +424,16 @@ class ChatHubAppRuntime {
             conversation,
         };
     }
-    async listConversations(subjectId) {
+    async listConversations(subjectId, options) {
         await this.ensureAuthenticated();
         const resolvedSubjectId = subjectId || this.config.subjects?.[0]?.subjectId || undefined;
         const conversations = await this.client.conversations.list({
             tenantId: this.tenantId,
             typeId: this.config.conversationType?.typeId,
             subjectId: resolvedSubjectId,
+            ...(options?.limit ? { limit: options.limit } : {}),
+            ...(options?.cursor ? { cursor: options.cursor } : {}),
+            ...(options?.search ? { search: options.search } : {}),
         });
         // Participants are intentionally NOT fetched here: doing so would fan out
         // one `/conversation-runtime/participants` HTTP request per conversation
@@ -517,22 +549,41 @@ class ChatHubAppRuntime {
             if (refreshPromise) {
                 return refreshPromise;
             }
-            const afterSequence = lastSequence;
             refreshPromise = (async () => {
                 try {
-                    const messages = await this.listMessages({
-                        conversationId: options.conversationId,
-                        limit,
-                        afterSequence,
-                    });
-                    const maxSequence = messages.reduce((current, message) => {
-                        const sequence = typeof message.sequence === 'number' && Number.isFinite(message.sequence)
-                            ? Math.floor(message.sequence)
-                            : current;
-                        return Math.max(current, sequence);
-                    }, lastSequence);
-                    lastSequence = Math.max(lastSequence, maxSequence);
-                    await options.onMessages({ reason, messages, afterSequence });
+                    let cursor = lastSequence;
+                    for (let page = 0; page < MAX_CATCHUP_PAGES; page += 1) {
+                        const pageAfterSequence = cursor;
+                        const messages = await this.listMessages({
+                            conversationId: options.conversationId,
+                            limit,
+                            afterSequence: pageAfterSequence,
+                        });
+                        const maxSequence = messages.reduce((current, message) => {
+                            const sequence = typeof message.sequence === 'number' && Number.isFinite(message.sequence)
+                                ? Math.floor(message.sequence)
+                                : current;
+                            return Math.max(current, sequence);
+                        }, cursor);
+                        const advanced = maxSequence > cursor;
+                        if (advanced) {
+                            cursor = maxSequence;
+                        }
+                        lastSequence = Math.max(lastSequence, maxSequence);
+                        await options.onMessages({
+                            reason,
+                            messages,
+                            afterSequence: pageAfterSequence,
+                        });
+                        // 收敛条件：不满页说明已追平；本页没有推进说明游标打转，必须停下
+                        // （否则服务端若回传不含 sequence 的消息会死循环）。
+                        if (messages.length < limit || !advanced) {
+                            if (page > 0) {
+                                console.info('[chat-hub-sdk] watch caught up', options.conversationId, 'pages=', page + 1, 'lastSequence=', lastSequence);
+                            }
+                            break;
+                        }
+                    }
                 }
                 catch (error) {
                     options.onError?.(error);
@@ -619,6 +670,8 @@ class ChatHubAppRuntime {
             mentionedSubjectIds: input.mentionedSubjectIds,
             metadata: input.metadata,
             status: input.status,
+            client: input.client,
+            runtimePreference: input.runtimePreference,
         });
     }
     async sendMessage(input) {
@@ -633,6 +686,8 @@ class ChatHubAppRuntime {
             content: input.content,
             mentionedSubjectIds: input.mentionedSubjectIds,
             metadata: input.metadata,
+            client: input.client,
+            runtimePreference: input.runtimePreference,
         });
     }
     async updateMessage(input) {
@@ -791,6 +846,13 @@ class PlatformApi extends BaseApi {
             query: { externalCorrelationId },
         });
     }
+    async createAdminInvite(tenantId, input) {
+        return this.request({
+            method: 'POST',
+            path: `/open-platform/platform/tenants/${encodeURIComponent(tenantId)}/admin-invites`,
+            body: input,
+        });
+    }
     async toggleGrant(grantId, status) {
         return this.request({
             method: 'POST',
@@ -811,5 +873,15 @@ class PlatformApi extends BaseApi {
             body: { ...notify, ...request, targetTenantId },
         });
     }
+    /**
+     * 重发认领凭证（平台级）：租户 7 天内未认领时，服务商重新签发 claimToken。
+     * **重发即作废**——epoch 递增，旧 token 立即失效；仅 pending 租户可重发。
+     */
+    async reissueClaimToken(tenantId) {
+        return this.request({
+            method: 'POST',
+            path: `/open-platform/platform/tenants/${encodeURIComponent(tenantId)}/claim-token`,
+        });
+    }
 }
 exports.PlatformApi = PlatformApi;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthen/sdk-core",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "AppThen Conversation Hub SDK - platform-agnostic core",
   "type": "module",
   "main": "./dist/index.js",