@jchat/addon-sdk 0.0.1 → 1.0.0-alpha.1

package/src/index.d.ts

@@ -0,0 +1,249 @@
+import type { IconPack } from "@jchat/icon";
+import type { Elysia } from "elysia";
+import type { Kysely } from "kysely";
+import type { AddonManifest, AddonPermission, MountPoint } from "./contracts";
+export { MOUNT_POINTS, type AddonManifest, type AddonPermission, type AddonPermissionDefinition, type ConfigSchemaField, type MountPoint } from "./contracts";
+export type AddonJsonBody = Record<string, unknown> | unknown[] | null;
+/**
+ * @jchat/addon-sdk
+ *
+ *   Lightweight SDK for Jchat addon developers. Provides TypeScript types for addon props, manifest
+ *   schema, and host API access. This package is always EXTERNALISED from addon bundles — the host
+ *   app provides the runtime implementation.
+ */
+/** Minimal user profile accessible to addon backends. */
+export interface AddonUser {
+    /** Unique user identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Full display name */
+    displayName: string;
+    /** Full URL to the user's avatar image */
+    avatar: string;
+    /** User's gender identifier */
+    gender: string;
+}
+export interface AddonRequestUser {
+    id?: string;
+    permissions?: string[];
+    siteId?: string;
+}
+/**
+ * Typed, schema-scoped database facade for an addon. The host deliberately omits raw execution,
+ * schema switching, dialect/connection access, and lifecycle methods.
+ */
+export type AddonDatabase<TDatabase = Record<string, Record<string, unknown>>> = Pick<Kysely<TDatabase>, "deleteFrom" | "fn" | "insertInto" | "selectFrom" | "transaction" | "updateTable">;
+/**
+ * Context provided to an addon's server-side factory. Parameterize it with the addon's table
+ * interface: `AddonServerContext<MyAddonDatabase>`.
+ */
+export interface AddonServerContext<TDatabase = Record<string, Record<string, unknown>>> {
+    /**
+     * Retrieve the encrypted settings for this addon for a specific site. Internal secrets are
+     * automatically decrypted using the host's master key.
+     */
+    getConfig: (siteId: string) => Promise<Record<string, unknown>>;
+    /** Fetch a specific user's public profile */
+    getUser: (userId: string) => Promise<AddonUser | null>;
+    /** Efficiently fetch multiple user profiles in a single query. Returns a Map keyed by user ID. */
+    getUsers: (userIds: string[]) => Promise<Map<string, AddonUser>>;
+    /**
+     * Check whether the request user holds a given permission. Provides autocomplete for core Jchat
+     * permissions while also accepting any custom addon permission string.
+     *
+     * @param user - The user object from the request context
+     * @param permission - The permission to check, e.g., 'message.send' or 'addon.stories.view'
+     */
+    hasPermission: (user: AddonRequestUser | null | undefined, permission: AddonPermission) => boolean;
+    /**
+     * A Kysely database instance scoped entirely to your addon's tables. You cannot access core Jchat
+     * tables (Users, Rooms, etc.) through this instance.
+     */
+    db: AddonDatabase<TDatabase>;
+}
+/**
+ * The entry point for your addon's server bundle. You should default-export a function matching
+ * this signature.
+ *
+ * @example
+ *   ;```ts
+ *   import { type AddonServerFactory } from '@jchat/addon-sdk'
+ *
+ *   const factory: AddonServerFactory = ({ db, hasPermission }, app) => {
+ *   return app.get('/trending', async () => { ... })
+ *   }
+ *   export default factory
+ *   ```
+ */
+export type AddonServerFactory<TDatabase = Record<string, Record<string, unknown>>> = (ctx: AddonServerContext<TDatabase>, app: Elysia) => Elysia;
+/** Props passed to your addon's root React component by the Jchat host. */
+export interface AddonProps {
+    /** The mount point where this addon instance is rendered (e.g., 'chat-sidebar') */
+    mountPoint: MountPoint;
+    /** Information about the currently logged-in user (if any) */
+    user?: {
+        id: string;
+        name: string;
+        displayName?: string;
+        avatar?: string;
+        gender?: string;
+    };
+    /** The ID of the room the user is currently viewing (if applicable) */
+    roomId?: string;
+    /** The ID of the active Jchat site */
+    siteId?: string;
+}
+export interface AddonApi {
+    get: <TResponse = unknown>(path: string) => Promise<TResponse>;
+    post: <TResponse = unknown>(path: string, body?: AddonJsonBody) => Promise<TResponse>;
+    put: <TResponse = unknown>(path: string, body?: AddonJsonBody) => Promise<TResponse>;
+    delete: <TResponse = unknown>(path: string) => Promise<TResponse>;
+}
+export type AddonEventListener = (data: unknown) => void;
+/** A font option provided by the JChat host. */
+export interface AddonFont {
+    /** Display label shown to users (e.g. 'Modern', 'Elegant') */
+    label: string;
+    /** Font identifier stored in the database (e.g. 'poppins', 'lato') */
+    value: string;
+    /** CSS font-family string ready for use in inline styles */
+    family: string;
+    /** Google Fonts name for loading the font via a <link> tag */
+    googleName: string;
+    /** Relative size multiplier — apply this to base font sizes to match the host's rendering */
+    scale: number;
+}
+/**
+ * The bridge between your addon and the Jchat host application. Use the `useAddonSDK()` hook to
+ * access this interface in your components.
+ */
+export interface AddonSDK {
+    /**
+     * Make authenticated API calls to your addon's backend or core Jchat endpoints. All calls
+     * automatically include the current user's sessionId and site validation headers.
+     */
+    api: AddonApi;
+    /**
+     * Display a temporary notification toast in the host UI.
+     *
+     * @param message - The text content to display
+     * @param variant - Visual style: 'default' (blue), 'success' (green), or 'error' (red)
+     */
+    toast: (message: string, variant?: "default" | "success" | "error") => void;
+    /**
+     * Navigate the host application to a different internal route.
+     *
+     * @param path - The target location, e.g., '/settings' or '/addons/store'
+     */
+    navigate: (path: string) => void;
+    /**
+     * Interaction utilities for the active Slate message editor. Only available if your addon is
+     * mounted near the chat input.
+     */
+    editor: {
+        /**
+         * Trigger a specialized editor command defined by the host.
+         *
+         * @example
+         *   sdk.editor.dispatchCommand("INSERT_YOUTUBE_COMMAND", "dQw4w9WgXcQ")
+         */
+        dispatchCommand: (command: string, payload?: unknown) => void;
+        /**
+         * Insert a low-level Slate node directly at the user's cursor position.
+         *
+         * @param node - A valid Slate Descendant or Fragment object
+         */
+        insertNode: (node: unknown) => void;
+        /**
+         * Upload and attach a file to the current message without inserting it inline. Users will see
+         * the file in the attachment bar below the editor.
+         */
+        addAttachment: (attachment: {
+            url: string;
+            name: string;
+            type: string;
+        }) => void;
+        /** Force the browser focus back to the editor input */
+        focus: () => void;
+    };
+    /** Event Bus for reacting to real-time application state changes. */
+    events: {
+        /**
+         * Register a persistent listener for a specific event.
+         *
+         * @param event - Event name, e.g., 'room.message', 'user.typing'
+         */
+        on: (event: string, callback: AddonEventListener) => void;
+        /** Unregister a previously attached listener */
+        off: (event: string, callback: AddonEventListener) => void;
+    };
+    /**
+     * The list of fonts available in this JChat deployment, as configured by the site administrator.
+     * Use this to build a font picker or apply a matching font family in your addon UI.
+     */
+    supportedFonts?: AddonFont[];
+}
+/**
+ * Seed data for your addon's tables, provided inside the addon's isolated schema.
+ *
+ * These documents are inserted into the addon's dedicated schema on installation and can be used to
+ * provide default values, references, or supporting data. The host guarantees that these documents
+ * do not conflict with core schemas or other addons.
+ */
+export interface AddonSeedDocument {
+    /** Addon-owned table name. Core prefixes the addon's isolated PostgreSQL schema. */
+    table: string;
+    /** Behavior when a row conflicts with an existing unique or primary key. */
+    conflict?: "error" | "ignore" | "update";
+    /** Required for update behavior; identifies the unique key used by ON CONFLICT. */
+    conflictColumns?: string[];
+    /** JSON-compatible rows inserted using parameterized values. */
+    rows: Record<string, unknown>[];
+}
+/** Define a manifest with full validation-friendly typing while preserving literal values. */
+export declare function defineAddonManifest<const TManifest extends AddonManifest>(manifest: TManifest): TManifest;
+/** Define a typed server factory without widening its addon database interface. */
+export declare function defineAddonServer<TDatabase = Record<string, Record<string, unknown>>>(factory: AddonServerFactory<TDatabase>): AddonServerFactory<TDatabase>;
+/**
+ * Access the host application's SDK. Provides authenticated API access, toast notifications, and
+ * navigation.
+ *
+ * This function is a shell; the real implementation is provided by the Jchat host environment at
+ * runtime.
+ *
+ * @example
+ *   ;```tsx
+ *   import { useAddonSDK } from "@jchat/addon-sdk"
+ *
+ *   export default function MyAddon({ mountPoint }: AddonProps) {
+ *     const sdk = useAddonSDK()
+ *
+ *     const handleClick = async () => {
+ *       const data = await sdk.api.get("/trending")
+ *       sdk.toast("Fetched trending posts!", "success")
+ *     }
+ *   }
+ *   ```
+ */
+export declare function useAddonSDK(): AddonSDK;
+/**
+ * Access the host application's active icon pack. Returns the icon set matching the site's
+ * configured icon pack preference.
+ *
+ * This function is a shell; the real implementation is provided by the Jchat host environment at
+ * runtime.
+ *
+ * @example
+ *   ;```tsx
+ *   import { useIcons } from "@jchat/addon-sdk"
+ *
+ *   export default function MyAddon() {
+ *     const { Icons } = useIcons()
+ *     return <Icons.Send className="size-5" />
+ *   }
+ *   ```
+ */
+export declare function useIcons(): {
+    Icons: IconPack;
+};

package/src/index.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test"
+import { Elysia } from "elysia"
+import {
+  defineAddonManifest,
+  defineAddonServer,
+  MOUNT_POINTS,
+  type AddonManifest,
+  type AddonServerContext
+} from "./index"
+
+describe("addon SDK definition helpers", () => {
+  test("defineAddonManifest preserves the manifest", () => {
+    const manifest = {
+      id: "example-addon",
+      name: "Example addon",
+      version: "1.0.0",
+      description: "An example addon",
+      author: "Jchat",
+      compatibility: { jchat: "^1.0.0", addonSdk: "^1.0.0" },
+      permissions: ["message.read"]
+    } as const satisfies AddonManifest
+
+    expect(defineAddonManifest(manifest)).toBe(manifest)
+  })
+
+  test("keeps manifest mount points available from the public entry", () => {
+    expect(MOUNT_POINTS.CHAT_HEADER).toBe("chat-header")
+  })
+
+  test("defineAddonServer preserves the server factory", () => {
+    const factory = (_context: AddonServerContext) => new Elysia()
+
+    expect(defineAddonServer(factory)).toBe(factory)
+  })
+})

package/src/index.ts

@@ -0,0 +1,299 @@
+import type { IconPack } from "@jchat/icon"
+import type { Elysia } from "elysia"
+import type { Kysely } from "kysely"
+import type { AddonManifest, AddonPermission, MountPoint } from "./contracts"
+
+export {
+  MOUNT_POINTS,
+  type AddonManifest,
+  type AddonPermission,
+  type AddonPermissionDefinition,
+  type ConfigSchemaField,
+  type MountPoint
+} from "./contracts"
+
+export type AddonJsonBody = Record<string, unknown> | unknown[] | null
+
+/**
+ * @jchat/addon-sdk
+ *
+ *   Lightweight SDK for Jchat addon developers. Provides TypeScript types for addon props, manifest
+ *   schema, and host API access. This package is always EXTERNALISED from addon bundles — the host
+ *   app provides the runtime implementation.
+ */
+
+/** Minimal user profile accessible to addon backends. */
+export interface AddonUser {
+  /** Unique user identifier */
+  id: string
+  /** Display name */
+  name: string
+  /** Full display name */
+  displayName: string
+  /** Full URL to the user's avatar image */
+  avatar: string
+  /** User's gender identifier */
+  gender: string
+}
+
+export interface AddonRequestUser {
+  id?: string
+  permissions?: string[]
+  siteId?: string
+}
+
+/**
+ * Typed, schema-scoped database facade for an addon. The host deliberately omits raw execution,
+ * schema switching, dialect/connection access, and lifecycle methods.
+ */
+export type AddonDatabase<TDatabase = Record<string, Record<string, unknown>>> = Pick<
+  Kysely<TDatabase>,
+  "deleteFrom" | "fn" | "insertInto" | "selectFrom" | "transaction" | "updateTable"
+>
+
+/**
+ * Context provided to an addon's server-side factory. Parameterize it with the addon's table
+ * interface: `AddonServerContext<MyAddonDatabase>`.
+ */
+export interface AddonServerContext<TDatabase = Record<string, Record<string, unknown>>> {
+  /**
+   * Retrieve the encrypted settings for this addon for a specific site. Internal secrets are
+   * automatically decrypted using the host's master key.
+   */
+  getConfig: (siteId: string) => Promise<Record<string, unknown>>
+
+  /** Fetch a specific user's public profile */
+  getUser: (userId: string) => Promise<AddonUser | null>
+
+  /** Efficiently fetch multiple user profiles in a single query. Returns a Map keyed by user ID. */
+  getUsers: (userIds: string[]) => Promise<Map<string, AddonUser>>
+
+  /**
+   * Check whether the request user holds a given permission. Provides autocomplete for core Jchat
+   * permissions while also accepting any custom addon permission string.
+   *
+   * @param user - The user object from the request context
+   * @param permission - The permission to check, e.g., 'message.send' or 'addon.stories.view'
+   */
+  hasPermission: (user: AddonRequestUser | null | undefined, permission: AddonPermission) => boolean
+
+  /**
+   * A Kysely database instance scoped entirely to your addon's tables. You cannot access core Jchat
+   * tables (Users, Rooms, etc.) through this instance.
+   */
+  db: AddonDatabase<TDatabase>
+}
+
+/**
+ * The entry point for your addon's server bundle. You should default-export a function matching
+ * this signature.
+ *
+ * @example
+ *   ;```ts
+ *   import { type AddonServerFactory } from '@jchat/addon-sdk'
+ *
+ *   const factory: AddonServerFactory = ({ db, hasPermission }, app) => {
+ *   return app.get('/trending', async () => { ... })
+ *   }
+ *   export default factory
+ *   ```
+ */
+export type AddonServerFactory<TDatabase = Record<string, Record<string, unknown>>> = (
+  ctx: AddonServerContext<TDatabase>,
+  app: Elysia
+) => Elysia
+
+/** Props passed to your addon's root React component by the Jchat host. */
+export interface AddonProps {
+  /** The mount point where this addon instance is rendered (e.g., 'chat-sidebar') */
+  mountPoint: MountPoint
+  /** Information about the currently logged-in user (if any) */
+  user?: {
+    id: string
+    name: string
+    displayName?: string
+    avatar?: string
+    gender?: string
+  }
+  /** The ID of the room the user is currently viewing (if applicable) */
+  roomId?: string
+  /** The ID of the active Jchat site */
+  siteId?: string
+}
+
+export interface AddonApi {
+  get: <TResponse = unknown>(path: string) => Promise<TResponse>
+  post: <TResponse = unknown>(path: string, body?: AddonJsonBody) => Promise<TResponse>
+  put: <TResponse = unknown>(path: string, body?: AddonJsonBody) => Promise<TResponse>
+  delete: <TResponse = unknown>(path: string) => Promise<TResponse>
+}
+
+export type AddonEventListener = (data: unknown) => void
+
+/** A font option provided by the JChat host. */
+export interface AddonFont {
+  /** Display label shown to users (e.g. 'Modern', 'Elegant') */
+  label: string
+  /** Font identifier stored in the database (e.g. 'poppins', 'lato') */
+  value: string
+  /** CSS font-family string ready for use in inline styles */
+  family: string
+  /** Google Fonts name for loading the font via a <link> tag */
+  googleName: string
+  /** Relative size multiplier — apply this to base font sizes to match the host's rendering */
+  scale: number
+}
+
+/**
+ * The bridge between your addon and the Jchat host application. Use the `useAddonSDK()` hook to
+ * access this interface in your components.
+ */
+export interface AddonSDK {
+  /**
+   * Make authenticated API calls to your addon's backend or core Jchat endpoints. All calls
+   * automatically include the current user's sessionId and site validation headers.
+   */
+  api: AddonApi
+
+  /**
+   * Display a temporary notification toast in the host UI.
+   *
+   * @param message - The text content to display
+   * @param variant - Visual style: 'default' (blue), 'success' (green), or 'error' (red)
+   */
+  toast: (message: string, variant?: "default" | "success" | "error") => void
+
+  /**
+   * Navigate the host application to a different internal route.
+   *
+   * @param path - The target location, e.g., '/settings' or '/addons/store'
+   */
+  navigate: (path: string) => void
+
+  /**
+   * Interaction utilities for the active Slate message editor. Only available if your addon is
+   * mounted near the chat input.
+   */
+  editor: {
+    /**
+     * Trigger a specialized editor command defined by the host.
+     *
+     * @example
+     *   sdk.editor.dispatchCommand("INSERT_YOUTUBE_COMMAND", "dQw4w9WgXcQ")
+     */
+    dispatchCommand: (command: string, payload?: unknown) => void
+
+    /**
+     * Insert a low-level Slate node directly at the user's cursor position.
+     *
+     * @param node - A valid Slate Descendant or Fragment object
+     */
+    insertNode: (node: unknown) => void
+
+    /**
+     * Upload and attach a file to the current message without inserting it inline. Users will see
+     * the file in the attachment bar below the editor.
+     */
+    addAttachment: (attachment: { url: string; name: string; type: string }) => void
+
+    /** Force the browser focus back to the editor input */
+    focus: () => void
+  }
+
+  /** Event Bus for reacting to real-time application state changes. */
+  events: {
+    /**
+     * Register a persistent listener for a specific event.
+     *
+     * @param event - Event name, e.g., 'room.message', 'user.typing'
+     */
+    on: (event: string, callback: AddonEventListener) => void
+
+    /** Unregister a previously attached listener */
+    off: (event: string, callback: AddonEventListener) => void
+  }
+
+  /**
+   * The list of fonts available in this JChat deployment, as configured by the site administrator.
+   * Use this to build a font picker or apply a matching font family in your addon UI.
+   */
+  supportedFonts?: AddonFont[]
+}
+
+/**
+ * Seed data for your addon's tables, provided inside the addon's isolated schema.
+ *
+ * These documents are inserted into the addon's dedicated schema on installation and can be used to
+ * provide default values, references, or supporting data. The host guarantees that these documents
+ * do not conflict with core schemas or other addons.
+ */
+export interface AddonSeedDocument {
+  /** Addon-owned table name. Core prefixes the addon's isolated PostgreSQL schema. */
+  table: string
+  /** Behavior when a row conflicts with an existing unique or primary key. */
+  conflict?: "error" | "ignore" | "update"
+  /** Required for update behavior; identifies the unique key used by ON CONFLICT. */
+  conflictColumns?: string[]
+  /** JSON-compatible rows inserted using parameterized values. */
+  rows: Record<string, unknown>[]
+}
+
+/** Define a manifest with full validation-friendly typing while preserving literal values. */
+export function defineAddonManifest<const TManifest extends AddonManifest>(
+  manifest: TManifest
+): TManifest {
+  return manifest
+}
+
+/** Define a typed server factory without widening its addon database interface. */
+export function defineAddonServer<TDatabase = Record<string, Record<string, unknown>>>(
+  factory: AddonServerFactory<TDatabase>
+): AddonServerFactory<TDatabase> {
+  return factory
+}
+
+/**
+ * Access the host application's SDK. Provides authenticated API access, toast notifications, and
+ * navigation.
+ *
+ * This function is a shell; the real implementation is provided by the Jchat host environment at
+ * runtime.
+ *
+ * @example
+ *   ;```tsx
+ *   import { useAddonSDK } from "@jchat/addon-sdk"
+ *
+ *   export default function MyAddon({ mountPoint }: AddonProps) {
+ *     const sdk = useAddonSDK()
+ *
+ *     const handleClick = async () => {
+ *       const data = await sdk.api.get("/trending")
+ *       sdk.toast("Fetched trending posts!", "success")
+ *     }
+ *   }
+ *   ```
+ */
+export function useAddonSDK(): AddonSDK {
+  throw new Error("AddonSDK must be used within the Jchat host environment.")
+}
+
+/**
+ * Access the host application's active icon pack. Returns the icon set matching the site's
+ * configured icon pack preference.
+ *
+ * This function is a shell; the real implementation is provided by the Jchat host environment at
+ * runtime.
+ *
+ * @example
+ *   ;```tsx
+ *   import { useIcons } from "@jchat/addon-sdk"
+ *
+ *   export default function MyAddon() {
+ *     const { Icons } = useIcons()
+ *     return <Icons.Send className="size-5" />
+ *   }
+ *   ```
+ */
+export function useIcons(): { Icons: IconPack } {
+  throw new Error("useIcons must be used within the Jchat host environment.")
+}

package/src/vite.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test"
+import crypto from "node:crypto"
+import { createAddonServerBuildArguments, requireAddonSigningKey, signAddonManifest } from "./vite"
+
+describe("addon package signing", () => {
+  test("builds a self-contained Bun ESM server artifact", () => {
+    expect(createAddonServerBuildArguments("src/api.ts", "build/api.js", false)).toEqual([
+      "build",
+      "src/api.ts",
+      "--target=bun",
+      "--format=esm",
+      "--outfile=build/api.js",
+      "--minify"
+    ])
+  })
+
+  test("permits unsigned database artifacts only in explicit development builds", () => {
+    expect(requireAddonSigningKey(undefined, true)).toBeUndefined()
+    expect(() => requireAddonSigningKey(undefined, false)).toThrow(
+      "require JCHAT_ADDON_SIGNING_PRIVATE_KEY"
+    )
+    expect(requireAddonSigningKey("private-key", false)).toBe("private-key")
+  })
+
+  test("signs the canonical package digest", () => {
+    const { privateKey, publicKey } = crypto.generateKeyPairSync("rsa", {
+      modulusLength: 2048
+    })
+    const signed = signAddonManifest(
+      {
+        id: "sample",
+        name: "Sample",
+        version: "1.0.0",
+        compatibility: { jchat: "^1.0.0", addonSdk: "^1.0.0" },
+        publisher: { id: "test" },
+        server: {
+          bundle: "api.ts",
+          migrations: ["migrations/001.sql"],
+          seeds: ["seeds/items.json"]
+        }
+      },
+      [
+        { path: "manifest.json", contents: Buffer.from("") },
+        { path: "migrations/001.sql", contents: Buffer.from("safe") },
+        {
+          path: "seeds/items.json",
+          contents: Buffer.from('{"table":"Items","rows":[]}')
+        }
+      ],
+      privateKey.export({ format: "pem", type: "pkcs8" }).toString()
+    )
+    expect(signed.signature?.digest).toHaveLength(64)
+    expect(
+      crypto.verify(
+        "sha256",
+        Buffer.from(signed.signature?.digest ?? ""),
+        publicKey,
+        Buffer.from(signed.signature?.value ?? "", "base64url")
+      )
+    ).toBe(true)
+  })
+})