sa2kit 3.8.0 → 3.9.1

package/dist/index-BHgDdlJW.d.mts

@@ -0,0 +1,177 @@
+/** 支持的第三方 App 提供方 */
+type AppProviderId = 'amap' | 'baidu' | 'google' | 'wechat' | 'qq' | 'generic';
+/** 运行平台 */
+type AppLaunchPlatform = 'web' | 'rn';
+/** 唤起结果状态 */
+type AppLaunchStatus = 'opened' | 'fallback' | 'unavailable' | 'cancelled' | 'timeout';
+type AppLaunchUrls = {
+    /** 优先尝试的 scheme / URI */
+    primary: string;
+    /** 无法唤起 App 时的降级链接（通常为 https://uri.* 网页版） */
+    fallback?: string;
+};
+type AppLaunchResult = {
+    provider: AppProviderId;
+    action: string;
+    status: AppLaunchStatus;
+    url: string;
+    platform: AppLaunchPlatform;
+    data?: Record<string, unknown>;
+};
+declare class AppLaunchError extends Error {
+    readonly code: 'UNKNOWN_PROVIDER' | 'UNKNOWN_ACTION' | 'INVALID_PARAMS' | 'ADAPTER_MISSING' | 'OPEN_FAILED';
+    readonly details?: Record<string, unknown>;
+    constructor(code: AppLaunchError['code'], message: string, details?: Record<string, unknown>);
+}
+type AppReturnPayload = {
+    provider?: AppProviderId;
+    action?: string;
+    url: string;
+    params: Record<string, string>;
+    raw?: unknown;
+};
+type AppLaunchCallbacks = {
+    /** 已成功尝试唤起（Web 端通过页面隐藏等方式推断） */
+    onOpened?: (result: AppLaunchResult) => void;
+    /** 使用了 fallback 链接 */
+    onFallback?: (result: AppLaunchResult) => void;
+    /** 无法唤起目标 App */
+    onUnavailable?: (result: AppLaunchResult) => void;
+    /** 第三方 App 通过 returnUrl / deep link 回传 */
+    onReturn?: (payload: AppReturnPayload) => void;
+    /** 任意错误 */
+    onError?: (error: AppLaunchError) => void;
+};
+type AppLaunchOptions = {
+    /** 第三方统计用的来源应用名，如 profile-v1 */
+    sourceApplication?: string;
+    /** 自定义 fallback，覆盖 provider 默认值 */
+    fallbackUrl?: string;
+    /** 回跳地址（如 myapp://launch/callback），供宿主监听 */
+    returnUrl?: string;
+    /** Web 端等待 App 唤起的超时（毫秒） */
+    timeoutMs?: number;
+};
+type AppLaunchRequest = {
+    provider: AppProviderId;
+    action: string;
+    params?: Record<string, unknown>;
+    options?: AppLaunchOptions;
+    callbacks?: AppLaunchCallbacks;
+    /** 单次调用可覆盖全局 adapter */
+    adapter?: AppLaunchAdapter;
+};
+type LaunchExecutionOptions = {
+    timeoutMs: number;
+    callbacks?: AppLaunchCallbacks;
+    provider: AppProviderId;
+    action: string;
+};
+/** 平台适配器：负责实际 openURL 与结果推断 */
+type AppLaunchAdapter = {
+    platform: AppLaunchPlatform;
+    launch(urls: AppLaunchUrls, options: LaunchExecutionOptions): Promise<AppLaunchResult>;
+    canOpen?(url: string): Promise<boolean>;
+};
+type AppLauncherConfig = {
+    sourceApplication: string;
+    adapter?: AppLaunchAdapter;
+    defaultOptions?: AppLaunchOptions;
+    defaultCallbacks?: AppLaunchCallbacks;
+};
+type AppLaunchProviderContext = {
+    sourceApplication: string;
+    options: AppLaunchOptions;
+};
+/** 各子功能（高德/微信/QQ 等）的统一契约 */
+type AppLaunchProvider = {
+    id: AppProviderId;
+    actions: readonly string[];
+    buildUrls(action: string, params: Record<string, unknown>, context: AppLaunchProviderContext): AppLaunchUrls;
+    validateParams?(action: string, params: Record<string, unknown>): void;
+};
+
+/** RN Linking 最小能力面，避免硬依赖 react-native */
+type RnLinkingLike = {
+    canOpenURL(url: string): Promise<boolean>;
+    openURL(url: string): Promise<void>;
+    addEventListener?: (type: 'url', handler: (event: {
+        url: string;
+    }) => void) => void;
+    removeEventListener?: (type: 'url', handler: (event: {
+        url: string;
+    }) => void) => void;
+    getInitialURL?: () => Promise<string | null>;
+};
+declare function createRnAppLaunchAdapter(linking: RnLinkingLike): AppLaunchAdapter;
+/**
+ * 在已安装 react-native 的宿主中快捷创建 adapter。
+ * 若未安装 react-native 将抛出明确错误。
+ */
+declare function createRnAppLaunchAdapterFromReactNative(): AppLaunchAdapter;
+
+declare function configureAppLauncher(patch: Partial<AppLauncherConfig>): AppLauncherConfig;
+declare function getAppLauncherConfig(): AppLauncherConfig;
+declare function resetAppLauncherConfig(): void;
+
+/**
+ * 统一唤起入口：按 provider + action 构建 scheme，经平台 adapter 拉起第三方 App。
+ */
+declare function launchApp(request: AppLaunchRequest): Promise<AppLaunchResult>;
+
+declare function parseReturnUrl(url: string): AppReturnPayload;
+type ReturnListener = (payload: AppReturnPayload) => void;
+/** 宿主 App 在收到 deep link 回跳时调用，分发给 onReturn 订阅者 */
+declare function notifyAppReturn(payload: AppReturnPayload): void;
+declare function subscribeAppReturn(listener: ReturnListener): () => void;
+declare function matchesReturnUrl(incomingUrl: string, expectedReturnUrl?: string): boolean;
+
+declare function registerAppProvider(provider: AppLaunchProvider): void;
+declare function getAppProvider(id: AppProviderId): AppLaunchProvider | undefined;
+declare function listAppProviders(): AppProviderId[];
+
+/** 地图导航提供方（关键词导航场景） */
+type MapNavigationProviderId = 'amap' | 'baidu' | 'google';
+type MapNavigationOption = {
+    id: MapNavigationProviderId;
+    label: string;
+    description?: string;
+};
+declare const MAP_NAVIGATION_OPTIONS: readonly MapNavigationOption[];
+type MapNavigationOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+};
+declare function launchMapNavigation(provider: MapNavigationProviderId, destination: string, options?: MapNavigationOptions): Promise<AppLaunchResult>;
+/** 同步唤起，结果通过 callbacks 回传 */
+declare function openMapNavigation(provider: MapNavigationProviderId, destination: string, options?: MapNavigationOptions): void;
+
+type AmapNavigationOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+};
+/** 高德关键词导航（日历等场景：仅地点文本） */
+declare function launchAmapNavigation(destination: string, options?: AmapNavigationOptions): Promise<AppLaunchResult>;
+/** 兼容同步调用：不阻塞 UI，结果通过 callbacks 回传 */
+declare function openAmapNavigation(destination: string, options?: AmapNavigationOptions): void;
+
+type WechatShareOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+    title: string;
+    description?: string;
+    url: string;
+    thumbUrl?: string;
+};
+declare function launchWechatShare(options: WechatShareOptions): Promise<AppLaunchResult>;
+type QqShareOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+    title: string;
+    summary?: string;
+    url: string;
+    imageUrl?: string;
+};
+declare function launchQqShare(options: QqShareOptions): Promise<AppLaunchResult>;
+declare function launchGenericUrl(url: string, options?: AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+    fallback?: string;
+}): Promise<AppLaunchResult>;
+
+export { type AppReturnPayload as A, type AppLaunchPlatform as B, type AppLaunchRequest as C, type AppLaunchStatus as D, type AppLaunchUrls as E, type AppLauncherConfig as F, type AppProviderId as G, AppLaunchError as H, type AmapNavigationOptions as I, type MapNavigationOption as J, type MapNavigationOptions as K, type LaunchExecutionOptions as L, MAP_NAVIGATION_OPTIONS as M, type QqShareOptions as Q, type RnLinkingLike as R, type WechatShareOptions as W, createRnAppLaunchAdapter as a, createRnAppLaunchAdapterFromReactNative as b, configureAppLauncher as c, launchAmapNavigation as d, launchGenericUrl as e, launchQqShare as f, getAppLauncherConfig as g, launchWechatShare as h, launchMapNavigation as i, type AppLaunchCallbacks as j, type AppLaunchOptions as k, launchApp as l, matchesReturnUrl as m, notifyAppReturn as n, openMapNavigation as o, parseReturnUrl as p, type AppLaunchResult as q, registerAppProvider as r, subscribeAppReturn as s, type MapNavigationProviderId as t, type AppLaunchAdapter as u, type AppLaunchProvider as v, resetAppLauncherConfig as w, getAppProvider as x, listAppProviders as y, openAmapNavigation as z };

package/dist/index-BHgDdlJW.d.ts

@@ -0,0 +1,177 @@
+/** 支持的第三方 App 提供方 */
+type AppProviderId = 'amap' | 'baidu' | 'google' | 'wechat' | 'qq' | 'generic';
+/** 运行平台 */
+type AppLaunchPlatform = 'web' | 'rn';
+/** 唤起结果状态 */
+type AppLaunchStatus = 'opened' | 'fallback' | 'unavailable' | 'cancelled' | 'timeout';
+type AppLaunchUrls = {
+    /** 优先尝试的 scheme / URI */
+    primary: string;
+    /** 无法唤起 App 时的降级链接（通常为 https://uri.* 网页版） */
+    fallback?: string;
+};
+type AppLaunchResult = {
+    provider: AppProviderId;
+    action: string;
+    status: AppLaunchStatus;
+    url: string;
+    platform: AppLaunchPlatform;
+    data?: Record<string, unknown>;
+};
+declare class AppLaunchError extends Error {
+    readonly code: 'UNKNOWN_PROVIDER' | 'UNKNOWN_ACTION' | 'INVALID_PARAMS' | 'ADAPTER_MISSING' | 'OPEN_FAILED';
+    readonly details?: Record<string, unknown>;
+    constructor(code: AppLaunchError['code'], message: string, details?: Record<string, unknown>);
+}
+type AppReturnPayload = {
+    provider?: AppProviderId;
+    action?: string;
+    url: string;
+    params: Record<string, string>;
+    raw?: unknown;
+};
+type AppLaunchCallbacks = {
+    /** 已成功尝试唤起（Web 端通过页面隐藏等方式推断） */
+    onOpened?: (result: AppLaunchResult) => void;
+    /** 使用了 fallback 链接 */
+    onFallback?: (result: AppLaunchResult) => void;
+    /** 无法唤起目标 App */
+    onUnavailable?: (result: AppLaunchResult) => void;
+    /** 第三方 App 通过 returnUrl / deep link 回传 */
+    onReturn?: (payload: AppReturnPayload) => void;
+    /** 任意错误 */
+    onError?: (error: AppLaunchError) => void;
+};
+type AppLaunchOptions = {
+    /** 第三方统计用的来源应用名，如 profile-v1 */
+    sourceApplication?: string;
+    /** 自定义 fallback，覆盖 provider 默认值 */
+    fallbackUrl?: string;
+    /** 回跳地址（如 myapp://launch/callback），供宿主监听 */
+    returnUrl?: string;
+    /** Web 端等待 App 唤起的超时（毫秒） */
+    timeoutMs?: number;
+};
+type AppLaunchRequest = {
+    provider: AppProviderId;
+    action: string;
+    params?: Record<string, unknown>;
+    options?: AppLaunchOptions;
+    callbacks?: AppLaunchCallbacks;
+    /** 单次调用可覆盖全局 adapter */
+    adapter?: AppLaunchAdapter;
+};
+type LaunchExecutionOptions = {
+    timeoutMs: number;
+    callbacks?: AppLaunchCallbacks;
+    provider: AppProviderId;
+    action: string;
+};
+/** 平台适配器：负责实际 openURL 与结果推断 */
+type AppLaunchAdapter = {
+    platform: AppLaunchPlatform;
+    launch(urls: AppLaunchUrls, options: LaunchExecutionOptions): Promise<AppLaunchResult>;
+    canOpen?(url: string): Promise<boolean>;
+};
+type AppLauncherConfig = {
+    sourceApplication: string;
+    adapter?: AppLaunchAdapter;
+    defaultOptions?: AppLaunchOptions;
+    defaultCallbacks?: AppLaunchCallbacks;
+};
+type AppLaunchProviderContext = {
+    sourceApplication: string;
+    options: AppLaunchOptions;
+};
+/** 各子功能（高德/微信/QQ 等）的统一契约 */
+type AppLaunchProvider = {
+    id: AppProviderId;
+    actions: readonly string[];
+    buildUrls(action: string, params: Record<string, unknown>, context: AppLaunchProviderContext): AppLaunchUrls;
+    validateParams?(action: string, params: Record<string, unknown>): void;
+};
+
+/** RN Linking 最小能力面，避免硬依赖 react-native */
+type RnLinkingLike = {
+    canOpenURL(url: string): Promise<boolean>;
+    openURL(url: string): Promise<void>;
+    addEventListener?: (type: 'url', handler: (event: {
+        url: string;
+    }) => void) => void;
+    removeEventListener?: (type: 'url', handler: (event: {
+        url: string;
+    }) => void) => void;
+    getInitialURL?: () => Promise<string | null>;
+};
+declare function createRnAppLaunchAdapter(linking: RnLinkingLike): AppLaunchAdapter;
+/**
+ * 在已安装 react-native 的宿主中快捷创建 adapter。
+ * 若未安装 react-native 将抛出明确错误。
+ */
+declare function createRnAppLaunchAdapterFromReactNative(): AppLaunchAdapter;
+
+declare function configureAppLauncher(patch: Partial<AppLauncherConfig>): AppLauncherConfig;
+declare function getAppLauncherConfig(): AppLauncherConfig;
+declare function resetAppLauncherConfig(): void;
+
+/**
+ * 统一唤起入口：按 provider + action 构建 scheme，经平台 adapter 拉起第三方 App。
+ */
+declare function launchApp(request: AppLaunchRequest): Promise<AppLaunchResult>;
+
+declare function parseReturnUrl(url: string): AppReturnPayload;
+type ReturnListener = (payload: AppReturnPayload) => void;
+/** 宿主 App 在收到 deep link 回跳时调用，分发给 onReturn 订阅者 */
+declare function notifyAppReturn(payload: AppReturnPayload): void;
+declare function subscribeAppReturn(listener: ReturnListener): () => void;
+declare function matchesReturnUrl(incomingUrl: string, expectedReturnUrl?: string): boolean;
+
+declare function registerAppProvider(provider: AppLaunchProvider): void;
+declare function getAppProvider(id: AppProviderId): AppLaunchProvider | undefined;
+declare function listAppProviders(): AppProviderId[];
+
+/** 地图导航提供方（关键词导航场景） */
+type MapNavigationProviderId = 'amap' | 'baidu' | 'google';
+type MapNavigationOption = {
+    id: MapNavigationProviderId;
+    label: string;
+    description?: string;
+};
+declare const MAP_NAVIGATION_OPTIONS: readonly MapNavigationOption[];
+type MapNavigationOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+};
+declare function launchMapNavigation(provider: MapNavigationProviderId, destination: string, options?: MapNavigationOptions): Promise<AppLaunchResult>;
+/** 同步唤起，结果通过 callbacks 回传 */
+declare function openMapNavigation(provider: MapNavigationProviderId, destination: string, options?: MapNavigationOptions): void;
+
+type AmapNavigationOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+};
+/** 高德关键词导航（日历等场景：仅地点文本） */
+declare function launchAmapNavigation(destination: string, options?: AmapNavigationOptions): Promise<AppLaunchResult>;
+/** 兼容同步调用：不阻塞 UI，结果通过 callbacks 回传 */
+declare function openAmapNavigation(destination: string, options?: AmapNavigationOptions): void;
+
+type WechatShareOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+    title: string;
+    description?: string;
+    url: string;
+    thumbUrl?: string;
+};
+declare function launchWechatShare(options: WechatShareOptions): Promise<AppLaunchResult>;
+type QqShareOptions = AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+    title: string;
+    summary?: string;
+    url: string;
+    imageUrl?: string;
+};
+declare function launchQqShare(options: QqShareOptions): Promise<AppLaunchResult>;
+declare function launchGenericUrl(url: string, options?: AppLaunchOptions & {
+    callbacks?: AppLaunchCallbacks;
+    fallback?: string;
+}): Promise<AppLaunchResult>;
+
+export { type AppReturnPayload as A, type AppLaunchPlatform as B, type AppLaunchRequest as C, type AppLaunchStatus as D, type AppLaunchUrls as E, type AppLauncherConfig as F, type AppProviderId as G, AppLaunchError as H, type AmapNavigationOptions as I, type MapNavigationOption as J, type MapNavigationOptions as K, type LaunchExecutionOptions as L, MAP_NAVIGATION_OPTIONS as M, type QqShareOptions as Q, type RnLinkingLike as R, type WechatShareOptions as W, createRnAppLaunchAdapter as a, createRnAppLaunchAdapterFromReactNative as b, configureAppLauncher as c, launchAmapNavigation as d, launchGenericUrl as e, launchQqShare as f, getAppLauncherConfig as g, launchWechatShare as h, launchMapNavigation as i, type AppLaunchCallbacks as j, type AppLaunchOptions as k, launchApp as l, matchesReturnUrl as m, notifyAppReturn as n, openMapNavigation as o, parseReturnUrl as p, type AppLaunchResult as q, registerAppProvider as r, subscribeAppReturn as s, type MapNavigationProviderId as t, type AppLaunchAdapter as u, type AppLaunchProvider as v, resetAppLauncherConfig as w, getAppProvider as x, listAppProviders as y, openAmapNavigation as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sa2kit",
-  "version": "3.8.0",
+  "version": "3.9.1",
   "description": "SA2Kit 2.0 — common API 稳定；business 实验田模块逐步迁出 profile-v1",
   "keywords": [
     "react",
@@ -309,6 +309,16 @@
       "import": "./dist/common/api/index.mjs",
       "require": "./dist/common/api/index.js"
     },
+    "./common/appLauncher": {
+      "types": "./dist/common/appLauncher/index.d.ts",
+      "import": "./dist/common/appLauncher/index.mjs",
+      "require": "./dist/common/appLauncher/index.js"
+    },
+    "./common/appLauncher/rn": {
+      "types": "./dist/common/appLauncher/rn/index.d.ts",
+      "import": "./dist/common/appLauncher/rn/index.mjs",
+      "require": "./dist/common/appLauncher/rn/index.js"
+    },
     "./common/auth/client": {
       "types": "./dist/common/auth/client/index.d.ts",
       "import": "./dist/common/auth/client/index.mjs",