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

package/dist/contracts.mjs

@@ -0,0 +1,38 @@
+//#region src/contracts.ts
+/** Valid locations where an addon can be rendered within the Jchat layout. */
+const MOUNT_POINTS = {
+	/** Top of the main chat column */
+	CHAT_HEADER: "chat-header",
+	/** Below the main chat header, above messages */
+	CHAT_TOOLBAR: "chat-toolbar",
+	/** The persistent right-side sidebar */
+	CHAT_SIDEBAR: "chat-sidebar",
+	/** Top of the left sidebar (room list) */
+	SIDEBAR_TOP: "sidebar-top",
+	/** Bottom of the left sidebar */
+	SIDEBAR_BOTTOM: "sidebar-bottom",
+	/** Action list shown when clicking a user's avatar */
+	USER_POPOVER_ACTIONS: "user-popover-actions",
+	/** Menu shown when right-clicking a message */
+	MESSAGE_CONTEXT_MENU: "message-context-menu",
+	/** Floating overlay rendered on top of the message stream */
+	MESSAGE_FEED_OVERLAY: "message-feed-overlay",
+	/** Main admin dashboard area */
+	ADMIN_PANEL: "admin-panel",
+	/** User or site settings dashboard area */
+	SETTINGS_PANEL: "settings-panel",
+	/** The 'plus' (+) menu in the message composer */
+	CHAT_PLUS_MENU: "chat-plus-menu",
+	/** Custom tab in the emoji/gif selection panel */
+	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"
+};
+//#endregion
+export { MOUNT_POINTS };

package/dist/diagnostics.d.mts

@@ -1,22 +1,68 @@
-import { t as AddonManifest } from "./contracts.mjs";
+import { AddonManifest } from "./contracts.mjs";
 //#region src/diagnostics.d.ts
-type AddonDiagnosticStatus = "pass" | "warning" | "error";
-interface AddonPackageDiagnostic {
+/**
+ * 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.
+ */
+export type AddonDiagnosticStatus = "pass" | "warning" | "error";
+/** Represents an individual diagnostic check result for an addon package. */
+export 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;
 }
-interface AddonPackageDiagnosticOptions {
+/** Options required to run diagnostic validation on an addon build package. */
+export 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;
 }
-declare function createCompatibleMajorRange(version: string): string;
-declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
-declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;
-//#endregion
-export { AddonDiagnosticStatus, AddonPackageDiagnostic, AddonPackageDiagnosticOptions, createCompatibleMajorRange, diagnoseAddonPackage, hasAddonDiagnosticErrors };
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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`.
+ */
+export declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;
+//#endregion

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 = [];
@@ -52,13 +76,25 @@ function diagnoseAddonPackage(options) {
 	const productionArchive = path$1.join(buildDir, `${manifest.id}-${manifest.version}.zip`);
 	const hasProductionArchive = fs$1.existsSync(productionArchive) && fs$1.statSync(productionArchive).isFile();
 	const totalBytes = options.productionPackage && hasProductionArchive ? fs$1.statSync(productionArchive).size : files.filter((file) => file !== productionArchive).reduce((total, file) => total + fs$1.statSync(file).size, 0);
-	const maxBytes = options.maxBytes ?? 25 * 1024 * 1024;
+	const maxBytes = options.maxBytes ?? 26214400;
 	diagnostics.push({
 		id: "package-size",
 		label: "Package size",
 		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/i18n-validator.d.mts

@@ -0,0 +1,17 @@
+//#region src/i18n-validator.d.ts
+export interface AddonLocaleValidationResult {
+  valid: boolean;
+  errors: string[];
+  missingFiles: string[];
+  missingKeys: Record<string, string[]>;
+  extraKeys: Record<string, string[]>;
+}
+/**
+ * Validates that an addon's `locales/` directory contains valid translation files for all 20 host
+ * languages with 100% key parity against `en.json`.
+ *
+ * @param dirPath - Path to the addon's locales directory.
+ * @param domainName - Optional label for error messages (defaults to "Addon").
+ */
+export declare function validateAddonLocales(dirPath: string, domainName?: string): AddonLocaleValidationResult;
+//#endregion

package/dist/i18n-validator.mjs

@@ -0,0 +1,90 @@
+import { t as HOST_LANGUAGES } from "./i18n.mjs";
+import * as fs$1 from "node:fs";
+import * as path$1 from "node:path";
+//#region src/i18n-validator.ts
+function extractNestedKeys(obj, prefix = "") {
+	if (!obj || typeof obj !== "object") return [];
+	const keys = [];
+	for (const [key, value] of Object.entries(obj)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+		if (value && typeof value === "object" && !Array.isArray(value)) keys.push(...extractNestedKeys(value, fullKey));
+		else keys.push(fullKey);
+	}
+	return keys;
+}
+/**
+* Validates that an addon's `locales/` directory contains valid translation files for all 20 host
+* languages with 100% key parity against `en.json`.
+*
+* @param dirPath - Path to the addon's locales directory.
+* @param domainName - Optional label for error messages (defaults to "Addon").
+*/
+function validateAddonLocales(dirPath, domainName = "Addon") {
+	const errors = [];
+	const missingFiles = [];
+	const missingKeys = {};
+	const extraKeys = {};
+	const enPath = path$1.join(dirPath, "en.json");
+	if (!fs$1.existsSync(enPath)) {
+		const errorMsg = `[${domainName}] Missing base locale file: en.json`;
+		errors.push(errorMsg);
+		missingFiles.push("en.json");
+		return {
+			valid: false,
+			errors,
+			missingFiles,
+			missingKeys,
+			extraKeys
+		};
+	}
+	let enContent;
+	try {
+		enContent = JSON.parse(fs$1.readFileSync(enPath, "utf-8"));
+	} catch (err) {
+		const errorMsg = `[${domainName}] Invalid JSON in en.json: ${err instanceof Error ? err.message : String(err)}`;
+		errors.push(errorMsg);
+		return {
+			valid: false,
+			errors,
+			missingFiles,
+			missingKeys,
+			extraKeys
+		};
+	}
+	const enKeys = new Set(extractNestedKeys(enContent));
+	for (const lang of HOST_LANGUAGES) {
+		if (lang === "en") continue;
+		const langFileName = `${lang}.json`;
+		const langPath = path$1.join(dirPath, langFileName);
+		if (!fs$1.existsSync(langPath)) {
+			errors.push(`[${domainName}] Missing locale file: ${langFileName}`);
+			missingFiles.push(langFileName);
+			continue;
+		}
+		try {
+			const langContent = JSON.parse(fs$1.readFileSync(langPath, "utf-8"));
+			const langKeys = new Set(extractNestedKeys(langContent));
+			for (const key of enKeys) if (!langKeys.has(key)) {
+				errors.push(`[${domainName}] Missing key in ${langFileName}: "${key}"`);
+				if (!missingKeys[lang]) missingKeys[lang] = [];
+				missingKeys[lang].push(key);
+			}
+			for (const key of langKeys) if (!enKeys.has(key)) {
+				errors.push(`[${domainName}] Extra key in ${langFileName} (not in en.json): "${key}"`);
+				if (!extraKeys[lang]) extraKeys[lang] = [];
+				extraKeys[lang].push(key);
+			}
+		} catch (err) {
+			errors.push(`[${domainName}] Invalid JSON in ${langFileName}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		missingFiles,
+		missingKeys,
+		extraKeys
+	};
+}
+//#endregion
+export { validateAddonLocales };

package/dist/i18n.mjs

@@ -0,0 +1,191 @@
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+//#region src/i18n.ts
+function checkIsRtl(code) {
+	if (!code) return false;
+	const normalized = code.toLowerCase().split("-")[0];
+	return normalized === "ar" || normalized === "he" || normalized === "ur";
+}
+function getLanguageDirection(code) {
+	return checkIsRtl(code) ? "rtl" : "ltr";
+}
+function interpolate(text, params) {
+	if (!params) return text;
+	return text.replace(/\{\{\s*(\w+)\s*\}\}|\{\s*(\w+)\s*\}/g, (match, key1, key2) => {
+		const key = key1 || key2;
+		return key in params ? String(params[key]) : match;
+	});
+}
+const HOST_LANGUAGES = [
+	"ar",
+	"bg",
+	"hr",
+	"de",
+	"el",
+	"en",
+	"es",
+	"fr",
+	"he",
+	"hi",
+	"kn",
+	"ml",
+	"nl",
+	"pt",
+	"ro",
+	"ru",
+	"ta",
+	"te",
+	"tr",
+	"ur"
+];
+const LocaleContext = createContext({
+	locale: "en",
+	dir: "ltr"
+});
+/** Resolves a nested key in an object dictionary using dot-notation (e.g. "buttons.submit") */
+function resolveNestedKey(obj, keyPath) {
+	if (!obj || typeof obj !== "object") return void 0;
+	const segments = keyPath.split(".");
+	let current = obj;
+	for (const seg of segments) if (current && typeof current === "object" && seg in current) current = current[seg];
+	else return;
+	return current;
+}
+/**
+* Creates a standalone translation function for backend server routes (`src/api.ts`) or utilities.
+*
+* @param resources - Dictionary of translation resources (e.g., `{ en: enJson, ta: taJson }`).
+* @param defaultLocale - Default locale to use if not specified per call (defaults to "en").
+* @param fallbackLocale - Fallback locale if a key is missing in the target language (defaults to
+*   "en").
+*/
+function createTranslator(resources = {}, defaultLocale = "en", fallbackLocale = "en") {
+	return (key, paramsOrLang, maybeLang) => {
+		let params;
+		let lang = defaultLocale;
+		if (typeof paramsOrLang === "string") lang = paramsOrLang;
+		else if (paramsOrLang && typeof paramsOrLang === "object") {
+			params = paramsOrLang;
+			if (typeof maybeLang === "string") lang = maybeLang;
+		}
+		const normalizedLang = (lang || defaultLocale).toLowerCase().split("-")[0];
+		const normalizedFallback = fallbackLocale.toLowerCase().split("-")[0];
+		const langDict = resources[normalizedLang];
+		let resolved = resolveNestedKey(langDict, key);
+		if (resolved === void 0 && normalizedLang !== normalizedFallback) {
+			const fallbackDict = resources[normalizedFallback];
+			resolved = resolveNestedKey(fallbackDict, key);
+		}
+		if (typeof resolved === "string") return interpolate(resolved, params);
+		return typeof resolved === "number" || typeof resolved === "boolean" ? String(resolved) : interpolate(key, params);
+	};
+}
+/**
+* Hook to access the current active host locale and text direction in an addon component.
+*
+* @example
+*   ;```tsx
+*   import { useLocale } from "@jchat/addon-sdk"
+*
+*   export default function MyAddon() {
+*     const { locale, dir, isRtl } = useLocale()
+*     return <div dir={dir}>Current language: {locale}</div>
+*   }
+*   ```
+*/
+function useLocale() {
+	const context = useContext(LocaleContext);
+	const locale = context?.locale || "en";
+	const dir = context?.dir || getLanguageDirection(locale);
+	return {
+		locale,
+		dir,
+		isRtl: dir === "rtl" || checkIsRtl(locale)
+	};
+}
+const loadedChunkCache = {};
+/**
+* Hook to access translation function and locale metadata inside addon components. Automatically
+* synchronizes with host language switches and falls back to English. Supports static dictionary
+* resources or dynamic async locale loaders.
+*
+* @example
+*   ;```tsx
+*   import { useTranslation } from "@jchat/addon-sdk"
+*   import locales from "./locales"
+*
+*   export default function MyAddon() {
+*     const { t, locale, dir } = useTranslation(locales)
+*     return (
+*       <div dir={dir}>
+*         <h1>{t("welcome", { name: "Guest" })}</h1>
+*       </div>
+*     )
+*   }
+*   ```
+*
+* @param resourcesOrLoader - Addon-scoped translation dictionaries or async chunk loader.
+* @param fallbackLocale - Fallback language code when a string is missing (default: "en").
+*/
+function useTranslation(resourcesOrLoader = {}, fallbackLocale = "en") {
+	const { locale, dir, isRtl } = useLocale();
+	const isLoader = typeof resourcesOrLoader === "function";
+	const [dynamicResources, setDynamicResources] = useState(() => {
+		return isLoader ? loadedChunkCache : resourcesOrLoader;
+	});
+	const [isReady, setIsReady] = useState(!isLoader);
+	useEffect(() => {
+		if (!isLoader) {
+			setDynamicResources(resourcesOrLoader);
+			setIsReady(true);
+			return;
+		}
+		const loader = resourcesOrLoader;
+		const normLocale = locale.toLowerCase().split("-")[0];
+		if (loadedChunkCache[normLocale]) {
+			setDynamicResources((prev) => ({
+				...prev,
+				[normLocale]: loadedChunkCache[normLocale]
+			}));
+			setIsReady(true);
+			return;
+		}
+		let isMounted = true;
+		Promise.resolve(loader(normLocale)).then((dict) => {
+			if (!isMounted || !dict) return;
+			loadedChunkCache[normLocale] = dict;
+			setDynamicResources((prev) => ({
+				...prev,
+				[normLocale]: dict
+			}));
+			setIsReady(true);
+		}).catch((err) => {
+			console.warn(`[addon-sdk] Failed to dynamically load locale chunk "${normLocale}":`, err);
+			if (isMounted) setIsReady(true);
+		});
+		return () => {
+			isMounted = false;
+		};
+	}, [
+		isLoader,
+		resourcesOrLoader,
+		locale
+	]);
+	const translator = useMemo(() => {
+		return createTranslator(dynamicResources, locale, fallbackLocale);
+	}, [
+		dynamicResources,
+		locale,
+		fallbackLocale
+	]);
+	return {
+		t: useMemo(() => {
+			return (key, params) => translator(key, params, locale);
+		}, [translator, locale]),
+		locale,
+		dir,
+		isRtl,
+		isReady
+	};
+}
+//#endregion
+export { useTranslation as a, useLocale as i, LocaleContext as n, createTranslator as r, HOST_LANGUAGES as t };

package/dist/icon.d.mts

@@ -0,0 +1,4 @@
+import { i as IconPack, n as IconComponent, r as IconName, t as ICON_NAMES } from "./types.mjs";
+import { a as getIconPack, c as lucidePack, i as fa6Pack, l as phosphorPack, n as Icons, o as heroPack, r as Youtube, s as isIconName, t as IconPackName, u as resolveIcon } from "./index.mjs";
+export * from "lucide-react";
+export { ICON_NAMES, type IconComponent, type IconName, type IconPack, IconPackName, Icons, Icons as default, Youtube, fa6Pack, getIconPack, heroPack, isIconName, lucidePack, phosphorPack, resolveIcon };

package/dist/icon.mjs

@@ -0,0 +1,4 @@
+import { i as IconPack, n as IconComponent, r as IconName, t as ICON_NAMES } from "./types.d.mts";
+import { a as getIconPack, c as lucidePack, i as fa6Pack, l as phosphorPack, n as Icons, o as heroPack, r as Youtube, s as isIconName, t as IconPackName, u as resolveIcon } from "./index.d.mts";
+export * from "lucide-react";
+export { ICON_NAMES, IconComponent, IconName, IconPack, IconPackName, Icons, Icons as default, Youtube, fa6Pack, getIconPack, heroPack, isIconName, lucidePack, phosphorPack, resolveIcon };