@jchat/addon-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Md. Jabarullah
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,45 @@
+# @jchat/addon-sdk
+
+TypeScript SDK for building [JChat](https://jchat.app) addons.
+
+Provides types, interfaces, and Vite build helpers for addon developers. This package is always
+**externalised** from addon bundles — the JChat host app provides the runtime implementation at
+load time.
+
+## Installation
+
+```bash
+npm install @jchat/addon-sdk
+# or
+bun add @jchat/addon-sdk
+```
+
+## Requirements
+
+- Node.js 20+ or Bun 1.3+
+- React 18+, Elysia, Kysely, and Vite as peer dependencies
+
+## Usage
+
+```ts
+import type {
+  AddonManifest,
+  AddonServerContext,
+  AddonClientContext,
+  AddonProps,
+} from "@jchat/addon-sdk"
+```
+
+For the Vite build plugin:
+
+```ts
+import { jchatAddon } from "@jchat/addon-sdk/vite"
+
+export default {
+  plugins: [jchatAddon()],
+}
+```
+
+## License
+
+Apache-2.0

package/dist/contracts.d.mts

@@ -0,0 +1,130 @@
+//#region src/contracts.d.ts
+type AddonPermission = string;
+/**
+ * Defines a single configuration field for an addon's settings panel. These are shown to site
+ * admins in the Jchat dashboard.
+ */
+interface ConfigSchemaField {
+  /** Unique key used to store and retrieve the value in `getConfig` */
+  key: string;
+  /** Data type for validation and UI rendering */
+  type: "string" | "number" | "boolean";
+  /** Human-readable label shown in the settings UI */
+  label: string;
+  /** If true, the admin must provide a value before saving */
+  required?: boolean;
+  /** Whether the value is sensitive (encrypted at rest and masked in the UI) */
+  secret?: boolean;
+  /** Default value pre-filled in the settings form for new installations */
+  default?: string | number | boolean;
+}
+/** Definition of a custom permission introduced by an addon. */
+interface AddonPermissionDefinition {
+  /** Permission identifier (recommended: `addon.<id>.<action>`) */
+  name: string;
+  /** Short, human-readable name for the permission */
+  label: string;
+  /** Detailed description of what the permission grants (shown in Rank editor) */
+  description: string;
+}
+/** Valid locations where an addon can be rendered within the Jchat layout. */
+declare const MOUNT_POINTS: {
+  /** Top of the main chat column */
+  readonly CHAT_HEADER: "chat-header";
+  /** Below the main chat header, above messages */
+  readonly CHAT_TOOLBAR: "chat-toolbar";
+  /** The persistent right-side sidebar */
+  readonly CHAT_SIDEBAR: "chat-sidebar";
+  /** Top of the left sidebar (room list) */
+  readonly SIDEBAR_TOP: "sidebar-top";
+  /** Bottom of the left sidebar */
+  readonly SIDEBAR_BOTTOM: "sidebar-bottom";
+  /** Action list shown when clicking a user's avatar */
+  readonly USER_POPOVER_ACTIONS: "user-popover-actions";
+  /** Menu shown when right-clicking a message */
+  readonly MESSAGE_CONTEXT_MENU: "message-context-menu";
+  /** Floating overlay rendered on top of the message stream */
+  readonly MESSAGE_FEED_OVERLAY: "message-feed-overlay";
+  /** Main admin dashboard area */
+  readonly ADMIN_PANEL: "admin-panel";
+  /** User or site settings dashboard area */
+  readonly SETTINGS_PANEL: "settings-panel";
+  /** The 'plus' (+) menu in the message composer */
+  readonly CHAT_PLUS_MENU: "chat-plus-menu";
+  /** Custom tab in the emoji/gif selection panel */
+  readonly EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab";
+  /** Full-screen or modal dialog specifically for TubeScan */
+  readonly TUBESCAN_DIALOG: "tubescan-dialog";
+};
+/** Union type of all valid addon mount points. */
+type MountPoint = (typeof MOUNT_POINTS)[keyof typeof MOUNT_POINTS];
+/**
+ * The `manifest.json` schema required for every Jchat addon. This file describes how the addon is
+ * identified and mounted.
+ */
+interface AddonManifest {
+  /** Unique kebab-case addon identifier (must match the folder name) */
+  id: string;
+  /** Human-readable addon name */
+  name: string;
+  /** Semver version string (e.g. `1.2.0`) */
+  version: string;
+  /** Brief summary of what the addon does */
+  description?: string;
+  /** Author name, organization, or GitHub handle */
+  author?: string;
+  /** Support or documentation URL */
+  homepage?: string;
+  /** SPDX license identifier (e.g. `MIT`) */
+  license?: string;
+  /** Host and SDK versions this directly executed plugin was built and tested against */
+  compatibility: {
+    /** Supported JChat versions as a semantic-version range, for example `^1.0.0` */
+    jchat: string;
+    /** Supported `@jchat/addon-sdk` versions as a semantic-version range */
+    addonSdk: string;
+  };
+  /** Identity of the trusted publisher that signed this package. Required when migrations exist */
+  publisher?: {
+    id: string;
+  };
+  /** Signature over the canonical archive digest. Required when migrations exist */
+  signature?: {
+    algorithm: "rsa-sha256";
+    digest: string;
+    value: string;
+  };
+  /** Configuration for the React-based frontend bundle */
+  frontend?: {
+    /** Relative path to the pre-compiled ESM bundle (created by Vite) */
+    bundle: string;
+    /** List of UI locations where this addon should be active */
+    mountPoints: MountPoint[];
+    /** Optional path to a specific UI for the settings panel */
+    settings?: string;
+    /** Additional shared packages this addon imports from the host */
+    externals?: string[];
+  };
+  /** Configuration for the server-side API bundle */
+  server?: {
+    /** Relative path to the pre-compiled server bundle */
+    bundle?: string;
+    /** List of SQL files to run (in order) to set up the addon's database tables */
+    migrations?: string[];
+    /** List of declarative JSON master-data files to apply once, in order */
+    seeds?: string[];
+  };
+  /**
+   * The minimum permission required to see or use this addon. If provided, the host gates
+   * visibility in the UI and access to all server routes.
+   */
+  accessPermission?: AddonPermission;
+  /** Full list of all permissions used by this addon for informational purposes */
+  permissions?: AddonPermission[];
+  /** Custom permissions that should be registered with the host application on installation */
+  permissionDefinitions?: AddonPermissionDefinition[];
+  /** Settings form structure shown to site admins. Values are stored encrypted per site */
+  configSchema?: ConfigSchemaField[];
+}
+//#endregion
+export { MOUNT_POINTS as a, ConfigSchemaField as i, AddonPermission as n, MountPoint as o, AddonPermissionDefinition as r, AddonManifest as t };

package/dist/diagnostics.d.mts

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

package/dist/diagnostics.mjs

@@ -0,0 +1 @@
+import*as e from"node:fs";import*as t from"node:path";function n(e){try{Bun.semver.order(e,e)}catch{throw Error(`Invalid semantic version: ${e}`)}let t=/^(?:v|=)?(\d+)\./.exec(e)?.[1],n=t?Number(t):NaN;if(!Number.isSafeInteger(n))throw Error(`Invalid semantic version: ${e}`);return`>=${e} <${n+1}.0.0`}function r(n){let{buildDir:r,manifest:i}=n,c=[];c.push(a(`jchat`,`JChat compatibility`,n.jchatVersion,i.compatibility?.jchat),a(`addon-sdk`,`Addon SDK compatibility`,n.addonSdkVersion,i.compatibility?.addonSdk));let l=[[`frontend-bundle`,`Frontend bundle`,i.frontend?.bundle],[`server-bundle`,`Server bundle`,i.server?.bundle],...(i.server?.migrations??[]).map(e=>[`migration:${e}`,`Migration ${e}`,e]),...(i.server?.seeds??[]).map(e=>[`seed:${e}`,`Seed ${e}`,e])];for(let[t,n,i]of l){if(!i)continue;let a=o(r,i);c.push({id:t,label:n,status:a&&e.existsSync(a)&&e.statSync(a).isFile()?`pass`:`error`,message:a&&e.existsSync(a)&&e.statSync(a).isFile()?i:`Missing or unsafe build file: ${i}`})}let u=s(r),d=t.join(r,`${i.id}-${i.version}.zip`),f=e.existsSync(d)&&e.statSync(d).isFile(),p=n.productionPackage&&f?e.statSync(d).size:u.filter(e=>e!==d).reduce((t,n)=>t+e.statSync(n).size,0),m=n.maxBytes??25*1024*1024;c.push({id:`package-size`,label:`Package size`,status:p<=m?`pass`:`error`,message:`${p} of ${m} bytes`});let h=u.filter(e=>e.endsWith(`.map`));c.push({id:`source-maps`,label:`Source maps`,status:n.productionPackage&&h.length?`warning`:`pass`,message:h.length?`${h.length} source map(s) present`:`No source maps`});let g=!!(i.server?.migrations?.length||i.server?.seeds?.length);return c.push({id:`database-signature`,label:`Database file signature`,status:g&&n.productionPackage&&!i.signature?.value?`error`:g&&!i.signature?.value?`warning`:`pass`,message:g&&!i.signature?.value?n.productionPackage?`Production database files require a publisher signature`:`Unsigned database files are allowed only in the developer sandbox`:g?`Publisher signature present`:`No database files declared`}),n.productionPackage&&c.push({id:`production-archive`,label:`Production archive`,status:f?`pass`:`error`,message:f?t.basename(d):`Production archive is missing`}),c}function i(e){return e.some(({status:e})=>e===`error`)}function a(e,t,n,r){let i=!!(r&&Bun.semver.satisfies(n,r));return{id:e,label:t,status:i?`pass`:`error`,message:r?`${n} ${i?`satisfies`:`does not satisfy`} ${r}`:`Compatibility range is missing`}}function o(e,n){if(t.isAbsolute(n)||n.includes(`\\`)||n.split(`/`).includes(`..`))return null;let r=t.resolve(e,...n.replace(/^\.\//,``).split(`/`)),i=t.relative(t.resolve(e),r);return i&&!i.startsWith(`..`)&&!t.isAbsolute(i)?r:null}function s(n){return e.existsSync(n)?e.readdirSync(n,{recursive:!0,withFileTypes:!0}).filter(e=>e.isFile()).map(e=>t.join(e.parentPath,e.name)):[]}export{n as createCompatibleMajorRange,r as diagnoseAddonPackage,i as hasAddonDiagnosticErrors};

package/dist/index.d.mts

@@ -0,0 +1,240 @@
+import { a as MOUNT_POINTS, i as ConfigSchemaField, n as AddonPermission, o as MountPoint, r as AddonPermissionDefinition, t as AddonManifest } from "./contracts.mjs";
+import { ComponentType, SVGProps } from "react";
+import { Elysia } from "elysia";
+import { Kysely } from "kysely";
+//#region ../icon/dist/index.d.mts
+//#region src/types.d.ts
+type IconComponent = ComponentType<SVGProps<SVGSVGElement>>;
+declare const ICON_NAMES: readonly ["ProfileMen", "ProfileWomen", "Stories", "Search", "AdminPanel", "Investigation", "Logout", "Users", "Settings", "RoomList", "AdminShip", "Announcement", "NewsFeed", "Ranks", "TopPoints", "Like", "DisLike", "Love", "Funny", "Comment", "Chat", "Brush", "Image", "Mic", "More", "Palette", "Smiley", "Send", "Private", "Action", "View", "Female", "Male", "LuSend", "Heart", "Trash", "HorizontalOption", "Menu", "UserGroup", "Globe", "Plus", "Loader", "X", "UserRoundPlus", "Footprints", "Calendar", "Volume", "Youtube", "Upload", "Play", "Pause", "Stop", "Ok", "ImageFill", "MicFill", "YoutubeFill", "PlusFill", "Music", "Gift", "Camera", "Envelope", "Key", "Signature", "UserPen", "Edit", "AddressCard", "Star", "StatusOnline", "StatusAway", "StatusBusy", "StatusEating", "StatusGaming", "StatusSinging", "StatusListening", "StatusStay"];
+type IconName = (typeof ICON_NAMES)[number];
+type IconPack = Record<IconName, IconComponent>;
+//#endregion
+//#region src/index.d.ts
+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. */
+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;
+}
+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.
+ */
+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>`.
+ */
+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
+ *   ```
+ */
+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. */
+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;
+}
+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>;
+}
+type AddonEventListener = (data: unknown) => void;
+/**
+ * The bridge between your addon and the Jchat host application. Use the `useAddonSDK()` hook to
+ * access this interface in your components.
+ */
+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;
+  };
+}
+/**
+ * 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.
+ */
+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. */
+declare function defineAddonManifest<const TManifest extends AddonManifest>(manifest: TManifest): TManifest;
+/** Define a typed server factory without widening its addon database interface. */
+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")
+ *     }
+ *   }
+ *   ```
+ */
+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" />
+ *   }
+ *   ```
+ */
+declare function useIcons(): {
+  Icons: IconPack;
+};
+//#endregion
+export { AddonApi, AddonDatabase, AddonEventListener, AddonJsonBody, type AddonManifest, type AddonPermission, type AddonPermissionDefinition, AddonProps, AddonRequestUser, AddonSDK, AddonSeedDocument, AddonServerContext, AddonServerFactory, AddonUser, type ConfigSchemaField, MOUNT_POINTS, type MountPoint, defineAddonManifest, defineAddonServer, useAddonSDK, useIcons };

package/dist/index.mjs

@@ -0,0 +1 @@
+const e={CHAT_HEADER:`chat-header`,CHAT_TOOLBAR:`chat-toolbar`,CHAT_SIDEBAR:`chat-sidebar`,SIDEBAR_TOP:`sidebar-top`,SIDEBAR_BOTTOM:`sidebar-bottom`,USER_POPOVER_ACTIONS:`user-popover-actions`,MESSAGE_CONTEXT_MENU:`message-context-menu`,MESSAGE_FEED_OVERLAY:`message-feed-overlay`,ADMIN_PANEL:`admin-panel`,SETTINGS_PANEL:`settings-panel`,CHAT_PLUS_MENU:`chat-plus-menu`,EMOJI_PICKER_GIF_TAB:`emoji-picker-gif-tab`,TUBESCAN_DIALOG:`tubescan-dialog`};function t(e){return e}function n(e){return e}function r(){throw Error(`AddonSDK must be used within the Jchat host environment.`)}function i(){throw Error(`useIcons must be used within the Jchat host environment.`)}export{e as MOUNT_POINTS,t as defineAddonManifest,n as defineAddonServer,r as useAddonSDK,i as useIcons};

package/dist/vite.d.mts

@@ -0,0 +1,29 @@
+import { t as AddonManifest } from "./contracts.mjs";
+import { Plugin } from "vite";
+//#region src/vite.d.ts
+interface EmbedCssOptions {
+  id?: string;
+}
+/**
+ * Vite plugin that gathers CSS styles generated by Tailwind CSS and embeds them directly inside the
+ * main UI JavaScript bundle at the top, avoiding the need to load external stylesheet files.
+ */
+declare function jchatEmbedCss(options?: EmbedCssOptions): Plugin;
+interface JchatAddonPluginOptions {
+  manifest: AddonManifest;
+  zip?: boolean;
+  signingPrivateKey?: string;
+}
+declare function createAddonServerBuildArguments(entryPath: string, outputPath: string, developmentBuild: boolean): string[];
+declare function signAddonManifest(manifest: AddonManifest, files: readonly {
+  path: string;
+  contents: Buffer;
+}[], privateKey: string): AddonManifest;
+declare function requireAddonSigningKey(signingPrivateKey: string | undefined, developmentBuild: boolean): string | undefined;
+/**
+ * Vite plugin to configure Jchat addon manifest generation, bundle backend scripts, copy
+ * migrations, declarative seed data, and zip production build artifacts.
+ */
+declare function jchatAddon(options: JchatAddonPluginOptions): Plugin;
+//#endregion
+export { EmbedCssOptions, JchatAddonPluginOptions, createAddonServerBuildArguments, jchatAddon, jchatEmbedCss, requireAddonSigningKey, signAddonManifest };

package/dist/vite.mjs

@@ -0,0 +1,10 @@
+import e from"node:fs";import t from"node:path";import{execFileSync as n}from"node:child_process";import r from"node:crypto";function i(n){return{name:`jchat-embed-css`,apply:`build`,writeBundle(){let r=t.resolve(process.cwd(),`build`);if(!e.existsSync(r))return;let i=e.readdirSync(r),a=i.find(e=>e.endsWith(`.css`)),o=i.find(e=>e.includes(`ui`)&&e.endsWith(`.js`));if(!a||!o)return;let s=t.join(r,a),c=t.join(r,o),l=e.readFileSync(s,`utf-8`),u=e.readFileSync(c,`utf-8`);l.length<10?l=``:n?.id&&(l=l.replace(/:root\s*\{[^}]+\}/g,``),l=l.replace(/\.dark\s*\{[^}]+\}/g,``),l=l.replace(/\[data-theme=[^\]]+\]\s*\{[^}]+\}/g,``),l=l.replace(/\.dark\s*\[data-theme=[^\]]+\]\s*\{[^}]+\}/g,``),l=`@scope (#addon-${n.id}) {\n*, ::before, ::after { border-color: var(--border); }\n${l}\n}`),u=`
+(function() {
+  if (typeof document !== 'undefined' && ${JSON.stringify(l)}.length > 0) {
+    const style = document.createElement('style');
+    style.type = 'text/css';
+    style.textContent = ${JSON.stringify(l)};
+    document.head.appendChild(style);
+  }
+})();
+`+u,e.writeFileSync(c,u);try{e.unlinkSync(s)}catch{}}}}function a(e,t,n){return[`build`,e,`--target=bun`,`--format=esm`,`--outfile=${t}`,n?`--sourcemap=external`:`--minify`]}function o(e){let t=e=>Array.isArray(e)?e.map(t):e&&typeof e==`object`?Object.fromEntries(Object.entries(e).sort(([e],[t])=>e.localeCompare(t)).map(([e,n])=>[e,t(n)])):e;return JSON.stringify(t(e))}function s(e,t,n){if(!e.publisher?.id)throw Error(`Signed addons require manifest.publisher.id`);let i={...e,signature:{algorithm:`rsa-sha256`,digest:``,value:``}},a=r.createHash(`sha256`);for(let e of[...t].sort((e,t)=>e.path.localeCompare(t.path)))a.update(e.path),a.update(`\0`),a.update(e.path===`manifest.json`?o(i):e.contents),a.update(`\0`);let s=a.digest(`hex`);return{...i,signature:{algorithm:`rsa-sha256`,digest:s,value:r.sign(`sha256`,Buffer.from(s),n).toString(`base64url`)}}}function c(e,t){if(e)return e;if(!t)throw Error(`Database-bearing addon builds require JCHAT_ADDON_SIGNING_PRIVATE_KEY`)}function l(r){let{manifest:i}=r,o=r.zip,l=!1;return{name:`jchat-addon`,apply:`build`,config(e,t){return{define:{"process.env.NODE_ENV":JSON.stringify(t.mode||`production`)}}},configResolved(e){l=e.mode===`development`,o===void 0&&(o=e.mode===`production`)},async writeBundle(){let u=process.cwd(),d=t.resolve(u,`package.json`);if(!e.existsSync(d))return;let f=JSON.parse(e.readFileSync(d,`utf-8`)),p=t.resolve(u,`build`);if(!e.existsSync(p))return;let m=e.readdirSync(p).find(e=>e.includes(`ui`)&&e.endsWith(`.js`));if(!m)return;let h={...i,version:f.version,frontend:{...i.frontend,bundle:`./${m}`,mountPoints:i.frontend?.mountPoints??[]}},g=t.resolve(u,`src/api.ts`),_=e.existsSync(g);_&&(n(`bun`,a(g,t.resolve(p,`api.js`),l),{stdio:`inherit`}),h={...h,server:{...h.server,bundle:`./api.js`}});let v=[...h.server?.migrations??[],...h.server?.seeds??[]];for(let n of[`migrations`,`seeds`])e.rmSync(t.resolve(p,n),{recursive:!0,force:!0});for(let n of v){if(t.isAbsolute(n)||n.includes(`\\`)||n.split(`/`).includes(`..`))throw Error(`Unsafe addon database file path: ${n}`);let r=t.resolve(u,n);if(!e.existsSync(r)||!e.statSync(r).isFile())throw Error(`Missing addon database file: ${n}`);let i=t.resolve(p,n);e.mkdirSync(t.dirname(i),{recursive:!0}),e.copyFileSync(r,i)}if(h.server?.migrations?.length||h.server?.seeds?.length){let n=c(r.signingPrivateKey??process.env.JCHAT_ADDON_SIGNING_PRIVATE_KEY,l);if(n){let r=[`manifest.json`,m,...h.server?.migrations??[],...h.server?.seeds??[]];_&&r.push(`api.js`),h=s(h,r.map(n=>({path:n,contents:n===`manifest.json`?Buffer.from(``):e.readFileSync(t.resolve(p,n))})),n)}}let y=JSON.stringify(h,null,2);if(e.writeFileSync(t.resolve(p,`manifest.json`),y),o){let r=`${h.id}-${f.version}.zip`,i=[`manifest.json`,m];e.existsSync(t.resolve(p,`api.js`))&&i.push(`api.js`);let a=t.resolve(p,`migrations`);e.existsSync(a)&&i.push(`migrations`);let o=t.resolve(p,`seeds`);e.existsSync(o)&&i.push(`seeds`),n(`tar`,[`-a`,`-cf`,r,...i],{cwd:p,stdio:`inherit`}),console.log(`Build Complete: ${h.id} v${f.version} → ${r}`)}}}}export{a as createAddonServerBuildArguments,l as jchatAddon,i as jchatEmbedCss,c as requireAddonSigningKey,s as signAddonManifest};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@jchat/addon-sdk",
+  "version": "0.0.1",
+  "private": false,
+  "keywords": [
+    "addon",
+    "chat",
+    "elysia",
+    "jchat",
+    "plugin",
+    "sdk",
+    "vite"
+  ],
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./diagnostics": {
+      "types": "./dist/diagnostics.d.mts",
+      "import": "./dist/diagnostics.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "import": "./dist/vite.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint . --config=../../oxlint.json",
+    "format": "oxfmt . --write",
+    "typecheck": "tsc --noEmit",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@jchat/icon": "1.0.0-alpha.1",
+    "@types/react": "^19.2.17",
+    "elysia": "^1.4.29",
+    "kysely": "^catalog:",
+    "tsdown": "^0.22.14",
+    "vite": "^8.1.5"
+  },
+  "peerDependencies": {
+    "elysia": "^1.4.29",
+    "kysely": "^catalog:",
+    "react": "^19.2.8",
+    "vite": "^8.1.5"
+  }
+}