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

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,91 @@
+import { HOST_LOCALES } from "./contracts.mjs";
+import "./i18n.mjs";
+import * as path$1 from "node:path";
+import * as fs$1 from "node:fs";
+//#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_LOCALES) {
+		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,169 @@
+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 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 i, createTranslator as n, useLocale as r, LocaleContext 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 };

package/dist/index.d.mts

@@ -1,271 +1,20 @@
-import { a as MOUNT_POINTS, i as ConfigSchemaField, n as AddonPermission, o as MountPoint, 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
-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];
-type IconPack = Record<IconName, IconComponent>;
+import { i as IconPack, n as IconComponent, r as IconName, t as ICON_NAMES } from "./types.mjs";
+//#region ../icon/dist/index.d.mts
+//#region src/packs/lucide.d.ts
+declare const Youtube: IconComponent;
+declare const lucidePack: IconPack;
 //#endregion
 //#region src/index.d.ts
-type AddonJsonBody = Record<string, unknown> | unknown[] | null;
-/**
- * @jchat/addon-sdk
- *
- *   Lightweight SDK for Jchat addon developers. Provides TypeScript types for addon props, manifest
- *   schema, and host API access. This package is always EXTERNALISED from addon bundles — the host
- *   app provides the runtime implementation.
- */
-/** Minimal user profile accessible to addon backends. */
-interface AddonUser {
-  /** Unique user identifier */
-  id: string;
-  /** Display name */
-  name: string;
-  /** Full display name */
-  displayName: string;
-  /** Full URL to the user's avatar image */
-  avatar: string;
-  /** User's gender identifier */
-  gender: string;
-}
-interface AddonRequestUser {
-  id?: string;
-  permissions?: string[];
-  siteId?: string;
-}
-/**
- * Typed, schema-scoped database facade for an addon. The host deliberately omits raw execution,
- * schema switching, dialect/connection access, and lifecycle methods.
- */
-type AddonDatabase<TDatabase = Record<string, Record<string, unknown>>> = Pick<Kysely<TDatabase>, "deleteFrom" | "fn" | "insertInto" | "selectFrom" | "transaction" | "updateTable">;
-/**
- * Context provided to an addon's server-side factory. Parameterize it with the addon's table
- * interface: `AddonServerContext<MyAddonDatabase>`.
- */
-interface AddonServerContext<TDatabase = Record<string, Record<string, unknown>>> {
-  /**
-   * Retrieve the encrypted settings for this addon for a specific site. Internal secrets are
-   * automatically decrypted using the host's master key.
-   */
-  getConfig: (siteId: string) => Promise<Record<string, unknown>>;
-  /** Fetch a specific user's public profile */
-  getUser: (userId: string) => Promise<AddonUser | null>;
-  /** Efficiently fetch multiple user profiles in a single query. Returns a Map keyed by user ID. */
-  getUsers: (userIds: string[]) => Promise<Map<string, AddonUser>>;
-  /**
-   * Check whether the request user holds a given permission. Provides autocomplete for core Jchat
-   * permissions while also accepting any custom addon permission string.
-   *
-   * @param user - The user object from the request context
-   * @param permission - The permission to check, e.g., 'message.send' or 'addon.stories.view'
-   */
-  hasPermission: (user: AddonRequestUser | null | undefined, permission: AddonPermission) => boolean;
-  /**
-   * A Kysely database instance scoped entirely to your addon's tables. You cannot access core Jchat
-   * tables (Users, Rooms, etc.) through this instance.
-   */
-  db: AddonDatabase<TDatabase>;
-}
-/**
- * The entry point for your addon's server bundle. You should default-export a function matching
- * this signature.
- *
- * @example
- *   ;```ts
- *   import { type AddonServerFactory } from '@jchat/addon-sdk'
- *
- *   const factory: AddonServerFactory = ({ db, hasPermission }, app) => {
- *   return app.get('/trending', async () => { ... })
- *   }
- *   export default factory
- *   ```
- */
-type AddonServerFactory<TDatabase = Record<string, Record<string, unknown>>> = (ctx: AddonServerContext<TDatabase>, app: Elysia) => Elysia;
-/** Props passed to your addon's root React component by the Jchat host. */
-interface AddonProps {
-  /** The mount point where this addon instance is rendered (e.g., 'chat-sidebar') */
-  mountPoint: MountPoint;
-  /** Information about the currently logged-in user (if any) */
-  user?: {
-    id: string;
-    name: string;
-    displayName?: string;
-    avatar?: string;
-    gender?: string;
-  };
-  /** The ID of the room the user is currently viewing (if applicable) */
-  roomId?: string;
-  /** The ID of the active Jchat site */
-  siteId?: string;
-}
-interface AddonApi {
-  get: <TResponse = unknown>(path: string) => Promise<TResponse>;
-  post: <TResponse = unknown>(path: string, body?: AddonJsonBody) => Promise<TResponse>;
-  put: <TResponse = unknown>(path: string, body?: AddonJsonBody) => Promise<TResponse>;
-  delete: <TResponse = unknown>(path: string) => Promise<TResponse>;
-}
-type AddonEventListener = (data: unknown) => void;
-/** A font option provided by the JChat host. */
-interface AddonFont {
-  /** Display label shown to users (e.g. 'Modern', 'Elegant') */
-  label: string;
-  /** Font identifier stored in the database (e.g. 'poppins', 'lato') */
-  value: string;
-  /** CSS font-family string ready for use in inline styles */
-  family: string;
-  /** Google Fonts name for loading the font via a <link> tag */
-  googleName: string;
-  /** Relative size multiplier — apply this to base font sizes to match the host's rendering */
-  scale: number;
-}
-/**
- * The bridge between your addon and the Jchat host application. Use the `useAddonSDK()` hook to
- * access this interface in your components.
- */
-interface AddonSDK {
-  /**
-   * Make authenticated API calls to your addon's backend or core Jchat endpoints. All calls
-   * automatically include the current user's sessionId and site validation headers.
-   */
-  api: AddonApi;
-  /**
-   * Display a temporary notification toast in the host UI.
-   *
-   * @param message - The text content to display
-   * @param variant - Visual style: 'default' (blue), 'success' (green), or 'error' (red)
-   */
-  toast: (message: string, variant?: "default" | "success" | "error") => void;
-  /**
-   * Navigate the host application to a different internal route.
-   *
-   * @param path - The target location, e.g., '/settings' or '/addons/store'
-   */
-  navigate: (path: string) => void;
-  /**
-   * Interaction utilities for the active Slate message editor. Only available if your addon is
-   * mounted near the chat input.
-   */
-  editor: {
-    /**
-     * Trigger a specialized editor command defined by the host.
-     *
-     * @example
-     *   sdk.editor.dispatchCommand("INSERT_YOUTUBE_COMMAND", "dQw4w9WgXcQ")
-     */
-    dispatchCommand: (command: string, payload?: unknown) => void;
-    /**
-     * Insert a low-level Slate node directly at the user's cursor position.
-     *
-     * @param node - A valid Slate Descendant or Fragment object
-     */
-    insertNode: (node: unknown) => void;
-    /**
-     * Upload and attach a file to the current message without inserting it inline. Users will see
-     * the file in the attachment bar below the editor.
-     */
-    addAttachment: (attachment: {
-      url: string;
-      name: string;
-      type: string;
-    }) => void;
-    /** Force the browser focus back to the editor input */
-    focus: () => void;
-  };
-  /** Event Bus for reacting to real-time application state changes. */
-  events: {
-    /**
-     * Register a persistent listener for a specific event.
-     *
-     * @param event - Event name, e.g., 'room.message', 'user.typing'
-     */
-    on: (event: string, callback: AddonEventListener) => void;
-    /** Unregister a previously attached listener */
-    off: (event: string, callback: AddonEventListener) => void;
-  };
-  /**
-   * The list of fonts available in this JChat deployment, as configured by the site administrator.
-   * Use this to build a font picker or apply a matching font family in your addon UI.
-   */
-  supportedFonts?: AddonFont[];
-}
-/**
- * Seed data for your addon's tables, provided inside the addon's isolated schema.
- *
- * These documents are inserted into the addon's dedicated schema on installation and can be used to
- * provide default values, references, or supporting data. The host guarantees that these documents
- * do not conflict with core schemas or other addons.
- */
-interface AddonSeedDocument {
-  /** Addon-owned table name. Core prefixes the addon's isolated PostgreSQL schema. */
-  table: string;
-  /** Behavior when a row conflicts with an existing unique or primary key. */
-  conflict?: "error" | "ignore" | "update";
-  /** Required for update behavior; identifies the unique key used by ON CONFLICT. */
-  conflictColumns?: string[];
-  /** JSON-compatible rows inserted using parameterized values. */
-  rows: Record<string, unknown>[];
-}
-/** Define a manifest with full validation-friendly typing while preserving literal values. */
-declare function defineAddonManifest<const TManifest extends AddonManifest>(manifest: TManifest): TManifest;
-/** Define a typed server factory without widening its addon database interface. */
-declare function defineAddonServer<TDatabase = Record<string, Record<string, unknown>>>(factory: AddonServerFactory<TDatabase>): AddonServerFactory<TDatabase>;
-/**
- * Access the host application's SDK. Provides authenticated API access, toast notifications, and
- * navigation.
- *
- * This function is a shell; the real implementation is provided by the Jchat host environment at
- * runtime.
- *
- * @example
- *   ;```tsx
- *   import { useAddonSDK } from "@jchat/addon-sdk"
- *
- *   export default function MyAddon({ mountPoint }: AddonProps) {
- *     const sdk = useAddonSDK()
- *
- *     const handleClick = async () => {
- *       const data = await sdk.api.get("/trending")
- *       sdk.toast("Fetched trending posts!", "success")
- *     }
- *   }
- *   ```
- */
-declare function useAddonSDK(): AddonSDK;
-/**
- * Access the host application's active icon pack. Returns the icon set matching the site's
- * configured icon pack preference.
- *
- * This function is a shell; the real implementation is provided by the Jchat host environment at
- * runtime.
- *
- * @example
- *   ;```tsx
- *   import { useIcons } from "@jchat/addon-sdk"
- *
- *   export default function MyAddon() {
- *     const { Icons } = useIcons()
- *     return <Icons.Send className="size-5" />
- *   }
- *   ```
- */
-declare function useIcons(): {
-  Icons: IconPack;
+declare const fa6Pack: IconPack;
+declare const heroPack: IconPack;
+declare const phosphorPack: IconPack;
+declare const IconPackName: {
+  readonly LUCIDE: "lucide";
 };
-/**
- * Get the version of the addon SDK. This is useful for checking compatibility with the host
- * application.
- *
- * @example
- *   ;```tsx
- *   import { getAddonSdkVersion } from "@jchat/addon-sdk"
- *
- *   console.log(getAddonSdkVersion())
- *   ```
- *
- * @returns
- */
-declare function getAddonSdkVersion(): string;
+type IconPackName = (typeof IconPackName)[keyof typeof IconPackName];
+declare const getIconPack: (_name?: string) => IconPack;
+declare const isIconName: (value: string) => value is IconName;
+declare function resolveIcon(packOrName?: IconPack | string, nameOrFallback?: string | IconName, fallback?: IconName): IconComponent;
+declare const Icons: IconPack;
 //#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 { getIconPack as a, lucidePack as c, fa6Pack as i, phosphorPack as l, Icons as n, heroPack as o, Youtube as r, isIconName as s, IconPackName as t, resolveIcon as u };