@docoi/mys-sdk 1.0.3 → 1.1.0

package/dist/transport/legacy.d.ts

@@ -0,0 +1,27 @@
+import { Transport } from '../types';
+/**
+ * 旧通道调用失败。
+ *
+ * kind 表达失败发生在哪一层，bridge.ts 据此映射 errCode：
+ * - `communication`：没形成完整的「发出 → 原生收到 → 回包」回合（找不到管道、发送抛错）
+ * - `native`：回合完成了，原生明确拒绝（旧原生只有「方法不存在」这一种）
+ */
+export declare class LegacyChannelError extends Error {
+    readonly kind: 'communication' | 'native';
+    constructor(kind: 'communication' | 'native', message: string);
+}
+/**
+ * import 时为 window.JSBridgeEvent 放一个空函数。
+ *
+ * 旧版 Native 在新版 App 上仍会广播页面生命周期事件（h5PageShow 等），与 H5 是否订阅无关；
+ * 三个全局入口是懒安装的，未装时该函数不存在，Native 调用会抛 TypeError（iOS）/ Script error（Android）。
+ * 此时也没有旧通道监听，先放一个静默空函数，首次真正使用旧通道时 ensureInstalled 会换成真实处理函数。
+ *
+ * 不能用 isInApp() 判断：它会缓存 App 信息，而 Demo 要在 import 之后、首次调用之前写入模拟版本。
+ */
+export declare function installEventStub(): void;
+/**
+ * 旧通道传输。状态在模块级共享，走哪个通道由 App 版本决定，一个页面只会用到其中一个。
+ * 每次调用前都会确保全局入口已安装，因此首次调用起 Native 就能回调 H5。
+ */
+export declare const legacyTransport: Transport;

package/dist/types/base.d.ts

@@ -1,7 +1,7 @@
 /**
  * mys-sdk 基础协议类型
  *
- * 定义 Native 与 SDK 对外暴露的统一数据格式。
+ * 定义 Native 与 SDK 对外暴露的统一数据格式，以及 Bridge 层的调用与监听选项。
  *
  * @module types/base
  */
@@ -29,12 +29,10 @@ export interface NativeResponse<TResult = void> {
 export interface ApiError {
     /** 错误描述，格式：`fnName:fail ...` */
     readonly errMsg: string;
-    /** 错误码，-1 表示参数校验失败或未知错误 */
+    /** 错误码，-1 表示未知异常 */
     readonly errCode: number;
-    /** Native result 或额外错误详情 */
+    /** 排查用的原始数据：Native 回包，或 SDK 判定失败时的依据；没有额外依据时不存在 */
     readonly errDetail?: unknown;
-    /** Native 原始响应，便于排查联调问题 */
-    readonly raw?: NativeResponse<unknown>;
 }
 /**
  * API 回调接口。
@@ -52,3 +50,77 @@ export interface Callbacks<TResult = void> {
     /** 完成回调，成功时返回 NativeResponse，失败时返回 ApiError */
     complete?: (res?: NativeResponse<TResult> | ApiError) => void;
 }
+/** 通信通道：mysJSBridge 为新通道，jsbridge 为旧通道，local 为不经过 Native 的本地动作（如 location.href、postMessage） */
+export type Channel = 'mysJSBridge' | 'jsbridge' | 'local';
+/** 通道单次调用的选项 */
+export interface ChannelCallOptions {
+    /** `serial` 时同一方法名的调用串行，其余并行 */
+    queue?: 'parallel' | 'serial';
+    /** 超时毫秒数，`false` 表示不超时；旧通道不实现超时，会忽略该字段 */
+    timeout?: number | false;
+}
+/** 通道调试日志选项 */
+export interface ChannelDebugOptions {
+    /** 最低日志级别：debug / info / warn / error */
+    logLevel?: string;
+    /** 是否输出到控制台 */
+    useConsole?: boolean;
+}
+/**
+ * 通信通道：mys-sdk 对底层传输的全部依赖。
+ *
+ * 新通道由 `@docoi/jsbridge-sdk` 提供；旧通道 jsbridge 由 `transport/legacy.ts` 自己实现，
+ * 因为旧 App 的通道命名与新通道不同，且旧通道会随 App 最低版本上升整体删除。
+ */
+export interface Transport {
+    /** 发起一次调用，resolve 原生原始回包（不拆 `{ code, msg, result }` 信封）；reject 表示这次调用失败 */
+    callAsync(method: string, data: Record<string, unknown>, options?: ChannelCallOptions): Promise<unknown>;
+    /** 监听原生事件 */
+    on(event: string, handler: (payload: unknown) => void): void;
+    /** 取消监听 */
+    off(event: string, handler: (payload: unknown) => void): void;
+    /** 注册供原生调用的方法 */
+    register(name: string, handler: (data: unknown) => unknown): void;
+    /** 注销注册的方法 */
+    unregister(name: string): void;
+    /** 开关调试日志 */
+    setDebug(enabled: boolean, options?: ChannelDebugOptions): void;
+}
+/** invoke 的扩展选项，在单次调用的通道选项之上增加通道选择与数据转换能力 */
+export interface InvokeOptions extends ChannelCallOptions {
+    /** 支持新通道的最低 App 版本，低于该版本走旧通道 jsbridge；不传则始终走新通道 mysJSBridge */
+    since?: string;
+    /** 始终走旧通道 jsbridge，不看 App 版本：该能力只有旧通道实现，新通道没有对应方法。优先级高于 since */
+    legacyOnly?: boolean;
+    /** 转换新通道返回的业务数据（NativeResponse.result），在 success / complete / resolve 之前执行，仅在走新通道且响应成功时生效；抛错代表这次调用失败，走 fail → complete → reject */
+    transformResult?: (result: unknown) => unknown;
+    /** 旧通道 jsbridge 的差异处理，仅在走旧通道时生效，各项均可选；两个转换函数抛错都代表这次调用失败 */
+    jsbridge?: {
+        /** 转换发给旧通道的参数 */
+        data?: (data: Record<string, unknown>) => Record<string, unknown>;
+        /** 转换旧通道返回的原始数据，转换结果会作为 NativeResponse.result；抛 ApiError 表示业务失败，会原样透传 */
+        result?: (raw: unknown) => unknown;
+    };
+}
+/** 一次调用的路由结果，供调试使用 */
+export interface RouteInfo {
+    fnName: string;
+    channel: Channel;
+    appVersion?: string;
+    since?: string;
+    /** 实际发给 Native 的方法名 */
+    method: string;
+    /** 实际发给 Native 的参数 */
+    data: Record<string, unknown>;
+}
+/** Native 调 H5 注册的方法的处理函数 */
+export type NativeHandler<TData = unknown, TResult = unknown> = (data: TData) => TResult | Promise<TResult>;
+/** listen 的选项 */
+export interface ListenOptions<T = unknown> {
+    /** 支持新通道的最低 App 版本，低于该版本走旧通道 jsbridge；不传则始终走新通道 mysJSBridge */
+    since?: string;
+    /** 只监听一次，触发后自动取消 */
+    once?: boolean;
+    /** 转换事件 payload，在 callback 之前执行 */
+    transform?: (payload: unknown) => T;
+}

package/dist/types/enums.d.ts

@@ -13,39 +13,52 @@ export declare enum ToastDuration {
     /** 长时显示 */
     Long = 1
 }
-/** 媒体预览类型 */
-export type PreviewMediaType = "image" | "video";
 /** 媒体文件类型 */
 export type MediaFileType = "image" | "video";
-/** 系统设置页类型。当前仅支持通知设置页 */
-export type SettingType = "notice";
+/** 系统设置页类型，取值与 PermissionType 一致，checkPermission 查出未授权后用同一个值打开对应设置页 */
+export type SettingType = "camera" | "microphone" | "location" | "storage" | "notification";
 /** 权限类型 */
 export type PermissionType = "camera" | "microphone" | "location" | "storage" | "notification";
 /** 权限状态 */
 export type PermissionStatus = "granted" | "denied" | "permanentlyDenied";
 /** 摄像头方向 */
 export type CameraDirection = "back" | "front";
-/** Webview 容器类型 */
-export type WebviewType = "immersive" | "normal" | "mini";
-/** 平台 */
-export type Platform = "android" | "ios";
-/** 网络类型 */
-export type NetworkTypeStr = "wifi" | "2g" | "3g" | "4g" | "5g" | "unknown" | "none";
+/** Webview 容器类型（daoke type 5 的 h5Type） */
+export type WebviewType = "normal" | "mini" | "immersive";
+/** Webview 扩展类型 */
+export type WebviewExtType = "dynamic" | "transparent";
+/** App 底部 tab */
+export type TabBarType = "home" | "discover" | "message" | "mine";
+/** 发现页二级 tab */
+export type DiscoverSubTab = "friends" | "square" | "comic";
+/** 新版首页顶部 tab */
+export type HomeTab = "official" | "community";
+/** 圈子主页关系操作 */
+export type CircleRelationType = "apprentice" | "graduate" | "intimacyShare" | "takeApprentice";
+/** 活动中心 tab */
+export type ActivityCenterTab = "welfare" | "activity";
+/** 玩家举报的对象类型 */
+export type ReportObjectType = "user" | "circle" | "comment" | "trends" | "message";
 /**
- * 分享渠道
- * - 1: 微信好友
- * - 2: 朋友圈
- * - 3: QQ
+ * navigateTo 可跳转的原生页面
+ *
+ * 每个值对应的 params 见 NavigatePageParamsMap
  */
-export type ShareChannelType = 1 | 2 | 3;
+export type NavigatePage = "dynamicDetailPage" | "topicPage" | "likeListPage" | "circleHomePage" | "joinCirclePage" | "homePage" | "guideCatalogPage" | "gamePushSettingPage" | "userHomePage" | "groupChatPage" | "joinGroupPage" | "privateChatPage" | "myPublishPage" | "myFavoritePage" | "browseHistoryPage" | "profileEditPage" | "coinRechargePage" | "gameSubscribePage" | "douyinMallPage" | "activityCenterPage" | "adPage" | "coinDetailPage" | "miniGamesPage" | "bindGamePage" | "playerReportPage" | "addCustomEmojiPage";
 /**
- * 图片分享弹窗操作
- * - wechat: 微信好友
- * - moment: 微信朋友圈
- * - qq: QQ 好友
- * - save: 保存图片
- * - cancel: 取消
+ * shareWebCard 的分享范围，决定 Native 分享面板展示哪些入口
+ * - RecentContacts / 1：最近联系人
+ * - External / 2：站外渠道
+ * - Channel / 3：频道（serverId 为空时展示全部圈子频道）
  */
+export declare enum ShareType {
+    RecentContacts = 1,
+    External = 2,
+    Channel = 3
+}
+/** 图片分享弹窗操作 */
 export type ShareImageAction = "wechat" | "moment" | "qq" | "save" | "cancel";
-/** 文件类型标签 */
-export type FileTypeTag = "image" | "video";
+/** shareWebCard 的分享内容类型 */
+export type ShareContentType = 1 | 2 | 3;
+/** 通知原生更新数据的类型，对应 updateData 的 type，需要附带参数的类型在说明里给出 params 结构 */
+export type UpdateDataType = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;

package/dist/types/index.d.ts

@@ -1,7 +1,5 @@
 /**
- * mys-sdk 类型定义
- *
- * barrel re-export，按需从拆分后的子模块导出
+ * 类型 barrel：统一转发各子模块的类型定义。
  *
  * @module types
  */
@@ -9,3 +7,4 @@ export * from './base';
 export * from './enums';
 export * from './params';
 export * from './results';
+export * from './router';

package/dist/types/params.d.ts

@@ -1,32 +1,17 @@
 import { Callbacks } from './base';
-import { MediaFileType, SettingType, CameraDirection, ShareChannelType, PermissionType, PreviewMediaType, ToastDuration } from './enums';
-import { ChooseMediaResult, CheckPermissionResult, ShareImageResult, UploadFilesProgress, UploadFilesResult } from './results';
-/**
- * 事件监听选项。
- *
- * 事件监听属于 native-event 通道，回调直接接收 Native 原始 payload，
- * 不包装 code/msg/result。
- */
+import { MediaFileType, SettingType, CameraDirection, PermissionType, ShareContentType, ToastDuration, UpdateDataType, ShareType } from './enums';
+import { ChooseMediaResult, CheckPermissionResult, ShareImageResult, UploadFilesProgressCallback, UploadFilesResult, VoteData, OpenAppResult, OpenFriendsListResult, RecordAudioEndCallback, RecordAudioProgressCallback, SharedCallback, SharePictureUrlHandler } from './results';
+/** 事件监听选项 */
 export interface EventListenOptions {
     /** 是否只监听一次，触发后自动取消监听 */
     once?: boolean;
 }
-/**
- * showToast 参数
- *
- * @example
- * ```ts
- * mys.showToast({ text: '操作成功', duration: ToastDuration.Short })
- * ```
- */
+/** showToast 参数 */
 export interface ShowToastParams extends Callbacks {
     /** 提示内容 */
     text: string;
     /**
-     * 显示时长。
-     *
-     * - ToastDuration.Short / 0：短时显示
-     * - ToastDuration.Long / 1：长时显示
+     * 显示时长：Short 短时显示，Long 长时显示。
      *
      * @default ToastDuration.Short
      */
@@ -34,8 +19,8 @@ export interface ShowToastParams extends Callbacks {
 }
 /** openPhoneSetting 参数 */
 export interface OpenPhoneSettingParams extends Callbacks {
-    /** 设置页类型。当前仅支持 notice，表示系统通知设置页 */
-    type: SettingType;
+    /** 要打开的系统设置页类型，取值与 checkPermission 的 permission 一致 */
+    permission: SettingType;
 }
 /**
  * checkPermission 参数
@@ -48,17 +33,15 @@ export interface CheckPermissionParams extends Callbacks<CheckPermissionResult>
  * previewImage / previewVideo 参数
  */
 export interface PlayMediaParams extends Callbacks {
-    /** 图片/视频 URL 列表 */
+    /** 图片/视频 URL 列表，不能为空 */
     urls: string[];
     /**
-     * 当前预览资源的数组下标，从 0 开始。
+     * 当前预览资源在 urls 中的下标，从 0 开始，不能超出 urls 范围。
      *
      * @default 0
      */
     current?: number;
 }
-/** playMedia Native 调用媒体类型 */
-export type PlayMediaType = PreviewMediaType;
 /**
  * chooseMedia 参数
  */
@@ -96,35 +79,36 @@ export interface ChooseMediaParams extends Callbacks<ChooseMediaResult> {
 }
 /** uploadFiles 参数 */
 export interface UploadFilesParams extends Callbacks<UploadFilesResult> {
-    /** 待上传文件列表，单个文件也需要放在数组中 */
+    /** 待上传的临时文件路径列表，来自 chooseMedia 或 startRecordAudio 的 onEnd，单个文件也要放在数组中 */
     files: string[];
-    /** 腾讯云 COS 目录前缀，默认 multipleSource/common/ */
+    /**
+     * 腾讯云 COS 目录前缀。
+     *
+     * @default 'multipleSource/common/'
+     */
     cosDirPath?: string;
     /** 上传进度回调，仅 H5 侧生效 */
-    onProgress?: (progress: UploadFilesProgress) => void;
+    onProgress?: UploadFilesProgressCallback;
 }
-/** 保存媒体文件到系统相册的通用参数 */
+/** saveImageToPhotosAlbum 参数 */
 export interface SaveImageToPhotosAlbumParams extends Callbacks {
-    /** 文件路径 */
+    /** 图片的 base64 数据，支持 data URL 或纯 base64 */
     filePath: string;
 }
-/** saveVideoToPhotosAlbum 参数（与 SaveImageToPhotosAlbumParams 结构相同） */
-export type SaveVideoToPhotosAlbumParams = SaveImageToPhotosAlbumParams;
-/** startRecord 参数 */
-export interface StartRecordParams extends Callbacks {
-    /** 录音最大时长（秒） */
+/** startRecordAudio 参数 */
+export interface StartRecordAudioParams extends Callbacks {
+    /** 录音最大时长，单位秒，必须大于 0，到达后自动结束录音；不传则由宿主 App 决定 */
     maxDuration?: number;
+    /** 录音结束回调，手动停止、到达最长时长、被系统打断时触发，只对本次录音有效；取消录音不会触发 */
+    onEnd?: RecordAudioEndCallback;
+    /** 录音音量回调，录音期间持续触发，只对本次录音有效；触发频率由宿主 App 决定 */
+    onProgress?: RecordAudioProgressCallback;
 }
 /** setClipboardData 参数 */
 export interface SetClipboardDataParams extends Callbacks {
-    /** 剪贴板内容 */
+    /** 剪贴板内容，允许空字符串 */
     data: string;
 }
-/** 外部浏览器打开参数 */
-export interface OpenInExternalBrowserParams extends Callbacks {
-    /** 目标 URL */
-    url: string;
-}
 /** triggerVibrate 多段震动序列项 */
 export interface VibrateStep {
     /** 本段时长，单位 ms */
@@ -145,93 +129,106 @@ export interface TriggerVibrateParams extends Callbacks {
     /** 多段变力度震动序列。有此字段时忽略 duration / intensity */
     steps?: VibrateStep[];
     /**
-     * 是否循环。true 表示无限循环，直到调用 stopVibrate。
+     * 是否循环，只在多段震动（传了 steps）时生效。true 表示无限循环整个序列，直到调用 stopVibrate。
      *
      * @default false
      */
     repeat?: boolean;
 }
+/** openApp 参数 */
+export interface OpenAppParams extends Callbacks<OpenAppResult> {
+    /** 未安装时的下载地址 */
+    url?: string;
+    /** 要打开的 App 包名列表。Android 可传多个包名，iOS 传单个元素的数组 */
+    packageNames?: string[];
+}
+/** showPageName 参数 */
+export interface ShowPageNameParams extends Callbacks {
+    /** 页面类型：1 名人堂页面 */
+    nameType: number;
+}
+/** swipeBack 参数 */
+export interface SwipeBackParams extends Callbacks {
+    /** 是否启用侧滑返回，Native 默认启用 */
+    enable: boolean;
+}
 /**
- * shareWebCard 参数
+ * setBeforeInfo 参数：当前页面的埋点信息，字段由业务决定，会原样传给 Native。
  *
- * 分享网页卡片到社交平台（微信、QQ 等）
- *
- * @example
- * ```ts
- * mys.shareWebCard({
- *   title: '精彩文章',
- *   content: '点开看看',
- *   shareUrl: 'https://example.com/article/1'
- * })
- * ```
+ * 常见字段为 PageID（页面编号）和 PageName（页面名称），业务也可以追加自己的字段。
  */
+export interface SetBeforeInfoParams extends Callbacks {
+    /** 页面编号 */
+    PageID?: string | number;
+    /** 页面名称 */
+    PageName?: string;
+    [key: string]: unknown;
+}
+/** shareWebCard 参数 */
 export interface ShareWebCardParams extends Callbacks {
     /** 分享标题 */
     title: string;
-    /** 分享文案 */
-    content?: string;
+    /** 分享内容 */
+    content: string;
     /** 分享图标 URL */
-    icon?: string;
+    icon: string;
     /** 分享链接 */
-    shareUrl?: string;
-    /** 朋友圈文案 */
-    externalContent?: string;
+    shareUrl: string;
+    /** 聊天列表外显内容 */
+    externalContent: string;
     /**
-     * 分享渠道
+     * 分享面板展示的范围，取值见 ShareType：1 最近联系人，2 站外渠道，3 频道（serverId 为空时展示全部圈子频道）
      *
-     * @default [1, 2, 3]
+     * @default [ShareType.RecentContacts, ShareType.External, ShareType.Channel]
      */
-    shareTypes?: ShareChannelType[];
-    /** 是否为截图分享 */
+    shareTypes?: ShareType[];
+    /** 是否分享图片；为 true 时需要通过 getSharePictureUrl 提供图片地址 */
     isSharePic?: boolean;
-    /** 服务器资源 ID */
+    /** 指定分享的圈子 ID */
     serverId?: string;
-    /** 埋点数据 */
+    /** 用于 Native 埋点上报，需自行 JSON.stringify */
     trackData?: string;
-    /** 稻壳圈子分享链接 */
-    daokeUrl?: string;
-    /** 渠道 ID */
+    /** daoke 通用链接，用于 App 内打开沉浸式、普通 H5 页面等，不能为空 */
+    daokeUrl: string;
+    /** 指定分享的频道 ID，英文逗号分隔，serverId 不为空时才有效 */
     channelIds?: string;
-    /** 内容类型 */
-    contentType?: string;
+    /** 分享内容类型 */
+    contentType?: ShareContentType;
+    /** 动态详情，长文动态分享时传给客户端做动态相关操作，传对象时 SDK 会序列化为 JSON 字符串后下发 */
+    activityDetail?: string | Record<string, unknown>;
+    /** 用户完成分享后的回调，只对本次调用生效；用户取消分享不会触发 */
+    onShared?: SharedCallback;
+    /** 提供分享图片的地址，仅 isSharePic 为 true 时生效；用户点击客户端的生成图片按钮时 Native 才会调用，可以返回 Promise，截图或上传失败时不返回 pictureUrl */
+    getSharePictureUrl?: SharePictureUrlHandler;
 }
-/**
- * shareImage 参数
- *
- * 唤起客户端图片分享弹窗
- *
- * @example
- * ```ts
- * mys.shareImage({ url: 'https://example.com/poster.png' })
- * ```
- */
+/** shareImage 参数 */
 export interface ShareImageParams extends Callbacks<ShareImageResult> {
     /** 待分享图片的网络地址，需为 http(s) URL */
     url: string;
 }
-/**
- * showAd 参数
- *
- * 展示原生广告视频
- *
- * @example
- * ```ts
- * mys.showAd({ type: 1, circle_id: '123' })
- * ```
- */
+/** showAd 参数 */
 export interface ShowAdParams extends Callbacks {
-    /** 广告类型 */
+    /** 广告类型：1 激励（观影有礼、补签），2 平台运营相关（天天有礼加码、任务、抽奖） */
     type: number;
-    /** 社群/圈子 ID */
+    /** 广告业务参数 */
+    params: ShowAdBizParams;
+}
+/** showAd 业务参数 */
+export interface ShowAdBizParams {
+    /** 圈子 ID */
     circle_id?: string;
-    /** 循环天数 */
+    /** 周期天数 */
     cycle_day?: string | number;
-    /** 模块 */
+    /** 模块：1 观影，2 天天领福利 */
     module?: string | number;
-    /** 循环 ID */
+    /** 对象 JSON 字符串，不能传单纯字符串，必须用对象包裹后转成 JSON 字符串 */
+    module_data?: string;
+    /** 周期 ID */
     cycle_id?: string;
-    /** 转盘抽奖 ID */
+    /** 转盘 ID */
     wheel_lottery_id?: string | number;
+    /** 活动 ID */
+    activity_id?: string | number;
 }
 /** toBindGameRole 参数 */
 export interface BindGameRoleParams extends Callbacks {
@@ -240,3 +237,40 @@ export interface BindGameRoleParams extends Callbacks {
     /** 服务器 ID */
     serverId: string;
 }
+/** openCommentPanel 参数 */
+export interface OpenCommentPanelParams extends Callbacks {
+    /** 服务器 ID */
+    serverId: string;
+    /** 动态 ID */
+    dynamicId: string;
+    /** 评论 ID，传入时定位到该评论 */
+    commentId?: string;
+    /** 打开后是否自动聚焦输入框 */
+    autoFocusInput?: boolean;
+}
+/** voteAction 参数：当前投票数据加上被点击的选项下标 */
+export interface VoteActionParams extends VoteData, Callbacks<VoteData> {
+    /** 被点击的投票选项下标 */
+    index: number;
+}
+/** openGiftBag 参数 */
+export interface OpenGiftBagParams extends Callbacks {
+    /** 赠送对象的用户 ID */
+    user_id: string;
+    /** 是否切换到背包 */
+    openBag?: boolean;
+    /** 服务器 ID */
+    server_id: string;
+}
+/** openFriendsList 参数 */
+export interface OpenFriendsListParams extends Callbacks<OpenFriendsListResult> {
+    /** 已选好友 ID，会在列表中回显为选中状态，没有已选好友时传空数组 */
+    selectedUserIds: string[];
+}
+/** updateData 参数 */
+export interface UpdateDataParams extends Callbacks {
+    /** 更新的数据类型，各类型含义和对应的 params 结构见可选值说明 */
+    type: UpdateDataType;
+    /** 附带参数，结构随 type 变化，不需要参数的类型可省略 */
+    params?: Record<string, unknown>;
+}