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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @jchat/addon-sdk
 
+## 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/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.mjs

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "1.0.0-alpha.3";
+var version = "1.0.0-alpha.4";
 //#endregion
 //#region src/contracts.ts
 /** Valid locations where an addon can be rendered within the Jchat layout. */

package/dist/vite.d.mts

@@ -2,13 +2,41 @@ import { t as AddonManifest } from "./contracts.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 /**
- * Vite plugin to configure Jchat addon manifest generation, bundle backend scripts, copy
- * migrations, declarative seed data, and zip production build artifacts.
+ * Vite plugin for building JChat sandboxed addon extensions.
+ *
+ * Configures automatic manifest generation (`manifest.json`), bundles server-side API scripts
+ * (`src/api.ts`), embeds scoped Tailwind CSS into the frontend bundle, packages database migrations
+ * and seed files, copies documentation (`README.md`), signs database-bearing addon manifests, and
+ * zips production build artifacts.
+ *
+ * @example
+ *   ;```ts
+ *   import { jchatAddon } from "@jchat/addon-sdk/vite"
+ *   import manifest from "./src/manifest"
+ *   import { defineConfig } from "vite"
+ *
+ *   export default defineConfig({
+ *     plugins: [jchatAddon({ manifest })]
+ *   })
+ *   ```
+ *
+ * @param options - Configuration options for the JChat addon Vite plugin.
+ * @returns A Vite {@link Plugin} instance configured for addon compilation.
  */
 declare function jchatAddon(options: JchatAddonPluginOptions): Plugin;
+/** Configuration options for the {@link jchatAddon} Vite plugin. */
 interface JchatAddonPluginOptions {
+  /** The base manifest specification for the addon. */
   manifest: AddonManifest;
+  /**
+   * Whether to package the build output into a `.zip` archive upon build completion. Defaults to
+   * `true` during production builds and `false` during development builds.
+   */
   zip?: boolean;
+  /**
+   * Optional RSA private key string used to cryptographically sign database-bearing addons. If
+   * omitted, falls back to the `JCHAT_ADDON_SIGNING_PRIVATE_KEY` environment variable.
+   */
   signingPrivateKey?: string;
   /**
    * Embed Tailwind CSS output into the JS bundle and scope it to the addon's DOM container.
@@ -16,11 +44,36 @@ interface JchatAddonPluginOptions {
    */
   css?: boolean;
 }
+/**
+ * Generates CLI argument parameters for bundling server-side Elysia API scripts (`src/api.ts`) via
+ * Bun.
+ *
+ * @param entryPath - Absolute file path to the server entry script (`src/api.ts`).
+ * @param outputPath - Absolute destination file path for the bundled output (`build/api.js`).
+ * @param developmentBuild - Indicates whether to enable external sourcemaps or minification.
+ * @returns Array of command line arguments for running `bun build`.
+ */
 declare function createAddonServerBuildArguments(entryPath: string, outputPath: string, developmentBuild: boolean): string[];
+/**
+ * Cryptographically signs an addon manifest using RSA-SHA256 over all archive file contents.
+ *
+ * @param manifest - Unsigned or base addon manifest.
+ * @param files - List of archive file paths and raw contents to digest.
+ * @param privateKey - RSA private key in PEM format.
+ * @returns Updated {@link AddonManifest} containing an RSA signature block.
+ */
 declare function signAddonManifest(manifest: AddonManifest, files: readonly {
   path: string;
   contents: Buffer;
 }[], privateKey: string): AddonManifest;
+/**
+ * Resolves the required RSA signing key for database-bearing addons.
+ *
+ * @param signingPrivateKey - Provided signing key or undefined.
+ * @param developmentBuild - Whether the current build is targeting development mode.
+ * @returns Resolved signing key string or undefined (in dev builds).
+ * @throws {@link Error} If building a database-bearing addon in production without a signing key.
+ */
 declare function requireAddonSigningKey(signingPrivateKey: string | undefined, developmentBuild: boolean): string | undefined;
 //#endregion
 export { JchatAddonPluginOptions, createAddonServerBuildArguments, jchatAddon, requireAddonSigningKey, signAddonManifest };

package/dist/vite.mjs

@@ -4,8 +4,26 @@ import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 //#region src/vite.ts
 /**
-* Vite plugin to configure Jchat addon manifest generation, bundle backend scripts, copy
-* migrations, declarative seed data, and zip production build artifacts.
+* Vite plugin for building JChat sandboxed addon extensions.
+*
+* Configures automatic manifest generation (`manifest.json`), bundles server-side API scripts
+* (`src/api.ts`), embeds scoped Tailwind CSS into the frontend bundle, packages database migrations
+* and seed files, copies documentation (`README.md`), signs database-bearing addon manifests, and
+* zips production build artifacts.
+*
+* @example
+*   ;```ts
+*   import { jchatAddon } from "@jchat/addon-sdk/vite"
+*   import manifest from "./src/manifest"
+*   import { defineConfig } from "vite"
+*
+*   export default defineConfig({
+*     plugins: [jchatAddon({ manifest })]
+*   })
+*   ```
+*
+* @param options - Configuration options for the JChat addon Vite plugin.
+* @returns A Vite {@link Plugin} instance configured for addon compilation.
 */
 function jchatAddon(options) {
 	const { manifest: manifestData } = options;
@@ -81,12 +99,15 @@ function jchatAddon(options) {
 					})), signingPrivateKey);
 				}
 			}
+			const readmeSource = path.resolve(rootDir, "README.md");
+			if (fs.existsSync(readmeSource)) fs.copyFileSync(readmeSource, path.resolve(buildDir, "README.md"));
 			const manifestJson = JSON.stringify(manifest, null, 2);
 			fs.writeFileSync(path.resolve(buildDir, "manifest.json"), manifestJson);
 			if (shouldZip) {
 				const zipName = `${manifest.id}-${pkg.version}.zip`;
 				const filesToZip = ["manifest.json", bundleFile];
 				if (fs.existsSync(path.resolve(buildDir, "api.js"))) filesToZip.push("api.js");
+				if (fs.existsSync(path.resolve(buildDir, "README.md"))) filesToZip.push("README.md");
 				const migrationsDest = path.resolve(buildDir, "migrations");
 				if (fs.existsSync(migrationsDest)) filesToZip.push("migrations");
 				const seedsDest = path.resolve(buildDir, "seeds");
@@ -105,6 +126,15 @@ function jchatAddon(options) {
 		}
 	};
 }
+/**
+* Generates CLI argument parameters for bundling server-side Elysia API scripts (`src/api.ts`) via
+* Bun.
+*
+* @param entryPath - Absolute file path to the server entry script (`src/api.ts`).
+* @param outputPath - Absolute destination file path for the bundled output (`build/api.js`).
+* @param developmentBuild - Indicates whether to enable external sourcemaps or minification.
+* @returns Array of command line arguments for running `bun build`.
+*/
 function createAddonServerBuildArguments(entryPath, outputPath, developmentBuild) {
 	return [
 		"build",
@@ -112,9 +142,17 @@ function createAddonServerBuildArguments(entryPath, outputPath, developmentBuild
 		"--target=bun",
 		"--format=esm",
 		`--outfile=${outputPath}`,
-		developmentBuild ? "--sourcemap=external" : "--minify"
+		developmentBuild ? "--sourcemap=inline" : "--minify"
 	];
 }
+/**
+* Cryptographically signs an addon manifest using RSA-SHA256 over all archive file contents.
+*
+* @param manifest - Unsigned or base addon manifest.
+* @param files - List of archive file paths and raw contents to digest.
+* @param privateKey - RSA private key in PEM format.
+* @returns Updated {@link AddonManifest} containing an RSA signature block.
+*/
 function signAddonManifest(manifest, files, privateKey) {
 	if (!manifest.publisher?.id) throw new Error("Signed addons require manifest.publisher.id");
 	const unsigned = {
@@ -142,6 +180,14 @@ function signAddonManifest(manifest, files, privateKey) {
 		}
 	};
 }
+/**
+* Resolves the required RSA signing key for database-bearing addons.
+*
+* @param signingPrivateKey - Provided signing key or undefined.
+* @param developmentBuild - Whether the current build is targeting development mode.
+* @returns Resolved signing key string or undefined (in dev builds).
+* @throws {@link Error} If building a database-bearing addon in production without a signing key.
+*/
 function requireAddonSigningKey(signingPrivateKey, developmentBuild) {
 	if (signingPrivateKey) return signingPrivateKey;
 	if (developmentBuild) return void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jchat/addon-sdk",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "private": false,
   "keywords": [
     "addon",
@@ -44,7 +44,7 @@
   },
   "scripts": {
     "build": "tsdown",
-    "lint": "oxlint . --config=../../oxlint.json",
+    "lint": "oxlint .",
     "format": "oxfmt . --write",
     "typecheck": "tsc --noEmit",
     "prepack": "bun run build"