@spopc/wechat-miniprogram 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @spopc/wechat-miniprogram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+H5 调用微信小程序原生能力的 TypeScript SDK。使用 URL 协议和一个自动执行的原生页面，零 Taro / React / Vue 运行时依赖。
+
+## 安装
+
+```sh
+npm install @spopc/wechat-miniprogram
+```
+
+包提供 ESM 和 TypeScript 类型声明，供浏览器 H5 项目使用；在客户端创建实例，SSR 项目需放在挂载后的客户端代码中。普通浏览器可直接使用 mock，真实微信能力还需要小程序宿主实现本文的 URL 协议。仅安装 H5 SDK 不会自动添加原生小程序页面。
+
+源码仓库内使用 npm workspace 开发，无需先发布到 npm。
+
+## 快速接入
+
+默认自动识别环境：小程序 WebView 使用原生桥接，普通浏览器使用 mock。真实小程序调用需要网页加载微信 JSSDK：`https://res.wx.qq.com/open/js/jweixin-1.6.0.js`；浏览器 mock 无需加载它。每个页面创建一个 SDK 实例。
+
+```ts
+import { createWechatBridge } from '@spopc/wechat-miniprogram'
+
+const bridge = createWechatBridge({
+  mode: 'auto', // 默认值；也可强制 'native' 或 'mock'
+  onResult({ result, delivery, source }) {
+    // 唯一业务结果入口：live 与文档重建后的 recovered 都经过这里。
+    // 若同时消费 Promise，请避免对同一调用重复执行业务副作用。
+    console.log(result.method, result.status, delivery, source)
+  }
+})
+
+// 由 H5 上的用户操作触发；原生页自动执行，无需再点“执行”和“返回”。
+const scan = await bridge.scanCode({ scanType: ['qrCode', 'barCode'] })
+const position = await bridge.getLocation({ type: 'gcj02' })
+const { code } = await bridge.login()
+// 将 code 提交给自己的业务后端，换取业务登录态；不要把 AppSecret 放在 H5。
+```
+
+上述调用是顺序示例；根据实际按钮分别触发。页面卸载 / 组件卸载时调用 `bridge.dispose()`。它移除监听并拒绝当前 Promise，原生模式保留请求记录以支持文档重建。
+
+## 自动识别与 Mock
+
+```ts
+const bridge = createWechatBridge() // 等同于 { mode: 'auto' }
+const environment = await bridge.ready() // 'native' | 'mock'
+console.log(bridge.environment, bridge.isMock)
+const location = await bridge.getLocation() // 调用本身也会等待识别，无需手动 ready
+```
+
+`auto` 结合小程序标记、User-Agent、`wx.miniProgram.getEnv` 和 `WeixinJSBridgeReady` 识别。普通浏览器直接使用 mock，即使网页加载了微信 JSSDK 也不会被误判为小程序。微信容器仍在初始化时，默认最多等待 2000 ms；可用 `environmentTimeoutMs` 调整为 100–30000 ms。无法确认时抛出 `ENVIRONMENT_TIMEOUT`，加载完成后可重试 `ready()` / 调用，不把未知环境当成模拟成功。
+
+自动识别完成后，本实例固定使用选定模式。真实调用的权限拒绝、导航失败、超时等不会退回 mock。已识别为小程序但缺少 JSSDK 时抛出 `JSSDK_NOT_READY`。`mode: 'native'` 可以强制真实调用，浏览器中会报 `NOT_IN_MINIPROGRAM`；`mode: 'mock'` 可以在任何环境强制模拟。`isInMiniProgram()` 检测实际环境，不会因强制 mock 返回假值。检测未完成时 `environment` 为 undefined，应等待 `ready()` 再读取 `isMock`。
+
+8 项能力均内置成功数据：固定模拟坐标、门店码、无效的 MOCK 登录 code、虚构地址及成功标记。可覆盖任意方法，其余保持默认：
+
+```ts
+import { createWechatBridge, BridgeError } from '@spopc/wechat-miniprogram'
+
+const bridge = createWechatBridge({
+  mode: 'auto',
+  mock: {
+    delayMs: 500, // 默认 300；0–600000 ms，计入调用超时
+    handlers: {
+      getLocation: params => ({
+        latitude: 22.5431, longitude: 114.0579,
+        accuracy: 10, type: params.type ?? 'gcj02'
+      }),
+      scanCode: async (_params, { signal, requestId }) => {
+        // 可按业务场景返回自定义扫码数据；signal 在超时/销毁/完成时终止。
+        return { result: 'tea-store://demo?table=08', scanType: 'QR_CODE' }
+      },
+      chooseAddress: () => { throw new BridgeError('CANCELLED', '模拟用户取消') },
+      checkSession: () => { throw new BridgeError('SESSION_EXPIRED', '模拟登录过期') }
+    }
+  }
+})
+```
+
+mock 与真实调用共用参数/结果校验、Promise 类型、单次并发限制和调用超时。`CANCELLED` 产生 cancel 事件；其他 `BridgeError` 保留错误码；普通异常变成 `MOCK_FAILED`，不合法/超大的返回值变成 `INVALID_MOCK_RESULT`。超时或 dispose 后的迟到结果被丢弃，自定义异步工作可响应 `signal` 提前结束。
+
+mock 的 `onResult.source`、`trigger` 均为 `mock`，`delivery` 固定为 `live`；只在当前内存中返回数据，不跳页面、不读写原生 pending 记录、不消费或修改 URL。即使传入调用参数 `mode: 'query'`，也不模拟重载，因此不能用来验证 WebView 的 Hash / Query 传输和文档重建。模拟登录 code 不能交给微信换登录态，模拟支付不会产生订单或真实支付；业务后端联调需配套测试数据。
+
+测试页直接打开 `http://127.0.0.1:13334/` 即自动进入 mock，可选成功/取消/失败。`?mode=native`、`?mode=mock` 强制模式，旧 `?mock=1` 也可用。这些 URL 开关只属于测试页面，SDK 本身不读取它们。
+
+## 方法与参数
+
+所有快捷方法接受 `mode?: 'hash' | 'query'`、`timeoutMs?: number`。这里的 mode 指返回 URL 格式，与创建 SDK 时的运行模式不同。默认 Hash、120000 毫秒；超时可设 1000–600000 毫秒。`login`、`chooseAddress`、`requestPayment` 只允许 Hash。
+
+| 方法 | 原生参数 | 成功结果 |
+| --- | --- | --- |
+| `getLocation(options?)` | type: gcj02（默认）或 wgs84 | latitude、longitude、accuracy、type |
+| `scanCode(options?)` | onlyFromCamera?: boolean；scanType?: qrCode / barCode / datamatrix / pdf417 数组 | result、scanType；可选 charSet、path、rawData |
+| `login(options?)` | timeout?: 1000–60000，微信接口自身超时 | code |
+| `checkSession(options?)` | 无 | valid: true |
+| `openLocation(options)` | GCJ-02 latitude、longitude；可选 name、address、scale（5–18） | ok: true |
+| `chooseAddress(options?)` | 无 | userName、telNumber、provinceName、cityName、countyName、detailInfo，以及平台返回的可选地址字段 |
+| `makePhoneCall(options)` | phoneNumber | ok: true |
+| `requestPayment(options)` | timeStamp、nonceStr、package、signType、paySign | ok: true |
+
+底层通用入口也有方法与参数、结果的类型关联：
+
+```ts
+const result = await bridge.invoke('scanCode', { onlyFromCamera: true }, { mode: 'hash' })
+await bridge.openLocation({ latitude: 31.2, longitude: 121.4, name: '门店', scale: 16 })
+// 实际支付参数必须由业务后端签发：
+// await bridge.requestPayment(paymentParamsFromYourServer)
+```
+
+`requestPayment.package` 使用 `prepay_id=...` 格式，`signType` 明确传 RSA / MD5 / HMAC-SHA256。支付没有自动重试；最终订单状态以业务后端的支付通知或查单结果为准。`makePhoneCall` 成功只表示原生接口调用成功，不表示电话已接通。
+
+## 返回与错误
+
+同一网页上下文存活时，成功 resolve 对应能力的数据，失败或取消 reject `BridgeError`。`onResult` 同时收到结构化事件：
+
+```ts
+{
+  result: {
+    v: 1, id, method, mode, completedAt,
+    status: 'success', data // 或 status: 'cancel' | 'error', error: { code, message }
+  },
+  delivery: 'live', // 或 'recovered'
+  source: 'native', // 或 'mock'
+  trigger: 'hashchange' // 或 startup / pageshow / visible / mock
+}
+```
+
+网页重建时旧 Promise 无法继续，必须在新页面重新创建 SDK 并使用 `onResult` 恢复。回传按 id、method、mode 同时关联，消费后清理 URL 和 sessionStorage，一次调用最多交付一次。
+
+常见错误：`CANCELLED`、`PERMISSION_DENIED`、`NATIVE_FAILED`、`SESSION_EXPIRED`、`UNSUPPORTED`、`TIMEOUT`、`RESULT_TOO_LARGE`、`INVALID_NATIVE_RESULT`。H5 侧还会产生 `BUSY`、`NOT_IN_MINIPROGRAM`、`ENVIRONMENT_TIMEOUT`、`JSSDK_NOT_READY`、`INVALID_PARAMS`、`STORAGE_UNAVAILABLE`、`NAVIGATE_FAILED`、`DISPOSED`、`MOCK_FAILED`、`INVALID_MOCK_RESULT`。微信错误原文保留在 message，不依赖它处理分支。H5 本地校验、环境识别、导航失败和本地等待超时通过 Promise 拒绝；它们没有原生回传，因此不产生 `onResult`。
+
+`checkSession` 仅检查微信 session_key，不验证业务服务自己的 token。`login` 不获取手机号、头像或昵称；手机号授权需要原生按钮交互，不属于本版静默桥接范围。
+
+## 宿主契约与扩展
+
+默认原生路由 `/native/invoke`，通过 `request` URL 参数携带 JSON：v、id、method、params、mode、returnUrl、createdAt、expiresAt。可用 `nativePath` 更改路由，原生宿主须实现相同协议。旧的 `/native/location` 在示例宿主保留兼容。
+
+原生页解析请求后，在页面 ready 时调用注册的 handler；成功、取消、失败或超时后自动 navigateBack。宿主把结果添加到 WebView src 的 `__mp_bridge` 字段。JS 协议模块同时导出于 `@spopc/wechat-miniprogram/protocol`，可供小程序端使用，不依赖 DOM、URL、Node API。
+
+当前支持的方法采用明确注册表，拒绝未知方法和额外参数，不开放任意 wx 方法执行。扩展能力时同步修改协议类型与校验、宿主 handler、SDK 快捷方法和测试。
+
+默认只适配示例中允许的业务域名。请求与结果 JSON 的应用上限为 16,384 字符，宿主/微信版本可能有更低 URL 限制；大内容应走业务后端引用。Hash 路由需兼容临时的 `__mp_bridge` 字段。超时后原生操作本身不一定可撤销，尤其支付不得仅因超时直接重试。
+
+中间页无需用户操作，但扫码、地图、收货地址、拨号、支付和权限提示由微信展示，不能承诺无感或没有路由动画。扫码 UI 及支付参数约定见 [Taro 扫码文档](https://docs.taro.zone/docs/apis/device/scan/scanCode)、[Taro 支付文档](https://docs.taro.zone/docs/apis/payment/requestPayment)。
+
+## 已验证范围
+
+2026-10-13，Windows 微信开发者工具 Stable 2.02.2608070 / 基础库 3.17.4：自动 login、getLocation、checkSession、scanCode 成功及扫码取消均完成往返，通过 Hash 在同一页面收到 live 结果。扫码使用开发者工具选择测试二维码图片，不代表真机相机扫描已测试。初版定位页另验证过 Query 重载与 recovered 恢复。iOS / Android 真机、真实支付、拨号、地图、个人地址尚未实测。
+
+构建：`npm run build`。打包检查：`npm pack --dry-run`。包只包含 dist、README 和 package.json。

package/dist/environment.d.ts

@@ -0,0 +1,19 @@
+export interface WechatWindow extends Window {
+    __wxjs_environment?: string;
+    WeixinJSBridge?: unknown;
+    wx?: {
+        miniProgram?: {
+            getEnv(callback: (env: {
+                miniprogram: boolean;
+            }) => void): void;
+            navigateTo(options: {
+                url: string;
+                fail?: (error: {
+                    errMsg?: string;
+                }) => void;
+            }): void;
+        };
+    };
+}
+/** A negative result must identify a browser, not an unfinished WeChat initialization. */
+export declare function detectMiniProgram(browser: WechatWindow, signal: AbortSignal, timeoutMs: number): Promise<boolean>;

package/dist/environment.js

@@ -0,0 +1,59 @@
+import { BridgeError } from './errors.js';
+/** A negative result must identify a browser, not an unfinished WeChat initialization. */
+export function detectMiniProgram(browser, signal, timeoutMs) {
+    if (signal.aborted)
+        return Promise.reject(new BridgeError('DISPOSED', 'SDK 已销毁'));
+    const userAgent = browser.navigator?.userAgent ?? '';
+    const marked = () => browser.__wxjs_environment === 'miniprogram' || /\bminiProgram\b/i.test(userAgent);
+    if (marked())
+        return Promise.resolve(true);
+    // Loading jweixin.js in Chrome also creates wx.miniProgram, but getEnv may never
+    // call back there. Its presence alone is not evidence of a WeChat container.
+    if (!/MicroMessenger|wechatdevtools/i.test(userAgent) && !browser.WeixinJSBridge)
+        return Promise.resolve(false);
+    return new Promise((resolve, reject) => {
+        let done = false;
+        let queried;
+        let poll;
+        const finish = (inside, error) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(deadline);
+            clearTimeout(poll);
+            browser.document.removeEventListener('WeixinJSBridgeReady', check);
+            signal.removeEventListener('abort', aborted);
+            if (error)
+                reject(error);
+            else
+                resolve(!!inside);
+        };
+        const aborted = () => finish(undefined, new BridgeError('DISPOSED', 'SDK 已销毁'));
+        const deadline = setTimeout(() => finish(undefined, new BridgeError('ENVIRONMENT_TIMEOUT', '微信环境尚未就绪，请在 JSSDK 加载完成后重试')), timeoutMs);
+        function check() {
+            if (done)
+                return;
+            clearTimeout(poll);
+            if (marked()) {
+                finish(true);
+                return;
+            }
+            const api = browser.wx?.miniProgram;
+            if (api && api !== queried && typeof api.getEnv === 'function') {
+                queried = api;
+                try {
+                    api.getEnv(env => { if (typeof env?.miniprogram === 'boolean')
+                        finish(marked() || env.miniprogram); });
+                }
+                catch {
+                    queried = undefined; /* Retry after bridge readiness. */
+                }
+            }
+            if (!done)
+                poll = setTimeout(check, 50);
+        }
+        browser.document.addEventListener('WeixinJSBridgeReady', check);
+        signal.addEventListener('abort', aborted, { once: true });
+        check();
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class BridgeError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,7 @@
+export class BridgeError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BridgeError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { type BridgeResult, type BridgeMethod, type ParamsOf, type DataOf, type ReturnMode } from './protocol.js';
+import { type MockOptions } from './mock.js';
+export * from './protocol.js';
+export { BridgeError } from './errors.js';
+export { defaultMockHandlers, type MockOptions, type MockHandlers, type MockHandler, type MockContext } from './mock.js';
+export type BridgeMode = 'auto' | 'native' | 'mock';
+export type BridgeEnvironment = 'native' | 'mock';
+export interface ResultEvent {
+    result: BridgeResult;
+    source: 'native' | 'mock';
+    delivery: 'live' | 'recovered';
+    trigger: string;
+}
+export interface BridgeOptions {
+    /** Default: auto. WeChat mini-programs use native APIs; other browsers use mock. */
+    mode?: BridgeMode;
+    mock?: MockOptions;
+    /** Maximum wait for an unfinished WeChat environment. Default: 2000 ms. */
+    environmentTimeoutMs?: number;
+    timeoutMs?: number;
+    nativePath?: string;
+    onResult?: (event: ResultEvent) => void;
+    onDiagnostic?: (message: string) => void;
+}
+export interface CallOptions {
+    mode?: ReturnMode;
+    timeoutMs?: number;
+}
+export declare function createWechatBridge(options?: BridgeOptions): {
+    invoke: <M extends BridgeMethod>(method: M, params: ParamsOf<M>, callOptions?: CallOptions) => Promise<DataOf<M>>;
+    isInMiniProgram: () => Promise<boolean>;
+    ready: () => Promise<BridgeEnvironment>;
+    readonly environment: BridgeEnvironment | undefined;
+    readonly isMock: boolean;
+    getLocation: (input?: ParamsOf<"getLocation"> & CallOptions) => Promise<import("./protocol.js").LocationData>;
+    scanCode: (input?: ParamsOf<"scanCode"> & CallOptions) => Promise<import("./protocol.js").ScanCodeData>;
+    login: (input?: ParamsOf<"login"> & CallOptions) => Promise<{
+        code: string;
+    }>;
+    checkSession: (input?: CallOptions) => Promise<{
+        valid: true;
+    }>;
+    chooseAddress: (input?: CallOptions) => Promise<import("./protocol.js").AddressData>;
+    openLocation: (input: ParamsOf<"openLocation"> & CallOptions) => Promise<{
+        ok: true;
+    }>;
+    makePhoneCall: (input: ParamsOf<"makePhoneCall"> & CallOptions) => Promise<{
+        ok: true;
+    }>;
+    requestPayment: (input: ParamsOf<"requestPayment"> & CallOptions) => Promise<{
+        ok: true;
+    }>;
+    dispose(): void;
+};

package/dist/index.js

@@ -0,0 +1,272 @@
+import { buildNativeUrl, readReturnUrl, normalizeParams, parseRequest, DEFAULT_TIMEOUT_MS } from './protocol.js';
+import { BridgeError } from './errors.js';
+import { createMockTransport } from './mock.js';
+import { detectMiniProgram } from './environment.js';
+export * from './protocol.js';
+export { BridgeError } from './errors.js';
+export { defaultMockHandlers } from './mock.js';
+// Keep the existing key so a package rename cannot orphan an in-flight native request.
+const STORAGE_KEY = 'brazosd.bridge.pending.v1';
+export function createWechatBridge(options = {}) {
+    const browser = window;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const mode = options.mode ?? 'auto';
+    if (!['auto', 'native', 'mock'].includes(mode))
+        throw new BridgeError('INVALID_PARAMS', 'Invalid SDK mode');
+    const environmentTimeoutMs = options.environmentTimeoutMs ?? 2000;
+    if (!Number.isFinite(environmentTimeoutMs) || environmentTimeoutMs < 100 || environmentTimeoutMs > 30000)
+        throw new BridgeError('INVALID_PARAMS', 'environmentTimeoutMs must be between 100 and 30000');
+    const simulate = createMockTransport(options.mock ?? {});
+    let mockTransport = mode === 'mock' ? simulate : undefined;
+    let environment = mode === 'auto' ? undefined : mode;
+    let readiness;
+    let listening = false;
+    const environmentController = new AbortController();
+    let disposed = false;
+    let launching = false;
+    let active;
+    const diagnostic = (message) => { try {
+        options.onDiagnostic?.(message);
+    }
+    catch { /* Consumer logging cannot break transport. */ } };
+    function loadPending() {
+        if (mockTransport)
+            return;
+        try {
+            const value = JSON.parse(browser.sessionStorage.getItem(STORAGE_KEY) || 'null');
+            if (!value || !Number.isFinite(value.deadline))
+                return;
+            return { request: parseRequest(JSON.stringify(value.request)), deadline: value.deadline };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function removePending() { if (!mockTransport) {
+        try {
+            browser.sessionStorage.removeItem(STORAGE_KEY);
+        }
+        catch { /* Memory delivery still works. */ }
+    } }
+    function fail(code, message) {
+        const waiting = active;
+        active = undefined;
+        if (waiting) {
+            clearTimeout(waiting.timer);
+            waiting.reject(new BridgeError(code, message));
+            waiting.cleanup?.();
+        }
+        removePending();
+    }
+    function publish(result, delivery, trigger) {
+        try {
+            options.onResult?.({ result, delivery, trigger, source: mockTransport ? 'mock' : 'native' });
+        }
+        catch {
+            diagnostic('onResult 回调抛出异常，SDK 已完成结果交付');
+        }
+    }
+    function consume(trigger) {
+        if (disposed || environment !== 'native')
+            return;
+        try {
+            const { result, cleanUrl } = readReturnUrl(browser.location.href);
+            if (!result)
+                return;
+            const saved = loadPending();
+            if ((!active || active.request.id !== result.id) && saved?.request.id !== result.id) {
+                diagnostic('忽略未关联或已消费的回传结果');
+                browser.history.replaceState(browser.history.state, '', cleanUrl);
+                return;
+            }
+            if (saved && saved.deadline < Date.now()) {
+                fail('TIMEOUT', '原生调用已超时');
+                browser.history.replaceState(browser.history.state, '', cleanUrl);
+                return;
+            }
+            const expected = active?.request.id === result.id ? active.request : saved?.request;
+            if (expected?.mode !== result.mode || expected.method !== result.method)
+                throw new Error('Return method/mode mismatch');
+            const waiting = active?.request.id === result.id ? active : undefined;
+            if (waiting)
+                clearTimeout(waiting.timer);
+            active = undefined;
+            removePending();
+            browser.history.replaceState(browser.history.state, '', cleanUrl);
+            if (waiting) {
+                if (result.status === 'success')
+                    waiting.resolve(result.data);
+                else
+                    waiting.reject(new BridgeError(result.error.code, result.error.message));
+            }
+            publish(result, waiting ? 'live' : 'recovered', trigger);
+        }
+        catch (error) {
+            diagnostic(`回传解析失败：${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const hashListener = () => consume('hashchange');
+    const showListener = () => consume('pageshow');
+    const visibleListener = () => { if (document.visibilityState === 'visible')
+        consume('visible'); };
+    function listen() {
+        if (listening || disposed || environment !== 'native')
+            return;
+        listening = true;
+        browser.addEventListener('hashchange', hashListener);
+        browser.addEventListener('pageshow', showListener);
+        document.addEventListener('visibilitychange', visibleListener);
+        Promise.resolve().then(() => consume('startup'));
+    }
+    function isInMiniProgram() {
+        return detectMiniProgram(browser, environmentController.signal, environmentTimeoutMs);
+    }
+    async function ready() {
+        if (disposed)
+            throw new BridgeError('DISPOSED', 'SDK 已销毁');
+        if (environment) {
+            listen();
+            return environment;
+        }
+        if (!readiness)
+            readiness = isInMiniProgram().then(inside => {
+                if (disposed)
+                    throw new BridgeError('DISPOSED', 'SDK 已销毁');
+                environment = inside ? 'native' : 'mock';
+                mockTransport = inside ? undefined : simulate;
+                listen();
+                diagnostic(`运行环境：${environment}（自动识别）`);
+                return environment;
+            }).catch(error => { readiness = undefined; throw error; });
+        return readiness;
+    }
+    // Start recovery without requiring a first API call, and consume initialization failures.
+    void ready().catch(error => diagnostic(error instanceof Error ? error.message : String(error)));
+    async function invoke(method, params, callOptions = {}) {
+        if (disposed)
+            throw new BridgeError('DISPOSED', 'SDK 已销毁');
+        if (active || launching)
+            throw new BridgeError('BUSY', '已有一次调用正在进行');
+        launching = true;
+        try {
+            await ready();
+        }
+        finally {
+            launching = false;
+        }
+        if (disposed)
+            throw new BridgeError('DISPOSED', 'SDK 已销毁');
+        const saved = loadPending();
+        if (saved && saved.deadline > Date.now())
+            throw new BridgeError('BUSY', '有尚未完成的调用，请等待结果或超时');
+        let nativeParams;
+        const duration = callOptions.timeoutMs ?? timeoutMs;
+        const mode = callOptions.mode ?? 'hash';
+        try {
+            nativeParams = normalizeParams(method, params);
+            if (!Number.isFinite(duration) || duration < 1000 || duration > 600000)
+                throw new Error('timeoutMs must be between 1000 and 600000');
+            if (mode !== 'hash' && mode !== 'query')
+                throw new Error('Invalid return mode');
+            // Credentials and address details must not enter HTTP query logs.
+            if (mode === 'query' && ['login', 'chooseAddress', 'requestPayment'].includes(method))
+                throw new Error(`${method} requires hash mode`);
+        }
+        catch (error) {
+            throw new BridgeError('INVALID_PARAMS', error instanceof Error ? error.message : String(error));
+        }
+        if (!mockTransport) {
+            launching = true;
+            let inside = false;
+            try {
+                inside = await isInMiniProgram();
+            }
+            finally {
+                launching = false;
+            }
+            if (disposed)
+                throw new BridgeError('DISPOSED', 'SDK 已销毁');
+            if (!inside)
+                throw new BridgeError('NOT_IN_MINIPROGRAM', '请在微信小程序 WebView 中运行');
+            if (typeof browser.wx?.miniProgram?.navigateTo !== 'function')
+                throw new BridgeError('JSSDK_NOT_READY', '请在微信 JSSDK 加载完成后重试');
+        }
+        const createdAt = Date.now();
+        const request = parseRequest(JSON.stringify({
+            v: 1, id: browser.crypto.randomUUID(), method, mode,
+            returnUrl: mockTransport ? browser.location.href : readReturnUrl(browser.location.href).cleanUrl, createdAt,
+            expiresAt: createdAt + duration, params: nativeParams
+        }));
+        // Validate the route before reserving storage, so invalid configuration cannot leave a BUSY slot.
+        const url = mockTransport ? undefined : buildNativeUrl(request, options.nativePath);
+        if (!mockTransport) {
+            try {
+                browser.sessionStorage.setItem(STORAGE_KEY, JSON.stringify({ request, deadline: request.expiresAt }));
+            }
+            catch {
+                throw new BridgeError('STORAGE_UNAVAILABLE', '无法保存调用信息，不能可靠恢复 URL 回传');
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => fail('TIMEOUT', mockTransport ? '等待模拟结果超时' : '等待原生页面回传超时'), duration);
+            active = { request, resolve, reject, timer };
+            if (mockTransport) {
+                active.cleanup = mockTransport(request, result => {
+                    const waiting = active;
+                    if (!waiting || waiting.request.id !== request.id || disposed)
+                        return;
+                    active = undefined;
+                    clearTimeout(waiting.timer);
+                    waiting.cleanup?.();
+                    if (result.status === 'success')
+                        waiting.resolve(result.data);
+                    else
+                        waiting.reject(new BridgeError(result.error.code, result.error.message));
+                    publish(result, 'live', 'mock');
+                });
+                diagnostic(`模拟 ${method} · ${request.id}`);
+                return;
+            }
+            diagnostic(`发起 ${method} · ${request.mode} · ${request.id}`);
+            try {
+                browser.wx.miniProgram.navigateTo({ url: url, fail: error => fail('NAVIGATE_FAILED', error.errMsg || '原生页面跳转失败') });
+            }
+            catch (error) {
+                fail('NAVIGATE_FAILED', String(error));
+            }
+        });
+    }
+    function call(method, input) {
+        const { mode, timeoutMs, ...params } = input;
+        return invoke(method, params, { mode, timeoutMs });
+    }
+    return {
+        invoke, isInMiniProgram, ready,
+        get environment() { return environment; },
+        get isMock() { return environment === 'mock'; },
+        getLocation: (input = {}) => call('getLocation', input),
+        scanCode: (input = {}) => call('scanCode', input),
+        login: (input = {}) => call('login', input),
+        checkSession: (input = {}) => invoke('checkSession', {}, input),
+        chooseAddress: (input = {}) => invoke('chooseAddress', {}, input),
+        openLocation: (input) => call('openLocation', input),
+        makePhoneCall: (input) => call('makePhoneCall', input),
+        requestPayment: (input) => call('requestPayment', input),
+        dispose() {
+            disposed = true;
+            environmentController.abort();
+            if (listening) {
+                browser.removeEventListener('hashchange', hashListener);
+                browser.removeEventListener('pageshow', showListener);
+                document.removeEventListener('visibilitychange', visibleListener);
+            }
+            const waiting = active;
+            active = undefined;
+            if (waiting) {
+                clearTimeout(waiting.timer);
+                waiting.reject(new BridgeError('DISPOSED', 'SDK 已销毁'));
+                waiting.cleanup?.();
+            }
+        }
+    };
+}

package/dist/mock.d.ts

@@ -0,0 +1,28 @@
+import { type BridgeMethod, type BridgeRequest, type BridgeResult, type ParamsOf, type DataOf } from './protocol.js';
+export interface MockContext {
+    requestId: string;
+    /** Aborted on timeout, disposal, or completion. Check this before any delayed work. */
+    signal: AbortSignal;
+}
+export type MockHandler<M extends BridgeMethod> = (params: ParamsOf<M>, context: MockContext) => DataOf<M> | Promise<DataOf<M>>;
+export type MockHandlers = {
+    [M in BridgeMethod]?: MockHandler<M>;
+};
+export interface MockOptions {
+    /** Delay before calling the handler, in milliseconds. Default: 300; range: 0–600000. */
+    delayMs?: number;
+    /** Override selected methods; the others use the built-in successful fixtures. */
+    handlers?: MockHandlers;
+}
+/** Fictional fixtures only. No WeChat APIs, backend requests, or real transactions. */
+export declare const defaultMockHandlers: Readonly<{
+    getLocation: MockHandler<"getLocation">;
+    scanCode: MockHandler<"scanCode">;
+    login: MockHandler<"login">;
+    checkSession: MockHandler<"checkSession">;
+    openLocation: MockHandler<"openLocation">;
+    chooseAddress: MockHandler<"chooseAddress">;
+    makePhoneCall: MockHandler<"makePhoneCall">;
+    requestPayment: MockHandler<"requestPayment">;
+}>;
+export declare function createMockTransport(options: MockOptions): (request: BridgeRequest, complete: (result: BridgeResult) => void) => (() => void);

package/dist/mock.js

@@ -0,0 +1,62 @@
+import { BridgeError } from './errors.js';
+import { BRIDGE_METHODS, parseResult } from './protocol.js';
+/** Fictional fixtures only. No WeChat APIs, backend requests, or real transactions. */
+export const defaultMockHandlers = Object.freeze({
+    getLocation: params => ({ latitude: 31.2304, longitude: 121.4737, accuracy: 10, type: params.type ?? 'gcj02' }),
+    scanCode: params => ({
+        result: 'tea-store://mock?store=demo&table=08',
+        scanType: { qrCode: 'QR_CODE', barCode: 'CODE_128', datamatrix: 'DATA_MATRIX', pdf417: 'PDF_417' }[params.scanType?.[0] ?? 'qrCode'],
+        charSet: 'UTF-8'
+    }),
+    login: () => ({ code: 'MOCK_LOGIN_CODE_NOT_VALID_FOR_WECHAT' }),
+    checkSession: () => ({ valid: true }),
+    openLocation: () => ({ ok: true }),
+    chooseAddress: () => ({
+        userName: '模拟收货人', telNumber: '00000000000', provinceName: '测试省',
+        cityName: '测试市', countyName: '测试区', detailInfo: '模拟门店路 1 号（测试数据）'
+    }),
+    makePhoneCall: () => ({ ok: true }),
+    requestPayment: () => ({ ok: true })
+});
+export function createMockTransport(options) {
+    const delayMs = options.delayMs ?? 300;
+    if (!Number.isFinite(delayMs) || delayMs < 0 || delayMs > 600000)
+        throw new BridgeError('INVALID_PARAMS', 'mock.delayMs must be between 0 and 600000');
+    const handlers = { ...options.handlers };
+    for (const [method, handler] of Object.entries(handlers)) {
+        if (!BRIDGE_METHODS.includes(method) || typeof handler !== 'function')
+            throw new BridgeError('INVALID_PARAMS', `Invalid mock handler: ${method}`);
+    }
+    return (request, complete) => {
+        const controller = new AbortController();
+        const envelope = () => ({ v: 1, id: request.id, method: request.method, mode: request.mode, completedAt: Date.now() });
+        function failure(code, message) {
+            // Bound user-provided errors so all mock results obey the same URL payload limit.
+            return parseResult(JSON.stringify({ ...envelope(), status: code === 'CANCELLED' ? 'cancel' : 'error', error: { code: code.slice(0, 128), message: message.slice(0, 1024) } }));
+        }
+        const timer = setTimeout(async () => {
+            let result;
+            try {
+                // The method and its parameters have already been validated together by invoke().
+                const handler = (handlers[request.method] ?? defaultMockHandlers[request.method]);
+                const data = await handler(request.params, { requestId: request.id, signal: controller.signal });
+                if (controller.signal.aborted)
+                    return;
+                try {
+                    result = parseResult(JSON.stringify({ ...envelope(), status: 'success', data }));
+                }
+                catch {
+                    result = failure('INVALID_MOCK_RESULT', `Invalid mock result for ${request.method}`);
+                }
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    return;
+                result = failure(error instanceof BridgeError ? error.code : 'MOCK_FAILED', error instanceof Error ? error.message : String(error));
+            }
+            if (!controller.signal.aborted)
+                complete(result);
+        }, delayMs);
+        return () => { clearTimeout(timer); controller.abort(); };
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,145 @@
+export declare const PROTOCOL_VERSION: 1;
+export declare const RESULT_KEY = "__mp_bridge";
+export declare const MAX_PAYLOAD_LENGTH = 16384;
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export type ReturnMode = 'hash' | 'query';
+export interface LocationData {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+    type: 'wgs84' | 'gcj02';
+}
+export interface ScanCodeParams {
+    onlyFromCamera?: boolean;
+    scanType?: Array<'barCode' | 'qrCode' | 'datamatrix' | 'pdf417'>;
+}
+export interface ScanCodeData {
+    result: string;
+    scanType: string;
+    charSet?: string;
+    path?: string;
+    rawData?: string;
+}
+export interface OpenLocationParams {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+    scale?: number;
+}
+export interface PaymentParams {
+    timeStamp: string;
+    nonceStr: string;
+    package: string;
+    signType: 'RSA' | 'MD5' | 'HMAC-SHA256';
+    paySign: string;
+}
+export interface AddressData {
+    userName: string;
+    telNumber: string;
+    provinceName: string;
+    cityName: string;
+    countyName: string;
+    detailInfo: string;
+    postalCode?: string;
+    nationalCode?: string;
+    streetName?: string;
+    detailInfoNew?: string;
+}
+export interface BridgeMethods {
+    getLocation: {
+        params: {
+            type?: 'wgs84' | 'gcj02';
+        };
+        data: LocationData;
+    };
+    scanCode: {
+        params: ScanCodeParams;
+        data: ScanCodeData;
+    };
+    login: {
+        params: {
+            timeout?: number;
+        };
+        data: {
+            code: string;
+        };
+    };
+    checkSession: {
+        params: Record<string, never>;
+        data: {
+            valid: true;
+        };
+    };
+    openLocation: {
+        params: OpenLocationParams;
+        data: {
+            ok: true;
+        };
+    };
+    chooseAddress: {
+        params: Record<string, never>;
+        data: AddressData;
+    };
+    makePhoneCall: {
+        params: {
+            phoneNumber: string;
+        };
+        data: {
+            ok: true;
+        };
+    };
+    requestPayment: {
+        params: PaymentParams;
+        data: {
+            ok: true;
+        };
+    };
+}
+export type BridgeMethod = keyof BridgeMethods;
+export type ParamsOf<M extends BridgeMethod> = BridgeMethods[M]['params'];
+export type DataOf<M extends BridgeMethod> = BridgeMethods[M]['data'];
+export declare const BRIDGE_METHODS: readonly ["getLocation", "scanCode", "login", "checkSession", "openLocation", "chooseAddress", "makePhoneCall", "requestPayment"];
+type Envelope = {
+    v: 1;
+    id: string;
+    mode: ReturnMode;
+};
+export type BridgeRequest<M extends BridgeMethod = BridgeMethod> = {
+    [K in M]: Envelope & {
+        method: K;
+        params: ParamsOf<K>;
+        returnUrl: string;
+        createdAt: number;
+        expiresAt?: number;
+    };
+}[M];
+export type BridgeResult<M extends BridgeMethod = BridgeMethod> = {
+    [K in M]: Envelope & {
+        method: K;
+        completedAt: number;
+    } & ({
+        status: 'success';
+        data: DataOf<K>;
+        error?: never;
+    } | {
+        status: 'cancel' | 'error';
+        error: {
+            code: string;
+            message: string;
+        };
+        data?: never;
+    });
+}[M];
+/** Validate on both sides of the bridge; never forward arbitrary wx options or callbacks. */
+export declare function normalizeParams<M extends BridgeMethod>(method: M, input: unknown): ParamsOf<M>;
+export declare function parseRequest(raw: string): BridgeRequest;
+export declare function parseResult(raw: string): BridgeResult;
+export declare function buildNativeUrl(request: BridgeRequest, path?: string): string;
+export declare function readReturnUrl(url: string): {
+    cleanUrl: string;
+    result?: BridgeResult;
+};
+export declare function buildReturnUrl(returnUrl: string, result: BridgeResult): string;
+export declare function isAllowedWebUrl(url: string, origins: readonly string[]): boolean;
+export {};

package/dist/protocol.js

@@ -0,0 +1,173 @@
+export const PROTOCOL_VERSION = 1;
+export const RESULT_KEY = '__mp_bridge';
+export const MAX_PAYLOAD_LENGTH = 16384;
+export const DEFAULT_TIMEOUT_MS = 120000;
+export const BRIDGE_METHODS = ['getLocation', 'scanCode', 'login', 'checkSession', 'openLocation', 'chooseAddress', 'makePhoneCall', 'requestPayment'];
+function record(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function validId(id) {
+    return typeof id === 'string' && /^[a-zA-Z0-9_-]{8,100}$/.test(id);
+}
+function common(value) {
+    return record(value) && value.v === 1 && validId(value.id) &&
+        typeof value.method === 'string' && BRIDGE_METHODS.includes(value.method) &&
+        (value.mode === 'hash' || value.mode === 'query');
+}
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+const text = (value, max = 2048) => typeof value === 'string' && value.length <= max;
+const coordinate = (value, max) => finite(value) && Math.abs(value) <= max;
+function requireValid(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function keys(value, allowed) {
+    requireValid(Object.keys(value).every(key => allowed.includes(key)), 'Unknown native parameter');
+}
+/** Validate on both sides of the bridge; never forward arbitrary wx options or callbacks. */
+export function normalizeParams(method, input) {
+    requireValid(record(input), 'Invalid native parameters');
+    const value = { ...input };
+    switch (method) {
+        case 'getLocation':
+            keys(value, ['type']);
+            value.type ?? (value.type = 'gcj02');
+            requireValid(value.type === 'wgs84' || value.type === 'gcj02', 'Invalid coordinate type');
+            break;
+        case 'scanCode':
+            keys(value, ['onlyFromCamera', 'scanType']);
+            requireValid(value.onlyFromCamera === undefined || typeof value.onlyFromCamera === 'boolean', 'Invalid camera option');
+            requireValid(value.scanType === undefined || (Array.isArray(value.scanType) && value.scanType.length > 0 && value.scanType.length <= 4 && value.scanType.every(type => ['barCode', 'qrCode', 'datamatrix', 'pdf417'].includes(type))), 'Invalid scan types');
+            break;
+        case 'login':
+            keys(value, ['timeout']);
+            requireValid(value.timeout === undefined || (finite(value.timeout) && value.timeout >= 1000 && value.timeout <= 60000), 'Invalid login timeout');
+            break;
+        case 'checkSession':
+        case 'chooseAddress':
+            keys(value, []);
+            break;
+        case 'openLocation':
+            keys(value, ['latitude', 'longitude', 'name', 'address', 'scale']);
+            requireValid(coordinate(value.latitude, 90) && coordinate(value.longitude, 180), 'Invalid coordinates');
+            requireValid(['name', 'address'].every(key => value[key] === undefined || text(value[key], 512)), 'Invalid map label');
+            requireValid(value.scale === undefined || (finite(value.scale) && value.scale >= 5 && value.scale <= 18), 'Invalid map scale');
+            break;
+        case 'makePhoneCall':
+            keys(value, ['phoneNumber']);
+            requireValid(typeof value.phoneNumber === 'string' && /^\+?[0-9][0-9 -]{2,30}$/.test(value.phoneNumber), 'Invalid phone number');
+            break;
+        case 'requestPayment':
+            keys(value, ['timeStamp', 'nonceStr', 'package', 'signType', 'paySign']);
+            requireValid(typeof value.timeStamp === 'string' && /^\d{1,16}$/.test(value.timeStamp), 'Invalid payment timestamp');
+            requireValid(text(value.nonceStr, 32) && value.nonceStr.length > 0 && text(value.paySign, 2048) && value.paySign.length > 0, 'Invalid payment signature');
+            requireValid(text(value.package, 512) && /^prepay_id=\S+$/.test(value.package), 'Invalid prepay package');
+            requireValid(['RSA', 'MD5', 'HMAC-SHA256'].includes(String(value.signType)), 'Invalid payment sign type');
+            break;
+        default: throw new Error('Unsupported native method');
+    }
+    return value;
+}
+export function parseRequest(raw) {
+    if (raw.length > MAX_PAYLOAD_LENGTH * 6)
+        throw new Error('Bridge request too large');
+    // WeChat versions may provide an already-decoded query. Never decode valid JSON twice.
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        value = JSON.parse(decodeURIComponent(raw));
+    }
+    if (!common(value) || typeof value.returnUrl !== 'string' || value.returnUrl.length > 4096 ||
+        !finite(value.createdAt) || (value.expiresAt !== undefined &&
+        (!finite(value.expiresAt) || value.expiresAt <= value.createdAt || value.expiresAt - value.createdAt > 600000))) {
+        throw new Error('Invalid bridge request');
+    }
+    value.params = normalizeParams(value.method, value.params);
+    requireValid(JSON.stringify(value).length <= MAX_PAYLOAD_LENGTH, 'Bridge request too large');
+    return value;
+}
+export function parseResult(raw) {
+    if (raw.length > MAX_PAYLOAD_LENGTH)
+        throw new Error('Bridge result too large');
+    const value = JSON.parse(raw);
+    if (!common(value) || !['success', 'cancel', 'error'].includes(String(value.status)) ||
+        typeof value.completedAt !== 'number' || !Number.isFinite(value.completedAt)) {
+        throw new Error('Invalid bridge result');
+    }
+    if (value.status === 'success') {
+        const data = value.data;
+        requireValid(record(data), 'Missing native result');
+        switch (value.method) {
+            case 'getLocation':
+                requireValid(coordinate(data.latitude, 90) && coordinate(data.longitude, 180) && finite(data.accuracy) && data.accuracy >= 0 && ['wgs84', 'gcj02'].includes(String(data.type)), 'Invalid location result');
+                break;
+            case 'scanCode':
+                requireValid(text(data.result, MAX_PAYLOAD_LENGTH) && text(data.scanType, 100) && ['charSet', 'path', 'rawData'].every(key => data[key] === undefined || text(data[key], MAX_PAYLOAD_LENGTH)), 'Invalid scan result');
+                break;
+            case 'login':
+                requireValid(text(data.code, 1024) && data.code.length > 0, 'Invalid login code');
+                break;
+            case 'checkSession':
+                requireValid(data.valid === true, 'Invalid session result');
+                break;
+            case 'chooseAddress':
+                requireValid(['userName', 'telNumber', 'provinceName', 'cityName', 'countyName', 'detailInfo'].every(key => text(data[key])) && ['postalCode', 'nationalCode', 'streetName', 'detailInfoNew'].every(key => data[key] === undefined || text(data[key])), 'Invalid address result');
+                break;
+            default: requireValid(data.ok === true, 'Invalid native acknowledgment');
+        }
+    }
+    else if (!record(value.error) || typeof value.error.code !== 'string' ||
+        typeof value.error.message !== 'string')
+        throw new Error('Missing bridge error');
+    return value;
+}
+export function buildNativeUrl(request, path = '/native/invoke') {
+    if (!/^\/[a-zA-Z0-9/_-]+$/.test(path))
+        throw new Error('Invalid native page path');
+    return `${path}?request=${encodeURIComponent(JSON.stringify(request))}`;
+}
+// Keep this module independent of DOM, URL, Buffer and Node APIs: it also runs in WeChat.
+function splitUrl(url) {
+    const hashAt = url.indexOf('#');
+    const base = hashAt < 0 ? url : url.slice(0, hashAt);
+    const hash = hashAt < 0 ? '' : url.slice(hashAt + 1);
+    const queryAt = base.indexOf('?');
+    return { path: queryAt < 0 ? base : base.slice(0, queryAt),
+        query: queryAt < 0 ? '' : base.slice(queryAt + 1), hash };
+}
+function extract(part) {
+    const values = [];
+    const clean = part.split('&').filter(piece => {
+        if (!piece.startsWith(`${RESULT_KEY}=`))
+            return true;
+        values.push(piece.slice(RESULT_KEY.length + 1));
+        return false;
+    }).join('&');
+    return { clean, values };
+}
+export function readReturnUrl(url) {
+    const { path, query, hash } = splitUrl(url);
+    const q = extract(query), h = extract(hash);
+    const values = [...q.values, ...h.values];
+    if (values.length > 1)
+        throw new Error('Ambiguous bridge result');
+    return {
+        cleanUrl: path + (q.clean ? `?${q.clean}` : '') + (h.clean ? `#${h.clean}` : ''),
+        result: values.length ? parseResult(decodeURIComponent(values[0])) : undefined
+    };
+}
+export function buildReturnUrl(returnUrl, result) {
+    const { path, query, hash } = splitUrl(readReturnUrl(returnUrl).cleanUrl);
+    const payload = `${RESULT_KEY}=${encodeURIComponent(JSON.stringify(result))}`;
+    if (result.mode === 'hash')
+        return path + (query ? `?${query}` : '') + '#' + (hash ? `${hash}&` : '') + payload;
+    return path + '?' + (query ? `${query}&` : '') + payload + (hash ? `#${hash}` : '');
+}
+export function isAllowedWebUrl(url, origins) {
+    if (/[\s\\\u0000-\u001f]/.test(url))
+        return false;
+    const match = /^(https:\/\/[^/?#]+)(?:[/?#]|$)/.exec(url);
+    return !!match && origins.includes(match[1]);
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@spopc/wechat-miniprogram",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Web SDK for the WeChat Mini Program URL bridge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudcarver/miniprogram-shell.git",
+    "directory": "sdks/wechat-miniprogram"
+  },
+  "homepage": "https://www.npmjs.com/package/@spopc/wechat-miniprogram",
+  "keywords": ["wechat", "miniprogram", "webview", "bridge", "mock", "typescript"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "default": "./dist/index.js" },
+    "./protocol": { "types": "./dist/protocol.d.ts", "import": "./dist/protocol.js", "default": "./dist/protocol.js" }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": { "build": "tsc -p tsconfig.json", "prepack": "npm run build" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+}