@jchat/addon-sdk 1.0.0-alpha.3 → 1.0.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @jchat/addon-sdk
 
+## 1.0.0-alpha.6
+
+## 1.0.0-alpha.5
+
+### Minor Changes
+
+- 9755c28: Export curated UI components, types, and Tailwind styles from `@jchat/addon-sdk/ui` (`@jchat/addon-sdk/ui/tailwind.css`) for sandbox and third-party addon developers.
+
+### Patch Changes
+
+- ad4b00c: Add `OWNER_SETTINGS` (`"owner-settings"`) and `ADDON_SETTINGS` (`"addon-settings"`) to `MOUNT_POINTS` constant and strictly type `MountPoint` union to official mount points. Remove legacy `ConfigSchemaField` and `configSchema` from `AddonManifest` in favor of mount-point-driven settings.
+- ada430f: Formatted type declarations in the Addon SDK to align with project style guidelines.
+
+## 1.0.0-alpha.4
+
+### Patch Changes
+
+- ada430f: Formatted type declarations in the Addon SDK to align with project style guidelines.
+
 ## 1.0.0-alpha.3
 
 ### Patch Changes

package/README.md

@@ -40,6 +40,30 @@ export default {
 }
 ```
 
+## Database Architecture & Schema Isolation
+
+JChat database-bearing addons use **Kysely** for server-side database access:
+
+- **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.
+
+```ts
+import type { AddonDatabase } from "@jchat/addon-sdk"
+
+export interface MyAddonDatabase {
+  MyAddonSettings: {
+    id: string
+    siteId: string
+    createdAt: Date
+  }
+}
+
+export type MyAddonContext = AddonServerContext<MyAddonDatabase>
+```
+
 ## License
 
 Apache-2.0

package/dist/contracts.d.mts

@@ -1,23 +1,5 @@
 //#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>`) */
@@ -55,6 +37,10 @@ declare const MOUNT_POINTS: {
   readonly EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-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";
 };
 /** Union type of all valid addon mount points. */
 type MountPoint = (typeof MOUNT_POINTS)[keyof typeof MOUNT_POINTS];
@@ -123,8 +109,6 @@ interface AddonManifest {
   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 };
+export { MountPoint as a, MOUNT_POINTS as i, AddonPermission as n, AddonPermissionDefinition as r, AddonManifest as t };

package/dist/diagnostics.d.mts

@@ -1,22 +1,69 @@
 import { t as AddonManifest } from "./contracts.mjs";
 //#region src/diagnostics.d.ts
+/**
+ * Diagnostic result status indicator for addon validation checks. - `"pass"`: The diagnostic check
+ * passed successfully. - `"warning"`: Non-critical warning (e.g. source maps present in
+ * production). - `"error"`: Critical failure blocking addon installation or distribution.
+ */
 type AddonDiagnosticStatus = "pass" | "warning" | "error";
+/** Represents an individual diagnostic check result for an addon package. */
 interface AddonPackageDiagnostic {
+  /** Unique identifier for the diagnostic check (e.g. `"jchat"`, `"package-size"`). */
   id: string;
+  /** Human-readable title for the diagnostic check. */
   label: string;
+  /** Severity status outcome of the check. */
   status: AddonDiagnosticStatus;
+  /** Descriptive message or metric value providing check details. */
   message: string;
 }
+/** Options required to run diagnostic validation on an addon build package. */
 interface AddonPackageDiagnosticOptions {
+  /** Absolute path to the compiled addon build output directory (`build/`). */
   buildDir: string;
+  /** Parsed addon manifest object (`manifest.json`). */
   manifest: AddonManifest;
+  /** Semantic version of the host JChat platform instance. */
   jchatVersion: string;
+  /** Semantic version of the `@jchat/addon-sdk` package. */
   addonSdkVersion: string;
+  /** Whether the diagnostic target is a production `.zip` package build. Defaults to `false`. */
   productionPackage?: boolean;
+  /** Maximum allowable package size in bytes. Defaults to 25MB (`26,214,400` bytes). */
   maxBytes?: number;
 }
+/**
+ * Constructs a semantic version compatibility range covering all minor/patch versions of the
+ * current major version.
+ *
+ * @example
+ *   ;```ts
+ *   createCompatibleMajorRange("1.4.2") // returns ">=1.4.2 <2.0.0"
+ *   ```
+ *
+ * @param version - Valid semver string (e.g. `"1.2.0"`).
+ * @returns Semver range string matching the current major series (e.g. `">=1.2.0 <2.0.0"`).
+ * @throws {@link Error} If the input is not a valid semantic version string.
+ */
 declare function createCompatibleMajorRange(version: string): string;
+/**
+ * Performs comprehensive diagnostic validation checks on an addon package build directory.
+ *
+ * Validates version compatibility ranges, verifies required build files (frontend/server bundles,
+ * migrations, seeds), checks total package size limits, flags production source maps, and verifies
+ * publisher digital signatures.
+ *
+ * @param options - Configuration options specifying build directory, manifest, and environment
+ *   versions.
+ * @returns Array of {@link AddonPackageDiagnostic} results.
+ */
 declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
+/**
+ * Checks whether any diagnostic check in a diagnostic list returned a critical error.
+ *
+ * @param diagnostics - Array of diagnostic check results to evaluate.
+ * @returns `true` if at least one check has `status === "error"`, otherwise `false`.
+ */
 declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;
 //#endregion
 export { AddonDiagnosticStatus, AddonPackageDiagnostic, AddonPackageDiagnosticOptions, createCompatibleMajorRange, diagnoseAddonPackage, hasAddonDiagnosticErrors };

package/dist/diagnostics.mjs

@@ -1,6 +1,19 @@
 import * as fs$1 from "node:fs";
 import * as path$1 from "node:path";
 //#region src/diagnostics.ts
+/**
+* Constructs a semantic version compatibility range covering all minor/patch versions of the
+* current major version.
+*
+* @example
+*   ;```ts
+*   createCompatibleMajorRange("1.4.2") // returns ">=1.4.2 <2.0.0"
+*   ```
+*
+* @param version - Valid semver string (e.g. `"1.2.0"`).
+* @returns Semver range string matching the current major series (e.g. `">=1.2.0 <2.0.0"`).
+* @throws {@link Error} If the input is not a valid semantic version string.
+*/
 function createCompatibleMajorRange(version) {
 	try {
 		Bun.semver.order(version, version);
@@ -12,6 +25,17 @@ function createCompatibleMajorRange(version) {
 	if (!Number.isSafeInteger(major)) throw new Error(`Invalid semantic version: ${version}`);
 	return `>=${version} <${major + 1}.0.0`;
 }
+/**
+* Performs comprehensive diagnostic validation checks on an addon package build directory.
+*
+* Validates version compatibility ranges, verifies required build files (frontend/server bundles,
+* migrations, seeds), checks total package size limits, flags production source maps, and verifies
+* publisher digital signatures.
+*
+* @param options - Configuration options specifying build directory, manifest, and environment
+*   versions.
+* @returns Array of {@link AddonPackageDiagnostic} results.
+*/
 function diagnoseAddonPackage(options) {
 	const { buildDir, manifest } = options;
 	const diagnostics = [];
@@ -59,6 +83,18 @@ function diagnoseAddonPackage(options) {
 		status: totalBytes <= maxBytes ? "pass" : "error",
 		message: `${totalBytes} of ${maxBytes} bytes`
 	});
+	const addonPermPrefix = `addon.${manifest.id}.`;
+	const invalidPerms = Array.from(/* @__PURE__ */ new Set([
+		...manifest.accessPermission ? [manifest.accessPermission] : [],
+		...manifest.permissions ?? [],
+		...manifest.permissionDefinitions?.map((d) => d.name) ?? []
+	])).filter((perm) => !perm.startsWith(addonPermPrefix));
+	diagnostics.push({
+		id: "permission-namespacing",
+		label: "Permission namespacing",
+		status: invalidPerms.length === 0 ? "pass" : "error",
+		message: invalidPerms.length === 0 ? `All declared permissions start with ${addonPermPrefix}` : `Permission(s) do not follow naming convention ${addonPermPrefix}*: ${invalidPerms.join(", ")}`
+	});
 	const sourceMaps = files.filter((file) => file.endsWith(".map"));
 	diagnostics.push({
 		id: "source-maps",
@@ -81,9 +117,24 @@ function diagnoseAddonPackage(options) {
 	});
 	return diagnostics;
 }
+/**
+* Checks whether any diagnostic check in a diagnostic list returned a critical error.
+*
+* @param diagnostics - Array of diagnostic check results to evaluate.
+* @returns `true` if at least one check has `status === "error"`, otherwise `false`.
+*/
 function hasAddonDiagnosticErrors(diagnostics) {
 	return diagnostics.some(({ status }) => status === "error");
 }
+/**
+* Evaluates semantic version compatibility between a target version and a semver range string.
+*
+* @param id - Diagnostic check identifier.
+* @param label - Diagnostic check label.
+* @param version - Environment component version string.
+* @param range - Expected semver range string from manifest compatibility declarations.
+* @returns An {@link AddonPackageDiagnostic} result object.
+*/
 function compatibilityDiagnostic(id, label, version, range) {
 	const compatible = Boolean(range && Bun.semver.satisfies(version, range));
 	return {
@@ -93,12 +144,26 @@ function compatibilityDiagnostic(id, label, version, range) {
 		message: range ? `${version} ${compatible ? "satisfies" : "does not satisfy"} ${range}` : "Compatibility range is missing"
 	};
 }
+/**
+* Safely resolves a relative build file reference within a target build directory, guarding against
+* directory traversal attacks.
+*
+* @param buildDir - Absolute path to the build directory.
+* @param reference - Relative file path declared in manifest.
+* @returns Resolved absolute file path if safe and inside `buildDir`, or `null` if unsafe.
+*/
 function resolveBuildFile(buildDir, reference) {
 	if (path$1.isAbsolute(reference) || reference.includes("\\") || reference.split("/").includes("..")) return null;
 	const target = path$1.resolve(buildDir, ...reference.replace(/^\.\//, "").split("/"));
 	const relative = path$1.relative(path$1.resolve(buildDir), target);
 	return relative && !relative.startsWith("..") && !path$1.isAbsolute(relative) ? target : null;
 }
+/**
+* Recursively lists all regular files within a root directory.
+*
+* @param root - Path to search.
+* @returns Array of absolute file paths.
+*/
 function listRegularFiles(root) {
 	if (!fs$1.existsSync(root)) return [];
 	return fs$1.readdirSync(root, {

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { a as MOUNT_POINTS, i as ConfigSchemaField, n as AddonPermission, o as MountPoint, r as AddonPermissionDefinition, t as AddonManifest } from "./contracts.mjs";
+import { a as MountPoint, i as MOUNT_POINTS, n as AddonPermission, r as AddonPermissionDefinition, t as AddonManifest } from "./contracts.mjs";
 import { ComponentType, SVGProps } from "react";
 import { Elysia } from "elysia";
 import { Kysely } from "kysely";
-//#region ../icon/src/types.d.ts
+//#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];
@@ -268,4 +269,4 @@ declare function useIcons(): {
  */
 declare function getAddonSdkVersion(): string;
 //#endregion
-export { AddonApi, AddonDatabase, AddonEventListener, AddonFont, AddonJsonBody, type AddonManifest, type AddonPermission, type AddonPermissionDefinition, AddonProps, AddonRequestUser, AddonSDK, AddonSeedDocument, AddonServerContext, AddonServerFactory, AddonUser, type ConfigSchemaField, MOUNT_POINTS, type MountPoint, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonSDK, useIcons };
+export { AddonApi, AddonDatabase, AddonEventListener, AddonFont, AddonJsonBody, type AddonManifest, type AddonPermission, type AddonPermissionDefinition, AddonProps, AddonRequestUser, AddonSDK, AddonSeedDocument, AddonServerContext, AddonServerFactory, AddonUser, MOUNT_POINTS, type MountPoint, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonSDK, useIcons };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "1.0.0-alpha.3";
+var version = "1.0.0-alpha.6";
 //#endregion
 //#region src/contracts.ts
 /** Valid locations where an addon can be rendered within the Jchat layout. */
@@ -29,7 +29,11 @@ const MOUNT_POINTS = {
 	/** Custom tab in the emoji/gif selection panel */
 	EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab",
 	/** Full-screen or modal dialog specifically for TubeScan */
-	TUBESCAN_DIALOG: "tubescan-dialog"
+	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"
 };
 //#endregion
 //#region src/index.ts