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

package/README.md

@@ -1,45 +1,410 @@
 # @jchat/addon-sdk
 
-TypeScript SDK for building [JChat](https://jchat.app) addons.
+Official TypeScript SDK for developing extensions, UI widgets, and server plugins for the [JChat](https://jchatlive.com) communication platform.
 
-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.
+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)
+
+---
+
+## Architecture Overview
+
+JChat addons are **sandboxed, modular extensions** designed to enhance real-time chats without modifying core database schemas or server code.
+
+- **Ultra-Lightweight Server Bundles**: Elysia and TypeBox are externalized and provided directly by the host server runtime via `ctx.t` and `app`. Server bundles (`build/api.js`) compile down to just **2–7 KB**.
+- **Zero Frontend Bundle Bloat**: Host externals (`react`, `react-dom`, `@jchat/ui`, `@jchat/icon`, `@tanstack/react-query`, `jotai`) are injected at runtime by the JChat host application.
+- **Isolated Database Schema**: Addon tables reside exclusively in the isolated `addons` PostgreSQL schema (e.g. `addons.GlimpseStories`), preventing collisions with core chat tables.
+- **Scoped Cache & Real-Time Events**: Addons receive namespaced Redis cache (`addon:<id>:<key>`) and real-time WebSocket event broadcasting scoped to sites, rooms, or users.
+- **20-Language i18n Standard**: First-class internationalization with 100% parity across all 20 supported host languages, including full RTL direction support.
+
+---
+
+## Requirements
+
+- **Bun**: `1.4.0+`
+- **React**: `19+`
+- **Vite**: `8+`
+
+---
 
 ## Installation
 
+Install as a development dependency:
+
 ```bash
-npm install @jchat/addon-sdk
-# or
-bun add @jchat/addon-sdk
+bun add -d @jchat/addon-sdk
 ```
 
-## Requirements
+Or scaffold a new addon instantly with the official CLI:
 
-- Node.js 20+ or Bun 1.3+
-- React 18+, Elysia, Kysely, and Vite as peer dependencies
+```bash
+bun create @jchat/addon my-new-addon
+```
+
+---
 
-## Usage
+## Quick Start Guide
+
+### 1. Define the Addon Manifest (`src/manifest.ts`)
+
+Use `defineAddonManifest` (or type with `AddonManifest`) to declare metadata, permissions, mount points, and supported languages:
 
 ```ts
-import type {
-  AddonManifest,
-  AddonServerContext,
-  AddonClientContext,
-  AddonProps
-} from "@jchat/addon-sdk"
+import { defineAddonManifest } from "@jchat/addon-sdk"
+
+export default defineAddonManifest({
+  id: "gifyard",
+  name: "Gifyard GIF Picker",
+  version: "1.0.0",
+  description: "Search and insert animated GIFs directly into chat messages.",
+  author: "JChat Ecosystem Team",
+  publisher: { id: "jchat" },
+  compatibility: {
+    jchat: ">=1.0.0-alpha.0 <2.0.0",
+    addonSdk: "^1.0.0"
+  },
+  locales: [
+    "ar",
+    "bg",
+    "de",
+    "el",
+    "en",
+    "es",
+    "fr",
+    "he",
+    "hi",
+    "hr",
+    "kn",
+    "ml",
+    "nl",
+    "pt",
+    "ro",
+    "ru",
+    "ta",
+    "te",
+    "tr",
+    "ur"
+  ],
+  defaultLocale: "en",
+  frontend: {
+    bundle: "./ui.js",
+    mountPoints: ["chat-toolbar", "emoji-picker-gif-tab", "addon-settings"]
+  },
+  server: {
+    bundle: "./api.ts",
+    migrations: ["./migrations/0001_init.sql"]
+  },
+  accessPermission: "addon.gifyard.view",
+  permissions: ["addon.gifyard.view", "addon.gifyard.manage"],
+  permissionDefinitions: [
+    {
+      name: "addon.gifyard.view",
+      label: "View GIFs",
+      description: "Search and preview animated GIFs in chat"
+    },
+    {
+      name: "addon.gifyard.manage",
+      label: "Manage Gifyard",
+      description: "Configure Giphy API keys and content rating settings"
+    }
+  ]
+})
 ```
 
-For the Vite build plugin:
+---
+
+### 2. Build the Frontend UI (`src/ui.tsx`)
+
+Addon UI components receive typed `AddonProps` and access host services via the `useAddonSDK()` hook:
+
+```tsx
+import { useAddonSDK, useAddonQuery, useTranslation, type AddonProps } from "@jchat/addon-sdk"
+import Icons from "@jchat/addon-sdk/icon"
+import locales from "./locales"
+
+export default function MyAddon({ mountPoint, roomId }: AddonProps) {
+  const sdk = useAddonSDK()
+  const { t, dir } = useTranslation(locales)
+
+  // Type-safe data fetching via TanStack Query bridge
+  const { data, isLoading } = useAddonQuery<{ items: string[] }>({
+    path: "/items",
+    queryKey: [roomId]
+  })
+
+  const handleInsert = (text: string) => {
+    // Insert rich content directly into the active Slate message editor
+    sdk.editor.dispatchCommand("INSERT_TEXT", text)
+    sdk.toast(t("item_inserted"), "success")
+  }
+
+  return (
+    <div dir={dir} className="rounded-2xl border border-border bg-card p-4 shadow-sm">
+      <div className="flex items-center gap-2 font-bold">
+        <Icons.Sparkles className="size-4 text-primary" />
+        <span>{t("addon_title")}</span>
+      </div>
+      {isLoading ? (
+        <p className="text-xs text-muted-foreground">{t("loading")}</p>
+      ) : (
+        <button
+          onClick={() => handleInsert("Hello from Addon!")}
+          className="mt-3 rounded-lg bg-primary px-3 py-1.5 text-xs font-semibold text-primary-foreground"
+        >
+          {t("insert_action")}
+        </button>
+      )}
+    </div>
+  )
+}
+```
+
+> **Directional Styling Rule**: Always use Tailwind logical directional properties (`ps-*`, `pe-*`, `ms-*`, `me-*`, `text-start`, `text-end`, `start-*`, `end-*`) to automatically adapt to RTL languages (`ar`, `he`, `ur`).
+
+---
+
+### 3. Build the Backend API (`src/api.ts`)
+
+Define type-safe Elysia API endpoints. The schema validator `t` is injected directly via `ctx.t`, so your production bundle never imports or bundles Elysia:
 
 ```ts
+import type { AddonApp, AddonServerContext } from "@jchat/addon-sdk"
+
+export interface MyAddonDatabase {
+  addon_items: {
+    id: string
+    siteId: string
+    roomId: string
+    userId: string
+    title: string
+    createdAt: Date
+  }
+}
+
+export default (
+  { db, t, emit, cache, getConfig, getUser, hasPermission }: AddonServerContext<MyAddonDatabase>,
+  app: AddonApp
+) => {
+  return app
+    .get(
+      "/items",
+      async ({ query, user }) => {
+        const siteId = user?.siteId ?? ""
+        const items = await db
+          .selectFrom("addon_items")
+          .where("siteId", "=", siteId)
+          .where("roomId", "=", query.roomId ?? "")
+          .orderBy("createdAt", "desc")
+          .limit(20)
+          .selectAll()
+          .execute()
+
+        return { items }
+      },
+      {
+        requirePermission: "addon.myaddon.view",
+        query: t.Object({
+          roomId: t.Optional(t.String())
+        })
+      }
+    )
+    .post(
+      "/items",
+      async ({ body, user, status }) => {
+        if (!user) {
+          return status(401, { error: "Authentication required" })
+        }
+
+        const id = Bun.randomUUIDv7()
+        await db
+          .insertInto("addon_items")
+          .values({
+            id,
+            siteId: user.siteId!,
+            roomId: body.roomId,
+            userId: user.id,
+            title: body.title,
+            createdAt: new Date()
+          })
+          .execute()
+
+        // Broadcast real-time WebSocket event
+        await emit("addon:myaddon:item-created", { id, title: body.title }, { roomId: body.roomId })
+
+        return { id, title: body.title }
+      },
+      {
+        requirePermission: "addon.myaddon.manage",
+        body: t.Object({
+          roomId: t.String(),
+          title: t.String({ minLength: 1 })
+        })
+      }
+    )
+}
+```
+
+---
+
+### 4. Configure Vite Bundling (`vite.config.ts`)
+
+Include the official Vite plugin for automatic manifest bundling, externalization, and live development:
+
+```ts
+import { defineConfig } from "vite"
 import { jchatAddon } from "@jchat/addon-sdk/vite"
 
-export default {
+export default defineConfig({
   plugins: [jchatAddon()]
+})
+```
+
+---
+
+## SDK Modules & API Reference
+
+### 1. Host Bridge: `useAddonSDK()`
+
+Provides access to the active JChat host application bridge:
+
+| Property         | Type               | Description                                                                                                    |
+| :--------------- | :----------------- | :------------------------------------------------------------------------------------------------------------- |
+| `api`            | `AddonApi`         | Authenticated HTTP client (`get`, `post`, `put`, `delete`) automatically scoped to `/api/v1/addons/<addonId>`. |
+| `settings`       | `AddonSettingsApi` | First-class configuration helper to load and save addon settings (`get()`, `save()`).                          |
+| `editor`         | `AddonEditorApi`   | Active Slate editor controls (`dispatchCommand`, `insertNode`, `addAttachment`, `focus`).                      |
+| `events`         | `AddonEventBus`    | Real-time WebSocket event listeners (`on`, `off`).                                                             |
+| `toast`          | `function`         | Display host toast notifications (`default`, `success`, `error`).                                              |
+| `navigate`       | `function`         | Navigate to internal host routes without triggering a full page reload.                                        |
+| `supportedFonts` | `AddonFont[]`      | List of fonts configured by the site administrator with scale multipliers.                                     |
+| `locale`         | `string`           | Active user locale code (e.g. `'en'`, `'ta'`, `'ar'`).                                                         |
+| `dir`            | `'ltr' \| 'rtl'`   | Current layout text direction.                                                                                 |
+
+---
+
+### 2. Data Fetching: `@jchat/addon-sdk/query`
+
+Integrated TanStack Query wrappers pre-configured with host caching, auto-invalidation, and credentials:
+
+- **`useAddonQuery({ path, queryKey, ...options })`**: Cached GET requests automatically prefixed with `/api/v1/addons/<addonId>`.
+- **`useAddonMutation({ path, method, invalidateQueries, ...options })`**: Declarative mutations with automatic query invalidation.
+- **`useAddonInfiniteQuery({ path, queryKey, initialPageParam, getNextPageParam })`**: Paginated and infinite-scroll queries.
+- **`useQueryClient()`**: Access the underlying TanStack Query client.
+
+---
+
+### 3. Atomic State: `@jchat/addon-sdk/state`
+
+Re-exports Jotai state management primitives for maintaining synchronized, reactive UI state across multiple mount points:
+
+```tsx
+import { atom, useAtom, useAtomValue, useSetAtom } from "@jchat/addon-sdk/state"
+
+export const activeTabAtom = atom<"trending" | "search">("trending")
+```
+
+---
+
+### 4. Localization: `useTranslation()` & `useLocale()`
+
+Addons must support all **20 host languages**:
+`ar`, `bg`, `de`, `el`, `en`, `es`, `fr`, `he`, `hi`, `hr`, `kn`, `ml`, `nl`, `pt`, `ro`, `ru`, `ta`, `te`, `tr`, `ur`.
+
+```tsx
+import { useTranslation, useLocale } from "@jchat/addon-sdk"
+import locales from "./locales"
+
+export default function MyComponent() {
+  const { t, dir, isRtl, locale } = useTranslation(locales)
+  return <div dir={dir}>{t("welcome", { name: "User" })}</div>
 }
 ```
 
+For backend server routes (`src/api.ts`), use `createTranslator(locales, defaultLocale)` to translate server-sent notifications or messages.
+
+---
+
+### 5. Icons: `@jchat/addon-sdk/icon`
+
+Imports the site's active icon pack directly, ensuring visual consistency with the host theme:
+
+```tsx
+import Icons from "@jchat/addon-sdk/icon"
+
+;<Icons.Heart className="size-4 text-red-500" />
+```
+
+---
+
+### 6. Server Context: `AddonServerContext`
+
+The context passed to your server plugin (`src/api.ts`):
+
+| Property        | Type                   | Description                                                                               |
+| :-------------- | :--------------------- | :---------------------------------------------------------------------------------------- |
+| `t`             | `typeof t`             | Elysia / TypeBox schema validator for defining `body`, `query`, `params`, and `headers`.  |
+| `db`            | `AddonDatabase<T>`     | Schema-scoped Kysely query builder (`selectFrom`, `insertInto`, `updateTable`, etc.).     |
+| `cache`         | `AddonCacheClient`     | Namespaced Redis client (`get`, `set`, `del`, `incr`, `expire`, `ttl`).                   |
+| `emit`          | `function`             | Real-time WebSocket event broadcaster with target options (`siteId`, `roomId`, `userId`). |
+| `getConfig`     | `(siteId) => Promise`  | Retrieve encrypted site configuration with automatic decryption.                          |
+| `getUser`       | `(userId) => Promise`  | Fetch a single user's public profile (`id`, `name`, `displayName`, `avatar`, `gender`).   |
+| `getUsers`      | `(userIds) => Promise` | Batch-fetch multiple user profiles in a single query.                                     |
+| `hasPermission` | `(user, perm) => bool` | Check whether a request user holds a given permission scope.                              |
+
+---
+
+## Supported UI Mount Points
+
+Addons can mount into any combination of locations defined in `MOUNT_POINTS`:
+
+| Mount Point              | Identifier                 | Description                                                                     |
+| :----------------------- | :------------------------- | :------------------------------------------------------------------------------ |
+| **Chat Toolbar**         | `chat-toolbar`             | Action button rendered in the message composer toolbar.                         |
+| **Chat Plus Menu**       | `chat-plus-menu`           | Action item inside the message composer (+) expandable menu.                    |
+| **Chat Sidebar**         | `chat-sidebar`             | Dedicated right-hand collapsible panel in active chat rooms.                    |
+| **Chat Header**          | `chat-header`              | Action button or widget rendered in the chat room top header.                   |
+| **Sidebar Top**          | `sidebar-top`              | Placed at the top of the left-hand navigation sidebar.                          |
+| **Sidebar Bottom**       | `sidebar-bottom`           | Placed at the bottom of the left-hand navigation sidebar (e.g. AdSense banner). |
+| **User Popover Actions** | `user-popover-actions`     | Custom action buttons in the user profile card popup.                           |
+| **Message Context Menu** | `message-context-menu`     | Custom actions on right-clicking or long-pressing a message.                    |
+| **Message Feed Overlay** | `message-feed-overlay`     | Floating banner or widget overlaid across the message stream.                   |
+| **GIF Picker Tab**       | `emoji-picker-gif-tab`     | Custom GIF provider tab in the emoji/media drawer.                              |
+| **Sticker Picker Tab**   | `emoji-picker-sticker-tab` | Custom sticker provider tab in the emoji/media drawer.                          |
+| **Addon Settings**       | `addon-settings`           | Configuration panel inside the Site Admin Dashboard.                            |
+| **Owner Settings**       | `owner-settings`           | Global configuration panel inside the System Owner Dashboard.                   |
+
+---
+
+## CLI Development Workflow
+
+The SDK provides the `jchat-addon` CLI for local development, building, and validation:
+
+```bash
+# Start live development watcher with hot module reloading
+bun run dev
+
+# Run TypeScript typechecks
+bun run typecheck
+
+# Execute local unit and contract tests
+bun test
+
+# Build production bundles (build/ui.js and build/api.js)
+bun run build
+```
+
+---
+
+## Publishing to JChat Marketplace
+
+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.
+
+---
+
 ## License
 
-Apache-2.0
+Proprietary — All rights reserved. See the [Commercial EULA & Licensing Terms](https://jchatlive.com/terms) for full details.

package/dist/cli.d.mts

@@ -0,0 +1,35 @@
+import { AddonManifest } from "./contracts.mjs";
+import { InlineConfig } from "vite";
+//#region src/cli.d.ts
+/** Options for resolving addon build configuration. */
+export interface AddonCliOptions {
+  rootDir?: string;
+  command?: "build" | "dev" | "help";
+  mode?: "production" | "development";
+  watch?: boolean;
+  zip?: boolean;
+  signingPrivateKey?: string;
+}
+/**
+ * Automatically loads the addon manifest from `src/manifest.ts`, `src/manifest.js`, or
+ * `src/manifest.json`.
+ *
+ * @param rootDir - Root directory of the addon workspace.
+ * @returns Parsed {@link AddonManifest}.
+ */
+export declare function loadAddonManifest(rootDir: string): Promise<AddonManifest>;
+/**
+ * Resolves the full Vite configuration for building a JChat addon, merging user custom configs if
+ * present.
+ *
+ * @param options - CLI build options.
+ * @returns Fully merged {@link InlineConfig} for Vite.
+ */
+export declare function resolveAddonBuildConfig(options?: AddonCliOptions): Promise<InlineConfig>;
+/**
+ * Main CLI handler for `jchat-addon`.
+ *
+ * @param args - CLI arguments (defaults to `process.argv.slice(2)`).
+ */
+export declare function runAddonCli(args?: string[]): Promise<void>;
+//#endregion

package/dist/cli.mjs

@@ -0,0 +1,136 @@
+import { jchatAddon } from "./vite.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import tailwindcss from "@tailwindcss/vite";
+import { pathToFileURL } from "node:url";
+import { build, loadConfigFromFile, mergeConfig } from "vite";
+//#region src/cli.ts
+function hasPlugin(plugins, name) {
+	if (!plugins) return false;
+	if (Array.isArray(plugins)) return plugins.some((p) => hasPlugin(p, name));
+	if (typeof plugins === "object" && plugins !== null && "name" in plugins && plugins.name === name) return true;
+	return false;
+}
+/**
+* Automatically loads the addon manifest from `src/manifest.ts`, `src/manifest.js`, or
+* `src/manifest.json`.
+*
+* @param rootDir - Root directory of the addon workspace.
+* @returns Parsed {@link AddonManifest}.
+*/
+async function loadAddonManifest(rootDir) {
+	const existingPath = [
+		path.resolve(rootDir, "src/manifest.ts"),
+		path.resolve(rootDir, "src/manifest.js"),
+		path.resolve(rootDir, "src/manifest.mjs"),
+		path.resolve(rootDir, "src/manifest.json")
+	].find((filePath) => fs.existsSync(filePath));
+	if (existingPath) {
+		if (existingPath.endsWith(".json")) {
+			const text = fs.readFileSync(existingPath, "utf-8");
+			return JSON.parse(text);
+		}
+		const imported = await import(pathToFileURL(existingPath).href);
+		return imported.default || imported.manifest;
+	}
+	throw new Error(`Could not find addon manifest in ${rootDir}/src (expected manifest.ts or manifest.json)`);
+}
+/**
+* Resolves the full Vite configuration for building a JChat addon, merging user custom configs if
+* present.
+*
+* @param options - CLI build options.
+* @returns Fully merged {@link InlineConfig} for Vite.
+*/
+async function resolveAddonBuildConfig(options = {}) {
+	const rootDir = path.resolve(options.rootDir || process.cwd());
+	const isDev = options.command === "dev" || options.mode === "development";
+	const mode = options.mode || (isDev ? "development" : "production");
+	const watch = options.watch ?? options.command === "dev";
+	const manifest = await loadAddonManifest(rootDir);
+	const baseConfig = {
+		root: rootDir,
+		configFile: false,
+		mode,
+		plugins: [tailwindcss(), jchatAddon({
+			manifest,
+			development: isDev,
+			zip: options.zip,
+			signingPrivateKey: options.signingPrivateKey
+		})],
+		build: { watch: watch ? {} : null }
+	};
+	const customConfigPath = [
+		"vite.config.ts",
+		"vite.config.js",
+		"vite.config.mjs",
+		"vite.config.cjs"
+	].map((file) => path.resolve(rootDir, file)).find((file) => fs.existsSync(file));
+	if (customConfigPath) {
+		const loaded = await loadConfigFromFile({
+			command: "build",
+			mode
+		}, customConfigPath, rootDir);
+		if (loaded?.config) {
+			if (hasPlugin(loaded.config.plugins, "jchat-addon")) return mergeConfig(loaded.config, {
+				root: rootDir,
+				mode,
+				build: { watch: watch ? {} : null }
+			});
+			return mergeConfig(baseConfig, loaded.config);
+		}
+	}
+	return baseConfig;
+}
+/**
+* Main CLI handler for `jchat-addon`.
+*
+* @param args - CLI arguments (defaults to `process.argv.slice(2)`).
+*/
+async function runAddonCli(args = process.argv.slice(2)) {
+	let command = "build";
+	let watch = false;
+	let mode;
+	let zip;
+	for (const arg of args) if (arg === "dev") {
+		command = "dev";
+		watch = true;
+		mode = "development";
+	} else if (arg === "build") command = "build";
+	else if (arg === "--watch" || arg === "-w") watch = true;
+	else if (arg === "--dev") mode = "development";
+	else if (arg === "--prod" || arg === "--production") mode = "production";
+	else if (arg === "--no-zip") zip = false;
+	else if (arg === "--zip") zip = true;
+	else if (arg === "--help" || arg === "-h") command = "help";
+	if (command === "help") {
+		console.log(`
+JChat Addon CLI (jchat-addon)
+
+Usage:
+  jchat-addon build    Build the addon for production
+  jchat-addon dev      Build and watch the addon in development mode
+
+Options:
+  --watch, -w          Watch files for changes
+  --dev                Run in development mode
+  --prod               Run in production mode
+  --no-zip             Do not package the build into a .zip archive
+  --help, -h           Show this help message
+`);
+		return;
+	}
+	const config = await resolveAddonBuildConfig({
+		command,
+		mode,
+		watch,
+		zip
+	});
+	await build(config);
+}
+if (import.meta.main) runAddonCli().catch((error) => {
+	console.error("❌ Addon build failed:", error);
+	process.exit(1);
+});
+//#endregion
+export { loadAddonManifest, resolveAddonBuildConfig, runAddonCli };