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

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @jchat/addon-sdk
 
+## 1.0.0-alpha.22
+
+### Minor Changes
+
+- Introduce composer preview slot, active addon coordination, and lifecycle optimizations
+  
+  - Add CHAT_COMPOSER_PREVIEW mount point for live composer rich card previews
+  - Optimize message lifecycle pipeline with active addon caching and AbortSignal cancellation
+  - Allow passing verifyEntitlement function directly to verifyAddonEntitlement
+  - Provide activeAddonIds in AddonProps to enable addon self-coordination
+  - Update default service and documentation domains to jchatplatform.com
+
+### Patch Changes
+
+- Bumped `@jchat/*` dependencies:
+  - [`ui@1.0.0-alpha.22`](https://github.com/mjjabarullah/jchat/releases/tag/ui@v1.0.0-alpha.22)
+
+## 1.0.0-alpha.21
+
+### Minor Changes
+
+- Add message lifecycle interception hooks and chat message card mount point support
+
+- Add TypeScript typings for available editor commands in Addon SDK
+
+- Add verifyAddonEntitlement runtime helper and AddonServerContext method
+
+### Patch Changes
+
+- Remove redundant boilerplate test files
+
+- Enhance add-on CSS compilation to ensure consistent styling across dialogs and portals
+
+- Bumped `@jchat/*` dependencies:
+  - [`icon@1.0.0-alpha.21`](https://github.com/mjjabarullah/jchat/releases/tag/icon@v1.0.0-alpha.21)
+  - [`ui@1.0.0-alpha.21`](https://github.com/mjjabarullah/jchat/releases/tag/ui@v1.0.0-alpha.21)
+
 ## 1.0.0-alpha.20
 
 ### Patch Changes
@@ -57,7 +94,7 @@ No changes in this release.
 - c5fa55f: Support direct icon imports via `@jchat/addon-sdk/icon` and align icon packs with canonical Lucide icon definitions. Addons can now import `Icons` directly without requiring hook invocation (`useIcons`), while maintaining backward compatibility for existing addons.
 - 27efa80: - Update third-party developer guide in README with complete quick start, architecture specifications, hook references, and mount points
   - Include `LICENSE` file in published npm package distribution
-  - Update license badge and terms references to link to official public web address (`https://jchatlive.com/terms`)
+  - Update license badge and terms references to link to official public web address (`https://jchatplatform.com/terms`)
 
 ## 1.0.0-alpha.11
 

package/README.md

@@ -1,11 +1,11 @@
 # @jchat/addon-sdk
 
-Official TypeScript SDK for developing extensions, UI widgets, and server plugins for the [JChat](https://jchatlive.com) communication platform.
+Official TypeScript SDK for developing extensions, UI widgets, and server plugins for the [JChat](https://jchatplatform.com) communication platform.
 
 Provides typed interfaces, manifest contracts, Vite bundler plugins, and CLI development tooling for building sandboxed JChat addons.
 
 [![npm version](https://img.shields.io/npm/v/@jchat/addon-sdk.svg)](https://www.npmjs.com/package/@jchat/addon-sdk)
-[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](https://jchatlive.com/terms)
+[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](https://jchatplatform.com/terms)
 
 ---
 
@@ -401,10 +401,10 @@ bun run build
 1. Build your addon package: `bun run build`.
 2. Ensure all 20 translation files pass validation: `bun test`.
 3. Package your addon distribution archive.
-4. Sign in to the **[JChat Store Developer Portal](https://jchatlive.com/addons)** and submit your addon package for certified distribution.
+4. Sign in to the **[JChat Store Developer Portal](https://jchatplatform.com/addons)** and submit your addon package for certified distribution.
 
 ---
 
 ## License
 
-Proprietary — All rights reserved. See the [Commercial EULA & Licensing Terms](https://jchatlive.com/terms) for full details.
+Proprietary — All rights reserved. See the [Commercial EULA & Licensing Terms](https://jchatplatform.com/terms) for full details.

package/dist/contracts.d.mts

@@ -36,15 +36,36 @@ export declare const MOUNT_POINTS: {
   readonly EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab";
   /** Custom tab in the emoji/sticker selection panel */
   readonly EMOJI_PICKER_STICKER_TAB: "emoji-picker-sticker-tab";
-  /** Full-screen or modal dialog specifically for TubeScan */
-  readonly TUBESCAN_DIALOG: "tubescan-dialog";
   /** Dedicated settings panel rendered in the Owner Dashboard */
   readonly OWNER_SETTINGS: "owner-settings";
   /** Dedicated settings panel rendered in the Site Admin Dashboard */
   readonly ADDON_SETTINGS: "addon-settings";
+  /** Custom interactive card rendered inside an enriched chat message */
+  readonly CHAT_MESSAGE_CARD: "chat-message-card";
+  /** Custom badge, audio equalizer, or particle aura rendered on a chat bubble */
+  readonly CHAT_MESSAGE_FLAIR: "chat-message-flair";
+  /** Custom interactive preview card rendered in the message composer */
+  readonly CHAT_COMPOSER_PREVIEW: "chat-composer-preview";
 };
 /** Union type of all valid addon mount points. */
 export type MountPoint = (typeof MOUNT_POINTS)[keyof typeof MOUNT_POINTS];
+/** Parameter specification for an addon slash command. */
+export interface AddonCommandParameter {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+/** Declaration of an addon slash command available in the chat composer. */
+export interface AddonCommandDefinition {
+  /** The command keyword without leading slash (e.g. 'yt', 'roll', 'poll') */
+  name: string;
+  /** Short summary of what the command does, displayed in autocomplete */
+  description: string;
+  /** Usage syntax displayed as a hint (e.g. '<query | url>') */
+  syntax?: string;
+  /** Parameters accepted by this command */
+  parameters?: AddonCommandParameter[];
+}
 /**
  * The `manifest.json` schema required for every Jchat addon. This file describes how the addon is
  * identified and mounted.
@@ -117,5 +138,7 @@ export interface AddonManifest {
   permissions?: string[];
   /** Custom permissions that should be registered with the host application on installation */
   permissionDefinitions?: AddonPermissionDefinition[];
+  /** Interactive slash commands exposed in the chat composer */
+  commands?: AddonCommandDefinition[];
 }
 //#endregion

package/dist/contracts.mjs

@@ -27,12 +27,16 @@ const MOUNT_POINTS = {
 	EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab",
 	/** Custom tab in the emoji/sticker selection panel */
 	EMOJI_PICKER_STICKER_TAB: "emoji-picker-sticker-tab",
-	/** Full-screen or modal dialog specifically for TubeScan */
-	TUBESCAN_DIALOG: "tubescan-dialog",
 	/** Dedicated settings panel rendered in the Owner Dashboard */
 	OWNER_SETTINGS: "owner-settings",
 	/** Dedicated settings panel rendered in the Site Admin Dashboard */
-	ADDON_SETTINGS: "addon-settings"
+	ADDON_SETTINGS: "addon-settings",
+	/** Custom interactive card rendered inside an enriched chat message */
+	CHAT_MESSAGE_CARD: "chat-message-card",
+	/** Custom badge, audio equalizer, or particle aura rendered on a chat bubble */
+	CHAT_MESSAGE_FLAIR: "chat-message-flair",
+	/** Custom interactive preview card rendered in the message composer */
+	CHAT_COMPOSER_PREVIEW: "chat-composer-preview"
 };
 //#endregion
 export { MOUNT_POINTS };

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { MOUNT_POINTS } from "./contracts.mjs";
 import { a as useTranslation, i as useLocale, n as LocaleContext, r as createTranslator, t as HOST_LANGUAGES } from "./i18n.mjs";
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 //#region package.json
-var version = "1.0.0-alpha.19";
+var version = "1.0.0-alpha.21";
 //#endregion
 //#region src/query.ts
 /**
@@ -145,5 +145,32 @@ function useAddonSDK() {
 function getAddonSdkVersion() {
 	return version;
 }
+/**
+* Verifies purchase entitlement and identity integrity for commercial addons. Throws an error if
+* the addon fails entitlement verification or if its manifest ID has been tampered with to
+* impersonate another addon.
+*
+* @example
+*   ;```ts
+*   export default ({ verifyEntitlement, db, t }: AddonServerContext, app: AddonApp) => {
+*     verifyAddonEntitlement("tubescanpro", verifyEntitlement)
+*     return app.get("/trending", async () => { ... })
+*   }
+*   ```
+*
+* @param addonId - The canonical addon ID defined by the publisher (e.g. 'tubescanpro')
+* @param target - Either the `verifyEntitlement` function from context or the `AddonServerContext`
+*   object itself
+* @returns True if valid
+* @throws Error if entitlement verification fails
+*/
+function verifyAddonEntitlement(addonId, target) {
+	const verifyFn = typeof target === "function" ? target : target?.verifyEntitlement;
+	if (verifyFn) {
+		if (!verifyFn(addonId)) throw new Error(`addon_entitlement_verification_failed:${addonId}`);
+		return true;
+	}
+	return true;
+}
 //#endregion
-export { HOST_LANGUAGES, LocaleContext, MOUNT_POINTS, createTranslator, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonInfiniteQuery, useAddonMutation, useAddonQuery, useAddonSDK, useLocale, useQueryClient, useTranslation };
+export { HOST_LANGUAGES, LocaleContext, MOUNT_POINTS, createTranslator, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonInfiniteQuery, useAddonMutation, useAddonQuery, useAddonSDK, useLocale, useQueryClient, useTranslation, verifyAddonEntitlement };

package/dist/index2.d.mts

@@ -1,5 +1,5 @@
 import { i as IconPack, n as IconComponent, r as IconName } from "./types.mjs";
-import { AddonManifest, AddonPermissionDefinition, MOUNT_POINTS, MountPoint } from "./contracts.mjs";
+import { AddonCommandDefinition, AddonCommandParameter, 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";
@@ -209,6 +209,70 @@ export interface AddonServerEmitTarget {
   /** Target a specific user */
   userId?: string;
 }
+export interface AddonMessageMutableData {
+  /** Message content (can be Slate JSON structure or string) */
+  content: unknown;
+  /** Optional message attachments */
+  attachments?: unknown[] | null;
+  /**
+   * Namespaced metadata bucket for this addon. Keyed as `metadata["addon:<addonId>"]`. Storing data
+   * here automatically attaches it to the message broadcast and database record.
+   */
+  metadata: Record<string, unknown>;
+}
+export interface AddonMessageContext {
+  /** The site ID where the message is being sent */
+  siteId: string;
+  /** The chat room ID */
+  roomId: string;
+  /** The authenticated user sending the message (read-only) */
+  user: AddonRequestUser;
+  /** Mutable message payload */
+  message: AddonMessageMutableData;
+  /** Convenience method to set metadata under this addon's namespace */
+  setMetadata: (key: string, value: unknown) => void;
+  /**
+   * Abort the message sending pipeline with a user-facing error code and reason. Only active during
+   * `beforeValidate` and `transformContent`.
+   */
+  abort: (error: {
+    code: string;
+    reason?: string;
+  }) => never;
+  /**
+   * AbortSignal triggered if this interceptor times out or the message pipeline is cancelled. Can
+   * be passed to `fetch(url, { signal: context.signal })` or async operations.
+   */
+  signal?: AbortSignal;
+}
+export interface AddonMessageAfterSaveContext {
+  siteId: string;
+  roomId: string;
+  user: AddonRequestUser;
+  message: {
+    id: string;
+    content: unknown;
+    attachments?: unknown[] | null;
+    metadata?: Record<string, unknown> | null;
+    type: string;
+    createdAt: Date | string;
+  };
+  /** AbortSignal triggered if the observer times out or is cancelled. */
+  signal?: AbortSignal;
+}
+export interface AddonPipelineHooks {
+  /** Optional priority ordering. Lower numbers execute first (e.g. 10 runs before 100). Default is 100. */
+  priority?: number;
+  /**
+   * Run before validation to inspect or guard actions (rate-limits, permission gates). Throw or
+   * call `context.abort()` to reject the message.
+   */
+  beforeValidate?: (context: AddonMessageContext) => Promise<void> | void;
+  /** Run before persistence to mutate text, parse slash commands, or enrich metadata. */
+  transformContent?: (context: AddonMessageContext) => Promise<void> | void;
+  /** Run asynchronously after database save (fire-and-forget observers). */
+  afterSave?: (context: AddonMessageAfterSaveContext) => Promise<void> | void;
+}
 /**
  * Context provided to an addon's server-side factory. Parameterize it with the addon's table
  * interface: `AddonServerContext<MyAddonDatabase>`.
@@ -249,6 +313,21 @@ export interface AddonServerContext<TDatabase = Record<string, Record<string, un
    * `sdk.events.on('addon:<addonId>:<event>', callback)` or `sdk.events.on(event, callback)`.
    */
   emit: (event: string, payload: unknown, target?: AddonServerEmitTarget) => Promise<void>;
+  /**
+   * Register lifecycle interception hooks for chat messages. Hooks run in the core chat execution
+   * path with strict 50ms timeout guards and fail-open fault tolerance.
+   */
+  pipeline?: {
+    register: (hooks: AddonPipelineHooks) => void;
+  };
+  /**
+   * Cryptographically verify that this addon instance holds a valid host license entitlement.
+   * Commercial paid addons should invoke this or call `verifyAddonEntitlement(addonId, context)`.
+   *
+   * @param expectedAddonId - The canonical addon ID defined by the publisher
+   * @returns True if valid, or false if entitlement is missing or invalid
+   */
+  verifyEntitlement?: (expectedAddonId?: string) => boolean;
 }
 /**
  * Elysia app instance provided to addon server endpoints with Jchat macro metadata (e.g.
@@ -309,6 +388,12 @@ export interface AddonProps {
   locale?: string;
   /** Text direction for the current locale */
   dir?: "ltr" | "rtl";
+  /** The message object when rendered inside 'chat-message-card' or 'chat-message-flair' */
+  message?: unknown;
+  /** The addon's specific payload extracted from message.metadata */
+  addonData?: unknown;
+  /** List of active addon IDs enabled on the current site */
+  activeAddonIds?: string[];
 }
 export interface AddonApi {
   get: <TResponse = unknown>(path: string) => Promise<TResponse>;
@@ -337,6 +422,59 @@ export interface AddonFont {
   /** Relative size multiplier — apply this to base font sizes to match the host's rendering */
   scale: number;
 }
+export interface AddonEditorInsertImagePayload {
+  src: string;
+  altText: string;
+  emoji?: {
+    col: number;
+    row: number;
+    size: number;
+  };
+  className?: string;
+}
+export interface AddonEditorInsertEmojiPayload {
+  col: number;
+  row: number;
+  unicode: string;
+  shortcode?: string;
+}
+export interface AddonEditorCommandMap {
+  INSERT_YOUTUBE_COMMAND: string;
+  INSERT_TEXT: string;
+  INSERT_TEXT_COMMAND: string;
+  INSERT_MENTION_COMMAND: string;
+  INSERT_IMAGE_COMMAND: AddonEditorInsertImagePayload;
+  INSERT_EMOJI_COMMAND: AddonEditorInsertEmojiPayload;
+  CLEAR_EDITOR: void;
+  CLEAR_EDITOR_COMMAND: void;
+}
+export type AddonEditorCommand = keyof AddonEditorCommandMap;
+export interface AddonEditorApi {
+  /**
+   * Trigger a specialized editor command defined by the host.
+   *
+   * @example
+   *   sdk.editor.dispatchCommand("INSERT_YOUTUBE_COMMAND", "dQw4w9WgXcQ")
+   */
+  dispatchCommand: <C extends AddonEditorCommand>(command: C, ...args: AddonEditorCommandMap[C] extends void ? [payload?: undefined] : [payload: AddonEditorCommandMap[C]]) => 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;
+}
 /**
  * The bridge between your addon and the Jchat host application. Use the `useAddonSDK()` hook to
  * access this interface in your components.
@@ -370,32 +508,7 @@ export interface AddonSDK {
    * 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;
-  };
+  editor: AddonEditorApi;
   /** Event Bus for reacting to real-time application state changes. */
   events: {
     /**
@@ -474,5 +587,27 @@ export declare function useAddonSDK(): AddonSDK;
  * @returns
  */
 export declare function getAddonSdkVersion(): string;
+/**
+ * Verifies purchase entitlement and identity integrity for commercial addons. Throws an error if
+ * the addon fails entitlement verification or if its manifest ID has been tampered with to
+ * impersonate another addon.
+ *
+ * @example
+ *   ;```ts
+ *   export default ({ verifyEntitlement, db, t }: AddonServerContext, app: AddonApp) => {
+ *     verifyAddonEntitlement("tubescanpro", verifyEntitlement)
+ *     return app.get("/trending", async () => { ... })
+ *   }
+ *   ```
+ *
+ * @param addonId - The canonical addon ID defined by the publisher (e.g. 'tubescanpro')
+ * @param target - Either the `verifyEntitlement` function from context or the `AddonServerContext`
+ *   object itself
+ * @returns True if valid
+ * @throws Error if entitlement verification fails
+ */
+export declare function verifyAddonEntitlement(addonId: string, target?: ((expectedAddonId?: string) => boolean) | {
+  verifyEntitlement?: (expectedAddonId?: string) => boolean;
+}): boolean;
 //#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 };
+export { type AddonCommandDefinition, type AddonCommandParameter, 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/vite.mjs

@@ -82,7 +82,7 @@ function jchatAddon(options) {
 			if (!fs.existsSync(buildDir)) return;
 			const bundleFile = fs.readdirSync(buildDir).find((f) => f.includes("ui") && f.endsWith(".js"));
 			if (!bundleFile) return;
-			if (options.css !== false) embedCssIntoBundle(buildDir, manifestData.id);
+			if (options.css !== false) embedCssIntoBundle(buildDir);
 			let manifest = {
 				...manifestData,
 				version: pkg.version,
@@ -243,7 +243,7 @@ function requireAddonSigningKey(signingPrivateKey, developmentBuild) {
 	if (developmentBuild) return void 0;
 	throw new Error("Database-bearing addon builds require JCHAT_ADDON_SIGNING_PRIVATE_KEY");
 }
-function embedCssIntoBundle(buildDir, addonId) {
+function embedCssIntoBundle(buildDir) {
 	const files = fs.readdirSync(buildDir);
 	const cssFile = files.find((f) => f.endsWith(".css"));
 	const jsFile = files.find((f) => f.includes("ui") && f.endsWith(".js"));
@@ -274,7 +274,7 @@ function embedCssIntoBundle(buildDir, addonId) {
 		css = css.replace(/\.user-border\s*\{[^}]+\}/g, "");
 		css = css.replace(/\.scrollbar-hide[^{]*\{[^}]+\}/g, "");
 		css = css.replace(/@layer\s+components(?:\s*\{[^}]*\}|;)/g, "");
-		css = minifyCss(`@scope (#addon-${addonId}) { ${css} }`);
+		css = minifyCss(css);
 	}
 	if (css.trim().length > 0) {
 		const injection = `
@@ -294,12 +294,14 @@ function embedCssIntoBundle(buildDir, addonId) {
 	} catch {}
 }
 function stripLayer(css, layerName) {
-	const marker = `@layer ${layerName} {`;
-	let idx = css.indexOf(marker);
-	while (idx !== -1) {
-		let braceCount = 0;
-		let endIdx = idx + marker.length - 1;
-		for (let i = idx + marker.length - 1; i < css.length; i++) if (css[i] === "{") braceCount++;
+	const regex = new RegExp(`@layer\\s+${layerName}\\s*\\{`);
+	let match = regex.exec(css);
+	while (match) {
+		const startIdx = match.index;
+		const openBraceIdx = startIdx + match[0].length - 1;
+		let braceCount = 1;
+		let endIdx = -1;
+		for (let i = openBraceIdx + 1; i < css.length; i++) if (css[i] === "{") braceCount++;
 		else if (css[i] === "}") {
 			braceCount--;
 			if (braceCount === 0) {
@@ -307,8 +309,9 @@ function stripLayer(css, layerName) {
 				break;
 			}
 		}
-		css = css.slice(0, idx) + css.slice(endIdx + 1);
-		idx = css.indexOf(marker);
+		if (endIdx === -1) break;
+		css = css.slice(0, startIdx) + css.slice(endIdx + 1);
+		match = regex.exec(css);
 	}
 	return css;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jchat/addon-sdk",
-  "version": "1.0.0-alpha.20",
+  "version": "1.0.0-alpha.22",
   "private": false,
   "description": "JChat Addon SDK for building JChat addons.",
   "keywords": [