@struxa/extension-sdk 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,243 @@
+# @struxa/extension-sdk
+
+SDK for building [Struxa](https://struxa.cloud) extensions. Provides manifest types and validation, the server-side `defineExtension()` helper, a preconfigured oRPC client, the iframe host bridge, and React hooks — everything an extension needs to integrate with the host panel.
+
+```bash
+npm install @struxa/extension-sdk
+```
+
+## Exports
+
+| Entry point | Contents |
+|---|---|
+| `@struxa/extension-sdk` | Manifest schema/types, permission constants, `HOST_API_VERSION` |
+| `@struxa/extension-sdk/server` | `defineExtension()`, `ExtensionContext`, hook typings |
+| `@struxa/extension-sdk/client` | `createHostClient()`, `createBridge()`, host bridge types |
+| `@struxa/extension-sdk/react` | `createExtension()`, `useHostBridge()` |
+
+## Server entry (`server/index.js`)
+
+The host loads `server/index.js`, calls `mod.default.register(ctx)`, and mounts the returned router at `ext.<id>.*`. Use `defineExtension()` as the default export:
+
+```js
+import { defineExtension } from "@struxa/extension-sdk/server";
+
+export default defineExtension({
+  async register(ctx) {
+    ctx.hooks.on("server.created", async ({ serverId }) => {
+      ctx.logger.info("server created", { serverId });
+    });
+
+    const router = {
+      ping: ctx.procedures.protectedProcedure.handler(() => ({
+        ok: true,
+        timestamp: new Date().toISOString(),
+      })),
+    };
+
+    return { router };
+  },
+});
+```
+
+### Context (`ctx`)
+
+All host capabilities arrive through `ctx` — there is no other sanctioned import path from `server/index.js`:
+
+| Field | Type | Requires permission |
+|---|---|---|
+| `ctx.logger` | `{ info, warn, error }` | — |
+| `ctx.db` | Drizzle handle (fenced to `ext_<id>_*` tables) | `db:own` |
+| `ctx.coreMeta.<entity>` | `{ get, set }` on the entity's `metadata` column | `core.metadata:<entity>` |
+| `ctx.settings` | `{ get, set, all }` scoped to approved key prefixes | `settings:<prefix>` |
+| `ctx.hooks` | `{ on(event, handler) }` | `hook:<event>` |
+| `ctx.procedures` | `{ publicProcedure?, protectedProcedure?, adminProcedure? }` | `api:<level>` |
+| `ctx.fieldOutputs` | `{ set, clear }` — publish computed values for named UI fields | `output:<entity>:<field>` |
+
+### Hook events
+
+Subscribe via `ctx.hooks.on(event, handler)` with the matching `hook:<event>` permission:
+
+| Event | Payload | Description |
+|---|---|---|
+| `server.created` | `{ serverId, userId }` | A server was created |
+| `server.updated` | `{ serverId, userId }` | A server's config was updated |
+| `server.deleted` | `{ serverId, userId }` | A server was deleted |
+| `server.power` | `{ serverId, action }` | A power action was sent to a server |
+| `server.settings.saved` | `{ serverId, key, value }` | One of this extension's server settings was saved by the user |
+| `admin.settings.saved` | `{ tabId, changes }` | One of this extension's admin settings tabs was saved |
+| `node.created` | `{ nodeId }` | A node was created |
+| `node.updated` | `{ nodeId }` | A node was updated |
+| `node.deleted` | `{ nodeId }` | A node was deleted |
+| `user.created` | `{ userId }` | A user registered |
+| `user.updated` | `{ userId }` | A user's profile was updated |
+| `user.deleted` | `{ userId }` | A user was deleted |
+
+`server.settings.saved` and `admin.settings.saved` are fired only to the extension whose settings were changed — other extensions do not receive these events.
+
+### `ctx.fieldOutputs` — requires `output:<entity>:<field>`
+
+Publish a computed value for a named UI field. The host panel reads these values and displays them instead of the default (e.g. showing a Cloudflare-generated subdomain instead of the raw server IP).
+
+```js
+// In register(), populate on startup from persisted data:
+ctx.hooks.on("server.created", async ({ serverId }) => {
+  const subdomain = await provisionSubdomain(serverId);
+  ctx.fieldOutputs.set("server", "address", serverId, `${subdomain}:25565`);
+});
+
+// Clear when the server is deleted:
+ctx.hooks.on("server.deleted", async ({ serverId }) => {
+  ctx.fieldOutputs.clear("server", "address", serverId);
+});
+```
+
+Values are in-memory — repopulate them in `register()` by reading from `ctx.settings` or `ctx.coreMeta` if you need them to survive restarts.
+
+Currently overridable fields:
+
+| Entity | Field | Where it appears |
+|---|---|---|
+| `server` | `address` | Server console page — address stat |
+| `server` | `sftp.host` | Server settings page — SFTP section and sidebar |
+
+## React UI
+
+### `createExtension(element)`
+
+Bootstraps a React app into `#root`. Wraps in an error boundary and removes the boot-status indicator.
+
+```tsx
+// src/main.tsx
+import { createExtension } from "@struxa/extension-sdk/react";
+import { App } from "./App";
+
+createExtension(<App />);
+```
+
+### `useHostBridge()`
+
+Mounts the iframe bridge once, exposes the host context (theme, session, route params, translated messages), and returns navigation/toast/resize helpers. Auto-resize is on by default.
+
+```tsx
+function App() {
+  const { context, navigate, toast } = useHostBridge();
+
+  return (
+    <button onClick={() => toast("success", "done!")}>
+      Hello, {context?.session.userId}
+    </button>
+  );
+}
+```
+
+### `bridge.t(key, params?)` — translations
+
+The bridge exposes a `t()` helper that resolves dot-notation keys from the extension's translated messages (pushed by the host on init from the `messages` manifest field):
+
+```ts
+const bridge = createBridge({ onInit: (ctx) => render(ctx) });
+
+// After onInit fires:
+bridge.t("nav.title")              // → "My Extension"
+bridge.t("msg.count", { n: 3 })   // → "3 items" (if messages has "msg.count": "{n} items")
+```
+
+Falls back to the key itself if no translation is found. Supports `{param}` placeholder substitution.
+
+## oRPC client (`createHostClient`)
+
+Same-origin, cookie-authenticated. Call your extension's procedures under `client.ext["<your-id>"].*`:
+
+```ts
+import { createHostClient } from "@struxa/extension-sdk/client";
+
+const client = createHostClient();
+const res = await client.ext["hello-world"].ping();
+```
+
+## Manifest (`manifest.json`)
+
+Validated by `manifestSchema` (Zod). Full example:
+
+```json
+{
+  "id": "hello-world",
+  "name": "Hello World",
+  "version": "1.0.0",
+  "struxaApi": "^1.0.0",
+  "permissions": [
+    "hook:server.created",
+    "api:protected",
+    "core.metadata:server",
+    "output:server:address",
+    "output:server:sftp.host"
+  ],
+  "messages": {
+    "en": "messages/en.json",
+    "pl": "messages/pl.json"
+  },
+  "ui": {
+    "pages": [
+      { "route": "/hello", "section": "panel", "label": "nav.hello", "icon": "Blocks" }
+    ],
+    "slots": [
+      { "slot": "server.stats.after", "widget": "/hello/stats-widget" }
+    ],
+    "serverSettings": [
+      {
+        "key": "subdomain_prefix",
+        "label": "Subdomain prefix",
+        "description": "Prefix used when generating Cloudflare subdomains.",
+        "type": "text",
+        "placeholder": "mc"
+      },
+      {
+        "key": "enabled",
+        "label": "Enable automatic subdomains",
+        "type": "toggle"
+      }
+    ],
+    "adminSettingsTabs": [
+      {
+        "id": "cloudflare",
+        "label": "Cloudflare",
+        "sections": [
+          {
+            "title": "API Credentials",
+            "description": "Connect your Cloudflare account.",
+            "fields": [
+              { "key": "api_token", "label": "API Token", "type": "password" },
+              { "key": "zone_id", "label": "Zone ID", "type": "text", "placeholder": "abc123…" },
+              {
+                "key": "plan",
+                "label": "Plan",
+                "type": "select",
+                "options": [
+                  { "value": "free", "label": "Free" },
+                  { "value": "pro", "label": "Pro" }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Permission grammar
+
+| Permission | Grants |
+|---|---|
+| `db:own` | Create and use `ext_<id>_*` tables |
+| `core.metadata:<entity>` | Read/write the `metadata` JSON on `server`, `node`, or `user` |
+| `settings:<prefix>` | Get/set settings keys under `<prefix>` |
+| `hook:<event>` | Subscribe to a lifecycle event (e.g. `hook:server.created`) |
+| `api:public` / `api:protected` / `api:admin` | Expose oRPC procedures at that auth level |
+| `output:<entity>:<field>` | Publish a computed value for a named UI field (e.g. `output:server:address`) |
+
+## License
+
+[MIT](https://github.com/struxadotcloud/struxa/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struxa/extension-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",

package/src/client.ts

@@ -49,6 +49,8 @@ export interface HostContext {
   session: HostSessionSummary;
   /** Route context the iframe was opened with (e.g. { serverId }). */
   params: Record<string, string>;
+  /** Translated messages for this extension's locale, keyed by dot-notation path. */
+  messages: Record<string, unknown>;
 }
 
 type HostInbound =
@@ -88,6 +90,11 @@ export interface Bridge {
   navigate(route: string): void;
   toast(level: "success" | "error" | "info", message: string): void;
   reportHeight(height?: number): void;
+  /**
+   * Resolve a dot-notation key from the extension's messages (e.g. `"nav.title"`).
+   * Supports `{param}` placeholder substitution. Falls back to the key itself.
+   */
+  t(key: string, params?: Record<string, string | number>): string;
   destroy(): void;
 }
 
@@ -100,6 +107,17 @@ function applyTheme(theme: HostTheme): void {
   }
 }
 
+/** Resolve a dotted key path into a nested object, returning a string or null. */
+function resolveDotKey(obj: Record<string, unknown>, key: string): string | null {
+  const parts = key.split(".");
+  let cur: unknown = obj;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== "object") return null;
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  return typeof cur === "string" ? cur : null;
+}
+
 /**
  * Initialize the bridge. Call once on iframe boot.
  */
@@ -118,6 +136,16 @@ export function createBridge(options: BridgeOptions = {}): Bridge {
             ? document.documentElement.scrollHeight
             : 0),
       }),
+    t(key, params) {
+      const messages = bridge.context?.messages ?? {};
+      let str = resolveDotKey(messages, key) ?? key;
+      if (params) {
+        for (const [k, v] of Object.entries(params)) {
+          str = str.replaceAll(`{${k}}`, String(v));
+        }
+      }
+      return str;
+    },
     destroy: () => {
       if (typeof window !== "undefined") {
         window.removeEventListener("message", onMessage);

package/src/index.ts

@@ -19,6 +19,8 @@ export const HOOK_EVENTS = [
   "server.updated",
   "server.deleted",
   "server.power",
+  "server.settings.saved",
+  "admin.settings.saved",
   "node.created",
   "node.updated",
   "node.deleted",
@@ -43,7 +45,7 @@ export type ApiLevel = "public" | "protected" | "admin";
 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))$/,
+    /^(db:own|core\.metadata:(server|node|user)|settings:[a-zA-Z0-9_.*-]+|hook:[a-zA-Z0-9_.*-]+|api:(public|protected|admin)|output:[a-z]+:[a-zA-Z0-9_]+)$/,
     "invalid permission",
   );
 
@@ -74,6 +76,45 @@ const uiSlotSchema = z.object({
   widget: z.string().min(1),
 });
 
+const serverSettingFieldSchema = z.object({
+  /** Storage key — alphanumeric + underscores only, unique within this extension. */
+  key: z.string().regex(/^[a-zA-Z0-9_]+$/).min(1).max(64),
+  /** Label shown in the settings row. */
+  label: z.string().min(1).max(120),
+  description: z.string().max(500).optional(),
+  /** Rendered as a text input or an on/off toggle. */
+  type: z.enum(["text", "toggle"]),
+  /** Placeholder text for text inputs. */
+  placeholder: z.string().max(255).optional(),
+});
+
+const adminSettingsFieldSchema = z.object({
+  /** Storage key — alphanumeric + underscores only. Must be unique within the tab. */
+  key: z.string().regex(/^[a-zA-Z0-9_]+$/).min(1).max(64),
+  label: z.string().min(1).max(120),
+  description: z.string().max(500).optional(),
+  type: z.enum(["text", "password", "textarea", "toggle", "select"]),
+  placeholder: z.string().max(255).optional(),
+  /** Required when type is "select". */
+  options: z
+    .array(z.object({ value: z.string().min(1).max(255), label: z.string().min(1).max(120) }))
+    .optional(),
+});
+
+const adminSettingsSectionSchema = z.object({
+  title: z.string().min(1).max(120),
+  description: z.string().max(500).optional(),
+  fields: z.array(adminSettingsFieldSchema).min(1),
+});
+
+const adminSettingsTabSchema = z.object({
+  /** Unique within this extension — used as part of the tab key. */
+  id: z.string().regex(/^[a-zA-Z0-9_-]+$/).min(1).max(64),
+  /** Display label for the tab. May be a literal string or an i18n key resolved under ext.<id>.*. */
+  label: z.string().min(1).max(120),
+  sections: z.array(adminSettingsSectionSchema).min(1),
+});
+
 export const manifestSchema = z.object({
   id: z
     .string()
@@ -89,6 +130,18 @@ export const manifestSchema = z.object({
     .object({
       pages: z.array(uiPageSchema).default([]),
       slots: z.array(uiSlotSchema).default([]),
+      /**
+       * Custom settings rows injected into the server settings page.
+       * Requires the `core.metadata:server` permission to be granted —
+       * values are stored in the server's metadata under this extension's key.
+       */
+      serverSettings: z.array(serverSettingFieldSchema).default([]),
+      /**
+       * Tabs injected into the admin /admin/settings page. Values are stored
+       * in the global settings table under the extension's namespace and
+       * accessible at runtime via `ctx.settings`.
+       */
+      adminSettingsTabs: z.array(adminSettingsTabSchema).default([]),
     })
     .optional(),
   /** Map of locale -> relative path of a namespaced messages JSON file. */
@@ -98,6 +151,9 @@ export const manifestSchema = z.object({
 export type Manifest = z.infer<typeof manifestSchema>;
 export type ManifestUiPage = z.infer<typeof uiPageSchema>;
 export type ManifestUiSlot = z.infer<typeof uiSlotSchema>;
+export type ManifestServerSettingField = z.infer<typeof serverSettingFieldSchema>;
+export type ManifestAdminSettingsField = z.infer<typeof adminSettingsFieldSchema>;
+export type ManifestAdminSettingsTab = z.infer<typeof adminSettingsTabSchema>;
 
 /** The current host API version. Extensions declare a range against this. */
 export const HOST_API_VERSION = "1.0.0";

package/src/server.ts

@@ -51,6 +51,8 @@ export interface HookPayloads {
   "server.updated": { serverId: string; userId: string | null };
   "server.deleted": { serverId: string; userId: string | null };
   "server.power": { serverId: string; action: string };
+  "server.settings.saved": { serverId: string; key: string; value: string };
+  "admin.settings.saved": { tabId: string; changes: Record<string, string> };
   "node.created": { nodeId: string };
   "node.updated": { nodeId: string };
   "node.deleted": { nodeId: string };
@@ -81,6 +83,16 @@ export interface ScopedProcedures {
   adminProcedure?: ProcedureBuilder;
 }
 
+/**
+ * Publish computed values for named output fields (e.g. `server.address`).
+ * Granted by `output:<entity>:<field>` permissions. Values are held in memory
+ * and should be repopulated in `register()` if the extension persists them.
+ */
+export interface FieldOutputs {
+  set(entity: string, field: string, entityId: string, value: string): void;
+  clear(entity: string, field: string, entityId: string): void;
+}
+
 export interface ExtensionContext {
   readonly extId: string;
   readonly version: string;
@@ -95,6 +107,7 @@ export interface ExtensionContext {
   readonly settings: ScopedSettings;
   readonly hooks: HookApi;
   readonly procedures: ScopedProcedures;
+  readonly fieldOutputs: FieldOutputs;
 }
 
 export interface ExtensionRegistration {