@jchat/addon-sdk 1.0.0-alpha.2 → 1.0.0-alpha.20

package/src/diagnostics.d.ts

@@ -1,19 +0,0 @@
-import type { AddonManifest } from "./contracts";
-export type AddonDiagnosticStatus = "pass" | "warning" | "error";
-export interface AddonPackageDiagnostic {
-    id: string;
-    label: string;
-    status: AddonDiagnosticStatus;
-    message: string;
-}
-export interface AddonPackageDiagnosticOptions {
-    buildDir: string;
-    manifest: AddonManifest;
-    jchatVersion: string;
-    addonSdkVersion: string;
-    productionPackage?: boolean;
-    maxBytes?: number;
-}
-export declare function createCompatibleMajorRange(version: string): string;
-export declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
-export declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;

package/src/diagnostics.test.ts

@@ -1,106 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import * as fs from "node:fs"
-import * as os from "node:os"
-import * as path from "node:path"
-import {
-  createCompatibleMajorRange,
-  diagnoseAddonPackage,
-  hasAddonDiagnosticErrors
-} from "./diagnostics"
-
-describe("addon package diagnostics", () => {
-  test("accepts compatible builds with every declared file", () => {
-    const buildDir = fs.mkdtempSync(path.join(os.tmpdir(), "jchat-addon-diagnostics-"))
-    fs.writeFileSync(path.join(buildDir, "ui.js"), "export default function Addon() {}")
-    fs.writeFileSync(path.join(buildDir, "api.js"), "export default () => {}")
-
-    try {
-      const diagnostics = diagnoseAddonPackage({
-        buildDir,
-        manifest: {
-          id: "sample-addon",
-          name: "Sample addon",
-          version: "1.0.0",
-          compatibility: {
-            jchat: ">=1.0.0-alpha.0 <2.0.0",
-            addonSdk: "^1.0.0"
-          },
-          frontend: { bundle: "./ui.js", mountPoints: ["chat-toolbar"] },
-          server: { bundle: "./api.js" }
-        },
-        jchatVersion: "1.0.0-alpha.0",
-        addonSdkVersion: "1.0.0"
-      })
-
-      expect(hasAddonDiagnosticErrors(diagnostics)).toBe(false)
-      expect(diagnostics.find(({ id }) => id === "jchat")?.status).toBe("pass")
-      expect(diagnostics.find(({ id }) => id === "server-bundle")?.status).toBe("pass")
-    } finally {
-      fs.rmSync(buildDir, { recursive: true })
-    }
-  })
-
-  test("reports incompatible versions, missing files, and unsafe references", () => {
-    const buildDir = fs.mkdtempSync(path.join(os.tmpdir(), "jchat-addon-diagnostics-"))
-    try {
-      const diagnostics = diagnoseAddonPackage({
-        buildDir,
-        manifest: {
-          id: "sample-addon",
-          name: "Sample addon",
-          version: "1.0.0",
-          compatibility: { jchat: "^2.0.0", addonSdk: "^1.0.0" },
-          frontend: { bundle: "../ui.js", mountPoints: [] },
-          server: { bundle: "./missing-api.js" }
-        },
-        jchatVersion: "1.0.0-alpha.0",
-        addonSdkVersion: "1.0.0"
-      })
-
-      expect(hasAddonDiagnosticErrors(diagnostics)).toBe(true)
-      expect(diagnostics.find(({ id }) => id === "jchat")?.status).toBe("error")
-      expect(diagnostics.find(({ id }) => id === "frontend-bundle")?.status).toBe("error")
-      expect(diagnostics.find(({ id }) => id === "server-bundle")?.status).toBe("error")
-    } finally {
-      fs.rmSync(buildDir, { recursive: true })
-    }
-  })
-
-  test("creates a prerelease-compatible range for the current major", () => {
-    expect(createCompatibleMajorRange("1.0.0-alpha.0")).toBe(">=1.0.0-alpha.0 <2.0.0")
-  })
-
-  test("rejects malformed versions using Bun semver validation", () => {
-    expect(() => createCompatibleMajorRange("1.invalid.0")).toThrow(
-      "Invalid semantic version: 1.invalid.0"
-    )
-  })
-
-  test("measures the distributable archive for production package size", () => {
-    const buildDir = fs.mkdtempSync(path.join(os.tmpdir(), "jchat-addon-diagnostics-"))
-    fs.writeFileSync(path.join(buildDir, "ui.js"), "unpacked content is intentionally larger")
-    fs.writeFileSync(path.join(buildDir, "sample-addon-1.0.0.zip"), "zip")
-
-    try {
-      const diagnostics = diagnoseAddonPackage({
-        buildDir,
-        manifest: {
-          id: "sample-addon",
-          name: "Sample addon",
-          version: "1.0.0",
-          compatibility: { jchat: "^1.0.0", addonSdk: "^1.0.0" },
-          frontend: { bundle: "./ui.js", mountPoints: ["chat-toolbar"] }
-        },
-        jchatVersion: "1.0.0",
-        addonSdkVersion: "1.0.0",
-        productionPackage: true,
-        maxBytes: 3
-      })
-
-      expect(diagnostics.find(({ id }) => id === "package-size")?.status).toBe("pass")
-      expect(diagnostics.find(({ id }) => id === "production-archive")?.status).toBe("pass")
-    } finally {
-      fs.rmSync(buildDir, { recursive: true })
-    }
-  })
-})

package/src/diagnostics.ts

@@ -1,182 +0,0 @@
-import * as fs from "node:fs"
-import * as path from "node:path"
-import type { AddonManifest } from "./contracts"
-
-export type AddonDiagnosticStatus = "pass" | "warning" | "error"
-
-export interface AddonPackageDiagnostic {
-  id: string
-  label: string
-  status: AddonDiagnosticStatus
-  message: string
-}
-
-export interface AddonPackageDiagnosticOptions {
-  buildDir: string
-  manifest: AddonManifest
-  jchatVersion: string
-  addonSdkVersion: string
-  productionPackage?: boolean
-  maxBytes?: number
-}
-
-export function createCompatibleMajorRange(version: string): string {
-  try {
-    Bun.semver.order(version, version)
-  } catch {
-    throw new Error(`Invalid semantic version: ${version}`)
-  }
-
-  const majorComponent = /^(?:v|=)?(\d+)\./.exec(version)?.[1]
-  const major = majorComponent ? Number(majorComponent) : Number.NaN
-  if (!Number.isSafeInteger(major)) throw new Error(`Invalid semantic version: ${version}`)
-
-  return `>=${version} <${major + 1}.0.0`
-}
-
-export function diagnoseAddonPackage(
-  options: AddonPackageDiagnosticOptions
-): AddonPackageDiagnostic[] {
-  const { buildDir, manifest } = options
-  const diagnostics: AddonPackageDiagnostic[] = []
-  diagnostics.push(
-    compatibilityDiagnostic(
-      "jchat",
-      "JChat compatibility",
-      options.jchatVersion,
-      manifest.compatibility?.jchat
-    ),
-    compatibilityDiagnostic(
-      "addon-sdk",
-      "Addon SDK compatibility",
-      options.addonSdkVersion,
-      manifest.compatibility?.addonSdk
-    )
-  )
-
-  const references = [
-    ["frontend-bundle", "Frontend bundle", manifest.frontend?.bundle],
-    ["server-bundle", "Server bundle", manifest.server?.bundle],
-    ...(manifest.server?.migrations ?? []).map(
-      (file) => [`migration:${file}`, `Migration ${file}`, file] as const
-    ),
-    ...(manifest.server?.seeds ?? []).map((file) => [`seed:${file}`, `Seed ${file}`, file] as const)
-  ] as const
-
-  for (const [id, label, reference] of references) {
-    if (!reference) continue
-    const file = resolveBuildFile(buildDir, reference)
-    diagnostics.push({
-      id,
-      label,
-      status: file && fs.existsSync(file) && fs.statSync(file).isFile() ? "pass" : "error",
-      message:
-        file && fs.existsSync(file) && fs.statSync(file).isFile()
-          ? reference
-          : `Missing or unsafe build file: ${reference}`
-    })
-  }
-
-  const files = listRegularFiles(buildDir)
-  const productionArchive = path.join(buildDir, `${manifest.id}-${manifest.version}.zip`)
-  const hasProductionArchive =
-    fs.existsSync(productionArchive) && fs.statSync(productionArchive).isFile()
-  const totalBytes =
-    options.productionPackage && hasProductionArchive
-      ? fs.statSync(productionArchive).size
-      : files
-          .filter((file) => file !== productionArchive)
-          .reduce((total, file) => total + fs.statSync(file).size, 0)
-  const maxBytes = options.maxBytes ?? 25 * 1024 * 1024
-  diagnostics.push({
-    id: "package-size",
-    label: "Package size",
-    status: totalBytes <= maxBytes ? "pass" : "error",
-    message: `${totalBytes} of ${maxBytes} bytes`
-  })
-
-  const sourceMaps = files.filter((file) => file.endsWith(".map"))
-  diagnostics.push({
-    id: "source-maps",
-    label: "Source maps",
-    status: options.productionPackage && sourceMaps.length ? "warning" : "pass",
-    message: sourceMaps.length ? `${sourceMaps.length} source map(s) present` : "No source maps"
-  })
-
-  const hasDatabaseFiles = Boolean(
-    manifest.server?.migrations?.length || manifest.server?.seeds?.length
-  )
-  diagnostics.push({
-    id: "database-signature",
-    label: "Database file signature",
-    status:
-      hasDatabaseFiles && options.productionPackage && !manifest.signature?.value
-        ? "error"
-        : hasDatabaseFiles && !manifest.signature?.value
-          ? "warning"
-          : "pass",
-    message:
-      hasDatabaseFiles && !manifest.signature?.value
-        ? options.productionPackage
-          ? "Production database files require a publisher signature"
-          : "Unsigned database files are allowed only in the developer sandbox"
-        : hasDatabaseFiles
-          ? "Publisher signature present"
-          : "No database files declared"
-  })
-
-  if (options.productionPackage) {
-    diagnostics.push({
-      id: "production-archive",
-      label: "Production archive",
-      status: hasProductionArchive ? "pass" : "error",
-      message: hasProductionArchive
-        ? path.basename(productionArchive)
-        : "Production archive is missing"
-    })
-  }
-
-  return diagnostics
-}
-
-export function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean {
-  return diagnostics.some(({ status }) => status === "error")
-}
-
-function compatibilityDiagnostic(
-  id: string,
-  label: string,
-  version: string,
-  range: string | undefined
-): AddonPackageDiagnostic {
-  const compatible = Boolean(range && Bun.semver.satisfies(version, range))
-  return {
-    id,
-    label,
-    status: compatible ? "pass" : "error",
-    message: range
-      ? `${version} ${compatible ? "satisfies" : "does not satisfy"} ${range}`
-      : "Compatibility range is missing"
-  }
-}
-
-function resolveBuildFile(buildDir: string, reference: string): string | null {
-  if (
-    path.isAbsolute(reference) ||
-    reference.includes("\\") ||
-    reference.split("/").includes("..")
-  ) {
-    return null
-  }
-  const target = path.resolve(buildDir, ...reference.replace(/^\.\//, "").split("/"))
-  const relative = path.relative(path.resolve(buildDir), target)
-  return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? target : null
-}
-
-function listRegularFiles(root: string): string[] {
-  if (!fs.existsSync(root)) return []
-  return fs
-    .readdirSync(root, { recursive: true, withFileTypes: true })
-    .filter((entry) => entry.isFile())
-    .map((entry) => path.join(entry.parentPath, entry.name))
-}

package/src/index.d.ts

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

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