@jenil94/plugin-sdk 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @jenil94/plugin-sdk
+
+SDK for building Harness plugins with React. Provides communication utilities, context management, and routing synchronization for plugins running in iframes.
+
+## Installation
+
+```bash
+npm install @jenil94/plugin-sdk
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+- `react` (^18.0.0 || ^19.0.0)
+- `react-dom` (^18.0.0 || ^19.0.0)
+- `react-router-dom` (^6.0.0 || ^7.0.0)
+
+## Usage
+
+### Basic Setup
+
+```tsx
+import { PluginAPI, PluginContextProvider, PluginRouter } from '@jenil94/plugin-sdk'
+
+// Initialize the plugin as early as possible
+PluginAPI.init()
+
+function App() {
+  return (
+    <PluginContextProvider>
+      <PluginRouter>
+        {/* Your app routes here */}
+      </PluginRouter>
+    </PluginContextProvider>
+  )
+}
+```
+
+### Using Plugin Context
+
+```tsx
+import { usePluginContext } from '@jenil94/plugin-sdk'
+
+function MyComponent() {
+  const context = usePluginContext()
+
+  if (!context) {
+    return <div>Loading...</div>
+  }
+
+  return (
+    <div>
+      <p>Theme: {context.theme}</p>
+      <p>Location: {context.location}</p>
+    </div>
+  )
+}
+```
+
+### Proxy Fetch (for authenticated API calls)
+
+```tsx
+import { PluginAPI } from '@jenil94/plugin-sdk'
+
+async function fetchData() {
+  const response = await PluginAPI.proxyFetch('/api/some-endpoint')
+  const data = await response.json()
+  return data
+}
+```
+
+## API Reference
+
+### PluginAPI
+
+Static class for communication with the host application.
+
+- `PluginAPI.init()` - Signals to the host that the plugin is ready
+- `PluginAPI.getContext()` - Retrieves the current plugin context
+- `PluginAPI.proxyFetch(url, init?)` - Proxies fetch requests through the host
+
+### PluginContextProvider
+
+React context provider that manages plugin context state.
+
+### usePluginContext()
+
+Hook to access the current plugin context.
+
+### PluginRouter
+
+Router component that synchronizes with the parent page's URL.
+
+### useParentRoutingSync()
+
+Hook for manual route synchronization with the parent page.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT
+

package/dist/index.cjs

@@ -0,0 +1,227 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PluginAPI: () => PluginAPI,
+  PluginContextProvider: () => PluginContextProvider,
+  PluginMessageType: () => PluginMessageType,
+  PluginRouter: () => PluginRouter,
+  useParentRoutingSync: () => useParentRoutingSync,
+  usePluginContext: () => usePluginContext
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/plugin-api.ts
+var PluginMessageType = {
+  Init: "init",
+  Context: "context",
+  GetContext: "getContext",
+  Fetch: "fetch",
+  FetchResponse: "fetchResponse"
+};
+var PluginAPI = class {
+  /**
+   * Signals to the host that the plugin is ready
+   * This should be called as early as possible in the plugin lifecycle
+   */
+  static async init() {
+    window.parent.postMessage({ type: PluginMessageType.Init }, "*");
+  }
+  /**
+   * Retrieves the current plugin context from the host
+   * Includes entity data, user info, theme settings, and API base URL
+   */
+  static async getContext() {
+    return new Promise((resolve) => {
+      const handler = (event) => {
+        if (event.data.type === PluginMessageType.Context) {
+          window.removeEventListener("message", handler);
+          resolve(event.data.data);
+        }
+      };
+      window.addEventListener("message", handler);
+      window.parent.postMessage({ type: PluginMessageType.GetContext }, "*");
+    });
+  }
+  /**
+   * Proxies a fetch request through the host application
+   * This allows the host to handle authentication and CORS
+   */
+  static async proxyFetch(url, init) {
+    return new Promise((resolve) => {
+      const handler = (event) => {
+        const response = event.data?.response;
+        if (response) {
+          window.removeEventListener("message", handler);
+          console.log("proxyFetch response from host:", event.data);
+          let body = response.body;
+          if (body !== null && typeof body === "object") {
+            body = JSON.stringify(body);
+          }
+          resolve(
+            new Response(body, {
+              status: response.status ?? 200,
+              statusText: response.statusText ?? "",
+              headers: response.headers
+            })
+          );
+        }
+      };
+      window.addEventListener("message", handler);
+      window.parent.postMessage(
+        {
+          type: PluginMessageType.Fetch,
+          url,
+          init
+        },
+        "*"
+      );
+    });
+  }
+};
+
+// src/plugin-context.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var PluginDataContext = (0, import_react.createContext)(null);
+function PluginContextProvider({ children }) {
+  const [context, setContext] = (0, import_react.useState)(null);
+  (0, import_react.useEffect)(() => {
+    const handler = (event) => {
+      if (event.data?.type === "context") {
+        console.log("Received context from host:", event.data.data);
+        setContext(event.data.data);
+      }
+    };
+    window.addEventListener("message", handler);
+    return () => window.removeEventListener("message", handler);
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PluginDataContext.Provider, { value: context, children });
+}
+function usePluginContext() {
+  const context = (0, import_react.useContext)(PluginDataContext);
+  return context;
+}
+
+// src/plugin-router.tsx
+var import_react2 = require("react");
+var import_react_router_dom = require("react-router-dom");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var toCamelCase = (str) => {
+  return str.split("-").filter((segment) => segment.length > 0).map(
+    (word, index) => index === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+  ).join("");
+};
+var useParentRoutingSync = () => {
+  const context = usePluginContext();
+  const tag = context?.tag;
+  const queryParamKey = (0, import_react2.useMemo)(() => {
+    return tag ? toCamelCase(tag) + "PluginRoute" : "pluginRoute";
+  }, [tag]);
+  const location = (0, import_react_router_dom.useLocation)();
+  const navigate = (0, import_react_router_dom.useNavigate)();
+  (0, import_react2.useEffect)(() => {
+    const newRoute = `${location.pathname}${location.search}${location.hash}`;
+    console.log("Syncing route to parent:", newRoute);
+    window.parent.postMessage(
+      {
+        type: "routeChange",
+        route: newRoute,
+        queryParamKey
+      },
+      "*"
+    );
+  }, [location, queryParamKey]);
+  (0, import_react2.useEffect)(() => {
+    const handleMessage = (event) => {
+      if (event.data?.type === "navigateTo" && event.data.route) {
+        console.log("Received navigation command from parent:", event.data.route);
+        navigate(event.data.route);
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  }, [navigate]);
+};
+var ParentRouterSync = () => {
+  useParentRoutingSync();
+  return null;
+};
+var PluginRouter = ({ children, initialEntries }) => {
+  const context = usePluginContext();
+  const tag = context?.tag;
+  const [initialRoute, setInitialRoute] = (0, import_react2.useState)(null);
+  const [isReady, setIsReady] = (0, import_react2.useState)(false);
+  (0, import_react2.useEffect)(() => {
+    const queryParamKey = tag ? toCamelCase(tag) + "PluginRoute" : "pluginRoute";
+    const handleMessage = (event) => {
+      if (event.data?.type === "initialRoute") {
+        console.log("Received initial route from parent:", event.data.route);
+        setInitialRoute(event.data.route || "/");
+        setIsReady(true);
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    window.parent.postMessage(
+      {
+        type: "getInitialRoute",
+        queryParamKey
+      },
+      "*"
+    );
+    const timeout = setTimeout(() => {
+      if (!isReady) {
+        console.log("No initial route from parent, using default");
+        setInitialRoute("/");
+        setIsReady(true);
+      }
+    }, 300);
+    return () => {
+      window.removeEventListener("message", handleMessage);
+      clearTimeout(timeout);
+    };
+  }, [tag, isReady]);
+  const defaultInitialEntries = (0, import_react2.useMemo)(() => {
+    if (initialRoute) {
+      return [initialRoute.startsWith("/") ? initialRoute : "/" + initialRoute];
+    }
+    if (initialEntries && initialEntries.length > 0) {
+      return initialEntries;
+    }
+    return ["/"];
+  }, [initialEntries, initialRoute]);
+  if (!isReady) {
+    return null;
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_react_router_dom.MemoryRouter, { initialEntries: defaultInitialEntries, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ParentRouterSync, {}),
+    children
+  ] });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PluginAPI,
+  PluginContextProvider,
+  PluginMessageType,
+  PluginRouter,
+  useParentRoutingSync,
+  usePluginContext
+});

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { ReactNode } from 'react';
+
+/**
+ * Plugin API for communication with the host application
+ * Based on the Cortex plugin architecture pattern
+ */
+interface PluginContext {
+    apiBaseUrl: string;
+    entity: unknown | null;
+    location: 'ENTITY' | 'GLOBAL';
+    tag: string | null;
+    user: unknown;
+    style: Record<string, string>;
+    theme: 'light' | 'dark';
+}
+declare const PluginMessageType: {
+    readonly Init: "init";
+    readonly Context: "context";
+    readonly GetContext: "getContext";
+    readonly Fetch: "fetch";
+    readonly FetchResponse: "fetchResponse";
+};
+declare class PluginAPI {
+    /**
+     * Signals to the host that the plugin is ready
+     * This should be called as early as possible in the plugin lifecycle
+     */
+    static init(): Promise<void>;
+    /**
+     * Retrieves the current plugin context from the host
+     * Includes entity data, user info, theme settings, and API base URL
+     */
+    static getContext(): Promise<PluginContext>;
+    /**
+     * Proxies a fetch request through the host application
+     * This allows the host to handle authentication and CORS
+     */
+    static proxyFetch(url: string, init?: RequestInit): Promise<Response>;
+}
+
+declare function PluginContextProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function usePluginContext(): PluginContext | null;
+
+/**
+ * Custom hook that synchronizes the in-app route with the parent page's URL via postMessage.
+ */
+declare const useParentRoutingSync: () => void;
+interface PluginRouterProps {
+    children: ReactNode;
+    initialEntries?: string[];
+}
+/**
+ * PluginRouter wraps your app's routing logic and sets the initial route
+ * based on the parent page's URL if no initial route is provided.
+ */
+declare const PluginRouter: React$1.FC<PluginRouterProps>;
+
+export { PluginAPI, type PluginContext, PluginContextProvider, PluginMessageType, PluginRouter, useParentRoutingSync, usePluginContext };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { ReactNode } from 'react';
+
+/**
+ * Plugin API for communication with the host application
+ * Based on the Cortex plugin architecture pattern
+ */
+interface PluginContext {
+    apiBaseUrl: string;
+    entity: unknown | null;
+    location: 'ENTITY' | 'GLOBAL';
+    tag: string | null;
+    user: unknown;
+    style: Record<string, string>;
+    theme: 'light' | 'dark';
+}
+declare const PluginMessageType: {
+    readonly Init: "init";
+    readonly Context: "context";
+    readonly GetContext: "getContext";
+    readonly Fetch: "fetch";
+    readonly FetchResponse: "fetchResponse";
+};
+declare class PluginAPI {
+    /**
+     * Signals to the host that the plugin is ready
+     * This should be called as early as possible in the plugin lifecycle
+     */
+    static init(): Promise<void>;
+    /**
+     * Retrieves the current plugin context from the host
+     * Includes entity data, user info, theme settings, and API base URL
+     */
+    static getContext(): Promise<PluginContext>;
+    /**
+     * Proxies a fetch request through the host application
+     * This allows the host to handle authentication and CORS
+     */
+    static proxyFetch(url: string, init?: RequestInit): Promise<Response>;
+}
+
+declare function PluginContextProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function usePluginContext(): PluginContext | null;
+
+/**
+ * Custom hook that synchronizes the in-app route with the parent page's URL via postMessage.
+ */
+declare const useParentRoutingSync: () => void;
+interface PluginRouterProps {
+    children: ReactNode;
+    initialEntries?: string[];
+}
+/**
+ * PluginRouter wraps your app's routing logic and sets the initial route
+ * based on the parent page's URL if no initial route is provided.
+ */
+declare const PluginRouter: React$1.FC<PluginRouterProps>;
+
+export { PluginAPI, type PluginContext, PluginContextProvider, PluginMessageType, PluginRouter, useParentRoutingSync, usePluginContext };

package/dist/index.js

@@ -0,0 +1,195 @@
+// src/plugin-api.ts
+var PluginMessageType = {
+  Init: "init",
+  Context: "context",
+  GetContext: "getContext",
+  Fetch: "fetch",
+  FetchResponse: "fetchResponse"
+};
+var PluginAPI = class {
+  /**
+   * Signals to the host that the plugin is ready
+   * This should be called as early as possible in the plugin lifecycle
+   */
+  static async init() {
+    window.parent.postMessage({ type: PluginMessageType.Init }, "*");
+  }
+  /**
+   * Retrieves the current plugin context from the host
+   * Includes entity data, user info, theme settings, and API base URL
+   */
+  static async getContext() {
+    return new Promise((resolve) => {
+      const handler = (event) => {
+        if (event.data.type === PluginMessageType.Context) {
+          window.removeEventListener("message", handler);
+          resolve(event.data.data);
+        }
+      };
+      window.addEventListener("message", handler);
+      window.parent.postMessage({ type: PluginMessageType.GetContext }, "*");
+    });
+  }
+  /**
+   * Proxies a fetch request through the host application
+   * This allows the host to handle authentication and CORS
+   */
+  static async proxyFetch(url, init) {
+    return new Promise((resolve) => {
+      const handler = (event) => {
+        const response = event.data?.response;
+        if (response) {
+          window.removeEventListener("message", handler);
+          console.log("proxyFetch response from host:", event.data);
+          let body = response.body;
+          if (body !== null && typeof body === "object") {
+            body = JSON.stringify(body);
+          }
+          resolve(
+            new Response(body, {
+              status: response.status ?? 200,
+              statusText: response.statusText ?? "",
+              headers: response.headers
+            })
+          );
+        }
+      };
+      window.addEventListener("message", handler);
+      window.parent.postMessage(
+        {
+          type: PluginMessageType.Fetch,
+          url,
+          init
+        },
+        "*"
+      );
+    });
+  }
+};
+
+// src/plugin-context.tsx
+import { createContext, useContext, useState, useEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+var PluginDataContext = createContext(null);
+function PluginContextProvider({ children }) {
+  const [context, setContext] = useState(null);
+  useEffect(() => {
+    const handler = (event) => {
+      if (event.data?.type === "context") {
+        console.log("Received context from host:", event.data.data);
+        setContext(event.data.data);
+      }
+    };
+    window.addEventListener("message", handler);
+    return () => window.removeEventListener("message", handler);
+  }, []);
+  return /* @__PURE__ */ jsx(PluginDataContext.Provider, { value: context, children });
+}
+function usePluginContext() {
+  const context = useContext(PluginDataContext);
+  return context;
+}
+
+// src/plugin-router.tsx
+import { useEffect as useEffect2, useMemo, useState as useState2 } from "react";
+import { MemoryRouter, useLocation, useNavigate } from "react-router-dom";
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+var toCamelCase = (str) => {
+  return str.split("-").filter((segment) => segment.length > 0).map(
+    (word, index) => index === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+  ).join("");
+};
+var useParentRoutingSync = () => {
+  const context = usePluginContext();
+  const tag = context?.tag;
+  const queryParamKey = useMemo(() => {
+    return tag ? toCamelCase(tag) + "PluginRoute" : "pluginRoute";
+  }, [tag]);
+  const location = useLocation();
+  const navigate = useNavigate();
+  useEffect2(() => {
+    const newRoute = `${location.pathname}${location.search}${location.hash}`;
+    console.log("Syncing route to parent:", newRoute);
+    window.parent.postMessage(
+      {
+        type: "routeChange",
+        route: newRoute,
+        queryParamKey
+      },
+      "*"
+    );
+  }, [location, queryParamKey]);
+  useEffect2(() => {
+    const handleMessage = (event) => {
+      if (event.data?.type === "navigateTo" && event.data.route) {
+        console.log("Received navigation command from parent:", event.data.route);
+        navigate(event.data.route);
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  }, [navigate]);
+};
+var ParentRouterSync = () => {
+  useParentRoutingSync();
+  return null;
+};
+var PluginRouter = ({ children, initialEntries }) => {
+  const context = usePluginContext();
+  const tag = context?.tag;
+  const [initialRoute, setInitialRoute] = useState2(null);
+  const [isReady, setIsReady] = useState2(false);
+  useEffect2(() => {
+    const queryParamKey = tag ? toCamelCase(tag) + "PluginRoute" : "pluginRoute";
+    const handleMessage = (event) => {
+      if (event.data?.type === "initialRoute") {
+        console.log("Received initial route from parent:", event.data.route);
+        setInitialRoute(event.data.route || "/");
+        setIsReady(true);
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    window.parent.postMessage(
+      {
+        type: "getInitialRoute",
+        queryParamKey
+      },
+      "*"
+    );
+    const timeout = setTimeout(() => {
+      if (!isReady) {
+        console.log("No initial route from parent, using default");
+        setInitialRoute("/");
+        setIsReady(true);
+      }
+    }, 300);
+    return () => {
+      window.removeEventListener("message", handleMessage);
+      clearTimeout(timeout);
+    };
+  }, [tag, isReady]);
+  const defaultInitialEntries = useMemo(() => {
+    if (initialRoute) {
+      return [initialRoute.startsWith("/") ? initialRoute : "/" + initialRoute];
+    }
+    if (initialEntries && initialEntries.length > 0) {
+      return initialEntries;
+    }
+    return ["/"];
+  }, [initialEntries, initialRoute]);
+  if (!isReady) {
+    return null;
+  }
+  return /* @__PURE__ */ jsxs(MemoryRouter, { initialEntries: defaultInitialEntries, children: [
+    /* @__PURE__ */ jsx2(ParentRouterSync, {}),
+    children
+  ] });
+};
+export {
+  PluginAPI,
+  PluginContextProvider,
+  PluginMessageType,
+  PluginRouter,
+  useParentRoutingSync,
+  usePluginContext
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jenil94/plugin-sdk",
+  "version": "0.1.0",
+  "description": "SDK for building Harness plugins with React",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.13.0",
+    "tsup": "^8.0.0",
+    "typescript": "~5.9.3"
+  },
+  "keywords": [
+    "harness",
+    "plugin",
+    "sdk",
+    "react"
+  ],
+  "license": "MIT"
+}
+