@vector-metis/browser-sdk 0.1.3 → 0.2.0

package/README.md

@@ -8,18 +8,25 @@
 npm install @vector-metis/browser-sdk
 ```
 
-应用入口仍需先加载平台脚本：
+```ts
+import { init } from "@vector-metis/browser-sdk";
 
-```html
-<script src="/api/runtime/v1/browser-sdk.js"></script>
+const Metis = await init();
+const dependencies = await Metis.listDependencies();
 ```
 
-```ts
-import { Metis } from "@vector-metis/browser-sdk";
+`init()` 会自动加载当前平台的 `/api/runtime/v1/browser-sdk.js`，并在脚本完成且能力校验通过后返回 SDK。重复调用会复用已经加载的 `window.Metis`。本地开发或严格 CSP 场景可以覆盖脚本地址、nonce 和超时时间：
 
-const dependencies = await Metis.listDependencies();
+```ts
+const Metis = await init({
+  scriptUrl: "/api/runtime/v1/browser-sdk.js",
+  nonce: document.querySelector("meta[name=csp-nonce]")?.content,
+  timeoutMs: 10000,
+});
 ```
 
+请在浏览器应用启动阶段调用 `init()`；服务端渲染、Node.js 和构建阶段不提供浏览器环境。
+
 浏览器 SDK 不暴露应用令牌、模型 API key、对象存储凭据或 Service 端口。完整说明见[开发文档](https://github.com/vector-metis/metis-sdk-typescript#readme)。
 
 Apache-2.0，见仓库中的 `LICENSE`。

package/dist/index.d.ts

@@ -34,10 +34,16 @@ declare global {
         Metis?: InjectedBrowserSDK;
     }
 }
-/** 返回平台已经注入的浏览器能力；脚本缺失时明确失败。 */
-export declare function injected(): InjectedBrowserSDK;
-/** 对平台注入能力做延迟解析的类型化代理。 */
-export declare const Metis: InjectedBrowserSDK;
+export type BrowserSDKInitOptions = {
+    /** Same-origin by default; override for local development or a platform proxy. */
+    scriptUrl?: string;
+    /** Optional CSP nonce for the dynamically-created script element. */
+    nonce?: string;
+    /** Milliseconds to wait for the platform script before rejecting. */
+    timeoutMs?: number;
+};
+/** Load the platform-injected browser capabilities and return a ready SDK. */
+export declare function init(options?: BrowserSDKInitOptions): Promise<InjectedBrowserSDK>;
 export type MetisBrowserContext = BrowserContext;
 export type MetisBrowserSDK = InjectedBrowserSDK;
 export type MetisWebDependency = WebDependency;

package/dist/index.js

@@ -1,17 +1,77 @@
-/** 返回平台已经注入的浏览器能力；脚本缺失时明确失败。 */
-export function injected() {
-    const sdk = globalThis.window?.Metis;
-    if (!sdk) {
-        throw new Error("Metis browser SDK is not injected; load /api/runtime/v1/browser-sdk.js first");
+let initialization;
+function validateSDK(value) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Metis browser SDK loaded without a valid window.Metis object");
+    }
+    const sdk = value;
+    const methods = [
+        "appURL",
+        "getContext",
+        "listDependencies",
+        "dependency",
+        "dependencyURL",
+        "openAppPage",
+    ];
+    if (methods.some((method) => typeof sdk[method] !== "function")) {
+        throw new Error("Metis browser SDK loaded without the required platform methods");
     }
     return sdk;
 }
-/** 对平台注入能力做延迟解析的类型化代理。 */
-export const Metis = Object.freeze({
-    appURL: (path) => injected().appURL(path),
-    getContext: () => injected().getContext(),
-    listDependencies: () => injected().listDependencies(),
-    dependency: (selector) => injected().dependency(selector),
-    dependencyURL: (selector, path) => injected().dependencyURL(selector, path),
-    openAppPage: (options) => injected().openAppPage(options),
-});
+/** Load the platform-injected browser capabilities and return a ready SDK. */
+export function init(options = {}) {
+    if (initialization) {
+        return initialization;
+    }
+    const browserWindow = globalThis.window;
+    const document = globalThis.document;
+    if (!browserWindow) {
+        return Promise.reject(new Error("Metis browser SDK requires a browser environment"));
+    }
+    if (browserWindow.Metis) {
+        return Promise.resolve(validateSDK(browserWindow.Metis));
+    }
+    if (!document) {
+        return Promise.reject(new Error("Metis browser SDK requires a browser document"));
+    }
+    const timeoutMs = options.timeoutMs ?? 10000;
+    const script = document.createElement("script");
+    let timer;
+    let resolveInitialization;
+    let rejectInitialization;
+    initialization = new Promise((resolve, reject) => {
+        resolveInitialization = resolve;
+        rejectInitialization = reject;
+    });
+    const pending = initialization;
+    const fail = (error) => {
+        if (timer)
+            clearTimeout(timer);
+        initialization = undefined;
+        rejectInitialization(error);
+    };
+    script.src = options.scriptUrl ?? "/api/runtime/v1/browser-sdk.js";
+    script.async = true;
+    if (options.nonce)
+        script.nonce = options.nonce;
+    script.onload = () => {
+        try {
+            if (timer)
+                clearTimeout(timer);
+            const sdk = validateSDK(browserWindow.Metis);
+            initialization = undefined;
+            resolveInitialization(sdk);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error : new Error(String(error)));
+        }
+    };
+    script.onerror = () => fail(new Error(`Failed to load Metis browser SDK: ${script.src}`));
+    timer = setTimeout(() => fail(new Error(`Metis browser SDK load timed out after ${timeoutMs}ms`)), timeoutMs);
+    try {
+        document.head.appendChild(script);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error : new Error(String(error)));
+    }
+    return pending;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vector-metis/browser-sdk",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Metis browser SDK for injected application capabilities",
   "repository": {
     "type": "git",