@cyodaa/plugin-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyodaa Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,114 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  registerPlugin: () => registerPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/register.ts
+var import_react2 = require("react");
+
+// src/context.ts
+var import_react = require("react");
+var CyodaaSDKContext = (0, import_react.createContext)(null);
+CyodaaSDKContext.displayName = "CyodaaSDKContext";
+function CyodaaSDKProvider({ value, children }) {
+  return (0, import_react.createElement)(CyodaaSDKContext.Provider, { value }, children);
+}
+
+// src/register.ts
+function registerPlugin(config) {
+  const instance = {
+    config,
+    root: null,
+    mounted: false
+  };
+  async function loadReactDOM() {
+    const mod = await import(
+      /* @vite-ignore */
+      "react-dom/client"
+    );
+    return mod;
+  }
+  function buildTree(ctx, components) {
+    const children = components.map(
+      (Comp, i) => (0, import_react2.createElement)(Comp, { key: i })
+    );
+    const fragment = (0, import_react2.createElement)(import_react2.Fragment, null, ...children);
+    return (0, import_react2.createElement)(
+      CyodaaSDKProvider,
+      { value: ctx, children: fragment }
+    );
+  }
+  function mount(container, ctx) {
+    if (instance.mounted) {
+      unmount();
+    }
+    void (async () => {
+      try {
+        const reactDOM = await loadReactDOM();
+        const root = reactDOM.createRoot(container);
+        instance.root = root;
+        instance.mounted = true;
+        if (config.onInit) {
+          await Promise.resolve(config.onInit(ctx));
+        }
+        const tree = buildTree(ctx, config.components);
+        root.render(tree);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Plugin \u8F09\u5165\u5931\u6557";
+        container.textContent = `[plugin-sdk] ${message}`;
+      }
+    })();
+  }
+  function unmount() {
+    if (!instance.mounted) return;
+    if (config.onDestroy) {
+      try {
+        void Promise.resolve(config.onDestroy());
+      } catch {
+      }
+    }
+    try {
+      instance.root?.unmount();
+    } catch {
+    }
+    instance.root = null;
+    instance.mounted = false;
+  }
+  return { mount, unmount };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  registerPlugin
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/register.ts","../src/context.ts"],"sourcesContent":["/**\n * @cyodaa/plugin-sdk — 主要匯出入口\n *\n * 匯出 registerPlugin 註冊函式與所有公開型別。\n */\n\n// 核心註冊函式\nexport { registerPlugin } from './register';\n\n// 型別匯出\nexport type {\n  CyodaaPluginContext,\n  CyodaaContext,\n  CyodaaUser,\n  CyodaaTenant,\n  CyodaaPlatform,\n  PluginModule,\n  PluginConfig,\n  PluginComponent,\n} from './types';\n","/**\n * registerPlugin — Plugin 註冊入口\n *\n * 接收 PluginConfig，回傳符合 PluginModule 合約的 { mount, unmount }，\n * 供 PluginRenderer 的 Shadow DOM 沙箱呼叫。\n *\n * react-dom 採用動態 import，避免 SDK 直接捆綁 react-dom。\n */\n\nimport { createElement, Fragment, type ComponentType } from 'react';\nimport type { CyodaaPluginContext, PluginConfig, PluginModule } from './types';\nimport { CyodaaSDKProvider } from './context';\n\n// ============================================================\n// react-dom/client 動態載入型別\n// ============================================================\n\ninterface ReactDOMRoot {\n  render: (element: React.ReactNode) => void;\n  unmount: () => void;\n}\n\ninterface ReactDOMClient {\n  createRoot: (container: HTMLElement) => ReactDOMRoot;\n}\n\n// ============================================================\n// 內部狀態（per-plugin instance）\n// ============================================================\n\ninterface PluginInstance {\n  readonly config: PluginConfig;\n  root: ReactDOMRoot | null;\n  mounted: boolean;\n}\n\n// ============================================================\n// registerPlugin\n// ============================================================\n\n/**\n * 註冊 Plugin，回傳 PluginModule。\n *\n * @example\n * ```ts\n * import { registerPlugin } from '@cyodaa/plugin-sdk';\n * import { App } from './App';\n *\n * const plugin = registerPlugin({\n *   id: 'my-plugin',\n *   components: [App],\n * });\n *\n * export const { mount, unmount } = plugin;\n * ```\n */\nexport function registerPlugin(config: PluginConfig): PluginModule {\n  const instance: PluginInstance = {\n    config,\n    root: null,\n    mounted: false,\n  };\n\n  /** 動態載入 react-dom/client */\n  async function loadReactDOM(): Promise<ReactDOMClient> {\n    // eslint-disable-next-line @typescript-eslint/no-require-imports -- 動態載入避免 SDK 直接捆綁 react-dom\n    const mod: ReactDOMClient = await import(/* @vite-ignore */ 'react-dom/client');\n    return mod;\n  }\n\n  /** 建構 Plugin 元件樹：Provider 包裹所有 components */\n  function buildTree(ctx: CyodaaPluginContext, components: readonly ComponentType[]): React.ReactNode {\n    const children = components.map((Comp, i) =>\n      createElement(Comp, { key: i })\n    );\n\n    const fragment = createElement(Fragment, null, ...children);\n\n    return createElement(\n      CyodaaSDKProvider,\n      { value: ctx, children: fragment },\n    );\n  }\n\n  /** mount — PluginRenderer 呼叫此函式掛載 Plugin */\n  function mount(container: HTMLElement, ctx: CyodaaPluginContext): void {\n    if (instance.mounted) {\n      // 防止重複掛載：先卸載再重新掛載\n      unmount();\n    }\n\n    // 同步啟動（createRoot 不需要 await）\n    // 但因為 react-dom 是動態 import，改用 async IIFE\n    void (async () => {\n      try {\n        const reactDOM = await loadReactDOM();\n        const root = reactDOM.createRoot(container);\n\n        instance.root = root;\n        instance.mounted = true;\n\n        // 觸發 onInit 回調\n        if (config.onInit) {\n          await Promise.resolve(config.onInit(ctx));\n        }\n\n        // 渲染元件樹\n        const tree = buildTree(ctx, config.components);\n        root.render(tree);\n      } catch (err) {\n        // 渲染失敗時顯示錯誤訊息在容器中\n        const message = err instanceof Error ? err.message : 'Plugin 載入失敗';\n        container.textContent = `[plugin-sdk] ${message}`;\n      }\n    })();\n  }\n\n  /** unmount — PluginRenderer 呼叫此函式卸載 Plugin */\n  function unmount(): void {\n    if (!instance.mounted) return;\n\n    // 觸發 onDestroy 回調\n    if (config.onDestroy) {\n      try {\n        void Promise.resolve(config.onDestroy());\n      } catch {\n        // 忽略 onDestroy 錯誤，確保卸載流程不中斷\n      }\n    }\n\n    // 卸載 React 根節點\n    try {\n      instance.root?.unmount();\n    } catch {\n      // 忽略 unmount 錯誤\n    }\n\n    instance.root = null;\n    instance.mounted = false;\n  }\n\n  return { mount, unmount };\n}\n","/**\n * SDK 內部 React Context\n *\n * 將宿主注入的 CyodaaPluginContext 透過 React Context 傳遞給\n * Plugin 元件樹，供各 hook 消費。\n */\n\nimport { createContext, useContext, createElement } from 'react';\nimport type { ReactNode } from 'react';\nimport type { CyodaaPluginContext } from './types';\n\n// ============================================================\n// Context\n// ============================================================\n\n/** SDK 內部用 Context — 不直接對外導出 */\nconst CyodaaSDKContext = createContext<CyodaaPluginContext | null>(null);\n\nCyodaaSDKContext.displayName = 'CyodaaSDKContext';\n\n// ============================================================\n// Provider\n// ============================================================\n\ninterface ProviderProps {\n  readonly value: CyodaaPluginContext;\n  readonly children: ReactNode;\n}\n\n/** 將平台 Context 注入 React 元件樹 */\nexport function CyodaaSDKProvider({ value, children }: ProviderProps) {\n  return createElement(CyodaaSDKContext.Provider, { value }, children);\n}\n\n// ============================================================\n// 內部 Hook\n// ============================================================\n\n/**\n * 內部 hook：讀取原始 CyodaaPluginContext。\n * 僅供 SDK 內部 hook 使用，不對外導出。\n *\n * @throws {Error} 若在 CyodaaSDKProvider 外使用\n */\nexport function useSDKContext(): CyodaaPluginContext {\n  const ctx = useContext(CyodaaSDKContext);\n\n  if (ctx === null) {\n    throw new Error(\n      '[plugin-sdk] useSDKContext 必須在 CyodaaSDKProvider 內使用。' +\n      '請確認 Plugin 已透過 registerPlugin() 正確註冊。'\n    );\n  }\n\n  return ctx;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACSA,IAAAA,gBAA4D;;;ACF5D,mBAAyD;AASzD,IAAM,uBAAmB,4BAA0C,IAAI;AAEvE,iBAAiB,cAAc;AAYxB,SAAS,kBAAkB,EAAE,OAAO,SAAS,GAAkB;AACpE,aAAO,4BAAc,iBAAiB,UAAU,EAAE,MAAM,GAAG,QAAQ;AACrE;;;ADwBO,SAAS,eAAe,QAAoC;AACjE,QAAM,WAA2B;AAAA,IAC/B;AAAA,IACA,MAAM;AAAA,IACN,SAAS;AAAA,EACX;AAGA,iBAAe,eAAwC;AAErD,UAAM,MAAsB,MAAM;AAAA;AAAA,MAA0B;AAAA,IAAkB;AAC9E,WAAO;AAAA,EACT;AAGA,WAAS,UAAU,KAA0B,YAAuD;AAClG,UAAM,WAAW,WAAW;AAAA,MAAI,CAAC,MAAM,UACrC,6BAAc,MAAM,EAAE,KAAK,EAAE,CAAC;AAAA,IAChC;AAEA,UAAM,eAAW,6BAAc,wBAAU,MAAM,GAAG,QAAQ;AAE1D,eAAO;AAAA,MACL;AAAA,MACA,EAAE,OAAO,KAAK,UAAU,SAAS;AAAA,IACnC;AAAA,EACF;AAGA,WAAS,MAAM,WAAwB,KAAgC;AACrE,QAAI,SAAS,SAAS;AAEpB,cAAQ;AAAA,IACV;AAIA,UAAM,YAAY;AAChB,UAAI;AACF,cAAM,WAAW,MAAM,aAAa;AACpC,cAAM,OAAO,SAAS,WAAW,SAAS;AAE1C,iBAAS,OAAO;AAChB,iBAAS,UAAU;AAGnB,YAAI,OAAO,QAAQ;AACjB,gBAAM,QAAQ,QAAQ,OAAO,OAAO,GAAG,CAAC;AAAA,QAC1C;AAGA,cAAM,OAAO,UAAU,KAAK,OAAO,UAAU;AAC7C,aAAK,OAAO,IAAI;AAAA,MAClB,SAAS,KAAK;AAEZ,cAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,kBAAU,cAAc,gBAAgB,OAAO;AAAA,MACjD;AAAA,IACF,GAAG;AAAA,EACL;AAGA,WAAS,UAAgB;AACvB,QAAI,CAAC,SAAS,QAAS;AAGvB,QAAI,OAAO,WAAW;AACpB,UAAI;AACF,aAAK,QAAQ,QAAQ,OAAO,UAAU,CAAC;AAAA,MACzC,QAAQ;AAAA,MAER;AAAA,IACF;AAGA,QAAI;AACF,eAAS,MAAM,QAAQ;AAAA,IACzB,QAAQ;AAAA,IAER;AAEA,aAAS,OAAO;AAChB,aAAS,UAAU;AAAA,EACrB;AAEA,SAAO,EAAE,OAAO,QAAQ;AAC1B;","names":["import_react"]}

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+/**
+ * @cyodaa/plugin-sdk 型別定義
+ *
+ * 與 PluginRenderer.tsx 定義的介面完全一致，
+ * 確保 Plugin 在 Shadow DOM 沙箱內正確運作。
+ */
+/** 由宿主 PluginRenderer 注入的唯讀 Context */
+interface CyodaaPluginContext {
+    readonly tenantId: string;
+    readonly userId: number | null;
+    readonly theme: 'light' | 'dark';
+    readonly tier: string;
+}
+/** 使用者資訊（由 SDK 從 CyodaaPluginContext 轉換） */
+interface CyodaaUser {
+    readonly id: string;
+    readonly displayName: string;
+    readonly email: string;
+    readonly role: string;
+}
+/** 租戶資訊 */
+interface CyodaaTenant {
+    readonly id: string;
+    readonly name: string;
+}
+/** 平台版本資訊 */
+interface CyodaaPlatform {
+    readonly version: string;
+}
+/** 提供給 Plugin 開發者的豐富 Context */
+interface CyodaaContext {
+    readonly user: CyodaaUser | null;
+    readonly theme: 'light' | 'dark';
+    readonly tenant: CyodaaTenant;
+    readonly locale: string;
+    readonly platform: CyodaaPlatform;
+}
+/** Plugin 必須導出的 mount/unmount 介面 */
+interface PluginModule {
+    mount: (container: HTMLElement, ctx: CyodaaPluginContext) => void;
+    unmount: () => void;
+}
+/** React 元件型別（避免直接依賴 React 型別） */
+type PluginComponent = React.ComponentType;
+/** registerPlugin() 的設定參數 */
+interface PluginConfig {
+    /** Plugin 唯一識別碼 */
+    readonly id: string;
+    /** 要渲染的 React 元件列表（依序渲染） */
+    readonly components: readonly PluginComponent[];
+    /** Plugin 初始化回調（mount 時觸發） */
+    readonly onInit?: (ctx: CyodaaPluginContext) => void | Promise<void>;
+    /** Plugin 銷毀回調（unmount 時觸發） */
+    readonly onDestroy?: () => void | Promise<void>;
+}
+
+/**
+ * registerPlugin — Plugin 註冊入口
+ *
+ * 接收 PluginConfig，回傳符合 PluginModule 合約的 { mount, unmount }，
+ * 供 PluginRenderer 的 Shadow DOM 沙箱呼叫。
+ *
+ * react-dom 採用動態 import，避免 SDK 直接捆綁 react-dom。
+ */
+
+/**
+ * 註冊 Plugin，回傳 PluginModule。
+ *
+ * @example
+ * ```ts
+ * import { registerPlugin } from '@cyodaa/plugin-sdk';
+ * import { App } from './App';
+ *
+ * const plugin = registerPlugin({
+ *   id: 'my-plugin',
+ *   components: [App],
+ * });
+ *
+ * export const { mount, unmount } = plugin;
+ * ```
+ */
+declare function registerPlugin(config: PluginConfig): PluginModule;
+
+export { type CyodaaContext, type CyodaaPlatform, type CyodaaPluginContext, type CyodaaTenant, type CyodaaUser, type PluginComponent, type PluginConfig, type PluginModule, registerPlugin };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @cyodaa/plugin-sdk 型別定義
+ *
+ * 與 PluginRenderer.tsx 定義的介面完全一致，
+ * 確保 Plugin 在 Shadow DOM 沙箱內正確運作。
+ */
+/** 由宿主 PluginRenderer 注入的唯讀 Context */
+interface CyodaaPluginContext {
+    readonly tenantId: string;
+    readonly userId: number | null;
+    readonly theme: 'light' | 'dark';
+    readonly tier: string;
+}
+/** 使用者資訊（由 SDK 從 CyodaaPluginContext 轉換） */
+interface CyodaaUser {
+    readonly id: string;
+    readonly displayName: string;
+    readonly email: string;
+    readonly role: string;
+}
+/** 租戶資訊 */
+interface CyodaaTenant {
+    readonly id: string;
+    readonly name: string;
+}
+/** 平台版本資訊 */
+interface CyodaaPlatform {
+    readonly version: string;
+}
+/** 提供給 Plugin 開發者的豐富 Context */
+interface CyodaaContext {
+    readonly user: CyodaaUser | null;
+    readonly theme: 'light' | 'dark';
+    readonly tenant: CyodaaTenant;
+    readonly locale: string;
+    readonly platform: CyodaaPlatform;
+}
+/** Plugin 必須導出的 mount/unmount 介面 */
+interface PluginModule {
+    mount: (container: HTMLElement, ctx: CyodaaPluginContext) => void;
+    unmount: () => void;
+}
+/** React 元件型別（避免直接依賴 React 型別） */
+type PluginComponent = React.ComponentType;
+/** registerPlugin() 的設定參數 */
+interface PluginConfig {
+    /** Plugin 唯一識別碼 */
+    readonly id: string;
+    /** 要渲染的 React 元件列表（依序渲染） */
+    readonly components: readonly PluginComponent[];
+    /** Plugin 初始化回調（mount 時觸發） */
+    readonly onInit?: (ctx: CyodaaPluginContext) => void | Promise<void>;
+    /** Plugin 銷毀回調（unmount 時觸發） */
+    readonly onDestroy?: () => void | Promise<void>;
+}
+
+/**
+ * registerPlugin — Plugin 註冊入口
+ *
+ * 接收 PluginConfig，回傳符合 PluginModule 合約的 { mount, unmount }，
+ * 供 PluginRenderer 的 Shadow DOM 沙箱呼叫。
+ *
+ * react-dom 採用動態 import，避免 SDK 直接捆綁 react-dom。
+ */
+
+/**
+ * 註冊 Plugin，回傳 PluginModule。
+ *
+ * @example
+ * ```ts
+ * import { registerPlugin } from '@cyodaa/plugin-sdk';
+ * import { App } from './App';
+ *
+ * const plugin = registerPlugin({
+ *   id: 'my-plugin',
+ *   components: [App],
+ * });
+ *
+ * export const { mount, unmount } = plugin;
+ * ```
+ */
+declare function registerPlugin(config: PluginConfig): PluginModule;
+
+export { type CyodaaContext, type CyodaaPlatform, type CyodaaPluginContext, type CyodaaTenant, type CyodaaUser, type PluginComponent, type PluginConfig, type PluginModule, registerPlugin };

package/dist/index.js

@@ -0,0 +1,77 @@
+// src/register.ts
+import { createElement as createElement2, Fragment } from "react";
+
+// src/context.ts
+import { createContext, useContext, createElement } from "react";
+var CyodaaSDKContext = createContext(null);
+CyodaaSDKContext.displayName = "CyodaaSDKContext";
+function CyodaaSDKProvider({ value, children }) {
+  return createElement(CyodaaSDKContext.Provider, { value }, children);
+}
+
+// src/register.ts
+function registerPlugin(config) {
+  const instance = {
+    config,
+    root: null,
+    mounted: false
+  };
+  async function loadReactDOM() {
+    const mod = await import(
+      /* @vite-ignore */
+      "react-dom/client"
+    );
+    return mod;
+  }
+  function buildTree(ctx, components) {
+    const children = components.map(
+      (Comp, i) => createElement2(Comp, { key: i })
+    );
+    const fragment = createElement2(Fragment, null, ...children);
+    return createElement2(
+      CyodaaSDKProvider,
+      { value: ctx, children: fragment }
+    );
+  }
+  function mount(container, ctx) {
+    if (instance.mounted) {
+      unmount();
+    }
+    void (async () => {
+      try {
+        const reactDOM = await loadReactDOM();
+        const root = reactDOM.createRoot(container);
+        instance.root = root;
+        instance.mounted = true;
+        if (config.onInit) {
+          await Promise.resolve(config.onInit(ctx));
+        }
+        const tree = buildTree(ctx, config.components);
+        root.render(tree);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Plugin \u8F09\u5165\u5931\u6557";
+        container.textContent = `[plugin-sdk] ${message}`;
+      }
+    })();
+  }
+  function unmount() {
+    if (!instance.mounted) return;
+    if (config.onDestroy) {
+      try {
+        void Promise.resolve(config.onDestroy());
+      } catch {
+      }
+    }
+    try {
+      instance.root?.unmount();
+    } catch {
+    }
+    instance.root = null;
+    instance.mounted = false;
+  }
+  return { mount, unmount };
+}
+export {
+  registerPlugin
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/register.ts","../src/context.ts"],"sourcesContent":["/**\n * registerPlugin — Plugin 註冊入口\n *\n * 接收 PluginConfig，回傳符合 PluginModule 合約的 { mount, unmount }，\n * 供 PluginRenderer 的 Shadow DOM 沙箱呼叫。\n *\n * react-dom 採用動態 import，避免 SDK 直接捆綁 react-dom。\n */\n\nimport { createElement, Fragment, type ComponentType } from 'react';\nimport type { CyodaaPluginContext, PluginConfig, PluginModule } from './types';\nimport { CyodaaSDKProvider } from './context';\n\n// ============================================================\n// react-dom/client 動態載入型別\n// ============================================================\n\ninterface ReactDOMRoot {\n  render: (element: React.ReactNode) => void;\n  unmount: () => void;\n}\n\ninterface ReactDOMClient {\n  createRoot: (container: HTMLElement) => ReactDOMRoot;\n}\n\n// ============================================================\n// 內部狀態（per-plugin instance）\n// ============================================================\n\ninterface PluginInstance {\n  readonly config: PluginConfig;\n  root: ReactDOMRoot | null;\n  mounted: boolean;\n}\n\n// ============================================================\n// registerPlugin\n// ============================================================\n\n/**\n * 註冊 Plugin，回傳 PluginModule。\n *\n * @example\n * ```ts\n * import { registerPlugin } from '@cyodaa/plugin-sdk';\n * import { App } from './App';\n *\n * const plugin = registerPlugin({\n *   id: 'my-plugin',\n *   components: [App],\n * });\n *\n * export const { mount, unmount } = plugin;\n * ```\n */\nexport function registerPlugin(config: PluginConfig): PluginModule {\n  const instance: PluginInstance = {\n    config,\n    root: null,\n    mounted: false,\n  };\n\n  /** 動態載入 react-dom/client */\n  async function loadReactDOM(): Promise<ReactDOMClient> {\n    // eslint-disable-next-line @typescript-eslint/no-require-imports -- 動態載入避免 SDK 直接捆綁 react-dom\n    const mod: ReactDOMClient = await import(/* @vite-ignore */ 'react-dom/client');\n    return mod;\n  }\n\n  /** 建構 Plugin 元件樹：Provider 包裹所有 components */\n  function buildTree(ctx: CyodaaPluginContext, components: readonly ComponentType[]): React.ReactNode {\n    const children = components.map((Comp, i) =>\n      createElement(Comp, { key: i })\n    );\n\n    const fragment = createElement(Fragment, null, ...children);\n\n    return createElement(\n      CyodaaSDKProvider,\n      { value: ctx, children: fragment },\n    );\n  }\n\n  /** mount — PluginRenderer 呼叫此函式掛載 Plugin */\n  function mount(container: HTMLElement, ctx: CyodaaPluginContext): void {\n    if (instance.mounted) {\n      // 防止重複掛載：先卸載再重新掛載\n      unmount();\n    }\n\n    // 同步啟動（createRoot 不需要 await）\n    // 但因為 react-dom 是動態 import，改用 async IIFE\n    void (async () => {\n      try {\n        const reactDOM = await loadReactDOM();\n        const root = reactDOM.createRoot(container);\n\n        instance.root = root;\n        instance.mounted = true;\n\n        // 觸發 onInit 回調\n        if (config.onInit) {\n          await Promise.resolve(config.onInit(ctx));\n        }\n\n        // 渲染元件樹\n        const tree = buildTree(ctx, config.components);\n        root.render(tree);\n      } catch (err) {\n        // 渲染失敗時顯示錯誤訊息在容器中\n        const message = err instanceof Error ? err.message : 'Plugin 載入失敗';\n        container.textContent = `[plugin-sdk] ${message}`;\n      }\n    })();\n  }\n\n  /** unmount — PluginRenderer 呼叫此函式卸載 Plugin */\n  function unmount(): void {\n    if (!instance.mounted) return;\n\n    // 觸發 onDestroy 回調\n    if (config.onDestroy) {\n      try {\n        void Promise.resolve(config.onDestroy());\n      } catch {\n        // 忽略 onDestroy 錯誤，確保卸載流程不中斷\n      }\n    }\n\n    // 卸載 React 根節點\n    try {\n      instance.root?.unmount();\n    } catch {\n      // 忽略 unmount 錯誤\n    }\n\n    instance.root = null;\n    instance.mounted = false;\n  }\n\n  return { mount, unmount };\n}\n","/**\n * SDK 內部 React Context\n *\n * 將宿主注入的 CyodaaPluginContext 透過 React Context 傳遞給\n * Plugin 元件樹，供各 hook 消費。\n */\n\nimport { createContext, useContext, createElement } from 'react';\nimport type { ReactNode } from 'react';\nimport type { CyodaaPluginContext } from './types';\n\n// ============================================================\n// Context\n// ============================================================\n\n/** SDK 內部用 Context — 不直接對外導出 */\nconst CyodaaSDKContext = createContext<CyodaaPluginContext | null>(null);\n\nCyodaaSDKContext.displayName = 'CyodaaSDKContext';\n\n// ============================================================\n// Provider\n// ============================================================\n\ninterface ProviderProps {\n  readonly value: CyodaaPluginContext;\n  readonly children: ReactNode;\n}\n\n/** 將平台 Context 注入 React 元件樹 */\nexport function CyodaaSDKProvider({ value, children }: ProviderProps) {\n  return createElement(CyodaaSDKContext.Provider, { value }, children);\n}\n\n// ============================================================\n// 內部 Hook\n// ============================================================\n\n/**\n * 內部 hook：讀取原始 CyodaaPluginContext。\n * 僅供 SDK 內部 hook 使用，不對外導出。\n *\n * @throws {Error} 若在 CyodaaSDKProvider 外使用\n */\nexport function useSDKContext(): CyodaaPluginContext {\n  const ctx = useContext(CyodaaSDKContext);\n\n  if (ctx === null) {\n    throw new Error(\n      '[plugin-sdk] useSDKContext 必須在 CyodaaSDKProvider 內使用。' +\n      '請確認 Plugin 已透過 registerPlugin() 正確註冊。'\n    );\n  }\n\n  return ctx;\n}\n"],"mappings":";AASA,SAAS,iBAAAA,gBAAe,gBAAoC;;;ACF5D,SAAS,eAAe,YAAY,qBAAqB;AASzD,IAAM,mBAAmB,cAA0C,IAAI;AAEvE,iBAAiB,cAAc;AAYxB,SAAS,kBAAkB,EAAE,OAAO,SAAS,GAAkB;AACpE,SAAO,cAAc,iBAAiB,UAAU,EAAE,MAAM,GAAG,QAAQ;AACrE;;;ADwBO,SAAS,eAAe,QAAoC;AACjE,QAAM,WAA2B;AAAA,IAC/B;AAAA,IACA,MAAM;AAAA,IACN,SAAS;AAAA,EACX;AAGA,iBAAe,eAAwC;AAErD,UAAM,MAAsB,MAAM;AAAA;AAAA,MAA0B;AAAA,IAAkB;AAC9E,WAAO;AAAA,EACT;AAGA,WAAS,UAAU,KAA0B,YAAuD;AAClG,UAAM,WAAW,WAAW;AAAA,MAAI,CAAC,MAAM,MACrCC,eAAc,MAAM,EAAE,KAAK,EAAE,CAAC;AAAA,IAChC;AAEA,UAAM,WAAWA,eAAc,UAAU,MAAM,GAAG,QAAQ;AAE1D,WAAOA;AAAA,MACL;AAAA,MACA,EAAE,OAAO,KAAK,UAAU,SAAS;AAAA,IACnC;AAAA,EACF;AAGA,WAAS,MAAM,WAAwB,KAAgC;AACrE,QAAI,SAAS,SAAS;AAEpB,cAAQ;AAAA,IACV;AAIA,UAAM,YAAY;AAChB,UAAI;AACF,cAAM,WAAW,MAAM,aAAa;AACpC,cAAM,OAAO,SAAS,WAAW,SAAS;AAE1C,iBAAS,OAAO;AAChB,iBAAS,UAAU;AAGnB,YAAI,OAAO,QAAQ;AACjB,gBAAM,QAAQ,QAAQ,OAAO,OAAO,GAAG,CAAC;AAAA,QAC1C;AAGA,cAAM,OAAO,UAAU,KAAK,OAAO,UAAU;AAC7C,aAAK,OAAO,IAAI;AAAA,MAClB,SAAS,KAAK;AAEZ,cAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,kBAAU,cAAc,gBAAgB,OAAO;AAAA,MACjD;AAAA,IACF,GAAG;AAAA,EACL;AAGA,WAAS,UAAgB;AACvB,QAAI,CAAC,SAAS,QAAS;AAGvB,QAAI,OAAO,WAAW;AACpB,UAAI;AACF,aAAK,QAAQ,QAAQ,OAAO,UAAU,CAAC;AAAA,MACzC,QAAQ;AAAA,MAER;AAAA,IACF;AAGA,QAAI;AACF,eAAS,MAAM,QAAQ;AAAA,IACzB,QAAQ;AAAA,IAER;AAEA,aAAS,OAAO;AAChB,aAAS,UAAU;AAAA,EACrB;AAEA,SAAO,EAAE,OAAO,QAAQ;AAC1B;","names":["createElement","createElement"]}

package/dist/react/index.cjs

@@ -0,0 +1,211 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useCyodaaSDK: () => useCyodaaSDK,
+  usePluginAPI: () => usePluginAPI,
+  usePluginEvents: () => usePluginEvents,
+  usePluginStorage: () => usePluginStorage
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/react/useCyodaaSDK.ts
+var import_react2 = require("react");
+
+// src/context.ts
+var import_react = require("react");
+var CyodaaSDKContext = (0, import_react.createContext)(null);
+CyodaaSDKContext.displayName = "CyodaaSDKContext";
+function useSDKContext() {
+  const ctx = (0, import_react.useContext)(CyodaaSDKContext);
+  if (ctx === null) {
+    throw new Error(
+      "[plugin-sdk] useSDKContext \u5FC5\u9808\u5728 CyodaaSDKProvider \u5167\u4F7F\u7528\u3002\u8ACB\u78BA\u8A8D Plugin \u5DF2\u900F\u904E registerPlugin() \u6B63\u78BA\u8A3B\u518A\u3002"
+    );
+  }
+  return ctx;
+}
+
+// src/react/useCyodaaSDK.ts
+var SDK_VERSION = "0.1.0";
+var DEFAULT_LOCALE = "zh-TW";
+function useCyodaaSDK() {
+  const ctx = useSDKContext();
+  return (0, import_react2.useMemo)(() => {
+    const user = ctx.userId !== null ? {
+      id: String(ctx.userId),
+      displayName: "",
+      email: "",
+      role: ""
+    } : null;
+    return {
+      user,
+      theme: ctx.theme,
+      tenant: {
+        id: ctx.tenantId,
+        name: ctx.tenantId
+      },
+      locale: DEFAULT_LOCALE,
+      platform: {
+        version: SDK_VERSION
+      }
+    };
+  }, [ctx.tenantId, ctx.userId, ctx.theme]);
+}
+
+// src/react/usePluginAPI.ts
+var import_react3 = require("react");
+async function handleResponse(response) {
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(
+      `[plugin-sdk] API \u8ACB\u6C42\u5931\u6557\uFF1A${response.status} ${response.statusText}` + (text ? ` \u2014 ${text}` : "")
+    );
+  }
+  return response.json();
+}
+function getHeaders() {
+  return {
+    "Content-Type": "application/json",
+    "Accept": "application/json"
+  };
+}
+function usePluginAPI() {
+  const call = (0, import_react3.useCallback)(async (service, method, params) => {
+    const payload = { service, method, params };
+    const response = await fetch("/api/v1/plugins/rpc", {
+      method: "POST",
+      headers: getHeaders(),
+      body: JSON.stringify(payload)
+    });
+    return handleResponse(response);
+  }, []);
+  const get = (0, import_react3.useCallback)(async (path) => {
+    const response = await fetch(path, {
+      method: "GET",
+      headers: getHeaders()
+    });
+    return handleResponse(response);
+  }, []);
+  const post = (0, import_react3.useCallback)(async (path, body) => {
+    const response = await fetch(path, {
+      method: "POST",
+      headers: getHeaders(),
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    return handleResponse(response);
+  }, []);
+  return (0, import_react3.useMemo)(() => ({ call, get, post }), [call, get, post]);
+}
+
+// src/react/usePluginEvents.ts
+var import_react4 = require("react");
+function prefixedEventName(event) {
+  return `cyodaa:${event}`;
+}
+function usePluginEvents() {
+  const on = (0, import_react4.useCallback)((event, handler) => {
+    const eventName = prefixedEventName(event);
+    const listener = (e) => {
+      const customEvent = e;
+      handler(customEvent.detail);
+    };
+    window.addEventListener(eventName, listener);
+    return () => {
+      window.removeEventListener(eventName, listener);
+    };
+  }, []);
+  const emit = (0, import_react4.useCallback)((event, data) => {
+    const eventName = prefixedEventName(event);
+    const customEvent = new CustomEvent(eventName, {
+      detail: data,
+      bubbles: false,
+      cancelable: false
+    });
+    window.dispatchEvent(customEvent);
+  }, []);
+  return (0, import_react4.useMemo)(() => ({ on, emit }), [on, emit]);
+}
+
+// src/react/usePluginStorage.ts
+var import_react5 = require("react");
+function usePluginStorage(pluginId) {
+  const fullKey = (0, import_react5.useCallback)(
+    (key) => `plugin:${pluginId}:${key}`,
+    [pluginId]
+  );
+  const prefix = (0, import_react5.useMemo)(() => `plugin:${pluginId}:`, [pluginId]);
+  const get = (0, import_react5.useCallback)((key) => {
+    try {
+      const raw = localStorage.getItem(fullKey(key));
+      if (raw === null) return null;
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }, [fullKey]);
+  const set = (0, import_react5.useCallback)((key, value) => {
+    try {
+      const serialized = JSON.stringify(value);
+      localStorage.setItem(fullKey(key), serialized);
+    } catch {
+    }
+  }, [fullKey]);
+  const deleteKey = (0, import_react5.useCallback)((key) => {
+    localStorage.removeItem(fullKey(key));
+  }, [fullKey]);
+  const keys = (0, import_react5.useCallback)(() => {
+    const result = [];
+    const len = localStorage.length;
+    for (let i = 0; i < len; i++) {
+      const k = localStorage.key(i);
+      if (k !== null && k.startsWith(prefix)) {
+        result.push(k.slice(prefix.length));
+      }
+    }
+    return result;
+  }, [prefix]);
+  const clear = (0, import_react5.useCallback)(() => {
+    const keysToRemove = [];
+    const len = localStorage.length;
+    for (let i = 0; i < len; i++) {
+      const k = localStorage.key(i);
+      if (k !== null && k.startsWith(prefix)) {
+        keysToRemove.push(k);
+      }
+    }
+    for (const k of keysToRemove) {
+      localStorage.removeItem(k);
+    }
+  }, [prefix]);
+  return (0, import_react5.useMemo)(
+    () => ({ get, set, delete: deleteKey, keys, clear }),
+    [get, set, deleteKey, keys, clear]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useCyodaaSDK,
+  usePluginAPI,
+  usePluginEvents,
+  usePluginStorage
+});
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts","../../src/react/useCyodaaSDK.ts","../../src/context.ts","../../src/react/usePluginAPI.ts","../../src/react/usePluginEvents.ts","../../src/react/usePluginStorage.ts"],"sourcesContent":["/**\n * @cyodaa/plugin-sdk/react — React Hooks 匯出\n *\n * 提供 Plugin 開發者在 React 元件中使用的所有 hooks。\n */\n\nexport { useCyodaaSDK } from './useCyodaaSDK';\nexport { usePluginAPI } from './usePluginAPI';\nexport { usePluginEvents } from './usePluginEvents';\nexport { usePluginStorage } from './usePluginStorage';\n","/**\n * useCyodaaSDK — 取得豐富的平台 Context\n *\n * 將宿主注入的 CyodaaPluginContext 轉換為\n * 開發者友善的 CyodaaContext 格式。\n */\n\nimport { useMemo } from 'react';\nimport { useSDKContext } from '../context';\nimport type { CyodaaContext, CyodaaUser } from '../types';\n\n/** SDK 版本（與 package.json 同步） */\nconst SDK_VERSION = '0.1.0';\n\n/** 預設語系 */\nconst DEFAULT_LOCALE = 'zh-TW';\n\n/**\n * 取得豐富的 Cyodaa 平台 Context。\n *\n * @example\n * ```tsx\n * import { useCyodaaSDK } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const { user, theme, tenant } = useCyodaaSDK();\n *   return <div>Hi, {user?.displayName ?? 'Guest'}</div>;\n * }\n * ```\n */\nexport function useCyodaaSDK(): CyodaaContext {\n  const ctx = useSDKContext();\n\n  return useMemo<CyodaaContext>(() => {\n    // 將 userId 轉換為 CyodaaUser（null-safe）\n    const user: CyodaaUser | null = ctx.userId !== null\n      ? {\n          id: String(ctx.userId),\n          displayName: '',\n          email: '',\n          role: '',\n        }\n      : null;\n\n    return {\n      user,\n      theme: ctx.theme,\n      tenant: {\n        id: ctx.tenantId,\n        name: ctx.tenantId,\n      },\n      locale: DEFAULT_LOCALE,\n      platform: {\n        version: SDK_VERSION,\n      },\n    };\n  }, [ctx.tenantId, ctx.userId, ctx.theme]);\n}\n","/**\n * SDK 內部 React Context\n *\n * 將宿主注入的 CyodaaPluginContext 透過 React Context 傳遞給\n * Plugin 元件樹，供各 hook 消費。\n */\n\nimport { createContext, useContext, createElement } from 'react';\nimport type { ReactNode } from 'react';\nimport type { CyodaaPluginContext } from './types';\n\n// ============================================================\n// Context\n// ============================================================\n\n/** SDK 內部用 Context — 不直接對外導出 */\nconst CyodaaSDKContext = createContext<CyodaaPluginContext | null>(null);\n\nCyodaaSDKContext.displayName = 'CyodaaSDKContext';\n\n// ============================================================\n// Provider\n// ============================================================\n\ninterface ProviderProps {\n  readonly value: CyodaaPluginContext;\n  readonly children: ReactNode;\n}\n\n/** 將平台 Context 注入 React 元件樹 */\nexport function CyodaaSDKProvider({ value, children }: ProviderProps) {\n  return createElement(CyodaaSDKContext.Provider, { value }, children);\n}\n\n// ============================================================\n// 內部 Hook\n// ============================================================\n\n/**\n * 內部 hook：讀取原始 CyodaaPluginContext。\n * 僅供 SDK 內部 hook 使用，不對外導出。\n *\n * @throws {Error} 若在 CyodaaSDKProvider 外使用\n */\nexport function useSDKContext(): CyodaaPluginContext {\n  const ctx = useContext(CyodaaSDKContext);\n\n  if (ctx === null) {\n    throw new Error(\n      '[plugin-sdk] useSDKContext 必須在 CyodaaSDKProvider 內使用。' +\n      '請確認 Plugin 已透過 registerPlugin() 正確註冊。'\n    );\n  }\n\n  return ctx;\n}\n","/**\n * usePluginAPI — Plugin HTTP 通訊 hook\n *\n * 提供 RPC 呼叫與通用 HTTP 方法，\n * 全部使用相對 URL（same-origin）。\n */\n\nimport { useCallback, useMemo } from 'react';\n\n// ============================================================\n// 型別\n// ============================================================\n\n/** RPC 呼叫的請求格式 */\ninterface RPCPayload {\n  readonly service: string;\n  readonly method: string;\n  readonly params?: Record<string, unknown>;\n}\n\n/** API hook 回傳介面 */\ninterface PluginAPI {\n  /** 呼叫後端 RPC 端點 */\n  readonly call: <T = unknown>(\n    service: string,\n    method: string,\n    params?: Record<string, unknown>,\n  ) => Promise<T>;\n\n  /** GET 請求 */\n  readonly get: <T = unknown>(path: string) => Promise<T>;\n\n  /** POST 請求 */\n  readonly post: <T = unknown>(\n    path: string,\n    body?: unknown,\n  ) => Promise<T>;\n}\n\n// ============================================================\n// 內部工具\n// ============================================================\n\n/** 統一 fetch 錯誤處理 */\nasync function handleResponse<T>(response: Response): Promise<T> {\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `[plugin-sdk] API 請求失敗：${response.status} ${response.statusText}` +\n      (text ? ` — ${text}` : ''),\n    );\n  }\n\n  return response.json() as Promise<T>;\n}\n\n/** 取得通用 headers */\nfunction getHeaders(): HeadersInit {\n  return {\n    'Content-Type': 'application/json',\n    'Accept': 'application/json',\n  };\n}\n\n// ============================================================\n// Hook\n// ============================================================\n\n/**\n * 取得 Plugin API 呼叫工具。\n *\n * @example\n * ```tsx\n * import { usePluginAPI } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const api = usePluginAPI();\n *\n *   const handleClick = async () => {\n *     const result = await api.call('kpi', 'getSummary', { period: '2026-Q1' });\n *   };\n * }\n * ```\n */\nexport function usePluginAPI(): PluginAPI {\n  /** RPC 呼叫：POST /api/v1/plugins/rpc */\n  const call = useCallback(async <T = unknown>(\n    service: string,\n    method: string,\n    params?: Record<string, unknown>,\n  ): Promise<T> => {\n    const payload: RPCPayload = { service, method, params };\n\n    const response = await fetch('/api/v1/plugins/rpc', {\n      method: 'POST',\n      headers: getHeaders(),\n      body: JSON.stringify(payload),\n    });\n\n    return handleResponse<T>(response);\n  }, []);\n\n  /** GET 請求 */\n  const get = useCallback(async <T = unknown>(path: string): Promise<T> => {\n    const response = await fetch(path, {\n      method: 'GET',\n      headers: getHeaders(),\n    });\n\n    return handleResponse<T>(response);\n  }, []);\n\n  /** POST 請求 */\n  const post = useCallback(async <T = unknown>(\n    path: string,\n    body?: unknown,\n  ): Promise<T> => {\n    const response = await fetch(path, {\n      method: 'POST',\n      headers: getHeaders(),\n      body: body !== undefined ? JSON.stringify(body) : undefined,\n    });\n\n    return handleResponse<T>(response);\n  }, []);\n\n  return useMemo<PluginAPI>(() => ({ call, get, post }), [call, get, post]);\n}\n","/**\n * usePluginEvents — Plugin 事件通訊 hook\n *\n * 透過 window 上的 CustomEvent 實現\n * Plugin 與宿主平台之間的事件訂閱/發布。\n *\n * 事件名稱統一加上 `cyodaa:` 前綴避免衝突。\n */\n\nimport { useCallback, useMemo } from 'react';\n\n// ============================================================\n// 型別\n// ============================================================\n\n/** 事件處理器 */\ntype EventHandler<T = unknown> = (data: T) => void;\n\n/** 取消訂閱函式 */\ntype Unsubscribe = () => void;\n\n/** 事件 hook 回傳介面 */\ninterface PluginEvents {\n  /** 訂閱事件，回傳取消訂閱函式 */\n  readonly on: <T = unknown>(event: string, handler: EventHandler<T>) => Unsubscribe;\n\n  /** 發送事件 */\n  readonly emit: (event: string, data?: unknown) => void;\n}\n\n// ============================================================\n// 內部工具\n// ============================================================\n\n/** 產生帶前綴的事件名稱 */\nfunction prefixedEventName(event: string): string {\n  return `cyodaa:${event}`;\n}\n\n// ============================================================\n// Hook\n// ============================================================\n\n/**\n * 取得 Plugin 事件通訊工具。\n *\n * @example\n * ```tsx\n * import { usePluginEvents } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const events = usePluginEvents();\n *\n *   useEffect(() => {\n *     const unsub = events.on('theme:changed', (data) => {\n *       // 處理主題切換\n *     });\n *     return unsub;\n *   }, [events]);\n *\n *   const handleNotify = () => {\n *     events.emit('plugin:action', { type: 'refresh' });\n *   };\n * }\n * ```\n */\nexport function usePluginEvents(): PluginEvents {\n  /** 訂閱事件 */\n  const on = useCallback(<T = unknown>(\n    event: string,\n    handler: EventHandler<T>,\n  ): Unsubscribe => {\n    const eventName = prefixedEventName(event);\n\n    const listener = (e: Event) => {\n      const customEvent = e as CustomEvent<T>;\n      handler(customEvent.detail);\n    };\n\n    window.addEventListener(eventName, listener);\n\n    // 回傳取消訂閱函式\n    return () => {\n      window.removeEventListener(eventName, listener);\n    };\n  }, []);\n\n  /** 發送事件 */\n  const emit = useCallback((event: string, data?: unknown): void => {\n    const eventName = prefixedEventName(event);\n\n    const customEvent = new CustomEvent(eventName, {\n      detail: data,\n      bubbles: false,\n      cancelable: false,\n    });\n\n    window.dispatchEvent(customEvent);\n  }, []);\n\n  return useMemo<PluginEvents>(() => ({ on, emit }), [on, emit]);\n}\n","/**\n * usePluginStorage — Plugin 本地儲存 hook\n *\n * 基於 localStorage，以 `plugin:{pluginId}:` 為前綴隔離各 Plugin 資料。\n * pluginId 透過 SDK Context 內的 tenantId 命名空間進一步隔離。\n */\n\nimport { useCallback, useMemo } from 'react';\n\n// ============================================================\n// 型別\n// ============================================================\n\n/** 儲存 hook 回傳介面 */\ninterface PluginStorage {\n  /** 讀取值（JSON 反序列化） */\n  readonly get: <T = unknown>(key: string) => T | null;\n\n  /** 寫入值（JSON 序列化） */\n  readonly set: (key: string, value: unknown) => void;\n\n  /** 刪除指定 key */\n  readonly delete: (key: string) => void;\n\n  /** 列出此 Plugin 所有 key（不含前綴） */\n  readonly keys: () => readonly string[];\n\n  /** 清除此 Plugin 所有資料 */\n  readonly clear: () => void;\n}\n\n// ============================================================\n// Hook\n// ============================================================\n\n/**\n * 取得隔離的 Plugin 本地儲存工具。\n *\n * @param pluginId — Plugin 唯一識別碼\n *\n * @example\n * ```tsx\n * import { usePluginStorage } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const storage = usePluginStorage('my-plugin');\n *\n *   // 讀取\n *   const settings = storage.get<{ darkMode: boolean }>('settings');\n *\n *   // 寫入\n *   storage.set('settings', { darkMode: true });\n *\n *   // 列出所有 key\n *   const allKeys = storage.keys();\n * }\n * ```\n */\nexport function usePluginStorage(pluginId: string): PluginStorage {\n  /** 產生帶前綴的完整 key */\n  const fullKey = useCallback(\n    (key: string): string => `plugin:${pluginId}:${key}`,\n    [pluginId],\n  );\n\n  /** 前綴字串（用於 keys/clear） */\n  const prefix = useMemo(() => `plugin:${pluginId}:`, [pluginId]);\n\n  /** 讀取值 */\n  const get = useCallback(<T = unknown>(key: string): T | null => {\n    try {\n      const raw = localStorage.getItem(fullKey(key));\n      if (raw === null) return null;\n      return JSON.parse(raw) as T;\n    } catch {\n      return null;\n    }\n  }, [fullKey]);\n\n  /** 寫入值 */\n  const set = useCallback((key: string, value: unknown): void => {\n    try {\n      const serialized = JSON.stringify(value);\n      localStorage.setItem(fullKey(key), serialized);\n    } catch {\n      // localStorage 空間不足時靜默失敗\n    }\n  }, [fullKey]);\n\n  /** 刪除指定 key */\n  const deleteKey = useCallback((key: string): void => {\n    localStorage.removeItem(fullKey(key));\n  }, [fullKey]);\n\n  /** 列出所有屬於此 Plugin 的 key */\n  const keys = useCallback((): readonly string[] => {\n    const result: string[] = [];\n    const len = localStorage.length;\n\n    for (let i = 0; i < len; i++) {\n      const k = localStorage.key(i);\n      if (k !== null && k.startsWith(prefix)) {\n        result.push(k.slice(prefix.length));\n      }\n    }\n\n    return result;\n  }, [prefix]);\n\n  /** 清除此 Plugin 所有資料 */\n  const clear = useCallback((): void => {\n    // 先收集所有匹配 key，再批次刪除（避免遍歷時修改集合）\n    const keysToRemove: string[] = [];\n    const len = localStorage.length;\n\n    for (let i = 0; i < len; i++) {\n      const k = localStorage.key(i);\n      if (k !== null && k.startsWith(prefix)) {\n        keysToRemove.push(k);\n      }\n    }\n\n    for (const k of keysToRemove) {\n      localStorage.removeItem(k);\n    }\n  }, [prefix]);\n\n  return useMemo<PluginStorage>(\n    () => ({ get, set, delete: deleteKey, keys, clear }),\n    [get, set, deleteKey, keys, clear],\n  );\n}\n"],"mappings":"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","names":["import_react","import_react","import_react","import_react"]}

package/dist/react/index.d.cts

@@ -0,0 +1,169 @@
+/** 使用者資訊（由 SDK 從 CyodaaPluginContext 轉換） */
+interface CyodaaUser {
+    readonly id: string;
+    readonly displayName: string;
+    readonly email: string;
+    readonly role: string;
+}
+/** 租戶資訊 */
+interface CyodaaTenant {
+    readonly id: string;
+    readonly name: string;
+}
+/** 平台版本資訊 */
+interface CyodaaPlatform {
+    readonly version: string;
+}
+/** 提供給 Plugin 開發者的豐富 Context */
+interface CyodaaContext {
+    readonly user: CyodaaUser | null;
+    readonly theme: 'light' | 'dark';
+    readonly tenant: CyodaaTenant;
+    readonly locale: string;
+    readonly platform: CyodaaPlatform;
+}
+
+/**
+ * useCyodaaSDK — 取得豐富的平台 Context
+ *
+ * 將宿主注入的 CyodaaPluginContext 轉換為
+ * 開發者友善的 CyodaaContext 格式。
+ */
+
+/**
+ * 取得豐富的 Cyodaa 平台 Context。
+ *
+ * @example
+ * ```tsx
+ * import { useCyodaaSDK } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const { user, theme, tenant } = useCyodaaSDK();
+ *   return <div>Hi, {user?.displayName ?? 'Guest'}</div>;
+ * }
+ * ```
+ */
+declare function useCyodaaSDK(): CyodaaContext;
+
+/**
+ * usePluginAPI — Plugin HTTP 通訊 hook
+ *
+ * 提供 RPC 呼叫與通用 HTTP 方法，
+ * 全部使用相對 URL（same-origin）。
+ */
+/** API hook 回傳介面 */
+interface PluginAPI {
+    /** 呼叫後端 RPC 端點 */
+    readonly call: <T = unknown>(service: string, method: string, params?: Record<string, unknown>) => Promise<T>;
+    /** GET 請求 */
+    readonly get: <T = unknown>(path: string) => Promise<T>;
+    /** POST 請求 */
+    readonly post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+}
+/**
+ * 取得 Plugin API 呼叫工具。
+ *
+ * @example
+ * ```tsx
+ * import { usePluginAPI } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const api = usePluginAPI();
+ *
+ *   const handleClick = async () => {
+ *     const result = await api.call('kpi', 'getSummary', { period: '2026-Q1' });
+ *   };
+ * }
+ * ```
+ */
+declare function usePluginAPI(): PluginAPI;
+
+/**
+ * usePluginEvents — Plugin 事件通訊 hook
+ *
+ * 透過 window 上的 CustomEvent 實現
+ * Plugin 與宿主平台之間的事件訂閱/發布。
+ *
+ * 事件名稱統一加上 `cyodaa:` 前綴避免衝突。
+ */
+/** 事件處理器 */
+type EventHandler<T = unknown> = (data: T) => void;
+/** 取消訂閱函式 */
+type Unsubscribe = () => void;
+/** 事件 hook 回傳介面 */
+interface PluginEvents {
+    /** 訂閱事件，回傳取消訂閱函式 */
+    readonly on: <T = unknown>(event: string, handler: EventHandler<T>) => Unsubscribe;
+    /** 發送事件 */
+    readonly emit: (event: string, data?: unknown) => void;
+}
+/**
+ * 取得 Plugin 事件通訊工具。
+ *
+ * @example
+ * ```tsx
+ * import { usePluginEvents } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const events = usePluginEvents();
+ *
+ *   useEffect(() => {
+ *     const unsub = events.on('theme:changed', (data) => {
+ *       // 處理主題切換
+ *     });
+ *     return unsub;
+ *   }, [events]);
+ *
+ *   const handleNotify = () => {
+ *     events.emit('plugin:action', { type: 'refresh' });
+ *   };
+ * }
+ * ```
+ */
+declare function usePluginEvents(): PluginEvents;
+
+/**
+ * usePluginStorage — Plugin 本地儲存 hook
+ *
+ * 基於 localStorage，以 `plugin:{pluginId}:` 為前綴隔離各 Plugin 資料。
+ * pluginId 透過 SDK Context 內的 tenantId 命名空間進一步隔離。
+ */
+/** 儲存 hook 回傳介面 */
+interface PluginStorage {
+    /** 讀取值（JSON 反序列化） */
+    readonly get: <T = unknown>(key: string) => T | null;
+    /** 寫入值（JSON 序列化） */
+    readonly set: (key: string, value: unknown) => void;
+    /** 刪除指定 key */
+    readonly delete: (key: string) => void;
+    /** 列出此 Plugin 所有 key（不含前綴） */
+    readonly keys: () => readonly string[];
+    /** 清除此 Plugin 所有資料 */
+    readonly clear: () => void;
+}
+/**
+ * 取得隔離的 Plugin 本地儲存工具。
+ *
+ * @param pluginId — Plugin 唯一識別碼
+ *
+ * @example
+ * ```tsx
+ * import { usePluginStorage } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const storage = usePluginStorage('my-plugin');
+ *
+ *   // 讀取
+ *   const settings = storage.get<{ darkMode: boolean }>('settings');
+ *
+ *   // 寫入
+ *   storage.set('settings', { darkMode: true });
+ *
+ *   // 列出所有 key
+ *   const allKeys = storage.keys();
+ * }
+ * ```
+ */
+declare function usePluginStorage(pluginId: string): PluginStorage;
+
+export { useCyodaaSDK, usePluginAPI, usePluginEvents, usePluginStorage };

package/dist/react/index.d.ts

@@ -0,0 +1,169 @@
+/** 使用者資訊（由 SDK 從 CyodaaPluginContext 轉換） */
+interface CyodaaUser {
+    readonly id: string;
+    readonly displayName: string;
+    readonly email: string;
+    readonly role: string;
+}
+/** 租戶資訊 */
+interface CyodaaTenant {
+    readonly id: string;
+    readonly name: string;
+}
+/** 平台版本資訊 */
+interface CyodaaPlatform {
+    readonly version: string;
+}
+/** 提供給 Plugin 開發者的豐富 Context */
+interface CyodaaContext {
+    readonly user: CyodaaUser | null;
+    readonly theme: 'light' | 'dark';
+    readonly tenant: CyodaaTenant;
+    readonly locale: string;
+    readonly platform: CyodaaPlatform;
+}
+
+/**
+ * useCyodaaSDK — 取得豐富的平台 Context
+ *
+ * 將宿主注入的 CyodaaPluginContext 轉換為
+ * 開發者友善的 CyodaaContext 格式。
+ */
+
+/**
+ * 取得豐富的 Cyodaa 平台 Context。
+ *
+ * @example
+ * ```tsx
+ * import { useCyodaaSDK } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const { user, theme, tenant } = useCyodaaSDK();
+ *   return <div>Hi, {user?.displayName ?? 'Guest'}</div>;
+ * }
+ * ```
+ */
+declare function useCyodaaSDK(): CyodaaContext;
+
+/**
+ * usePluginAPI — Plugin HTTP 通訊 hook
+ *
+ * 提供 RPC 呼叫與通用 HTTP 方法，
+ * 全部使用相對 URL（same-origin）。
+ */
+/** API hook 回傳介面 */
+interface PluginAPI {
+    /** 呼叫後端 RPC 端點 */
+    readonly call: <T = unknown>(service: string, method: string, params?: Record<string, unknown>) => Promise<T>;
+    /** GET 請求 */
+    readonly get: <T = unknown>(path: string) => Promise<T>;
+    /** POST 請求 */
+    readonly post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+}
+/**
+ * 取得 Plugin API 呼叫工具。
+ *
+ * @example
+ * ```tsx
+ * import { usePluginAPI } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const api = usePluginAPI();
+ *
+ *   const handleClick = async () => {
+ *     const result = await api.call('kpi', 'getSummary', { period: '2026-Q1' });
+ *   };
+ * }
+ * ```
+ */
+declare function usePluginAPI(): PluginAPI;
+
+/**
+ * usePluginEvents — Plugin 事件通訊 hook
+ *
+ * 透過 window 上的 CustomEvent 實現
+ * Plugin 與宿主平台之間的事件訂閱/發布。
+ *
+ * 事件名稱統一加上 `cyodaa:` 前綴避免衝突。
+ */
+/** 事件處理器 */
+type EventHandler<T = unknown> = (data: T) => void;
+/** 取消訂閱函式 */
+type Unsubscribe = () => void;
+/** 事件 hook 回傳介面 */
+interface PluginEvents {
+    /** 訂閱事件，回傳取消訂閱函式 */
+    readonly on: <T = unknown>(event: string, handler: EventHandler<T>) => Unsubscribe;
+    /** 發送事件 */
+    readonly emit: (event: string, data?: unknown) => void;
+}
+/**
+ * 取得 Plugin 事件通訊工具。
+ *
+ * @example
+ * ```tsx
+ * import { usePluginEvents } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const events = usePluginEvents();
+ *
+ *   useEffect(() => {
+ *     const unsub = events.on('theme:changed', (data) => {
+ *       // 處理主題切換
+ *     });
+ *     return unsub;
+ *   }, [events]);
+ *
+ *   const handleNotify = () => {
+ *     events.emit('plugin:action', { type: 'refresh' });
+ *   };
+ * }
+ * ```
+ */
+declare function usePluginEvents(): PluginEvents;
+
+/**
+ * usePluginStorage — Plugin 本地儲存 hook
+ *
+ * 基於 localStorage，以 `plugin:{pluginId}:` 為前綴隔離各 Plugin 資料。
+ * pluginId 透過 SDK Context 內的 tenantId 命名空間進一步隔離。
+ */
+/** 儲存 hook 回傳介面 */
+interface PluginStorage {
+    /** 讀取值（JSON 反序列化） */
+    readonly get: <T = unknown>(key: string) => T | null;
+    /** 寫入值（JSON 序列化） */
+    readonly set: (key: string, value: unknown) => void;
+    /** 刪除指定 key */
+    readonly delete: (key: string) => void;
+    /** 列出此 Plugin 所有 key（不含前綴） */
+    readonly keys: () => readonly string[];
+    /** 清除此 Plugin 所有資料 */
+    readonly clear: () => void;
+}
+/**
+ * 取得隔離的 Plugin 本地儲存工具。
+ *
+ * @param pluginId — Plugin 唯一識別碼
+ *
+ * @example
+ * ```tsx
+ * import { usePluginStorage } from '@cyodaa/plugin-sdk/react';
+ *
+ * function MyComponent() {
+ *   const storage = usePluginStorage('my-plugin');
+ *
+ *   // 讀取
+ *   const settings = storage.get<{ darkMode: boolean }>('settings');
+ *
+ *   // 寫入
+ *   storage.set('settings', { darkMode: true });
+ *
+ *   // 列出所有 key
+ *   const allKeys = storage.keys();
+ * }
+ * ```
+ */
+declare function usePluginStorage(pluginId: string): PluginStorage;
+
+export { useCyodaaSDK, usePluginAPI, usePluginEvents, usePluginStorage };

package/dist/react/index.js

@@ -0,0 +1,181 @@
+// src/react/useCyodaaSDK.ts
+import { useMemo } from "react";
+
+// src/context.ts
+import { createContext, useContext, createElement } from "react";
+var CyodaaSDKContext = createContext(null);
+CyodaaSDKContext.displayName = "CyodaaSDKContext";
+function useSDKContext() {
+  const ctx = useContext(CyodaaSDKContext);
+  if (ctx === null) {
+    throw new Error(
+      "[plugin-sdk] useSDKContext \u5FC5\u9808\u5728 CyodaaSDKProvider \u5167\u4F7F\u7528\u3002\u8ACB\u78BA\u8A8D Plugin \u5DF2\u900F\u904E registerPlugin() \u6B63\u78BA\u8A3B\u518A\u3002"
+    );
+  }
+  return ctx;
+}
+
+// src/react/useCyodaaSDK.ts
+var SDK_VERSION = "0.1.0";
+var DEFAULT_LOCALE = "zh-TW";
+function useCyodaaSDK() {
+  const ctx = useSDKContext();
+  return useMemo(() => {
+    const user = ctx.userId !== null ? {
+      id: String(ctx.userId),
+      displayName: "",
+      email: "",
+      role: ""
+    } : null;
+    return {
+      user,
+      theme: ctx.theme,
+      tenant: {
+        id: ctx.tenantId,
+        name: ctx.tenantId
+      },
+      locale: DEFAULT_LOCALE,
+      platform: {
+        version: SDK_VERSION
+      }
+    };
+  }, [ctx.tenantId, ctx.userId, ctx.theme]);
+}
+
+// src/react/usePluginAPI.ts
+import { useCallback, useMemo as useMemo2 } from "react";
+async function handleResponse(response) {
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(
+      `[plugin-sdk] API \u8ACB\u6C42\u5931\u6557\uFF1A${response.status} ${response.statusText}` + (text ? ` \u2014 ${text}` : "")
+    );
+  }
+  return response.json();
+}
+function getHeaders() {
+  return {
+    "Content-Type": "application/json",
+    "Accept": "application/json"
+  };
+}
+function usePluginAPI() {
+  const call = useCallback(async (service, method, params) => {
+    const payload = { service, method, params };
+    const response = await fetch("/api/v1/plugins/rpc", {
+      method: "POST",
+      headers: getHeaders(),
+      body: JSON.stringify(payload)
+    });
+    return handleResponse(response);
+  }, []);
+  const get = useCallback(async (path) => {
+    const response = await fetch(path, {
+      method: "GET",
+      headers: getHeaders()
+    });
+    return handleResponse(response);
+  }, []);
+  const post = useCallback(async (path, body) => {
+    const response = await fetch(path, {
+      method: "POST",
+      headers: getHeaders(),
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    return handleResponse(response);
+  }, []);
+  return useMemo2(() => ({ call, get, post }), [call, get, post]);
+}
+
+// src/react/usePluginEvents.ts
+import { useCallback as useCallback2, useMemo as useMemo3 } from "react";
+function prefixedEventName(event) {
+  return `cyodaa:${event}`;
+}
+function usePluginEvents() {
+  const on = useCallback2((event, handler) => {
+    const eventName = prefixedEventName(event);
+    const listener = (e) => {
+      const customEvent = e;
+      handler(customEvent.detail);
+    };
+    window.addEventListener(eventName, listener);
+    return () => {
+      window.removeEventListener(eventName, listener);
+    };
+  }, []);
+  const emit = useCallback2((event, data) => {
+    const eventName = prefixedEventName(event);
+    const customEvent = new CustomEvent(eventName, {
+      detail: data,
+      bubbles: false,
+      cancelable: false
+    });
+    window.dispatchEvent(customEvent);
+  }, []);
+  return useMemo3(() => ({ on, emit }), [on, emit]);
+}
+
+// src/react/usePluginStorage.ts
+import { useCallback as useCallback3, useMemo as useMemo4 } from "react";
+function usePluginStorage(pluginId) {
+  const fullKey = useCallback3(
+    (key) => `plugin:${pluginId}:${key}`,
+    [pluginId]
+  );
+  const prefix = useMemo4(() => `plugin:${pluginId}:`, [pluginId]);
+  const get = useCallback3((key) => {
+    try {
+      const raw = localStorage.getItem(fullKey(key));
+      if (raw === null) return null;
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }, [fullKey]);
+  const set = useCallback3((key, value) => {
+    try {
+      const serialized = JSON.stringify(value);
+      localStorage.setItem(fullKey(key), serialized);
+    } catch {
+    }
+  }, [fullKey]);
+  const deleteKey = useCallback3((key) => {
+    localStorage.removeItem(fullKey(key));
+  }, [fullKey]);
+  const keys = useCallback3(() => {
+    const result = [];
+    const len = localStorage.length;
+    for (let i = 0; i < len; i++) {
+      const k = localStorage.key(i);
+      if (k !== null && k.startsWith(prefix)) {
+        result.push(k.slice(prefix.length));
+      }
+    }
+    return result;
+  }, [prefix]);
+  const clear = useCallback3(() => {
+    const keysToRemove = [];
+    const len = localStorage.length;
+    for (let i = 0; i < len; i++) {
+      const k = localStorage.key(i);
+      if (k !== null && k.startsWith(prefix)) {
+        keysToRemove.push(k);
+      }
+    }
+    for (const k of keysToRemove) {
+      localStorage.removeItem(k);
+    }
+  }, [prefix]);
+  return useMemo4(
+    () => ({ get, set, delete: deleteKey, keys, clear }),
+    [get, set, deleteKey, keys, clear]
+  );
+}
+export {
+  useCyodaaSDK,
+  usePluginAPI,
+  usePluginEvents,
+  usePluginStorage
+};
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/useCyodaaSDK.ts","../../src/context.ts","../../src/react/usePluginAPI.ts","../../src/react/usePluginEvents.ts","../../src/react/usePluginStorage.ts"],"sourcesContent":["/**\n * useCyodaaSDK — 取得豐富的平台 Context\n *\n * 將宿主注入的 CyodaaPluginContext 轉換為\n * 開發者友善的 CyodaaContext 格式。\n */\n\nimport { useMemo } from 'react';\nimport { useSDKContext } from '../context';\nimport type { CyodaaContext, CyodaaUser } from '../types';\n\n/** SDK 版本（與 package.json 同步） */\nconst SDK_VERSION = '0.1.0';\n\n/** 預設語系 */\nconst DEFAULT_LOCALE = 'zh-TW';\n\n/**\n * 取得豐富的 Cyodaa 平台 Context。\n *\n * @example\n * ```tsx\n * import { useCyodaaSDK } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const { user, theme, tenant } = useCyodaaSDK();\n *   return <div>Hi, {user?.displayName ?? 'Guest'}</div>;\n * }\n * ```\n */\nexport function useCyodaaSDK(): CyodaaContext {\n  const ctx = useSDKContext();\n\n  return useMemo<CyodaaContext>(() => {\n    // 將 userId 轉換為 CyodaaUser（null-safe）\n    const user: CyodaaUser | null = ctx.userId !== null\n      ? {\n          id: String(ctx.userId),\n          displayName: '',\n          email: '',\n          role: '',\n        }\n      : null;\n\n    return {\n      user,\n      theme: ctx.theme,\n      tenant: {\n        id: ctx.tenantId,\n        name: ctx.tenantId,\n      },\n      locale: DEFAULT_LOCALE,\n      platform: {\n        version: SDK_VERSION,\n      },\n    };\n  }, [ctx.tenantId, ctx.userId, ctx.theme]);\n}\n","/**\n * SDK 內部 React Context\n *\n * 將宿主注入的 CyodaaPluginContext 透過 React Context 傳遞給\n * Plugin 元件樹，供各 hook 消費。\n */\n\nimport { createContext, useContext, createElement } from 'react';\nimport type { ReactNode } from 'react';\nimport type { CyodaaPluginContext } from './types';\n\n// ============================================================\n// Context\n// ============================================================\n\n/** SDK 內部用 Context — 不直接對外導出 */\nconst CyodaaSDKContext = createContext<CyodaaPluginContext | null>(null);\n\nCyodaaSDKContext.displayName = 'CyodaaSDKContext';\n\n// ============================================================\n// Provider\n// ============================================================\n\ninterface ProviderProps {\n  readonly value: CyodaaPluginContext;\n  readonly children: ReactNode;\n}\n\n/** 將平台 Context 注入 React 元件樹 */\nexport function CyodaaSDKProvider({ value, children }: ProviderProps) {\n  return createElement(CyodaaSDKContext.Provider, { value }, children);\n}\n\n// ============================================================\n// 內部 Hook\n// ============================================================\n\n/**\n * 內部 hook：讀取原始 CyodaaPluginContext。\n * 僅供 SDK 內部 hook 使用，不對外導出。\n *\n * @throws {Error} 若在 CyodaaSDKProvider 外使用\n */\nexport function useSDKContext(): CyodaaPluginContext {\n  const ctx = useContext(CyodaaSDKContext);\n\n  if (ctx === null) {\n    throw new Error(\n      '[plugin-sdk] useSDKContext 必須在 CyodaaSDKProvider 內使用。' +\n      '請確認 Plugin 已透過 registerPlugin() 正確註冊。'\n    );\n  }\n\n  return ctx;\n}\n","/**\n * usePluginAPI — Plugin HTTP 通訊 hook\n *\n * 提供 RPC 呼叫與通用 HTTP 方法，\n * 全部使用相對 URL（same-origin）。\n */\n\nimport { useCallback, useMemo } from 'react';\n\n// ============================================================\n// 型別\n// ============================================================\n\n/** RPC 呼叫的請求格式 */\ninterface RPCPayload {\n  readonly service: string;\n  readonly method: string;\n  readonly params?: Record<string, unknown>;\n}\n\n/** API hook 回傳介面 */\ninterface PluginAPI {\n  /** 呼叫後端 RPC 端點 */\n  readonly call: <T = unknown>(\n    service: string,\n    method: string,\n    params?: Record<string, unknown>,\n  ) => Promise<T>;\n\n  /** GET 請求 */\n  readonly get: <T = unknown>(path: string) => Promise<T>;\n\n  /** POST 請求 */\n  readonly post: <T = unknown>(\n    path: string,\n    body?: unknown,\n  ) => Promise<T>;\n}\n\n// ============================================================\n// 內部工具\n// ============================================================\n\n/** 統一 fetch 錯誤處理 */\nasync function handleResponse<T>(response: Response): Promise<T> {\n  if (!response.ok) {\n    const text = await response.text().catch(() => '');\n    throw new Error(\n      `[plugin-sdk] API 請求失敗：${response.status} ${response.statusText}` +\n      (text ? ` — ${text}` : ''),\n    );\n  }\n\n  return response.json() as Promise<T>;\n}\n\n/** 取得通用 headers */\nfunction getHeaders(): HeadersInit {\n  return {\n    'Content-Type': 'application/json',\n    'Accept': 'application/json',\n  };\n}\n\n// ============================================================\n// Hook\n// ============================================================\n\n/**\n * 取得 Plugin API 呼叫工具。\n *\n * @example\n * ```tsx\n * import { usePluginAPI } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const api = usePluginAPI();\n *\n *   const handleClick = async () => {\n *     const result = await api.call('kpi', 'getSummary', { period: '2026-Q1' });\n *   };\n * }\n * ```\n */\nexport function usePluginAPI(): PluginAPI {\n  /** RPC 呼叫：POST /api/v1/plugins/rpc */\n  const call = useCallback(async <T = unknown>(\n    service: string,\n    method: string,\n    params?: Record<string, unknown>,\n  ): Promise<T> => {\n    const payload: RPCPayload = { service, method, params };\n\n    const response = await fetch('/api/v1/plugins/rpc', {\n      method: 'POST',\n      headers: getHeaders(),\n      body: JSON.stringify(payload),\n    });\n\n    return handleResponse<T>(response);\n  }, []);\n\n  /** GET 請求 */\n  const get = useCallback(async <T = unknown>(path: string): Promise<T> => {\n    const response = await fetch(path, {\n      method: 'GET',\n      headers: getHeaders(),\n    });\n\n    return handleResponse<T>(response);\n  }, []);\n\n  /** POST 請求 */\n  const post = useCallback(async <T = unknown>(\n    path: string,\n    body?: unknown,\n  ): Promise<T> => {\n    const response = await fetch(path, {\n      method: 'POST',\n      headers: getHeaders(),\n      body: body !== undefined ? JSON.stringify(body) : undefined,\n    });\n\n    return handleResponse<T>(response);\n  }, []);\n\n  return useMemo<PluginAPI>(() => ({ call, get, post }), [call, get, post]);\n}\n","/**\n * usePluginEvents — Plugin 事件通訊 hook\n *\n * 透過 window 上的 CustomEvent 實現\n * Plugin 與宿主平台之間的事件訂閱/發布。\n *\n * 事件名稱統一加上 `cyodaa:` 前綴避免衝突。\n */\n\nimport { useCallback, useMemo } from 'react';\n\n// ============================================================\n// 型別\n// ============================================================\n\n/** 事件處理器 */\ntype EventHandler<T = unknown> = (data: T) => void;\n\n/** 取消訂閱函式 */\ntype Unsubscribe = () => void;\n\n/** 事件 hook 回傳介面 */\ninterface PluginEvents {\n  /** 訂閱事件，回傳取消訂閱函式 */\n  readonly on: <T = unknown>(event: string, handler: EventHandler<T>) => Unsubscribe;\n\n  /** 發送事件 */\n  readonly emit: (event: string, data?: unknown) => void;\n}\n\n// ============================================================\n// 內部工具\n// ============================================================\n\n/** 產生帶前綴的事件名稱 */\nfunction prefixedEventName(event: string): string {\n  return `cyodaa:${event}`;\n}\n\n// ============================================================\n// Hook\n// ============================================================\n\n/**\n * 取得 Plugin 事件通訊工具。\n *\n * @example\n * ```tsx\n * import { usePluginEvents } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const events = usePluginEvents();\n *\n *   useEffect(() => {\n *     const unsub = events.on('theme:changed', (data) => {\n *       // 處理主題切換\n *     });\n *     return unsub;\n *   }, [events]);\n *\n *   const handleNotify = () => {\n *     events.emit('plugin:action', { type: 'refresh' });\n *   };\n * }\n * ```\n */\nexport function usePluginEvents(): PluginEvents {\n  /** 訂閱事件 */\n  const on = useCallback(<T = unknown>(\n    event: string,\n    handler: EventHandler<T>,\n  ): Unsubscribe => {\n    const eventName = prefixedEventName(event);\n\n    const listener = (e: Event) => {\n      const customEvent = e as CustomEvent<T>;\n      handler(customEvent.detail);\n    };\n\n    window.addEventListener(eventName, listener);\n\n    // 回傳取消訂閱函式\n    return () => {\n      window.removeEventListener(eventName, listener);\n    };\n  }, []);\n\n  /** 發送事件 */\n  const emit = useCallback((event: string, data?: unknown): void => {\n    const eventName = prefixedEventName(event);\n\n    const customEvent = new CustomEvent(eventName, {\n      detail: data,\n      bubbles: false,\n      cancelable: false,\n    });\n\n    window.dispatchEvent(customEvent);\n  }, []);\n\n  return useMemo<PluginEvents>(() => ({ on, emit }), [on, emit]);\n}\n","/**\n * usePluginStorage — Plugin 本地儲存 hook\n *\n * 基於 localStorage，以 `plugin:{pluginId}:` 為前綴隔離各 Plugin 資料。\n * pluginId 透過 SDK Context 內的 tenantId 命名空間進一步隔離。\n */\n\nimport { useCallback, useMemo } from 'react';\n\n// ============================================================\n// 型別\n// ============================================================\n\n/** 儲存 hook 回傳介面 */\ninterface PluginStorage {\n  /** 讀取值（JSON 反序列化） */\n  readonly get: <T = unknown>(key: string) => T | null;\n\n  /** 寫入值（JSON 序列化） */\n  readonly set: (key: string, value: unknown) => void;\n\n  /** 刪除指定 key */\n  readonly delete: (key: string) => void;\n\n  /** 列出此 Plugin 所有 key（不含前綴） */\n  readonly keys: () => readonly string[];\n\n  /** 清除此 Plugin 所有資料 */\n  readonly clear: () => void;\n}\n\n// ============================================================\n// Hook\n// ============================================================\n\n/**\n * 取得隔離的 Plugin 本地儲存工具。\n *\n * @param pluginId — Plugin 唯一識別碼\n *\n * @example\n * ```tsx\n * import { usePluginStorage } from '@cyodaa/plugin-sdk/react';\n *\n * function MyComponent() {\n *   const storage = usePluginStorage('my-plugin');\n *\n *   // 讀取\n *   const settings = storage.get<{ darkMode: boolean }>('settings');\n *\n *   // 寫入\n *   storage.set('settings', { darkMode: true });\n *\n *   // 列出所有 key\n *   const allKeys = storage.keys();\n * }\n * ```\n */\nexport function usePluginStorage(pluginId: string): PluginStorage {\n  /** 產生帶前綴的完整 key */\n  const fullKey = useCallback(\n    (key: string): string => `plugin:${pluginId}:${key}`,\n    [pluginId],\n  );\n\n  /** 前綴字串（用於 keys/clear） */\n  const prefix = useMemo(() => `plugin:${pluginId}:`, [pluginId]);\n\n  /** 讀取值 */\n  const get = useCallback(<T = unknown>(key: string): T | null => {\n    try {\n      const raw = localStorage.getItem(fullKey(key));\n      if (raw === null) return null;\n      return JSON.parse(raw) as T;\n    } catch {\n      return null;\n    }\n  }, [fullKey]);\n\n  /** 寫入值 */\n  const set = useCallback((key: string, value: unknown): void => {\n    try {\n      const serialized = JSON.stringify(value);\n      localStorage.setItem(fullKey(key), serialized);\n    } catch {\n      // localStorage 空間不足時靜默失敗\n    }\n  }, [fullKey]);\n\n  /** 刪除指定 key */\n  const deleteKey = useCallback((key: string): void => {\n    localStorage.removeItem(fullKey(key));\n  }, [fullKey]);\n\n  /** 列出所有屬於此 Plugin 的 key */\n  const keys = useCallback((): readonly string[] => {\n    const result: string[] = [];\n    const len = localStorage.length;\n\n    for (let i = 0; i < len; i++) {\n      const k = localStorage.key(i);\n      if (k !== null && k.startsWith(prefix)) {\n        result.push(k.slice(prefix.length));\n      }\n    }\n\n    return result;\n  }, [prefix]);\n\n  /** 清除此 Plugin 所有資料 */\n  const clear = useCallback((): void => {\n    // 先收集所有匹配 key，再批次刪除（避免遍歷時修改集合）\n    const keysToRemove: string[] = [];\n    const len = localStorage.length;\n\n    for (let i = 0; i < len; i++) {\n      const k = localStorage.key(i);\n      if (k !== null && k.startsWith(prefix)) {\n        keysToRemove.push(k);\n      }\n    }\n\n    for (const k of keysToRemove) {\n      localStorage.removeItem(k);\n    }\n  }, [prefix]);\n\n  return useMemo<PluginStorage>(\n    () => ({ get, set, delete: deleteKey, keys, clear }),\n    [get, set, deleteKey, keys, clear],\n  );\n}\n"],"mappings":"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","names":["useMemo","useCallback","useMemo","useCallback","useMemo"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@cyodaa/plugin-sdk",
+  "version": "0.1.0",
+  "description": "Cyodaa Plugin SDK - 在 Cyodaa 平台上開發插件的官方 SDK",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.mjs",
+      "require": "./dist/react/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "cyodaa",
+    "plugin",
+    "sdk",
+    "marketplace"
+  ],
+  "author": {
+    "name": "Cyodaa Team",
+    "email": "dev@cyodaa.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyodaa/plugin-sdk.git"
+  },
+  "homepage": "https://cyodaa.com/docs/sdk"
+}