easemob-websdk 4.24.1 → 5.0.0

package/cache/cache-crypto.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 缓存加密工具
+ */
+export interface CacheCryptoPayload {
+    readonly __enc: true;
+    readonly v: 1;
+    readonly alg: 'AES-GCM';
+    readonly kdf: 'SHA-256';
+    readonly iv: string;
+    readonly ct: string;
+}
+export interface CacheCryptoAdapter {
+    readonly isEnabled: () => boolean;
+    readonly encrypt: (plaintext: string) => Promise<string>;
+    readonly decrypt: (payload: string) => Promise<string | null>;
+}
+export declare class CacheCrypto implements CacheCryptoAdapter {
+    private readonly enabled;
+    private readonly keyPromise;
+    private getCrypto;
+    constructor(appKey: string, userId: string);
+    isEnabled(): boolean;
+    encrypt(plaintext: string): Promise<string>;
+    decrypt(payload: string): Promise<string | null>;
+    private deriveKey;
+}

package/cache/cache-eviction.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 缓存淘汰工具
+ */
+export interface EvictionResult<T> {
+    readonly kept: ReadonlyArray<T>;
+    readonly removed: ReadonlyArray<T>;
+}
+export declare const removeExpired: <T extends {
+    lastUpdate: number;
+}>(items: ReadonlyArray<T>, // 待处理列表
+ttlMs: number, // TTL 毫秒
+now: number) => EvictionResult<T>;
+export declare const evictByLru: <T extends {
+    lastAccess: number;
+}>(items: ReadonlyArray<T>, // 待处理列表
+removeCount: number) => EvictionResult<T>;

package/cache/cache-keys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 缓存 key 生成工具
+ */
+export declare const CACHE_KEY_PREFIX = "IMSDK";
+export declare const CacheKeyName: {
+    readonly CONVERSATIONS: "conversationMap";
+    readonly USER_INFO: "userInfoMap";
+    readonly GROUP_NAMECARD: "groupNamecardMap";
+    readonly CONTACT_RELATIONS: "contactRelationMap";
+    readonly CONTACT_VERSION: "contactVersion";
+    readonly CONTACT_META: "contactMeta";
+    readonly SESSION_LIST: "sessionListMap";
+    readonly SESSION_LIST_CHECKPOINT: "sessionListCheckpoint";
+    readonly JOINED_GROUP_PREVIEW: "joinedGroupPreview";
+    readonly METADATA: "metadata";
+};
+export type CacheKeyName = (typeof CacheKeyName)[keyof typeof CacheKeyName];
+export interface CacheKeyContext {
+    readonly appKey: string;
+    readonly userId: string;
+    readonly schemaVersion: number;
+}
+export declare const buildCacheKey: (context: CacheKeyContext, name: CacheKeyName) => string;

package/cache/cache-manager.d.ts

@@ -0,0 +1,254 @@
+/**
+ * 缓存管理器
+ */
+import type { ContactSnapshot } from '../types/contact';
+import type { UserInfo, UserInfoNotifyPatch } from '../types/user-info';
+import type { JoinedGroupSnapshot } from '../types/group';
+import type { CacheConfig, ContactCacheMeta, ContactRelationRecord, ContactVersionState, ConversationSummary, GroupNamecardCacheRecord, SessionListCheckpoint, UserInfoSummary } from './cache-types';
+import type { ConversationMark, ConversationType, ConversationItem, SessionListRemindType } from '../types/conversation';
+import type { Message } from '../types';
+import { type UserInfoRuntimeMergeResult, type UserInfoRuntimeUpsertRecord } from '../managers/user-info/user-info-runtime-store';
+export interface CacheManagerOptions {
+    readonly appKey: string;
+    readonly userId: string;
+    readonly cacheEncryptionMode?: 'auto' | 'off';
+    readonly config?: Partial<CacheConfig>;
+}
+export interface ConversationMergeResult {
+    readonly items: ReadonlyArray<ConversationSummary>;
+    readonly changed: boolean;
+}
+export interface ConversationMessagePatchResult {
+    readonly items: ReadonlyArray<ConversationSummary>;
+    readonly changed: boolean;
+}
+export interface SessionListPatchResult {
+    readonly items: ReadonlyArray<ConversationItem>;
+    readonly changed: boolean;
+}
+export interface ConversationUnreadClearResult extends SessionListPatchResult {
+    /** [zh-CN] 本地 conversation 或 session-list 缓存中是否存在目标会话。 [en-US] Whether the target conversation exists in the local conversation or session-list cache. */
+    readonly matched: boolean;
+}
+export interface SessionListDisplayRefreshTarget {
+    readonly userId: string;
+    readonly lastModified?: number;
+}
+export interface SessionListGroupDisplayRefreshTarget {
+    readonly groupId: string;
+    readonly name?: string;
+    readonly avatarUrl?: string;
+    readonly remindType?: SessionListRemindType;
+}
+export interface SessionListGroupDisplayRefreshOptions {
+    readonly onlyWhenNameMissing?: boolean;
+}
+export interface SessionListBatchApplyResult {
+    readonly items: ReadonlyArray<ConversationItem>;
+    readonly checkpoint: SessionListCheckpoint;
+}
+export interface ContactSyncApplyResult {
+    readonly snapshot: ContactSnapshot;
+    readonly changed: boolean;
+}
+export interface ContactLocalPatchResult {
+    readonly snapshot: ContactSnapshot;
+    readonly changed: boolean;
+}
+export declare class CacheManager {
+    private readonly config;
+    private readonly userId;
+    private readonly store;
+    private readonly metadataStore;
+    private readonly conversationCache;
+    private readonly userInfoCache;
+    private readonly groupNamecardCache;
+    private readonly sessionListCache;
+    private readonly joinedGroupPreviewCache;
+    private readonly contactCache;
+    private readonly userInfoRuntimeStore;
+    private readonly conversationDeletionTimestamps;
+    private currentConversation;
+    private readonly conversationKey;
+    private readonly userInfoKey;
+    private readonly groupNamecardKey;
+    private readonly sessionListKey;
+    private readonly sessionListCheckpointKey;
+    private readonly joinedGroupPreviewKey;
+    private readonly contactRelationKey;
+    private readonly contactVersionKey;
+    private readonly contactMetaKey;
+    private readonly metadataKey;
+    private sessionListCheckpoint;
+    private flushTimer;
+    private flushIdleHandle;
+    private activeFlushPromise;
+    private sessionListCommitInProgress;
+    private mutationRevision;
+    private readonly domainRevisions;
+    private pendingDirtyRevisions;
+    private readonly loadPromise;
+    constructor(options: CacheManagerOptions);
+    getConfig(): CacheConfig;
+    prepare(): Promise<void>;
+    loadConversationSummaries(): ReadonlyArray<ConversationSummary>;
+    loadSessionList(): ReadonlyArray<ConversationItem>;
+    loadJoinedGroupPreviewSnapshot(): JoinedGroupSnapshot;
+    applyJoinedGroupPreviewSnapshot(snapshot: JoinedGroupSnapshot): void;
+    /** @internal 在群组全量同步完成后严格提交权威预览，写入失败时不替换内存预览。 */
+    commitJoinedGroupPreviewSnapshot(snapshot: JoinedGroupSnapshot): Promise<JoinedGroupSnapshot>;
+    /** @internal 删除当前缓存用户的一个已加入群预览，并在返回前刷新持久化记录。 */
+    removeJoinedGroupPreview(groupId: string): Promise<JoinedGroupSnapshot>;
+    loadSessionListCheckpoint(): SessionListCheckpoint;
+    /**
+     * @internal
+     * [zh-CN] 正常会话结束前持久化待处理缓存域。
+     * [en-US] Flushes pending cache domains before a normal session shutdown.
+     */
+    flushPending(): Promise<void>;
+    resetSessionListCheckpoint(): void;
+    loadUserInfoSummaries(): ReadonlyArray<UserInfoSummary>;
+    loadGroupNamecards(groupId?: string): ReadonlyArray<GroupNamecardCacheRecord>;
+    loadContactSnapshot(source?: 'cache' | 'sync'): ContactSnapshot;
+    loadContactRelationRecords(): ReadonlyArray<ContactRelationRecord>;
+    loadContactVersionState(): ContactVersionState;
+    loadContactCacheMeta(): ContactCacheMeta;
+    markConversationAccess(targets: ReadonlyArray<{
+        conversationId: string;
+        type: ConversationType;
+    }>): void;
+    setCurrentConversation(params: {
+        readonly conversationId: string;
+        readonly type: ConversationType;
+    }): void;
+    resetCurrentConversation(): void;
+    getCurrentConversation(): {
+        readonly conversationId: string;
+        readonly type: ConversationType;
+    } | null;
+    clearConversationUnreadMessageCount(params: {
+        readonly conversationId: string;
+        readonly type: ConversationType;
+        readonly readAt?: number;
+    }): ConversationUnreadClearResult;
+    clearAllConversationUnreadMessageCount(params?: {
+        readonly readAt?: number;
+    }): SessionListPatchResult;
+    applyConversationPinnedMutation(params: {
+        readonly conversationId: string;
+        readonly type: ConversationType;
+        readonly isPinned: boolean;
+        readonly pinnedTime?: number;
+    }): SessionListPatchResult;
+    deleteConversation(params: {
+        readonly conversationId: string;
+        readonly type: ConversationType;
+        readonly deletedAt?: number;
+    }): SessionListPatchResult;
+    clearConversations(): SessionListPatchResult;
+    applyConversationMarkMutation(params: {
+        readonly conversations: ReadonlyArray<{
+            readonly conversationId: string;
+            readonly conversationType: ConversationType;
+            readonly applied: boolean;
+        }>;
+        readonly mark: ConversationMark;
+        readonly operation: 'addMark' | 'removeMark';
+    }): SessionListPatchResult;
+    replaceSessionList(items: ReadonlyArray<ConversationItem>, checkpoint?: Partial<SessionListCheckpoint>, options?: {
+        readonly syncStartedAt?: number;
+    }): void;
+    mergeSessionListIncremental(items: ReadonlyArray<ConversationItem>, checkpoint?: Partial<SessionListCheckpoint>): void;
+    commitSessionListSync(options: {
+        readonly items: ReadonlyArray<ConversationItem>;
+        readonly mode: 'full' | 'incremental';
+        readonly checkpoint: SessionListCheckpoint;
+        readonly syncStartedAt?: number;
+    }): Promise<SessionListBatchApplyResult>;
+    setUserInfoSummaries(items: ReadonlyArray<UserInfoSummary>): void;
+    upsertRuntimeUserInfos(items: ReadonlyArray<UserInfoRuntimeUpsertRecord>): void;
+    getRuntimeUserInfo(userId: string, updateAccess?: boolean): UserInfo | null;
+    applyUserInfoNotifyPatch(patch: UserInfoNotifyPatch): UserInfoRuntimeMergeResult;
+    updateUserInfoSummaryFromRuntime(userId: string): void;
+    getUserInfoSummaries(userIds: ReadonlyArray<string>, updateAccess: boolean): ReadonlyArray<UserInfoSummary>;
+    removeUserInfo(userIds: ReadonlyArray<string>): void;
+    getGroupNamecard(groupId: string, userId: string, updateAccess: boolean): GroupNamecardCacheRecord | null;
+    setGroupNamecards(items: ReadonlyArray<GroupNamecardCacheRecord>): void;
+    removeGroupNamecards(targets: ReadonlyArray<{
+        groupId: string;
+        userId: string;
+    }>): void;
+    setContactVersionState(state: ContactVersionState): void;
+    markContactCacheIncomplete(reason: ContactCacheMeta['reason']): void;
+    applyContactSync(options: {
+        mode: 'full' | 'incremental';
+        relations: ReadonlyArray<ContactRelationRecord>;
+        userInfos: ReadonlyArray<Pick<UserInfoSummary, 'userId' | 'nickname' | 'avatarUrl' | 'sign' | 'ext'>>;
+        version: string;
+        lastSyncTs: number;
+    }): ContactSyncApplyResult;
+    refreshSessionListDisplayFromUserInfos(targets: ReadonlyArray<SessionListDisplayRefreshTarget>): SessionListPatchResult;
+    refreshSessionListDisplayFromJoinedGroups(groups: ReadonlyArray<SessionListGroupDisplayRefreshTarget>, options?: SessionListGroupDisplayRefreshOptions): SessionListPatchResult;
+    removeContact(userId: string): ContactLocalPatchResult;
+    updateContactRemark(userId: string, remark: string): ContactLocalPatchResult;
+    applyContactRosterNotice(options: {
+        readonly action: 'add' | 'remove';
+        readonly userId: string;
+        readonly rosterVersion?: string;
+    }): ContactLocalPatchResult;
+    updateConversationsFromServer(items: ReadonlyArray<ConversationSummary>, options?: {
+        readonly syncStartedAt?: number;
+    }): ConversationMergeResult;
+    applyIncomingMessageToConversations(message: Message): ConversationMessagePatchResult;
+    applyIncomingMessageToSessionList(message: Message): SessionListPatchResult;
+    private loadFromStorage;
+    private readDump;
+    private readValue;
+    private normalizeSessionListCheckpoint;
+    private scheduleFlush;
+    private markDirty;
+    private getDomainRevision;
+    private ensureFlushScheduled;
+    private takePendingDirtyBatch;
+    private restoreDirtyBatch;
+    private addQuotaCleanupDomains;
+    private flushNow;
+    private flushDirtyBatch;
+    private writeDirtyDomains;
+    private writeDomain;
+    private writeSessionListStorageRecord;
+    private buildIncrementalSessionListRecords;
+    private buildSessionListSyncCandidate;
+    private filterItemsAgainstConversationDeletions;
+    private getConversationLatestUpdate;
+    private handleQuotaExceeded;
+    private evictByPolicy;
+    private calculateEvictCount;
+    private mergeConversationLists;
+    private isConversationListEqual;
+    private buildConversationSignature;
+    private buildConversationKey;
+    private areConversationMarksEqual;
+    private buildConversationFromMessage;
+    private resolveConversationFromMessage;
+    private buildMessageSnippet;
+    private normalizeMessageBody;
+    private buildSessionListRecordFromConversation;
+    private resolveSessionListUnreadCount;
+    private shouldIncreaseUnreadForMessage;
+    private buildSingleSessionDisplayFields;
+    private shouldSkipSessionUserDisplayRefresh;
+    private hydrateSessionListRecordsFromLocalProfiles;
+    private resolveSessionDisplayUserInfo;
+    private buildSessionMessageSender;
+    private buildSingleChatPeerMessageSender;
+    private isSenderEqual;
+    private buildGroupSessionDisplayFields;
+    private mapJoinedGroupRemindTypeToSession;
+    private buildChatRoomSessionDisplayFields;
+    private isSessionListEqual;
+    private buildSessionListSignature;
+    private refreshContactCacheIntegrity;
+    private buildContactSnapshotSignature;
+    private applyContactLocalPatch;
+}

package/cache/cache-metadata.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 缓存元信息管理
+ */
+import type { CacheMetadata } from './cache-types';
+import { CacheStore } from './cache-store';
+export declare class CacheMetadataStore {
+    private readonly store;
+    private readonly key;
+    private readonly schemaVersion;
+    constructor(store: CacheStore, key: string, schemaVersion: number);
+    load(): Promise<CacheMetadata>;
+    save(metadata: CacheMetadata): Promise<void>;
+    touchLastFlush(): Promise<CacheMetadata>;
+}

package/cache/cache-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * localStorage 访问封装
+ */
+import type { CacheCryptoAdapter } from './cache-crypto';
+export declare class CacheStore {
+    private readonly available;
+    private readonly cryptoAdapter;
+    constructor(cryptoAdapter?: CacheCryptoAdapter);
+    static checkAvailable(): boolean;
+    readAsync<T>(key: string, fallback: T): Promise<T>;
+    writeAsync(key: string, value: unknown): Promise<void>;
+    /**
+     * Writes a cache record and propagates serialization/storage failures to the caller.
+     * 写入缓存记录，并将序列化或存储失败抛给调用方。
+     */
+    writeStrictAsync(key: string, value: unknown): Promise<void>;
+    private writeInternal;
+    remove(key: string): void;
+}

package/cache/cache-types.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 缓存模块类型定义
+ */
+import type { ConversationIdentifier, ConversationItem, ConversationMark, ConversationType } from '../types/conversation';
+import type { MessageModifiedInfo } from '../types';
+import type { JoinedGroupSnapshotMeta, JoinedGroupSummary } from '../types/group';
+/**
+ * [zh-CN] 缓存中的消息摘要。
+ * [en-US] Message snippet stored in the cache.
+ */
+export interface MessageSnippet {
+    /** [zh-CN] 消息 ID。 [en-US] Message ID. */
+    readonly msgId: string;
+    /** [zh-CN] 消息类型。 [en-US] Message type. */
+    readonly type: string;
+    /** [zh-CN] 消息体摘要。 [en-US] Message body snippet. */
+    readonly body: Record<string, unknown>;
+    /** [zh-CN] 消息时间戳，单位毫秒。 [en-US] Message timestamp in milliseconds. */
+    readonly timestamp: number;
+    /** [zh-CN] 用户资料版本，单位秒。 [en-US] User profile version in seconds. */
+    readonly userInfoUpdateTime?: number;
+    /** [zh-CN] 群名片版本，单位秒。 [en-US] Group name card version in seconds. */
+    readonly namecardUpdateTime?: number;
+    /** [zh-CN] 消息修改信息。 [en-US] Message modification information. */
+    readonly modifiedInfo?: MessageModifiedInfo;
+}
+/**
+ * [zh-CN] 缓存中的会话摘要。
+ * [en-US] Conversation summary stored in the cache.
+ */
+export interface ConversationSummary {
+    /** [zh-CN] 会话 ID。 [en-US] Conversation ID. */
+    readonly conversationId: string;
+    /** [zh-CN] 会话类型。 [en-US] Conversation type. */
+    readonly type: ConversationType;
+    /** [zh-CN] 最后一条消息摘要。 [en-US] Last message snippet. */
+    readonly lastMessage: MessageSnippet | null;
+    /** [zh-CN] 未读消息数。 [en-US] Unread message count. */
+    readonly unreadCount: number;
+    /** [zh-CN] 是否置顶。 [en-US] Whether the conversation is pinned. */
+    readonly isPinned?: boolean;
+    /** [zh-CN] 置顶时间戳，单位毫秒。 [en-US] Pin timestamp in milliseconds. */
+    readonly pinnedTime?: number;
+    /** [zh-CN] 会话标记。 [en-US] Conversation marks. */
+    readonly marks: ReadonlyArray<ConversationMark>;
+    /** [zh-CN] 最近访问时间戳，单位毫秒。 [en-US] Last access timestamp in milliseconds. */
+    readonly lastAccess: number;
+    /** [zh-CN] 最近更新时间戳，单位毫秒。 [en-US] Last update timestamp in milliseconds. */
+    readonly lastUpdate: number;
+}
+/**
+ * [zh-CN] 缓存中的用户资料摘要。
+ * [en-US] User profile summary stored in the cache.
+ */
+export interface UserInfoSummary {
+    /** [zh-CN] 用户 ID。 [en-US] User ID. */
+    readonly userId: string;
+    /** [zh-CN] 用户昵称。 [en-US] User nickname. */
+    readonly nickname?: string;
+    /** [zh-CN] 用户头像 URL。 [en-US] User avatar URL. */
+    readonly avatarUrl?: string;
+    /** [zh-CN] 用户签名。 [en-US] User signature. */
+    readonly sign?: string;
+    /** [zh-CN] 用户扩展信息。 [en-US] User extension data. */
+    readonly ext?: string;
+    /** [zh-CN] 用户资料版本，单位秒。 [en-US] User profile version in seconds. */
+    readonly userInfoUpdateTime?: number;
+    /** [zh-CN] 最近同步时间戳，单位毫秒。 [en-US] Last synchronization timestamp in milliseconds. */
+    readonly lastSyncAt?: number;
+    /** [zh-CN] 最近访问时间戳，单位毫秒。 [en-US] Last access timestamp in milliseconds. */
+    readonly lastAccess: number;
+    /** [zh-CN] 最近更新时间戳，单位毫秒。 [en-US] Last update timestamp in milliseconds. */
+    readonly lastUpdate: number;
+}
+/**
+ * [zh-CN] 缓存中的群名片记录。
+ * [en-US] Group name card record stored in the cache.
+ */
+export interface GroupNamecardCacheRecord {
+    /** [zh-CN] 群组 ID。 [en-US] Group ID. */
+    readonly groupId: string;
+    /** [zh-CN] 用户 ID。 [en-US] User ID. */
+    readonly userId: string;
+    /** [zh-CN] 群名片。 [en-US] Group name card. */
+    readonly namecard: string;
+    /** [zh-CN] 群名片版本，单位秒。 [en-US] Group name card version in seconds. */
+    readonly namecardUpdateTime?: number;
+    /** [zh-CN] 最近同步时间戳，单位毫秒。 [en-US] Last synchronization timestamp in milliseconds. */
+    readonly lastSyncAt?: number;
+    /** [zh-CN] 最近访问时间戳，单位毫秒。 [en-US] Last access timestamp in milliseconds. */
+    readonly lastAccess: number;
+    /** [zh-CN] 最近更新时间戳，单位毫秒。 [en-US] Last update timestamp in milliseconds. */
+    readonly lastUpdate: number;
+}
+export type ContactCacheIntegrity = 'complete' | 'incomplete';
+export type ContactCacheIncompleteReason = 'quota_exceeded' | 'user_info_missing' | 'corrupted' | 'first_sync_pending' | 'manual_reset';
+export type ContactVersionSource = 'metadata' | 'sync_page' | 'roster_notice';
+export type ContactSyncMode = 'full' | 'incremental' | 'skipped';
+export interface ContactRelationRecord {
+    readonly userId: string;
+    readonly remark: string;
+    readonly sign: string;
+    readonly addTs: number;
+    readonly updatedAt: number;
+    readonly metadataUpdatedAt: number;
+}
+export interface ContactVersionState {
+    readonly version: string;
+    readonly lastVersionCheckAt: number;
+    readonly lastVersionSource: ContactVersionSource;
+}
+export interface ContactCacheMeta {
+    readonly cacheIntegrity: ContactCacheIntegrity;
+    readonly reason?: ContactCacheIncompleteReason;
+    readonly lastSyncTs: number;
+    readonly lastSuccessfulVersion: string;
+    readonly lastSyncMode: ContactSyncMode;
+}
+/**
+ * [zh-CN] 缓存元信息。
+ * [en-US] Cache metadata.
+ */
+export interface CacheMetadata {
+    /** [zh-CN] 缓存结构版本号。 [en-US] Cache schema version. */
+    readonly schemaVersion: number;
+    /** [zh-CN] 最近一次落盘时间戳，单位毫秒。 [en-US] Last flush timestamp in milliseconds. */
+    readonly lastFlush: number;
+}
+/**
+ * [zh-CN] 本地缓存配置。
+ * [en-US] Local cache configuration.
+ */
+export interface CacheConfig {
+    /** [zh-CN] 缓存结构版本号。 [en-US] Cache schema version. */
+    readonly schemaVersion: number;
+    /** [zh-CN] 缓存有效期，单位秒。 [en-US] Cache time to live in seconds. */
+    readonly ttlSeconds: number;
+    /** [zh-CN] 批量落盘间隔，单位毫秒。 [en-US] Batched flush interval in milliseconds. */
+    readonly flushIntervalMs: number;
+    /** [zh-CN] 用户资料缓存最大条数。 [en-US] Maximum number of cached user profiles. */
+    readonly maxUserInfoCount: number;
+    /** [zh-CN] 群名片缓存最大条数。 [en-US] Maximum number of cached group name cards. */
+    readonly maxGroupNamecardCount?: number;
+    /** [zh-CN] 会话缓存最大条数。 [en-US] Maximum number of cached conversations. */
+    readonly maxConversations?: number;
+}
+/**
+ * [zh-CN] 会话列表更新原因。
+ * - `conversation`：会话列表同步或会话缓存基线变化；
+ * - `profile`：好友或用户资料补全导致会话展示信息（例如，昵称或头像）变化；
+ * - `message`：收发消息导致最后一条消息、未读数或会话排序发生变化；
+ * - `local`：触发了本地会话操作，如置顶、标记、删除会话等。
+ * [en-US] The reason for a conversation list update.
+ * - `conversation`: Indicates a conversation list synchronization or changes to the baseline cache.
+ * - `profile`: Indicates that friend or user profile completion has updated the displayed information (e.g., nicknames or avatars) of the conversation.
+ * - `message`: Indicates that sending or receiving messages has updated the last message, unread count, or conversation sorting.
+ * - `local`: Indicates local conversation actions, such as pinning, marking, or deleting a conversation.
+ */
+export type ConversationListUpdateReason = 'conversation' | 'profile' | 'message' | 'local';
+/**
+ * [zh-CN] 会话列表更新补丁。简单的 UI 渲染可以直接使用 `ConversationListUpdatePayload.items`；只有在需要保留业务层自定义本地字段，或进行精细化数据合并时，才需要读取该补丁。
+ * [en-US] The patch for a conversation list update. Simple UIs can directly use `ConversationListUpdatePayload.items` for rendering; read this patch only when you need to preserve custom local fields or perform fine-grained data merging.
+ */
+export interface ConversationListUpdatePatch {
+    /**
+     * [zh-CN] 是否为一次整体基线重置。为 `true` 时，表示 SDK 重新建立或替换了会话列表基线（例如登录后加载缓存、服务端全量同步、回退到全量刷新等）。业务层若自行维护带本地自定义字段的列表，此时应将 `items` 视为唯一的权威快照，并按会话 Key 重新挂载本地字段；简单 UI 直接使用 `items` 渲染即可。
+     * [en-US] Whether this update is a full baseline reset. When `true`, it indicates that the SDK has rebuilt or replaced the conversation list baseline (e.g., loading cache upon login, full server synchronization, or falling back to a full refresh). If your app maintains a local list with custom fields, you should treat `items` as the current authoritative snapshot and re-bind your local fields by conversation key; simple UIs can directly use `items` for rendering.
+     */
+    readonly reset: boolean;
+    /** [zh-CN] 本次新增或 SDK 字段发生变化的会话。 [en-US] Conversations inserted or changed in SDK-owned fields during this update. */
+    readonly upserted: ReadonlyArray<ConversationItem>;
+    /** [zh-CN] 本次移除的会话标识。 [en-US] Conversation identifiers removed in this update. */
+    readonly removed: ReadonlyArray<ConversationIdentifier>;
+    /** [zh-CN] 本次受影响的会话 key，格式为 `${conversationType}:${conversationId}`。 [en-US] Affected conversation keys in `${conversationType}:${conversationId}` format. */
+    readonly affectedKeys: ReadonlyArray<string>;
+    /**
+     * [zh-CN] 本次是否改变了会话列表顺序。可能只有排序变化而没有 `upserted` 内容变化，例如置顶、最后消息时间或服务端排序基线变化。按补丁合并的业务在该值为 `true` 时，应按 `items` 中的顺序重排本地列表；直接使用 `items` 的业务无需额外处理。
+     * [en-US] Whether the conversation-list order changed. The order may change even when `upserted` is empty, for example due to pinning, last-message time, or server ordering baseline changes. Patch-merging consumers should reorder their local list according to `items` when this is `true`; consumers using `items` directly need no extra handling.
+     */
+    readonly orderChanged: boolean;
+}
+/**
+ * [zh-CN] `onConversationListUpdate` 事件载荷。`items` 始终是 SDK 当前完整且已排序的 `ConversationItem` 快照；`patch` 用于业务按增量合并并保留自定义本地字段。
+ * [en-US] Payload of `onConversationListUpdate`. `items` is always the SDK's current full, ordered `ConversationItem` snapshot; `patch` helps apps merge incrementally while preserving custom local fields.
+ */
+export interface ConversationListUpdatePayload {
+    /** [zh-CN] 会话列表快照版本号，每次有效派发递增，可用于忽略旧事件。 [en-US] Conversation list snapshot version, incremented for each effective dispatch and useful for ignoring stale events. */
+    readonly version: number;
+    /** [zh-CN] 当前完整且已排序的会话列表快照。简单 UI 推荐直接用该字段刷新列表。 [en-US] Current full and ordered conversation list snapshot. Simple UIs are recommended to render this field directly. */
+    readonly items: ReadonlyArray<ConversationItem>;
+    /** [zh-CN] 本次列表更新原因。 [en-US] Reason for this list update. */
+    readonly reason: ConversationListUpdateReason;
+    /** [zh-CN] 本次变化补丁，便于业务保留本地字段。 [en-US] Patch for this update, useful for preserving app-local fields. */
+    readonly patch: ConversationListUpdatePatch;
+}
+/**
+ * [zh-CN] 通用缓存落盘结构。
+ * [en-US] Generic persisted cache structure.
+ */
+export interface CacheDump<T> {
+    /** [zh-CN] 缓存项列表。 [en-US] Cached items. */
+    readonly items: ReadonlyArray<T>;
+}
+export interface SessionListCacheRecord extends ConversationItem {
+    readonly updatedAt: number;
+}
+export interface SessionListCheckpoint {
+    readonly lastSyncTime: number;
+    readonly lastSyncFinishedTs: number;
+    readonly sessionsLastSyncTs: number;
+    readonly lastSuccessfulAt: number;
+}
+export interface SessionListStorageRecord {
+    readonly items: ReadonlyArray<SessionListCacheRecord>;
+    readonly checkpoint?: SessionListCheckpoint;
+}
+export interface JoinedGroupPreviewStorageRecord {
+    readonly items: ReadonlyArray<JoinedGroupSummary>;
+    readonly meta: JoinedGroupSnapshotMeta;
+}
+export interface SessionListCapabilityState {
+    readonly status: 'unknown' | 'available' | 'unsupported' | 'unconfigured';
+    readonly determinedAt?: number;
+    readonly reason?: string;
+}

package/cache/cache-utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 缓存工具方法
+ */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const safeJsonParse: <T>(raw: string | null, fallback: T) => T;
+export declare const safeJsonStringify: (value: unknown) => string | null;
+export declare const isQuotaExceededError: (error: unknown) => boolean;

package/cache/contact-cache.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 联系人关系缓存
+ */
+import type { ContactCacheIncompleteReason, ContactCacheMeta, ContactRelationRecord, ContactSyncMode, ContactVersionState, UserInfoSummary } from './cache-types';
+import type { ContactSnapshot, ContactSyncSource } from '../types/contact';
+export declare class ContactCache {
+    private readonly items;
+    private versionState;
+    private meta;
+    load(rawItems: ReadonlyArray<ContactRelationRecord>, versionState?: ContactVersionState | null, meta?: ContactCacheMeta | null): void;
+    getAll(): ReadonlyArray<ContactRelationRecord>;
+    getVersionState(): ContactVersionState;
+    getMeta(): ContactCacheMeta;
+    getUserIds(): ReadonlyArray<string>;
+    replaceAll(items: ReadonlyArray<ContactRelationRecord>): void;
+    upsert(items: ReadonlyArray<ContactRelationRecord>): void;
+    addByNotice(userId: string, updatedAt: number): boolean;
+    remove(userId: string): boolean;
+    updateRemark(userId: string, remark: string, updatedAt: number): boolean;
+    setVersionState(state: ContactVersionState): void;
+    updateVersionFromNotice(version: string, updatedAt: number): boolean;
+    setMeta(meta: ContactCacheMeta): void;
+    updateMeta(options: {
+        cacheIntegrity: 'complete' | 'incomplete';
+        reason?: ContactCacheIncompleteReason;
+        lastSyncTs?: number;
+        lastSuccessfulVersion?: string;
+        lastSyncMode?: ContactSyncMode;
+    }): void;
+    computeIntegrity(userInfos: ReadonlyArray<UserInfoSummary>): ContactCacheMeta;
+    buildSnapshot(userInfos: ReadonlyArray<UserInfoSummary>, source: ContactSyncSource): ContactSnapshot;
+    private normalizeRecord;
+    private normalizeVersionState;
+    private normalizeMeta;
+}

package/cache/conversation-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 会话摘要缓存
+ */
+import type { ConversationSummary } from './cache-types';
+import type { ConversationType } from '../types/conversation';
+export declare class ConversationCache {
+    private items;
+    load(rawItems: ReadonlyArray<ConversationSummary>, now: number): void;
+    getAll(): ReadonlyArray<ConversationSummary>;
+    setAll(items: ReadonlyArray<ConversationSummary>): void;
+    updateLastAccess(conversationIds: ReadonlyArray<{
+        conversationId: string;
+        type: ConversationType;
+    }>, now: number): boolean;
+    removeExpired(ttlMs: number, now: number): boolean;
+    evictByLru(removeCount: number): boolean;
+    trimMax(maxCount?: number): boolean;
+    private findIndex;
+    private normalizeItem;
+    private normalizeMessage;
+}

package/cache/group-namecard-cache.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 群名片缓存
+ */
+import type { GroupNamecardCacheRecord } from './cache-types';
+export declare class GroupNamecardCache {
+    private readonly items;
+    load(rawItems: ReadonlyArray<GroupNamecardCacheRecord>, now: number): void;
+    getAll(): ReadonlyArray<GroupNamecardCacheRecord>;
+    get(groupId: string, userId: string, now: number, updateAccess: boolean): GroupNamecardCacheRecord | null;
+    getByGroupId(groupId: string, now: number, updateAccess: boolean): ReadonlyArray<GroupNamecardCacheRecord>;
+    setAll(items: ReadonlyArray<GroupNamecardCacheRecord>, now: number): void;
+    remove(targets: ReadonlyArray<{
+        groupId: string;
+        userId: string;
+    }>): void;
+    removeExpired(ttlMs: number, now: number, protectedUserIds?: ReadonlySet<string>): boolean;
+    evictByLru(removeCount: number, protectedUserIds?: ReadonlySet<string>): boolean;
+    trimMax(maxCount: number, protectedUserIds?: ReadonlySet<string>): boolean;
+    private normalizeItem;
+}