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

package/src/index.ts

@@ -1,299 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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)
-  })
-})

package/src/vite.ts

@@ -1,289 +0,0 @@
-import type { Plugin } from "vite"
-import { execFileSync } from "node:child_process"
-import crypto from "node:crypto"
-import fs from "node:fs"
-import path from "node:path"
-import type { AddonManifest } from "./contracts"
-
-/**
- * Vite plugin to configure Jchat addon manifest generation, bundle backend scripts, copy
- * migrations, declarative seed data, and zip production build artifacts.
- */
-export function jchatAddon(options: JchatAddonPluginOptions): Plugin {
-  const { manifest: manifestData } = options
-  let shouldZip = options.zip
-  let developmentBuild = false
-
-  return {
-    name: "jchat-addon",
-    apply: "build",
-    config(_, env) {
-      return {
-        define: {
-          "process.env.NODE_ENV": JSON.stringify(env.mode || "production")
-        }
-      }
-    },
-    configResolved(config) {
-      developmentBuild = config.mode === "development"
-      if (shouldZip === undefined) {
-        shouldZip = config.mode === "production"
-      }
-    },
-    async writeBundle() {
-      const rootDir = process.cwd()
-      const pkgPath = path.resolve(rootDir, "package.json")
-      if (!fs.existsSync(pkgPath)) return
-
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
-      const buildDir = path.resolve(rootDir, "build")
-      if (!fs.existsSync(buildDir)) return
-
-      const files = fs.readdirSync(buildDir)
-      const bundleFile = files.find((f) => f.includes("ui") && f.endsWith(".js"))
-
-      if (!bundleFile) return
-
-      if (options.css !== false) {
-        embedCssIntoBundle(buildDir, manifestData.id)
-      }
-
-      let manifest: AddonManifest = {
-        ...manifestData,
-        version: pkg.version,
-        frontend: {
-          ...manifestData.frontend,
-          bundle: `./${bundleFile}`,
-          mountPoints: manifestData.frontend?.mountPoints ?? []
-        }
-      }
-
-      const serverSrcPath = path.resolve(rootDir, "src/api.ts")
-      const hasServer = fs.existsSync(serverSrcPath)
-      if (hasServer) {
-        execFileSync(
-          "bun",
-          createAddonServerBuildArguments(
-            serverSrcPath,
-            path.resolve(buildDir, "api.js"),
-            developmentBuild
-          ),
-          { stdio: "inherit" }
-        )
-        manifest = {
-          ...manifest,
-          server: {
-            ...manifest.server,
-            bundle: "./api.js"
-          }
-        }
-      }
-
-      const databaseFiles = [
-        ...(manifest.server?.migrations ?? []),
-        ...(manifest.server?.seeds ?? [])
-      ]
-      for (const directory of ["migrations", "seeds"]) {
-        fs.rmSync(path.resolve(buildDir, directory), {
-          recursive: true,
-          force: true
-        })
-      }
-      for (const relativePath of databaseFiles) {
-        if (
-          path.isAbsolute(relativePath) ||
-          relativePath.includes("\\") ||
-          relativePath.split("/").includes("..")
-        ) {
-          throw new Error(`Unsafe addon database file path: ${relativePath}`)
-        }
-        const source = path.resolve(rootDir, relativePath)
-        if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
-          throw new Error(`Missing addon database file: ${relativePath}`)
-        }
-        const destination = path.resolve(buildDir, relativePath)
-        fs.mkdirSync(path.dirname(destination), { recursive: true })
-        fs.copyFileSync(source, destination)
-      }
-
-      if (manifest.server?.migrations?.length || manifest.server?.seeds?.length) {
-        const signingPrivateKey = requireAddonSigningKey(
-          options.signingPrivateKey ?? process.env.JCHAT_ADDON_SIGNING_PRIVATE_KEY,
-          developmentBuild
-        )
-        if (signingPrivateKey) {
-          const archivePaths = [
-            "manifest.json",
-            bundleFile,
-            ...(manifest.server?.migrations ?? []),
-            ...(manifest.server?.seeds ?? [])
-          ]
-          if (hasServer) archivePaths.push("api.js")
-          manifest = signAddonManifest(
-            manifest,
-            archivePaths.map((file) => ({
-              path: file,
-              contents:
-                file === "manifest.json"
-                  ? Buffer.from("")
-                  : fs.readFileSync(path.resolve(buildDir, file))
-            })),
-            signingPrivateKey
-          )
-        }
-      }
-
-      // Save manifest.json
-      const manifestJson = JSON.stringify(manifest, null, 2)
-      fs.writeFileSync(path.resolve(buildDir, "manifest.json"), manifestJson)
-
-      if (shouldZip) {
-        const zipName = `${manifest.id}-${pkg.version}.zip`
-        const filesToZip = ["manifest.json", bundleFile]
-
-        if (fs.existsSync(path.resolve(buildDir, "api.js"))) {
-          filesToZip.push("api.js")
-        }
-
-        const migrationsDest = path.resolve(buildDir, "migrations")
-        if (fs.existsSync(migrationsDest)) {
-          filesToZip.push("migrations")
-        }
-        const seedsDest = path.resolve(buildDir, "seeds")
-        if (fs.existsSync(seedsDest)) {
-          filesToZip.push("seeds")
-        }
-
-        execFileSync("tar", ["-a", "-cf", zipName, ...filesToZip], {
-          cwd: buildDir,
-          stdio: "inherit"
-        })
-        console.log(`Build Complete: ${manifest.id} v${pkg.version} → ${zipName}`)
-      }
-    }
-  }
-}
-
-export interface JchatAddonPluginOptions {
-  manifest: AddonManifest
-  zip?: boolean
-  signingPrivateKey?: string
-  /**
-   * Embed Tailwind CSS output into the JS bundle and scope it to the addon's DOM container.
-   * Defaults to `true`. Set to `false` only if the addon has no CSS.
-   */
-  css?: boolean
-}
-
-export function createAddonServerBuildArguments(
-  entryPath: string,
-  outputPath: string,
-  developmentBuild: boolean
-): string[] {
-  return [
-    "build",
-    entryPath,
-    "--target=bun",
-    "--format=esm",
-    `--outfile=${outputPath}`,
-    developmentBuild ? "--sourcemap=external" : "--minify"
-  ]
-}
-
-export function signAddonManifest(
-  manifest: AddonManifest,
-  files: readonly { path: string; contents: Buffer }[],
-  privateKey: string
-): AddonManifest {
-  if (!manifest.publisher?.id) throw new Error("Signed addons require manifest.publisher.id")
-  const unsigned: AddonManifest = {
-    ...manifest,
-    signature: { algorithm: "rsa-sha256", digest: "", value: "" }
-  }
-  const hash = crypto.createHash("sha256")
-  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
-    hash.update(file.path)
-    hash.update("\0")
-    hash.update(file.path === "manifest.json" ? stableStringify(unsigned) : file.contents)
-    hash.update("\0")
-  }
-  const digest = hash.digest("hex")
-  return {
-    ...unsigned,
-    signature: {
-      algorithm: "rsa-sha256",
-      digest,
-      value: crypto.sign("sha256", Buffer.from(digest), privateKey).toString("base64url")
-    }
-  }
-}
-
-export function requireAddonSigningKey(
-  signingPrivateKey: string | undefined,
-  developmentBuild: boolean
-): string | undefined {
-  if (signingPrivateKey) return signingPrivateKey
-  if (developmentBuild) return undefined
-  throw new Error("Database-bearing addon builds require JCHAT_ADDON_SIGNING_PRIVATE_KEY")
-}
-
-function embedCssIntoBundle(buildDir: string, addonId: string): void {
-  const files = fs.readdirSync(buildDir)
-  const cssFile = files.find((f) => f.endsWith(".css"))
-  const jsFile = files.find((f) => f.includes("ui") && f.endsWith(".js"))
-
-  if (!cssFile || !jsFile) return
-
-  const cssPath = path.join(buildDir, cssFile)
-  const jsPath = path.join(buildDir, jsFile)
-  let css = fs.readFileSync(cssPath, "utf-8")
-  const js = fs.readFileSync(jsPath, "utf-8")
-
-  if (css.length < 10) {
-    css = ""
-  } else {
-    // Strip out the host theme root and dark definitions to allow the addon to inherit them
-    css = css.replace(/:root\s*\{[^}]+\}/g, "")
-    css = css.replace(/\.dark\s*\{[^}]+\}/g, "")
-    css = css.replace(/\[data-theme=[^\]]+\]\s*\{[^}]+\}/g, "")
-    css = css.replace(/\.dark\s*\[data-theme=[^\]]+\]\s*\{[^}]+\}/g, "")
-
-    // Inject a base reset so addons don't default to currentColor (white in dark mode)
-    const resetCss = `*, ::before, ::after { border-color: var(--border); }`
-    css = `@scope (#addon-${addonId}) {\n${resetCss}\n${css}\n}`
-  }
-
-  // Inject the CSS into the head. Since addon styles are scoped,
-  // we don't need to force them to the top of the head.
-  const injection = `
-(function() {
-  if (typeof document !== 'undefined' && ${JSON.stringify(css)}.length > 0) {
-    const style = document.createElement('style');
-    style.type = 'text/css';
-    style.textContent = ${JSON.stringify(css)};
-    document.head.appendChild(style);
-  }
-})();
-`
-  fs.writeFileSync(jsPath, injection + js)
-  try {
-    fs.unlinkSync(cssPath)
-  } catch {
-    // ignore ENOENT if another plugin or build process already removed it
-  }
-}
-
-function stableStringify(value: unknown): string {
-  const sortValue = (child: unknown): unknown => {
-    if (Array.isArray(child)) return child.map(sortValue)
-    if (child && typeof child === "object") {
-      return Object.fromEntries(
-        Object.entries(child)
-          .sort(([left], [right]) => left.localeCompare(right))
-          .map(([key, nested]) => [key, sortValue(nested)])
-      )
-    }
-    return child
-  }
-  return JSON.stringify(sortValue(value))
-}