@jchat/addon-sdk 1.0.0-alpha.10 → 1.0.0-alpha.11

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 # @jchat/addon-sdk
 
+## 1.0.0-alpha.11
+
 ## 1.0.0-alpha.10
 
 ## 1.0.0-alpha.9

package/README.md

@@ -1,62 +1,104 @@
 # @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://jchat.im) 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.
+
+---
 
 ## Installation
 
 ```bash
-npm install @jchat/addon-sdk
-# or
-bun add @jchat/addon-sdk
+bun add -d @jchat/addon-sdk
 ```
 
+> **Note**: `@jchat/addon-sdk` is an externalized build dependency. The JChat host runtime automatically provides shared externals (React, UI primitives, Kysely, and context objects) at load time.
+
+---
+
 ## Requirements
 
-- Node.js 20+ or Bun 1.3+
-- React 18+, Elysia, Kysely, and Vite as peer dependencies
+- **Bun**: 1.4.0+
+- **React**: 18+ / 19+
+- **Vite**: 5+ / 6+
+
+---
 
-## Usage
+## Quick Start
+
+### 1. Define Addon Manifest
+
+Create `src/manifest.ts` with metadata, permissions, mount points, and compatibility ranges:
 
 ```ts
-import type {
-  AddonManifest,
-  AddonServerContext,
-  AddonClientContext,
-  AddonProps
-} from "@jchat/addon-sdk"
+import type { AddonManifest } from "@jchat/addon-sdk"
+
+const manifest: AddonManifest = {
+  id: "my-addon",
+  name: "My Addon",
+  version: "1.0.0",
+  description: "Custom feature extension for JChat",
+  author: "Developer",
+  compatibility: {
+    jchat: ">=1.0.0-alpha.0 <2.0.0",
+    addonSdk: ">=1.0.0-alpha.0 <2.0.0"
+  },
+  locales: ["en", "es", "fr", "de", "ar"],
+  defaultLocale: "en",
+  frontend: {
+    bundle: "./ui.js",
+    mountPoints: ["chat-toolbar", "room-settings"]
+  },
+  permissions: []
+}
+
+export default manifest
 ```
 
-For the Vite build plugin:
+### 2. Configure Vite Plugin
+
+In `vite.config.ts`, include the official JChat addon plugin:
 
 ```ts
+import { defineConfig } from "vite"
 import { jchatAddon } from "@jchat/addon-sdk/vite"
 
-export default {
+export default defineConfig({
   plugins: [jchatAddon()]
-}
+})
 ```
 
-## Database Architecture & Schema Isolation
+### 3. Build & Package Addon
 
-JChat database-bearing addons use **Kysely** for server-side database access:
+Use the built-in CLI to build, test, and bundle distribution packages:
 
-- **0 Bundle Overhead**: Table definitions are pure TypeScript interfaces (`src/db.ts`), resulting in 0 runtime JavaScript bundle footprint.
-- **Shared `addons` Schema**: All addon tables are placed inside the dedicated `"addons"` schema (e.g. `addons.DjDropTracks`, `addons.PollwisePolls`, `addons.GlimpseStories`), keeping them cleanly isolated from core `public` application tables without requiring dynamic PostgreSQL role creation (`CREATE ROLE`).
-- **Mandatory Table Naming**: Table names **must start with a Capital letter** and **must be prefixed with your capitalized `addonId`** (e.g. `addons.MyAddonSettings`). Unprefixed tables are rejected by the host migration validator.
-- **SQL Migrations**: Addon migrations are stored as plain SQL files (`migrations/001_*.sql`) listed in `manifest.ts` under `server.migrations`.
-- **ID Column Convention**: Use `text` / `varchar(36)` for host-referencing IDs (`siteId`, `roomId`, `userId`) to ensure driver-agnostic, cast-free query execution with UUID v7 strings.
+```bash
+# Build addon bundle and generate distribution zip
+bun run jchat-addon build --zip
+
+# Start live development watcher
+bun run jchat-addon dev
+```
+
+---
+
+## Database Architecture & Isolated Persistence
+
+For addons requiring persistence, JChat provides zero-overhead, type-safe database queries via **Kysely**:
+
+- **Zero Bundle Overhead**: Define tables as pure TypeScript interfaces (`src/db.ts`) with no ORM runtime footprint.
+- **Isolated `addons` Schema**: All addon tables reside in the dedicated `"addons"` schema (e.g. `addons.MyAddonSettings`, `addons.GlimpseStories`), preventing collision with core application tables.
+- **Table Naming Standard**: Table names must begin with a capital letter and start with your capitalized addon ID (e.g., `MyAddonItems`).
+- **SQL Migrations**: Store migration scripts as standard SQL files under `migrations/` referenced in your manifest.
 
 ```ts
-import type { AddonDatabase } from "@jchat/addon-sdk"
+import type { AddonServerContext } from "@jchat/addon-sdk"
 
 export interface MyAddonDatabase {
   MyAddonSettings: {
     id: string
     siteId: string
+    enabled: boolean
     createdAt: Date
   }
 }
@@ -64,6 +106,27 @@ export interface MyAddonDatabase {
 export type MyAddonContext = AddonServerContext<MyAddonDatabase>
 ```
 
+---
+
+## UI Mount Points & Lifecycle
+
+Addon UI components receive a structured `AddonProps` object containing user, room, localization, and host bridge APIs:
+
+```tsx
+import type { AddonProps } from "@jchat/addon-sdk"
+
+export default function MyAddonComponent({ context, t }: AddonProps) {
+  return (
+    <div className="p-4 rounded-lg bg-card text-card-foreground border shadow-sm">
+      <h3 className="font-semibold">{t("my_addon_title")}</h3>
+      <p className="text-sm text-muted-foreground">{context.siteId}</p>
+    </div>
+  )
+}
+```
+
+---
+
 ## License
 
-Apache-2.0
+Proprietary — All rights reserved. See the [LICENSE](./LICENSE) file included in this package for full terms and conditions.

package/dist/index.mjs

@@ -3,7 +3,7 @@ import * as fs$1 from "node:fs";
 import * as path$1 from "node:path";
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 //#region package.json
-var version = "1.0.0-alpha.10";
+var version = "1.0.0-alpha.11";
 //#endregion
 //#region ../icon/dist/types.mjs
 const e = `Activity.ArrowLeft.ArrowRight.Ban.Bell.BookOpen.Brush.Calendar.Camera.ChartBar.Check.CheckCheck.CheckCircle2.ChevronDown.ChevronLeft.ChevronRight.ChevronUp.CircleAlert.CircleCheck.CircleOff.CirclePlay.CirclePlus.Clock.Coffee.Contact.Cpu.Database.Dices.Ellipsis.Eraser.ExternalLink.Eye.EyeOff.Flag.Flame.FolderPlus.Footprints.Gamepad2.Gift.Globe.HardDrive.Headphones.Heart.Image.Info.Key.KeyRound.Layers.LayoutDashboard.LayoutList.LayoutTemplate.Link2.ListOrdered.Loader.LoaderCircle.Lock.LogOut.Mail.Maximize.Megaphone.MemoryStick.Menu.MessageCircle.MessageSquare.Mic.Minimize.Minus.Monitor.Moon.MoreHorizontal.Music.Music2.Newspaper.Palette.Paperclip.PartyPopper.Pause.PenLine.Play.Plus.Radio.Reply.RotateCcw.RotateCw.Search.Send.Server.Settings.Shield.ShieldAlert.ShieldCheck.SkipForward.SlidersHorizontal.Smartphone.Smile.Sparkles.Square.SquarePen.Star.Sun.ThumbsDown.ThumbsUp.Timer.Trash.Trash2.Trophy.Upload.User.UserCheck.UserCog.UserMinus.UserPen.UserPlus.UserRoundPlus.Users.UserX.Utensils.Video.VideoOff.Volume.Volume2.VolumeX.X.Youtube.Zap`.split(`.`);

package/package.json

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