@struxa/extension-sdk 1.0.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@struxa/extension-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "SDK for building Struxa extensions: manifest types, server entry helpers, the iframe host bridge, a preconfigured oRPC client, and React hooks.",
+  "license": "MIT",
+  "files": ["src", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server.ts",
+      "default": "./src/server.ts"
+    },
+    "./client": {
+      "types": "./src/client.ts",
+      "default": "./src/client.ts"
+    },
+    "./react": {
+      "types": "./src/react.tsx",
+      "default": "./src/react.tsx"
+    }
+  },
+  "dependencies": {
+    "@orpc/client": "^1.13.14",
+    "@orpc/server": "^1.13.14",
+    "drizzle-orm": "^0.45.1",
+    "zod": "^4.1.13"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@struxa/config": "workspace:*",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "^6"
+  }
+}

package/src/client.ts

@@ -0,0 +1,157 @@
+/**
+ * Browser-side iframe bridge. Runs inside an extension's web bundle (the iframe)
+ * and talks to the Struxa host shell over `postMessage`. Keeps extension UIs
+ * visually and behaviorally consistent with the host despite iframe isolation.
+ *
+ * The host injects the initial context (theme, locale, session summary) in the
+ * handshake; the extension can request height changes, navigate the host, and
+ * raise host toasts. For data, use {@link createHostClient} (or call `/api/rpc`
+ * directly with `credentials: "include"`) — the host session cookie authenticates
+ * you, no token plumbing needed.
+ */
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+
+/**
+ * Preconfigured oRPC client for the host API. Same-origin, cookie-authed. Call
+ * your extension's procedures under `client.ext["<your-id>"].*` (and core
+ * procedures too, if you need them).
+ *
+ * @example
+ * const client = createHostClient();
+ * const res = await client.ext["react-demo"].ping();
+ */
+export function createHostClient<TClient = Record<string, unknown>>(): TClient {
+  const origin = typeof location !== "undefined" ? location.origin : "";
+  const link = new RPCLink({
+    url: `${origin}/api/rpc`,
+    fetch: (url, options) => fetch(url, { ...options, credentials: "include" }),
+  });
+  return createORPCClient(link) as TClient;
+}
+
+export interface HostTheme {
+  /** "light" | "dark". */
+  mode: string;
+  /** CSS custom properties to mirror (e.g. --primary, --background). */
+  tokens: Record<string, string>;
+}
+
+export interface HostSessionSummary {
+  userId: string | null;
+  role: string | null;
+  locale: string;
+}
+
+export interface HostContext {
+  extId: string;
+  theme: HostTheme;
+  session: HostSessionSummary;
+  /** Route context the iframe was opened with (e.g. { serverId }). */
+  params: Record<string, string>;
+}
+
+type HostInbound =
+  | { type: "struxa:host:init"; context: HostContext }
+  | { type: "struxa:host:theme"; theme: HostTheme };
+
+type IframeOutbound =
+  | { type: "struxa:iframe:ready" }
+  | { type: "struxa:iframe:height"; height: number }
+  | { type: "struxa:iframe:navigate"; route: string }
+  | {
+      type: "struxa:iframe:toast";
+      level: "success" | "error" | "info";
+      message: string;
+    };
+
+const HOST_ORIGIN =
+  typeof location !== "undefined" ? location.origin : "*";
+
+function post(msg: IframeOutbound): void {
+  if (typeof window !== "undefined" && window.parent) {
+    window.parent.postMessage(msg, HOST_ORIGIN);
+  }
+}
+
+export interface BridgeOptions {
+  /** Called once the host sends its init context. */
+  onInit?: (ctx: HostContext) => void;
+  /** Called whenever the host theme changes (e.g. user toggles dark mode). */
+  onThemeChange?: (theme: HostTheme) => void;
+  /** Auto-report document height to the host so the iframe resizes. */
+  autoResize?: boolean;
+}
+
+export interface Bridge {
+  context: HostContext | null;
+  navigate(route: string): void;
+  toast(level: "success" | "error" | "info", message: string): void;
+  reportHeight(height?: number): void;
+  destroy(): void;
+}
+
+function applyTheme(theme: HostTheme): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  root.dataset.theme = theme.mode;
+  for (const [name, value] of Object.entries(theme.tokens)) {
+    root.style.setProperty(name, value);
+  }
+}
+
+/**
+ * Initialize the bridge. Call once on iframe boot.
+ */
+export function createBridge(options: BridgeOptions = {}): Bridge {
+  const bridge: Bridge = {
+    context: null,
+    navigate: (route) => post({ type: "struxa:iframe:navigate", route }),
+    toast: (level, message) =>
+      post({ type: "struxa:iframe:toast", level, message }),
+    reportHeight: (height) =>
+      post({
+        type: "struxa:iframe:height",
+        height:
+          height ??
+          (typeof document !== "undefined"
+            ? document.documentElement.scrollHeight
+            : 0),
+      }),
+    destroy: () => {
+      if (typeof window !== "undefined") {
+        window.removeEventListener("message", onMessage);
+      }
+      resizeObserver?.disconnect();
+    },
+  };
+
+  function onMessage(event: MessageEvent<HostInbound>) {
+    if (event.origin !== HOST_ORIGIN) return;
+    const data = event.data;
+    if (!data || typeof data !== "object") return;
+    if (data.type === "struxa:host:init") {
+      bridge.context = data.context;
+      applyTheme(data.context.theme);
+      options.onInit?.(data.context);
+    } else if (data.type === "struxa:host:theme") {
+      if (bridge.context) bridge.context.theme = data.theme;
+      applyTheme(data.theme);
+      options.onThemeChange?.(data.theme);
+    }
+  }
+
+  let resizeObserver: ResizeObserver | undefined;
+
+  if (typeof window !== "undefined") {
+    window.addEventListener("message", onMessage);
+    post({ type: "struxa:iframe:ready" });
+
+    if (options.autoResize && typeof ResizeObserver !== "undefined") {
+      resizeObserver = new ResizeObserver(() => bridge.reportHeight());
+      resizeObserver.observe(document.documentElement);
+    }
+  }
+
+  return bridge;
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+
+/**
+ * @struxa/extension-sdk
+ *
+ * The contract that extension authors build against. Pure types + zod schemas,
+ * no runtime dependency on the host. The host (`@struxa/extension-host`) imports
+ * these to validate manifests and to type the scoped context it hands to
+ * extensions.
+ */
+
+/** Core entities that expose a `metadata` JSON column extensions may write. */
+export const CORE_META_ENTITIES = ["server", "node", "user"] as const;
+export type CoreMetaEntity = (typeof CORE_META_ENTITIES)[number];
+
+/** Canonical lifecycle events extensions can subscribe to via `hook:<event>`. */
+export const HOOK_EVENTS = [
+  "server.created",
+  "server.updated",
+  "server.deleted",
+  "server.power",
+  "node.created",
+  "node.updated",
+  "node.deleted",
+  "user.created",
+  "user.updated",
+  "user.deleted",
+] as const;
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+
+/** Max oRPC procedure level an extension may expose. */
+export type ApiLevel = "public" | "protected" | "admin";
+
+/**
+ * Permission grammar. Validated loosely as strings (so the registry can carry
+ * forward-compatible perms) but documented here:
+ *   db:own                       create/use ext_<id>_* tables
+ *   core.metadata:<entity>       read/write the metadata JSON on a core entity
+ *   settings:<prefix>            get/set settings keys under <prefix>
+ *   hook:<event>                 subscribe to a lifecycle event
+ *   api:<level>                  expose procedures up to <level>
+ */
+const permissionSchema = z
+  .string()
+  .regex(
+    /^(db:own|core\.metadata:(server|node|user)|settings:[a-zA-Z0-9_.*-]+|hook:[a-zA-Z0-9_.*-]+|api:(public|protected|admin))$/,
+    "invalid permission",
+  );
+
+const navSection = z.enum(["panel", "admin"]);
+
+const uiPageSchema = z.object({
+  /**
+   * Host route the page is mounted at, e.g. "/foo". Panel pages appear at this
+   * path (`/foo`); admin pages appear under /admin (`/admin/foo`). It is matched
+   * against the live route — a path the core site already defines (e.g.
+   * /servers, /account) always wins, so an extension cannot shadow core routes.
+   */
+  route: z.string().regex(/^\/[a-z0-9-]+(\/[a-z0-9-]+)*$/),
+  /** Which sidebar/route-group the page lives under (controls auth gating). */
+  section: navSection,
+  /** i18n key (resolved under the ext.<id>.* namespace) for the nav label. */
+  label: z.string().min(1),
+  /** Allowlisted Lucide icon name. */
+  icon: z.string().min(1).optional(),
+  /** Path inside the extension web bundle to load; defaults to route tail. */
+  entry: z.string().optional(),
+});
+
+const uiSlotSchema = z.object({
+  /** Named anchor in a host page, e.g. "server.overview.after". */
+  slot: z.string().min(1),
+  /** Path inside the extension web bundle rendered into the slot iframe. */
+  widget: z.string().min(1),
+});
+
+export const manifestSchema = z.object({
+  id: z
+    .string()
+    .regex(/^[a-z][a-z0-9-]{1,62}$/, "id must be a lowercase slug"),
+  name: z.string().min(1).max(120),
+  version: z.string().min(1).max(32),
+  description: z.string().max(500).optional(),
+  author: z.string().max(120).optional(),
+  /** Host API semver range this extension was built against. */
+  struxaApi: z.string().min(1),
+  permissions: z.array(permissionSchema).default([]),
+  ui: z
+    .object({
+      pages: z.array(uiPageSchema).default([]),
+      slots: z.array(uiSlotSchema).default([]),
+    })
+    .optional(),
+  /** Map of locale -> relative path of a namespaced messages JSON file. */
+  messages: z.record(z.string(), z.string()).optional(),
+});
+
+export type Manifest = z.infer<typeof manifestSchema>;
+export type ManifestUiPage = z.infer<typeof uiPageSchema>;
+export type ManifestUiSlot = z.infer<typeof uiSlotSchema>;
+
+/** The current host API version. Extensions declare a range against this. */
+export const HOST_API_VERSION = "1.0.0";

package/src/react.tsx

@@ -0,0 +1,87 @@
+import { Component, useEffect, useRef, useState, type ErrorInfo, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { createBridge, type Bridge, type HostContext } from "./client";
+
+class ExtensionErrorBoundary extends Component<
+  { children: ReactNode },
+  { error: Error | null }
+> {
+  state: { error: Error | null } = { error: null };
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error("[struxa extension] render error", error, info);
+  }
+  render(): ReactNode {
+    if (this.state.error) {
+      return (
+        <div style={{ padding: 20, fontFamily: "monospace", fontSize: 13, color: "#f87171" }}>
+          <strong>Extension error</strong>
+          <pre style={{ marginTop: 8, whiteSpace: "pre-wrap" }}>
+            {this.state.error.message}
+          </pre>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * Bootstraps a React extension into #root. Wraps the element in an error
+ * boundary that displays errors visibly instead of leaving a blank page.
+ * Removes the #boot-status loading indicator on mount.
+ *
+ * @example
+ * // src/main.tsx
+ * import { createExtension } from "@struxa/extension-sdk/react";
+ * import { App } from "./App";
+ * createExtension(<App />);
+ */
+export function createExtension(element: ReactNode): void {
+  const root = document.getElementById("root");
+  if (!root) throw new Error("[struxa extension] #root element not found");
+  document.getElementById("boot-status")?.remove();
+  createRoot(root).render(<ExtensionErrorBoundary>{element}</ExtensionErrorBoundary>);
+}
+
+/**
+ * React adapter for the host iframe bridge. Mounts the bridge once, exposes the
+ * host context (theme/session/params) as state, and returns navigate/toast/
+ * resize helpers. Auto-resize is on by default.
+ *
+ * @example
+ * function App() {
+ *   const { context, toast } = useHostBridge();
+ *   return <button onClick={() => toast("success", "hi")}>{context?.session.userId}</button>;
+ * }
+ */
+export function useHostBridge(options: { autoResize?: boolean } = {}) {
+  const { autoResize = true } = options;
+  const [context, setContext] = useState<HostContext | null>(null);
+  const ref = useRef<Bridge | null>(null);
+
+  useEffect(() => {
+    const bridge = createBridge({
+      autoResize,
+      onInit: (ctx) => setContext(ctx),
+      onThemeChange: (theme) =>
+        setContext((c) => (c ? { ...c, theme } : c)),
+    });
+    ref.current = bridge;
+    return () => bridge.destroy();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return {
+    context,
+    navigate: (route: string) => ref.current?.navigate(route),
+    toast: (level: "success" | "error" | "info", message: string) =>
+      ref.current?.toast(level, message),
+    reportHeight: (height?: number) => ref.current?.reportHeight(height),
+  };
+}
+
+export type { HostContext } from "./client";

package/src/server.ts

@@ -0,0 +1,128 @@
+import type { AnyRouter } from "@orpc/server";
+import type { MySql2Database } from "drizzle-orm/mysql2";
+
+import type { CoreMetaEntity, HookEvent } from "./index";
+
+export type { HookEvent } from "./index";
+
+/**
+ * Server-side contract for an extension's `server/index.js`. The host loads the
+ * module, builds a capability-scoped {@link ExtensionContext} from the manifest's
+ * approved permissions, and calls `register(ctx)`. Everything the extension may
+ * touch in the host arrives through `ctx` — there is no other sanctioned import.
+ */
+
+/**
+ * oRPC builder type. Loosely typed: the concrete builder is bound to the host's
+ * private request Context, which the SDK can't reference without depending on
+ * the host. The host injects a real, fully-functional builder at register time;
+ * call `.handler(...)`, `.input(...)`, etc. as you would with `@orpc/server`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ProcedureBuilder = any;
+
+export interface ExtensionLogger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+}
+
+/**
+ * Read/write the namespaced slice of the `metadata` JSON column on a core
+ * entity. Reads/writes are confined to this extension's own key, so two
+ * extensions never clobber each other's fields. Granted by
+ * `core.metadata:<entity>`.
+ */
+export interface CoreMetaClient {
+  get(id: string): Promise<Record<string, unknown> | null>;
+  set(id: string, patch: Record<string, unknown>): Promise<void>;
+}
+
+/** Settings get/set scoped to the extension's approved key prefix(es). */
+export interface ScopedSettings {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  all(): Promise<Record<string, string>>;
+}
+
+/** Payload shape per event. Kept permissive; refine as the surface stabilizes. */
+export interface HookPayloads {
+  "server.created": { serverId: string; userId: string | null };
+  "server.updated": { serverId: string; userId: string | null };
+  "server.deleted": { serverId: string; userId: string | null };
+  "server.power": { serverId: string; action: string };
+  "node.created": { nodeId: string };
+  "node.updated": { nodeId: string };
+  "node.deleted": { nodeId: string };
+  "user.created": { userId: string };
+  "user.updated": { userId: string };
+  "user.deleted": { userId: string };
+}
+
+export interface HookApi {
+  on<E extends HookEvent>(
+    event: E,
+    handler: (
+      payload: E extends keyof HookPayloads
+        ? HookPayloads[E]
+        : Record<string, unknown>,
+    ) => void | Promise<void>,
+  ): void;
+}
+
+/**
+ * Procedure builders capped by the extension's `api:<level>` permission. Builders
+ * the extension was not granted are absent (undefined), so attempting to use one
+ * is a type error and a runtime no-op.
+ */
+export interface ScopedProcedures {
+  publicProcedure?: ProcedureBuilder;
+  protectedProcedure?: ProcedureBuilder;
+  adminProcedure?: ProcedureBuilder;
+}
+
+export interface ExtensionContext {
+  readonly extId: string;
+  readonly version: string;
+  readonly logger: ExtensionLogger;
+  /**
+   * Drizzle handle fenced to this extension's `ext_<id>_*` tables. Present only
+   * when `db:own` was granted. Pass your own table objects to query.
+   */
+  readonly db?: MySql2Database<Record<string, never>>;
+  /** Present per granted `core.metadata:<entity>` permission. */
+  readonly coreMeta: Partial<Record<CoreMetaEntity, CoreMetaClient>>;
+  readonly settings: ScopedSettings;
+  readonly hooks: HookApi;
+  readonly procedures: ScopedProcedures;
+}
+
+export interface ExtensionRegistration {
+  /** oRPC router mounted at `ext.<id>.*`. Build it with `ctx.procedures.*`. */
+  router?: AnyRouter;
+}
+
+export interface ExtensionDefinition {
+  register(ctx: ExtensionContext): ExtensionRegistration | Promise<ExtensionRegistration>;
+}
+
+/**
+ * Author entry point. The default export of `server/index.js` should be the
+ * result of this call.
+ *
+ * @example
+ * export default defineExtension({
+ *   async register(ctx) {
+ *     ctx.hooks.on("server.created", async ({ serverId }) => {
+ *       ctx.logger.info("server created", { serverId });
+ *     });
+ *     const router = {
+ *       hello: ctx.procedures.protectedProcedure!.handler(() => "hi"),
+ *     };
+ *     return { router };
+ *   },
+ * });
+ */
+export function defineExtension(def: ExtensionDefinition): ExtensionDefinition {
+  return def;
+}