easemob-websdk 4.24.1 → 5.0.0

package/upload/types.d.ts

@@ -0,0 +1,79 @@
+import type { ChatConversationType, FileUploadProgress, FileUploadResult, ImageType, Message, MessageType, SendMessageOptions, CombineMessageBody, FileMessageBody, ImageMessageBody, VideoMessageBody, VoiceMessageBody } from '../types';
+import type { ImageProcessor, NormalizedUploadSource, RequestAdapter } from '../platform';
+import type { DataReportOperationHandle } from '../data-report/types';
+export type AttachmentMessageType = Extract<MessageType, 'image' | 'video' | 'voice' | 'file' | 'combine'>;
+export type ImagePolicyReason = 'explicit-original' | 'default-large' | 'gif-force-origin' | 'large-fallback-origin';
+export type ImageCandidateSourceKind = 'origin' | 'big';
+export type AttachmentPrecheckThresholdType = 'image-origin' | 'image-big' | 'attachment';
+export type AttachmentMessageBody = ImageMessageBody | VideoMessageBody | VoiceMessageBody | FileMessageBody | CombineMessageBody;
+export interface UploadConfig {
+    restBaseUrl: string;
+    token: string;
+    appKey: string;
+    useCustomAttachmentUpload?: boolean;
+    enableMd5Check?: boolean;
+    enableMultipartUpload?: boolean;
+    requestAdapter?: RequestAdapter;
+    imageProcessor?: ImageProcessor;
+}
+export interface UploadRequest {
+    message: Message;
+    file: Blob;
+    conversationId: string;
+    conversationType: ChatConversationType;
+    messageType: AttachmentMessageType;
+    imageType?: ImageType;
+    md5?: string;
+    width?: number;
+    height?: number;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    thumbnailWidth?: number;
+    thumbnailHeight?: number;
+    callbacks?: SendMessageOptions;
+    config: UploadConfig;
+    dataReportOperation?: DataReportOperationHandle;
+}
+export interface UploadResponseEntity {
+    uuid?: string;
+    uri?: string;
+    exists?: boolean;
+    type?: string;
+    ['exists-type']?: 'origin' | 'large';
+    ['share-secret']?: string;
+    ['file-metadata']?: Record<string, unknown>;
+}
+export interface UploadResponsePayload {
+    entities?: UploadResponseEntity[];
+    uri?: string;
+}
+export interface ImageSendPolicy {
+    readonly resolvedImageType: ImageType;
+    readonly reason: ImagePolicyReason;
+}
+export interface ResolvedImageCandidate {
+    readonly imagePolicy: ImageSendPolicy;
+    readonly sourceKind: ImageCandidateSourceKind;
+    readonly fileInfo: NormalizedUploadSource;
+    readonly width: number;
+    readonly height: number;
+    readonly localUrl?: string;
+    readonly md5?: string;
+}
+export interface AttachmentPrecheckDecision {
+    readonly shouldPrecheck: boolean;
+    readonly thresholdType: AttachmentPrecheckThresholdType;
+    readonly thresholdBytes: number;
+    readonly actualBytes: number;
+    readonly reason: 'below-threshold' | 'threshold-exceeded';
+}
+export interface AttachmentPrecheckResult {
+    readonly uuid?: string;
+    readonly exists: boolean;
+    readonly existsType?: ImageType;
+    readonly shareSecret?: string;
+    readonly hit: boolean;
+}
+export type UploadProgressEvent = FileUploadProgress;
+export type UploadResult = FileUploadResult;

package/upload/utils.d.ts

@@ -0,0 +1,71 @@
+import { type NormalizedUploadSource } from '../platform/upload/upload-source';
+import type { CompatibleFile, ImageMessageBody, ImageType } from '../types';
+import type { AttachmentMessageBody, AttachmentMessageType, AttachmentPrecheckDecision, AttachmentPrecheckResult, AttachmentPrecheckThresholdType, ImageSendPolicy, UploadResponsePayload } from './types';
+export type ProtocolImageType = 1 | 2;
+export declare const IMAGE_TYPE_ORIGINAL: ImageType;
+export declare const IMAGE_TYPE_LARGE: ImageType;
+export declare const PROTOCOL_IMAGE_TYPE_ORIGINAL: ProtocolImageType;
+export declare const PROTOCOL_IMAGE_TYPE_LARGE: ProtocolImageType;
+export declare const IMAGE_PRECHECK_ORIGINAL_THRESHOLD: number;
+export declare const ATTACHMENT_PRECHECK_THRESHOLD: number;
+export declare const isRemoteUrl: (url: string) => boolean;
+export declare const isLocalUrl: (url: string) => boolean;
+export declare const shouldUploadByUrl: (url: string | undefined, hasData: boolean) => boolean;
+export declare const parseAppKey: (appKey: string) => {
+    orgName: string;
+    appName: string;
+};
+export declare const toUploadChatType: (conversationType: string) => string;
+export declare const appendUrlQueryParams: (url: string, params: Record<string, string | number | undefined>) => string;
+export declare const appendAttachUrlParams: (url: string, secret?: string) => string;
+export declare const resolveImageSendPolicy: (body: ImageMessageBody) => ImageSendPolicy;
+export declare const resolvePrecheckThresholdType: (messageType: AttachmentMessageType, imageType?: ImageType) => AttachmentPrecheckThresholdType;
+export declare const resolvePrecheckThresholdBytes: (thresholdType: AttachmentPrecheckThresholdType) => number;
+export declare const buildAttachmentPrecheckDecision: (options: {
+    messageType: AttachmentMessageType;
+    fileSize: number;
+    imageType?: ImageType;
+}) => AttachmentPrecheckDecision;
+export declare const isAttachmentPrecheckHit: (result: {
+    exists: boolean;
+    uuid?: string;
+    shareSecret?: string;
+}) => boolean;
+export declare const parseAttachmentPrecheckResult: (payload: UploadResponsePayload) => AttachmentPrecheckResult;
+export declare const deriveImageUrls: (remotePath: string, options?: {
+    deriveVariants?: boolean;
+}) => {
+    originalImageUrl?: string;
+    bigImageUrl?: string;
+    thumbnailUrl?: string;
+};
+export declare const toUploadImageType: (imageType: ImageType | undefined) => "origin" | "large";
+export declare const toProtocolImageType: (imageType: ImageType | undefined) => ProtocolImageType;
+export declare const fromProtocolImageType: (imageType: unknown) => ImageType;
+export declare const buildUploadResult: (options: {
+    response: UploadResponsePayload;
+    restBaseUrl: string;
+    orgName: string;
+    appName: string;
+    fileType: string;
+    fileName: string;
+    fallbackSize: number;
+    messageType: AttachmentMessageType;
+    imageType?: ImageType;
+    width?: number;
+    height?: number;
+    useCustomAttachmentUpload?: boolean;
+}) => {
+    url?: string;
+    isOriginalImage?: boolean;
+    originalImageUrl?: string;
+    bigImageUrl?: string;
+    secret?: string;
+    fileLength?: number;
+    filetype?: string;
+    filename?: string;
+    thumbnailUrl?: string;
+    width?: number;
+    height?: number;
+};
+export declare const normalizeAttachmentFile: (file: CompatibleFile | undefined, body: AttachmentMessageBody) => NormalizedUploadSource;

package/utils/env.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 运行时环境判断
+ */
+export declare const isUniAppRuntime: () => boolean;

package/utils/error-codes.d.ts

@@ -0,0 +1,2 @@
+export { ERROR_CODES } from './error-codes.generated';
+export type { ErrorCode } from './error-codes.generated';

package/utils/error-codes.generated.d.ts

@@ -0,0 +1,145 @@
+export declare const ERROR_CODES: {
+    readonly VALIDATION_REQUIRED: number;
+    readonly VALIDATION_INVALID_FORMAT: number;
+    readonly VALIDATION_UNKNOWN: number;
+    readonly AUTH_ALREADY_LOGIN: number;
+    readonly AUTH_NOT_LOGIN: number;
+    readonly AUTH_UNAUTHORIZED: number;
+    readonly AUTH_FORBIDDEN: number;
+    readonly AUTH_TOKEN_EXPIRED: number;
+    readonly AUTH_BIND_ANOTHER_DEVICE: number;
+    readonly AUTH_LOGIN_TOO_MANY_DEVICES: number;
+    readonly AUTH_USER_MUTED: number;
+    readonly CONNECTION_TIMEOUT: number;
+    readonly CONNECTION_WEBSOCKET_ERROR: number;
+    readonly CONNECTION_NOT_CREATED: number;
+    readonly CONNECTION_CLOSED_BEFORE_READY: number;
+    readonly CONNECTION_CANCELLED: number;
+    readonly CONNECTION_PROVISION_TIMEOUT: number;
+    readonly CONNECTION_PROVISION_REJECTED: number;
+    readonly CONNECTION_PROVISION_CLOSED: number;
+    readonly CONNECTION_DNSLIST_FAILED: number;
+    readonly STORAGE_OPERATION_FAILED: number;
+    readonly MESSAGE_NOT_CONNECTED: number;
+    readonly MESSAGE_ACK_TIMEOUT: number;
+    readonly MESSAGE_SEND_FAILED: number;
+    readonly MESSAGE_SENDER_DESTROYED: number;
+    readonly MESSAGE_ENCODE_FAILED: number;
+    readonly MESSAGE_DECODE_FAILED: number;
+    readonly MESSAGE_ACK_MISSING: number;
+    readonly MESSAGE_BLOCKED_BY_RECIPIENT: number;
+    readonly OPERATION_UNSUPPORTED: number;
+    readonly SERVER_BUSY: number;
+    readonly ATTACHMENT_NOT_FOUND: number;
+    readonly ATTACHMENT_INVALID: number;
+    readonly ATTACHMENT_EXPIRED: number;
+    readonly MESSAGE_INCLUDE_ILLEGAL_CONTENT: number;
+    readonly MESSAGE_SEND_TRAFFIC_LIMIT: number;
+    readonly MESSAGE_RECALL_TIME_LIMIT: number;
+    readonly SERVICE_NOT_ENABLED: number;
+    readonly MESSAGE_EXPIRED: number;
+    readonly MESSAGE_ILLEGAL_WHITELIST: number;
+    readonly MESSAGE_EXTERNAL_LOGIC_BLOCKED: number;
+    readonly MESSAGE_CURRENT_LIMITING: number;
+    readonly MESSAGE_SIZE_LIMIT: number;
+    readonly MESSAGE_EDIT_FAILED: number;
+    readonly INVALID_CONVERSATION: number;
+    readonly USER_LOGIN_ANOTHER_DEVICE: number;
+    readonly USER_REMOVED: number;
+    readonly USER_KICKED_BY_CHANGE_PASSWORD: number;
+    readonly USER_KICKED_BY_OTHER_DEVICE: number;
+    readonly USER_ALREADY_LOGIN_ANOTHER: number;
+    readonly USER_MUTED_BY_ADMIN: number;
+    readonly USER_DEVICE_CHANGED: number;
+    readonly USER_NOT_ON_ROSTER: number;
+    readonly SERVER_SERVING_DISABLED: number;
+    readonly FILE_DOWNLOAD_FAILED: number;
+    readonly FILE_TOO_LARGE: number;
+    readonly FILE_CONTENT_IMPROPER: number;
+    readonly THIRD_MODERATION_FAILED: number;
+    readonly THIRD_DEFAULT_FAILED: number;
+    readonly STREAM_SEND_NOT_SUPPORTED: number;
+    readonly STREAM_CHUNK_INVALID: number;
+    readonly STREAM_TIMEOUT_BY_SERVER: number;
+    readonly STREAM_STATE_CONFLICT: number;
+    readonly COMBINE_INVALID_INPUT: number;
+    readonly COMBINE_LEVEL_EXCEEDED: number;
+    readonly COMBINE_ITEM_LIMIT_EXCEEDED: number;
+    readonly COMBINE_ENCODE_FAILED: number;
+    readonly COMBINE_UPLOAD_FAILED: number;
+    readonly COMBINE_DOWNLOAD_FAILED: number;
+    readonly COMBINE_PARSE_FAILED: number;
+    readonly REST_NETWORK_ERROR: number;
+    readonly REST_TIMEOUT: number;
+    readonly REST_HTTP_ERROR: number;
+    readonly REST_BUSINESS_UNKNOWN: number;
+    readonly PUSH_TOKEN_UPLOAD_FAILED: number;
+    readonly PUSH_SILENT_MODE_OPERATION_FAILED: number;
+    readonly PUSH_LANGUAGE_OPERATION_FAILED: number;
+    readonly USER_INFO_SUBSCRIPTION_LIMIT_EXCEEDED: number;
+    readonly USER_INFO_SUBSCRIPTION_TARGET_LIMIT_EXCEEDED: number;
+    readonly USERINFO_USERCOUNT_EXCEED: number;
+    readonly USERINFO_DATALENGTH_EXCEED: number;
+    readonly CONTACT_ADD_USER_NOT_FOUND: number;
+    readonly CONTACT_ADD_ALREADY_FRIEND: number;
+    readonly CONTACT_ADD_BLOCKED_BY_USER: number;
+    readonly CONTACT_SET_REMARK_NOT_FRIEND: number;
+    readonly CONTACT_REACH_LIMIT: number;
+    readonly CONTACT_REACH_LIMIT_PEER: number;
+    readonly CONTACT_BLOCKLIST_USER_NOT_FOUND: number;
+    readonly GROUP_INVALID_ID: number;
+    readonly GROUP_ALREADY_JOINED: number;
+    readonly GROUP_NOT_JOINED: number;
+    readonly GROUP_PERMISSION_DENIED: number;
+    readonly GROUP_MEMBERS_FULL: number;
+    readonly GROUP_SHARED_FILE_INVALID_ID: number;
+    readonly GROUP_NOT_EXIST: number;
+    readonly GROUP_DISABLED: number;
+    readonly GROUP_NAME_VIOLATION: number;
+    readonly GROUP_MEMBER_ATTRIBUTES_REACH_LIMIT: number;
+    readonly GROUP_MEMBER_ATTRIBUTES_UPDATE_FAILED: number;
+    readonly GROUP_MEMBER_ATTRIBUTES_KEY_REACH_LIMIT: number;
+    readonly GROUP_MEMBER_ATTRIBUTES_VALUE_REACH_LIMIT: number;
+    readonly GROUP_USER_IN_BLOCKLIST: number;
+    readonly CHATROOM_INVALID_ID: number;
+    readonly CHATROOM_NOT_JOINED: number;
+    readonly CHATROOM_PERMISSION_DENIED: number;
+    readonly CHATROOM_MEMBERS_FULL: number;
+    readonly CHATROOM_NOT_EXIST: number;
+    readonly CHATROOM_OWNER_NOT_ALLOW_LEAVE: number;
+    readonly CHATROOM_USER_IN_BLOCKLIST: number;
+    readonly CONTACT_SYNC_METADATA_FAILED: number;
+    readonly CONTACT_SYNC_SOCKET_FAILED: number;
+    readonly CONTACT_SYNC_CURSOR_INVALID: number;
+    readonly CONTACT_SYNC_PROTO_DECODE_FAILED: number;
+    readonly CONTACT_SYNC_CANCELLED: number;
+    readonly SESSION_LIST_SOCKET_FAILED: number;
+    readonly SESSION_LIST_PROTO_DECODE_FAILED: number;
+    readonly SESSION_LIST_REQUEST_INVALID: number;
+    readonly SESSION_LIST_FETCH_FAILED: number;
+    readonly SESSION_LIST_SERVICE_DISABLED: number;
+    readonly SESSION_LIST_CANCELLED: number;
+    readonly PRESENCE_PARAM_LENGTH_EXCEED: number;
+    readonly PRESENCE_CANNOT_SUBSCRIBE_YOURSELF: number;
+    readonly TRANSLATE_PARAM_INVALID: number;
+    readonly TRANSLATE_SERVICE_NOT_ENABLED: number;
+    readonly TRANSLATE_USAGE_LIMIT: number;
+    readonly TRANSLATE_FAILED: number;
+    readonly VOICE_TO_TEXT_FILE_INVALID: number;
+    readonly VOICE_TO_TEXT_FILE_DURATION_TOO_LONG: number;
+    readonly VOICE_TO_TEXT_FAILED: number;
+    readonly VOICE_TO_TEXT_FILE_NOT_FOUND: number;
+    readonly VOICE_TO_TEXT_FILE_TOO_LARGE: number;
+    readonly REACTION_REACH_LIMIT: number;
+    readonly REACTION_ALREADY_OPERATED: number;
+    readonly REACTION_OPERATION_ILLEGAL: number;
+    readonly UPLOAD_REQUIRED_FIELD_MISSING: number;
+    readonly UPLOAD_INVALID_APPKEY: number;
+    readonly UPLOAD_SIZE_EXCEEDED: number;
+    readonly UPLOAD_REQUEST_FAILED: number;
+    readonly UPLOAD_TIMEOUT: number;
+    readonly UPLOAD_ABORTED: number;
+    readonly SERVICE_LIMIT_EXCEEDED: number;
+    readonly UNKNOWN: number;
+};
+export type ErrorCode = number;

package/utils/error-sanitizer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 从公开错误详情中的 URL 删除凭据、查询参数值和 Fragment。
+ */
+export declare const sanitizeErrorUrl: (url: string) => string;
+/**
+ * 对错误详情中的 URL 字段执行统一脱敏。
+ */
+export declare const sanitizeErrorDetails: (details: Record<string, unknown>) => Record<string, unknown>;

package/utils/errors.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 错误处理类
+ *
+ * 统一的错误类型和错误码定义
+ */
+import { type ErrorCode } from './error-codes';
+/**
+ * [zh-CN] SDK 错误附加详情。
+ *
+ * [en-US] Additional details attached to an SDK error.
+ */
+export type ErrorDetails = Record<string, unknown>;
+/**
+ * [zh-CN] SDK 错误上下文。
+ *
+ * [en-US] Context associated with an SDK error.
+ */
+export interface ErrorContext {
+    /**
+     * [zh-CN] 用于诊断错误的结构化附加信息。
+     *
+     * [en-US] Structured additional information for diagnosing the error.
+     */
+    details?: ErrorDetails;
+}
+/**
+ * SDK 错误类
+ */
+export declare class SDKError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: ErrorDetails;
+    constructor(message: string, code?: ErrorCode, context?: ErrorContext);
+    /**
+     * 转换为 JSON
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 网络错误
+ */
+export declare class NetworkError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * 连接错误
+ */
+export declare class ConnectionError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * 认证错误
+ */
+export declare class AuthenticationError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * 验证错误
+ */
+export declare class ValidationError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * 消息发送错误
+ */
+export declare class MessageSendError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * 消息接收错误
+ */
+export declare class MessageReceiveError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * 存储错误
+ */
+export declare class StorageError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+export declare class RestTransportError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+export declare class RestBusinessError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * 上传错误
+ */
+export declare class UploadError extends SDKError {
+    constructor(message: string, context?: ErrorContext & {
+        code?: ErrorCode;
+    });
+}
+/**
+ * [zh-CN] 判断未知值是否为 SDK 错误。
+ *
+ * 除当前模块创建的实例外，该方法也支持识别 iframe、微前端或重复安装的
+ * SDK 副本所创建的结构兼容错误。
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.login({ userId: 'u1', token: 'token' });
+ * } catch (error: unknown) {
+ *   if (isSDKError(error)) {
+ *     console.error(error.toJSON());
+ *   }
+ * }
+ * ```
+ *
+ * @param error [zh-CN] 需要判断的未知值。[en-US] The unknown value to inspect.
+ * @returns [zh-CN] 值为 SDK 错误时返回 `true`，并将类型收窄为 `SDKError`。
+ * [en-US] Returns `true` when the value is an SDK error and narrows it to `SDKError`.
+ * @throws [zh-CN] 此函数不会抛出错误。[en-US] This function does not throw errors.
+ *
+ * [en-US] Checks whether an unknown value is an SDK error.
+ *
+ * In addition to instances created by this module, this function recognizes structurally
+ * compatible errors created in iframes, micro-frontends, or duplicate SDK copies.
+ */
+export declare function isSDKError(error: unknown): error is SDKError;

package/utils/log-reporter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 日志上报器
+ *
+ * 支持缓存、分片与定时上报
+ */
+import type { LogLevel } from '../types';
+import type { RequestAdapter } from '../platform/types';
+export interface LogReporterContext {
+    restBaseUrl?: string;
+    appKey?: string;
+    userId?: string;
+    token?: string;
+    resource?: string;
+    requestAdapter?: RequestAdapter;
+}
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    args: ReadonlyArray<unknown>;
+}
+export interface LogReporterOptions {
+    reportIntervalMs?: number;
+    reportTimeoutMs?: number;
+    chunkDelayMs?: number;
+    maxChunkBytes?: number;
+    maxBufferBytes?: number;
+}
+export type LogReportState = 'unknown' | 'enabled' | 'disabled';
+export declare class LogReporter {
+    private state;
+    private reportIntervalMs;
+    private readonly reportTimeoutMs;
+    private readonly chunkDelayMs;
+    private readonly maxChunkBytes;
+    private readonly maxBufferBytes;
+    private timerId;
+    private reporting;
+    private context;
+    private buffer;
+    private bufferBytes;
+    constructor(options?: LogReporterOptions);
+    setEnabled(enabled: boolean): void;
+    setState(state: LogReportState): void;
+    updateContext(context: Partial<LogReporterContext>): void;
+    updateReportInterval(reportIntervalMs: number | undefined): void;
+    append(entry: LogEntry): void;
+    reportNow(): Promise<void>;
+    stop(): void;
+    private clearBuffer;
+    private start;
+    private normalizeReportInterval;
+    private canReport;
+    private formatEntry;
+    private pushBuffer;
+    private consumeBuffer;
+    private requeueChunk;
+    private reportLogs;
+    private reportChunk;
+}
+export declare const logReporter: LogReporter;

package/utils/log-sanitizer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 日志脱敏工具
+ *
+ * 对敏感字段进行掩码处理，遵循最小必要原则
+ */
+export declare const sanitizeLogArgs: (args: ReadonlyArray<unknown>) => ReadonlyArray<unknown>;

package/utils/logger.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 日志工具
+ *
+ * 支持结构化日志，多级别日志控制
+ */
+import { type LogReporterContext, type LogReportState } from './log-reporter';
+import type { LogLevel } from '../types';
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * 设置全局日志级别
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * 设置自定义日志器
+ */
+export declare function setLogger(logger: Logger): void;
+/**
+ * 获取当前日志器
+ */
+export declare function getLogger(): Logger;
+/**
+ * 设置日志上报开关
+ */
+export declare function setLogReportEnabled(enabled: boolean): void;
+/** 设置 DNS 驱动的日志上报三态。 */
+export declare function setLogReportState(state: LogReportState): void;
+/**
+ * 更新日志上报上下文
+ */
+export declare function updateLogReportContext(context: Partial<LogReporterContext>): void;
+/** 按毫秒更新 DNS 下发的日志上报间隔；缺失时恢复默认 5 分钟。 */
+export declare function setLogReportInterval(reportIntervalMs: number | undefined): void;
+/**
+ * 立即触发日志上报
+ */
+export declare function reportLogsNow(): Promise<void>;
+/**
+ * 停止日志上报定时器
+ */
+export declare function stopLogReporter(): void;
+/**
+ * 导出日志方法
+ */
+export declare const logger: Logger;

package/utils/md5.d.ts

@@ -0,0 +1 @@
+export declare const computeMd5Hex: (bytes: Uint8Array) => string;

package/utils/message-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 消息本地 ID 与本地 URL 生成工具
+ */
+import type { CompatibleFile } from '../types';
+/**
+ * 生成本地可用的文件 URL
+ */
+export declare const createLocalFileUrl: (file: CompatibleFile) => string | undefined;
+/**
+ * 生成本地消息 ID
+ */
+export declare const generateMsgLocalId: () => string;

package/utils/provision-error-mapping.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Provision 错误码到 EMError 的映射
+ */
+import { type ErrorCode } from './error-codes';
+/**
+ * Provision 错误解析结果
+ */
+export interface ProvisionErrorResolution {
+    readonly code: ErrorCode;
+    readonly retryable: boolean;
+}
+/** 消息发送错误解析结果 */
+export interface MessageSendErrorResolution extends ProvisionErrorResolution {
+    readonly message: string;
+}
+export declare const resolveProvisionError: (statusCode: number | undefined, reason?: string) => ProvisionErrorResolution;
+export declare const resolveProvisionErrorCode: (statusCode: number | undefined, reason?: string) => ErrorCode;
+/**
+ * 将消息 ACK 的状态码和原因解析为面向调用方的具体错误。
+ */
+export declare const resolveMessageSendError: (statusCode: number | undefined, reason?: string) => MessageSendErrorResolution;

package/utils/retry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 重试工具
+ *
+ * 支持指数退避策略
+ */
+export interface RetryOptions {
+    maxAttempts?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+    jitter?: boolean;
+}
+/**
+ * 重试函数
+ *
+ * @param fn 要重试的函数
+ * @param options 重试选项
+ * @returns Promise，成功时返回函数结果，失败时抛出最后一个错误
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * 重试函数（带条件判断）
+ *
+ * 只有满足条件的错误才会重试
+ */
+export declare function retryWithCondition<T>(fn: () => Promise<T>, shouldRetry: (error: unknown) => boolean, options?: RetryOptions): Promise<T>;

package/utils/runtime-global.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 统一获取跨运行时可用的全局对象。
+ */
+export declare const getRuntimeGlobal: <TGlobal extends object>(runtimeInput?: TGlobal) => TGlobal;

package/utils/trace-id.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 生成链路追踪 ID（时间戳 + 随机数）
+ */
+export declare const createTraceId: () => string;
+export declare const REQUEST_ID_HEADER = "X-Request-Id";

package/utils/utf8.d.ts

@@ -0,0 +1,2 @@
+export declare const encodeUtf8: (value: string) => Uint8Array;
+export declare const decodeUtf8: (bytes: Uint8Array) => string;