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

package/dist/index2.d.mts

@@ -0,0 +1,478 @@
+import { i as IconPack, n as IconComponent, r as IconName } from "./types.mjs";
+import { AddonManifest, AddonPermissionDefinition, MOUNT_POINTS, MountPoint } from "./contracts.mjs";
+import { InfiniteData, MutationFunction, QueryFunction, QueryFunctionContext, QueryKey, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryResult, useQueryClient } from "@tanstack/react-query";
+import { Elysia, t } from "elysia";
+import { ColumnType, Generated, Insertable, JSONColumnType, Kysely, Selectable, Updateable } from "kysely";
+//#region src/i18n.d.ts
+export declare const HOST_LANGUAGES: readonly ["ar", "bg", "hr", "de", "el", "en", "es", "fr", "he", "hi", "kn", "ml", "nl", "pt", "ro", "ru", "ta", "te", "tr", "ur"];
+export type HostLanguage = (typeof HOST_LANGUAGES)[number];
+export type AddonTranslationDictionary = Record<string, unknown>;
+export type AddonTranslationResources = Record<string, AddonTranslationDictionary>;
+export type AddonLocaleLoader = (locale: string) => Promise<AddonTranslationDictionary> | AddonTranslationDictionary;
+export interface LocaleContextValue {
+  locale: string;
+  dir: "ltr" | "rtl";
+}
+export declare const LocaleContext: import("react").Context<LocaleContextValue>;
+export interface TranslatorOptions {
+  resources?: AddonTranslationResources;
+  defaultLocale?: string;
+  fallbackLocale?: string;
+}
+export type TranslateFunction<TKeys extends string = string> = (key: TKeys | (string & {}), paramsOrLang?: Record<string, unknown> | string, maybeLang?: string) => string;
+/**
+ * Creates a standalone translation function for backend server routes (`src/api.ts`) or utilities.
+ *
+ * @param resources - Dictionary of translation resources (e.g., `{ en: enJson, ta: taJson }`).
+ * @param defaultLocale - Default locale to use if not specified per call (defaults to "en").
+ * @param fallbackLocale - Fallback locale if a key is missing in the target language (defaults to
+ *   "en").
+ */
+export declare function createTranslator<TResources extends AddonTranslationResources = AddonTranslationResources>(resources?: TResources, defaultLocale?: string, fallbackLocale?: string): TranslateFunction<TResources extends {
+  en: infer TEn;
+} ? TEn extends Record<string, unknown> ? Extract<keyof TEn, string> : string : string>;
+/**
+ * Hook to access the current active host locale and text direction in an addon component.
+ *
+ * @example
+ *   ;```tsx
+ *   import { useLocale } from "@jchat/addon-sdk"
+ *
+ *   export default function MyAddon() {
+ *     const { locale, dir, isRtl } = useLocale()
+ *     return <div dir={dir}>Current language: {locale}</div>
+ *   }
+ *   ```
+ */
+export declare function useLocale(): {
+  locale: string;
+  dir: "ltr" | "rtl";
+  isRtl: boolean;
+};
+/**
+ * Hook to access translation function and locale metadata inside addon components. Automatically
+ * synchronizes with host language switches and falls back to English. Supports static dictionary
+ * resources or dynamic async locale loaders.
+ *
+ * @example
+ *   ;```tsx
+ *   import { useTranslation } from "@jchat/addon-sdk"
+ *   import locales from "./locales"
+ *
+ *   export default function MyAddon() {
+ *     const { t, locale, dir } = useTranslation(locales)
+ *     return (
+ *       <div dir={dir}>
+ *         <h1>{t("welcome", { name: "Guest" })}</h1>
+ *       </div>
+ *     )
+ *   }
+ *   ```
+ *
+ * @param resourcesOrLoader - Addon-scoped translation dictionaries or async chunk loader.
+ * @param fallbackLocale - Fallback language code when a string is missing (default: "en").
+ */
+export declare function useTranslation<TResources extends AddonTranslationResources | AddonLocaleLoader = AddonTranslationResources>(resourcesOrLoader?: TResources, fallbackLocale?: string): {
+  t: TranslateFunction<TResources extends {
+    en: infer TEn;
+  } ? TEn extends Record<string, unknown> ? Extract<keyof TEn, string> : string : string>;
+  locale: string;
+  dir: "ltr" | "rtl";
+  isRtl: boolean;
+  isReady: boolean;
+};
+//#endregion
+//#region src/query.d.ts
+export interface UseAddonQueryOptions<TData = unknown, TError = Error> extends Omit<UndefinedInitialDataOptions<TData, TError, TData, QueryKey>, "queryKey" | "queryFn"> {
+  /** The API path to fetch, automatically prefixed with `/api/v1/addons/<addonId>` */
+  path?: string;
+  /** Custom query key elements appended to the automatic path cache key */
+  queryKey?: QueryKey;
+  /** Custom query function override */
+  queryFn?: QueryFunction<TData, QueryKey>;
+}
+export interface UseAddonMutationOptions<TData = unknown, TVariables = unknown, TError = Error, TContext = unknown> extends Omit<UseMutationOptions<TData, TError, TVariables, TContext>, "mutationFn"> {
+  /** The target API path, or a dynamic function of mutation variables */
+  path?: string | ((variables: TVariables) => string);
+  /** HTTP method to use (defaults to 'POST') */
+  method?: "POST" | "PUT" | "DELETE";
+  /** Query keys to automatically invalidate upon successful mutation */
+  invalidateQueries?: QueryKey[];
+  /** Custom mutation function override */
+  mutationFn?: MutationFunction<TData, TVariables>;
+}
+export interface UseAddonInfiniteQueryOptions<TData = unknown, TError = Error, TPageParam = unknown> extends Omit<UndefinedInitialDataInfiniteOptions<TData, TError, InfiniteData<TData, TPageParam>, QueryKey, TPageParam>, "queryKey" | "queryFn"> {
+  /** The API path to fetch, or a dynamic function that receives pageParam and returns the path */
+  path?: string | ((pageParam: TPageParam) => string);
+  /** Custom query key elements appended to the automatic cache key */
+  queryKey?: QueryKey;
+  /** Custom query function override */
+  queryFn?: (context: QueryFunctionContext<QueryKey, TPageParam>) => Promise<TData>;
+}
+/**
+ * Perform a declarative, cached GET request using the host's shared React Query instance.
+ * Automatically injects authentication headers and prefixes addon paths.
+ *
+ * @example
+ *   ;```tsx
+ *   const { data, isLoading } = useAddonQuery<{ polls: Poll[] }>({
+ *     path: "/polls",
+ *     queryKey: [siteId]
+ *   })
+ *   ```
+ */
+export declare function useAddonQuery<TData = unknown, TError = Error>(options: UseAddonQueryOptions<TData, TError>): UseQueryResult<TData, TError>;
+/**
+ * Perform a paginated or infinite scrolling request using the host's shared React Query instance.
+ *
+ * @example
+ *   ;```tsx
+ *   const { data, fetchNextPage, hasNextPage } = useAddonInfiniteQuery<GifResponse, Error, number>({
+ *   path: (page) => `/trending?offset=${page * 20}`,
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage, allPages) => (lastPage.hasMore ? allPages.length : undefined)
+ *   })
+ *   ```
+ */
+export declare function useAddonInfiniteQuery<TData = unknown, TError = Error, TPageParam = unknown>(options: UseAddonInfiniteQueryOptions<TData, TError, TPageParam>): UseInfiniteQueryResult<InfiniteData<TData, TPageParam>, TError>;
+/**
+ * Perform a declarative mutation using the host's shared React Query instance. Automatically
+ * executes the request and can invalidate specified query keys upon success.
+ *
+ * @example
+ *   ;```tsx
+ *   const { mutate, isPending } = useAddonMutation<Poll, CreatePollInput>({
+ *     path: "/polls",
+ *     method: "POST",
+ *     invalidateQueries: [["/polls"]],
+ *     onSuccess: () => sdk.toast("Poll created!", "success")
+ *   })
+ *   ```
+ */
+export declare function useAddonMutation<TData = unknown, TVariables = unknown, TError = Error, TContext = unknown>(options: UseAddonMutationOptions<TData, TVariables, TError, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;
+//#endregion
+//#region src/index.d.ts
+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">;
+/**
+ * Scoped caching and key-value client provided to addon server instances. Keys are automatically
+ * namespaced by the host as `addon:<addonId>:<key>`.
+ */
+export interface AddonCacheClient {
+  /** Retrieve a string or JSON-parsed value by key */
+  get: <T = string>(key: string) => Promise<T | null>;
+  /** Store a value with an optional time-to-live in seconds */
+  set: (key: string, value: unknown, ttlSeconds?: number) => Promise<void>;
+  /** Delete one or more keys */
+  del: (...keys: string[]) => Promise<number>;
+  /** Atomically increment a numeric counter and return the new value */
+  incr: (key: string) => Promise<number>;
+  /** Set a timeout on a key in seconds */
+  expire: (key: string, ttlSeconds: number) => Promise<boolean>;
+  /** Get the remaining time-to-live of a key in seconds (-2 if key does not exist, -1 if no TTL) */
+  ttl: (key: string) => Promise<number>;
+}
+export interface AddonServerEmitTarget {
+  /** Target a specific site (defaults to the request user's siteId) */
+  siteId?: string;
+  /** Target a specific chat room */
+  roomId?: string;
+  /** Target a specific user */
+  userId?: string;
+}
+/**
+ * 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>>> {
+  /**
+   * Elysia / TypeBox schema validator for defining route validation schemas (`body`, `query`,
+   * `params`, `headers`). Provided directly by the host runtime so your addon server bundle does
+   * not need to bundle Elysia.
+   */
+  t: typeof t;
+  /**
+   * 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: string) => 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>;
+  /** A secure, namespaced key-value cache client scoped to your addon (`addon:<addonId>:<key>`). */
+  cache: AddonCacheClient;
+  /**
+   * Broadcast a real-time event to connected clients across the site or room. Clients listen via
+   * `sdk.events.on('addon:<addonId>:<event>', callback)` or `sdk.events.on(event, callback)`.
+   */
+  emit: (event: string, payload: unknown, target?: AddonServerEmitTarget) => Promise<void>;
+}
+/**
+ * Elysia app instance provided to addon server endpoints with Jchat macro metadata (e.g.
+ * requirePermission) typed.
+ */
+export type AddonApp = Elysia<"", {
+  decorator: {};
+  store: {};
+  derive: {};
+  resolve: {
+    user: AddonRequestUser;
+  };
+}, {
+  typebox: {};
+  error: {};
+}, {
+  schema: {};
+  standaloneSchema: {};
+  macro: {
+    requirePermission?: string | string[];
+  };
+  macroFn: {};
+  parser: {};
+  response: {};
+}>;
+/**
+ * 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: AddonApp) => 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;
+  /** The active user locale (e.g. 'en', 'ta', 'ar') */
+  locale?: string;
+  /** Text direction for the current locale */
+  dir?: "ltr" | "rtl";
+}
+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>;
+}
+/** First-class addon settings management interface provided by the host. */
+export interface AddonSettingsApi {
+  /** Fetch the current site's saved configuration for this addon */
+  get: <T = Record<string, unknown>>() => Promise<T | null>;
+  /** Save updated configuration for this addon for the current site */
+  save: <T = Record<string, unknown>>(settings: T) => Promise<void>;
+}
+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. Relative paths
+   * are automatically prefixed with `/api/v1/addons/<addonId>`.
+   */
+  api: AddonApi;
+  /**
+   * First-class settings API to load and save addon configuration without boilerplate path
+   * construction.
+   */
+  settings: AddonSettingsApi;
+  /**
+   * 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[];
+  /** The active user locale (e.g. 'en', 'ta', 'ar') */
+  locale: string;
+  /** Text direction for the active locale ('ltr' or 'rtl') */
+  dir: "ltr" | "rtl";
+}
+/**
+ * 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;
+/**
+ * Get the version of the addon SDK. This is useful for checking compatibility with the host
+ * application.
+ *
+ * @example
+ *   ;```tsx
+ *   import { getAddonSdkVersion } from "@jchat/addon-sdk"
+ *
+ *   console.log(getAddonSdkVersion())
+ *   ```
+ *
+ * @returns
+ */
+export declare function getAddonSdkVersion(): string;
+//#endregion
+export { type AddonManifest, type AddonPermissionDefinition, type ColumnType, type Generated, type IconComponent, type IconName, type IconPack, type InfiniteData, type Insertable, type JSONColumnType, MOUNT_POINTS, type MountPoint, type QueryKey, type Selectable, type Updateable, useQueryClient };

package/dist/state.d.mts

@@ -0,0 +1 @@
+export * from "jotai";

package/dist/state.mjs

@@ -0,0 +1,2 @@
+export * from "jotai";
+export {};

package/dist/types.d.mts

@@ -0,0 +1,12 @@
+import { ComponentType, SVGProps } from "react";
+import { icons } from "lucide-react";
+//#region ../icon/dist/types.d.mts
+//#region src/types.d.ts
+type IconComponent = ComponentType<SVGProps<SVGSVGElement>>;
+type LucideIconName = keyof typeof icons;
+type IconName = LucideIconName | "Youtube";
+declare const ICON_NAMES: readonly IconName[];
+type IconPack = Record<IconName, IconComponent>;
+//#endregion
+//#endregion
+export { IconPack as i, IconComponent as n, IconName as r, ICON_NAMES as t };

package/dist/ui.d.mts

@@ -0,0 +1 @@
+export * from "@jchat/ui";

package/dist/ui.mjs

@@ -0,0 +1,2 @@
+export * from "@jchat/ui";
+export {};

package/dist/vite.d.mts

@@ -1,14 +1,44 @@
-import { t as AddonManifest } from "./contracts.mjs";
+import { AddonManifest } from "./contracts.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 /**
- * Vite plugin to configure Jchat addon manifest generation, bundle backend scripts, copy
- * migrations, declarative seed data, and zip production build artifacts.
+ * Vite plugin for building JChat sandboxed addon extensions.
+ *
+ * Configures automatic manifest generation (`manifest.json`), bundles server-side API scripts
+ * (`src/api.ts`), embeds scoped Tailwind CSS into the frontend bundle, packages database migrations
+ * and seed files, copies documentation (`README.md`), signs database-bearing addon manifests, and
+ * zips production build artifacts.
+ *
+ * @example
+ *   ;```ts
+ *   import { jchatAddon } from "@jchat/addon-sdk/vite"
+ *   import manifest from "./src/manifest"
+ *   import { defineConfig } from "vite"
+ *
+ *   export default defineConfig({
+ *     plugins: [jchatAddon({ manifest })]
+ *   })
+ *   ```
+ *
+ * @param options - Configuration options for the JChat addon Vite plugin.
+ * @returns A Vite {@link Plugin} instance configured for addon compilation.
  */
-declare function jchatAddon(options: JchatAddonPluginOptions): Plugin;
-interface JchatAddonPluginOptions {
+export declare function jchatAddon(options: JchatAddonPluginOptions): Plugin;
+/** Configuration options for the {@link jchatAddon} Vite plugin. */
+export interface JchatAddonPluginOptions {
+  /** The base manifest specification for the addon. */
   manifest: AddonManifest;
+  /** Explicitly declare development mode to permit unsigned database-bearing builds. */
+  development?: boolean;
+  /**
+   * Whether to package the build output into a `.zip` archive upon build completion. Defaults to
+   * `true` during production builds and `false` during development builds.
+   */
   zip?: boolean;
+  /**
+   * Optional RSA private key string used to cryptographically sign database-bearing addons. If
+   * omitted, falls back to the `JCHAT_ADDON_SIGNING_PRIVATE_KEY` environment variable.
+   */
   signingPrivateKey?: string;
   /**
    * Embed Tailwind CSS output into the JS bundle and scope it to the addon's DOM container.
@@ -16,11 +46,35 @@ interface JchatAddonPluginOptions {
    */
   css?: boolean;
 }
-declare function createAddonServerBuildArguments(entryPath: string, outputPath: string, developmentBuild: boolean): string[];
-declare function signAddonManifest(manifest: AddonManifest, files: readonly {
+/**
+ * Generates CLI argument parameters for bundling server-side Elysia API scripts (`src/api.ts`) via
+ * Bun.
+ *
+ * @param entryPath - Absolute file path to the server entry script (`src/api.ts`).
+ * @param outputPath - Absolute destination file path for the bundled output (`build/api.js`).
+ * @param developmentBuild - Indicates whether to enable external sourcemaps or minification.
+ * @returns Array of command line arguments for running `bun build`.
+ */
+export declare function createAddonServerBuildArguments(entryPath: string, outputPath: string, developmentBuild: boolean): string[];
+/**
+ * Cryptographically signs an addon manifest using RSA-SHA256 over all archive file contents.
+ *
+ * @param manifest - Unsigned or base addon manifest.
+ * @param files - List of archive file paths and raw contents to digest.
+ * @param privateKey - RSA private key in PEM format.
+ * @returns Updated {@link AddonManifest} containing an RSA signature block.
+ */
+export declare function signAddonManifest(manifest: AddonManifest, files: readonly {
   path: string;
   contents: Buffer;
 }[], privateKey: string): AddonManifest;
-declare function requireAddonSigningKey(signingPrivateKey: string | undefined, developmentBuild: boolean): string | undefined;
-//#endregion
-export { JchatAddonPluginOptions, createAddonServerBuildArguments, jchatAddon, requireAddonSigningKey, signAddonManifest };
+/**
+ * Resolves the required RSA signing key for database-bearing addons.
+ *
+ * @param signingPrivateKey - Provided signing key or undefined.
+ * @param developmentBuild - Whether the current build is targeting development mode.
+ * @returns Resolved signing key string or undefined (in dev builds).
+ * @throws {@link Error} If building a database-bearing addon in production without a signing key.
+ */
+export declare function requireAddonSigningKey(signingPrivateKey: string | undefined, developmentBuild: boolean): string | undefined;
+//#endregion