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

package/dist/diagnostics.mjs

@@ -1 +1,175 @@
-import*as e from"node:fs";import*as t from"node:path";function n(e){try{Bun.semver.order(e,e)}catch{throw Error(`Invalid semantic version: ${e}`)}let t=/^(?:v|=)?(\d+)\./.exec(e)?.[1],n=t?Number(t):NaN;if(!Number.isSafeInteger(n))throw Error(`Invalid semantic version: ${e}`);return`>=${e} <${n+1}.0.0`}function r(n){let{buildDir:r,manifest:i}=n,c=[];c.push(a(`jchat`,`JChat compatibility`,n.jchatVersion,i.compatibility?.jchat),a(`addon-sdk`,`Addon SDK compatibility`,n.addonSdkVersion,i.compatibility?.addonSdk));let l=[[`frontend-bundle`,`Frontend bundle`,i.frontend?.bundle],[`server-bundle`,`Server bundle`,i.server?.bundle],...(i.server?.migrations??[]).map(e=>[`migration:${e}`,`Migration ${e}`,e]),...(i.server?.seeds??[]).map(e=>[`seed:${e}`,`Seed ${e}`,e])];for(let[t,n,i]of l){if(!i)continue;let a=o(r,i);c.push({id:t,label:n,status:a&&e.existsSync(a)&&e.statSync(a).isFile()?`pass`:`error`,message:a&&e.existsSync(a)&&e.statSync(a).isFile()?i:`Missing or unsafe build file: ${i}`})}let u=s(r),d=t.join(r,`${i.id}-${i.version}.zip`),f=e.existsSync(d)&&e.statSync(d).isFile(),p=n.productionPackage&&f?e.statSync(d).size:u.filter(e=>e!==d).reduce((t,n)=>t+e.statSync(n).size,0),m=n.maxBytes??25*1024*1024;c.push({id:`package-size`,label:`Package size`,status:p<=m?`pass`:`error`,message:`${p} of ${m} bytes`});let h=u.filter(e=>e.endsWith(`.map`));c.push({id:`source-maps`,label:`Source maps`,status:n.productionPackage&&h.length?`warning`:`pass`,message:h.length?`${h.length} source map(s) present`:`No source maps`});let g=!!(i.server?.migrations?.length||i.server?.seeds?.length);return c.push({id:`database-signature`,label:`Database file signature`,status:g&&n.productionPackage&&!i.signature?.value?`error`:g&&!i.signature?.value?`warning`:`pass`,message:g&&!i.signature?.value?n.productionPackage?`Production database files require a publisher signature`:`Unsigned database files are allowed only in the developer sandbox`:g?`Publisher signature present`:`No database files declared`}),n.productionPackage&&c.push({id:`production-archive`,label:`Production archive`,status:f?`pass`:`error`,message:f?t.basename(d):`Production archive is missing`}),c}function i(e){return e.some(({status:e})=>e===`error`)}function a(e,t,n,r){let i=!!(r&&Bun.semver.satisfies(n,r));return{id:e,label:t,status:i?`pass`:`error`,message:r?`${n} ${i?`satisfies`:`does not satisfy`} ${r}`:`Compatibility range is missing`}}function o(e,n){if(t.isAbsolute(n)||n.includes(`\\`)||n.split(`/`).includes(`..`))return null;let r=t.resolve(e,...n.replace(/^\.\//,``).split(`/`)),i=t.relative(t.resolve(e),r);return i&&!i.startsWith(`..`)&&!t.isAbsolute(i)?r:null}function s(n){return e.existsSync(n)?e.readdirSync(n,{recursive:!0,withFileTypes:!0}).filter(e=>e.isFile()).map(e=>t.join(e.parentPath,e.name)):[]}export{n as createCompatibleMajorRange,r as diagnoseAddonPackage,i as hasAddonDiagnosticErrors};
+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);
+	} catch {
+		throw new Error(`Invalid semantic version: ${version}`);
+	}
+	const majorComponent = /^(?:v|=)?(\d+)\./.exec(version)?.[1];
+	const major = majorComponent ? Number(majorComponent) : NaN;
+	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 = [];
+	diagnostics.push(compatibilityDiagnostic("jchat", "JChat compatibility", options.jchatVersion, manifest.compatibility?.jchat), compatibilityDiagnostic("addon-sdk", "Addon SDK compatibility", options.addonSdkVersion, manifest.compatibility?.addonSdk));
+	const references = [
+		[
+			"frontend-bundle",
+			"Frontend bundle",
+			manifest.frontend?.bundle
+		],
+		[
+			"server-bundle",
+			"Server bundle",
+			manifest.server?.bundle
+		],
+		...(manifest.server?.migrations ?? []).map((file) => [
+			`migration:${file}`,
+			`Migration ${file}`,
+			file
+		]),
+		...(manifest.server?.seeds ?? []).map((file) => [
+			`seed:${file}`,
+			`Seed ${file}`,
+			file
+		])
+	];
+	for (const [id, label, reference] of references) {
+		if (!reference) continue;
+		const file = resolveBuildFile(buildDir, reference);
+		diagnostics.push({
+			id,
+			label,
+			status: file && fs$1.existsSync(file) && fs$1.statSync(file).isFile() ? "pass" : "error",
+			message: file && fs$1.existsSync(file) && fs$1.statSync(file).isFile() ? reference : `Missing or unsafe build file: ${reference}`
+		});
+	}
+	const files = listRegularFiles(buildDir);
+	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;
+	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",
+		label: "Source maps",
+		status: options.productionPackage && sourceMaps.length ? "warning" : "pass",
+		message: sourceMaps.length ? `${sourceMaps.length} source map(s) present` : "No source maps"
+	});
+	const hasDatabaseFiles = Boolean(manifest.server?.migrations?.length || manifest.server?.seeds?.length);
+	diagnostics.push({
+		id: "database-signature",
+		label: "Database file signature",
+		status: hasDatabaseFiles && options.productionPackage && !manifest.signature?.value ? "error" : hasDatabaseFiles && !manifest.signature?.value ? "warning" : "pass",
+		message: hasDatabaseFiles && !manifest.signature?.value ? options.productionPackage ? "Production database files require a publisher signature" : "Unsigned database files are allowed only in the developer sandbox" : hasDatabaseFiles ? "Publisher signature present" : "No database files declared"
+	});
+	if (options.productionPackage) diagnostics.push({
+		id: "production-archive",
+		label: "Production archive",
+		status: hasProductionArchive ? "pass" : "error",
+		message: hasProductionArchive ? path$1.basename(productionArchive) : "Production archive is missing"
+	});
+	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 {
+		id,
+		label,
+		status: compatible ? "pass" : "error",
+		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, {
+		recursive: true,
+		withFileTypes: true
+	}).filter((entry) => entry.isFile()).map((entry) => path$1.join(entry.parentPath, entry.name));
+}
+//#endregion
+export { createCompatibleMajorRange, diagnoseAddonPackage, hasAddonDiagnosticErrors };

package/dist/index.d.mts

@@ -1,14 +1,178 @@
-import { a as MOUNT_POINTS, i as ConfigSchemaField, n as AddonPermission, o as MountPoint, r as AddonPermissionDefinition, t as AddonManifest } from "./contracts.mjs";
+import { i as MountPoint, n as AddonPermissionDefinition, r as MOUNT_POINTS, t as AddonManifest } from "./contracts.mjs";
 import { ComponentType, SVGProps } from "react";
+import { InfiniteData, MutationFunction, QueryFunction, QueryFunctionContext, QueryKey, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryResult, useQueryClient } from "@tanstack/react-query";
 import { Elysia } from "elysia";
 import { Kysely } from "kysely";
-//#region ../icon/dist/index.d.mts
+//#region ../icon/dist/types.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"];
+declare const ICON_NAMES: readonly ["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"];
 type IconName = (typeof ICON_NAMES)[number];
 type IconPack = Record<IconName, IconComponent>;
 //#endregion
+//#region src/i18n.d.ts
+declare const HOST_LANGUAGES: readonly ["ar", "bg", "hr", "de", "el", "en", "es", "fr", "he", "hi", "kn", "ml", "nl", "pt", "ro", "ru", "ta", "te", "tr", "ur"];
+type HostLanguage = (typeof HOST_LANGUAGES)[number];
+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 11 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").
+ */
+declare function validateAddonLocales(dirPath: string, domainName?: string): AddonLocaleValidationResult;
+type AddonTranslationDictionary = Record<string, unknown>;
+type AddonTranslationResources = Record<string, AddonTranslationDictionary>;
+type AddonLocaleLoader = (locale: string) => Promise<AddonTranslationDictionary> | AddonTranslationDictionary;
+interface LocaleContextValue {
+  locale: string;
+  dir: "ltr" | "rtl";
+}
+declare const LocaleContext: import("react").Context<LocaleContextValue>;
+interface TranslatorOptions {
+  resources?: AddonTranslationResources;
+  defaultLocale?: string;
+  fallbackLocale?: string;
+}
+type TranslateFunction<TKeys extends string = string> = (key: TKeys | (string & {}), paramsOrLang?: Record<string, unknown> | string, maybeLang?: string) => string;
+/**
+ * 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").
+ */
+declare function createTranslator<TResources extends AddonTranslationResources = AddonTranslationResources>(resources?: TResources, defaultLocale?: string, fallbackLocale?: string): TranslateFunction<TResources extends {
+  en: infer TEn;
+} ? TEn extends Record<string, unknown> ? Extract<keyof TEn, string> : string : string>;
+/**
+ * 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>
+ *   }
+ *   ```
+ */
+declare function useLocale(): {
+  locale: string;
+  dir: "ltr" | "rtl";
+  isRtl: boolean;
+};
+/**
+ * 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").
+ */
+declare function useTranslation<TResources extends AddonTranslationResources | AddonLocaleLoader = AddonTranslationResources>(resourcesOrLoader?: TResources, fallbackLocale?: string): {
+  t: TranslateFunction<TResources extends {
+    en: infer TEn;
+  } ? TEn extends Record<string, unknown> ? Extract<keyof TEn, string> : string : string>;
+  locale: string;
+  dir: "ltr" | "rtl";
+  isRtl: boolean;
+  isReady: boolean;
+};
+//#endregion
+//#region src/query.d.ts
+interface UseAddonQueryOptions<TData = unknown, TError = Error> extends Omit<UndefinedInitialDataOptions<TData, TError, TData, QueryKey>, "queryKey" | "queryFn"> {
+  /** The API path to fetch, automatically prefixed with `/api/v1/addons/<addonId>` */
+  path?: string;
+  /** Custom query key elements appended to the automatic path cache key */
+  queryKey?: QueryKey;
+  /** Custom query function override */
+  queryFn?: QueryFunction<TData, QueryKey>;
+}
+interface UseAddonMutationOptions<TData = unknown, TVariables = unknown, TError = Error, TContext = unknown> extends Omit<UseMutationOptions<TData, TError, TVariables, TContext>, "mutationFn"> {
+  /** The target API path, or a dynamic function of mutation variables */
+  path?: string | ((variables: TVariables) => string);
+  /** HTTP method to use (defaults to 'POST') */
+  method?: "POST" | "PUT" | "DELETE";
+  /** Query keys to automatically invalidate upon successful mutation */
+  invalidateQueries?: QueryKey[];
+  /** Custom mutation function override */
+  mutationFn?: MutationFunction<TData, TVariables>;
+}
+interface UseAddonInfiniteQueryOptions<TData = unknown, TError = Error, TPageParam = unknown> extends Omit<UndefinedInitialDataInfiniteOptions<TData, TError, InfiniteData<TData, TPageParam>, QueryKey, TPageParam>, "queryKey" | "queryFn"> {
+  /** The API path to fetch, or a dynamic function that receives pageParam and returns the path */
+  path?: string | ((pageParam: TPageParam) => string);
+  /** Custom query key elements appended to the automatic cache key */
+  queryKey?: QueryKey;
+  /** Custom query function override */
+  queryFn?: (context: QueryFunctionContext<QueryKey, TPageParam>) => Promise<TData>;
+}
+/**
+ * Perform a declarative, cached GET request using the host's shared React Query instance.
+ * Automatically injects authentication headers and prefixes addon paths.
+ *
+ * @example
+ *   ;```tsx
+ *   const { data, isLoading } = useAddonQuery<{ polls: Poll[] }>({
+ *     path: "/polls",
+ *     queryKey: [siteId]
+ *   })
+ *   ```
+ */
+declare function useAddonQuery<TData = unknown, TError = Error>(options: UseAddonQueryOptions<TData, TError>): UseQueryResult<TData, TError>;
+/**
+ * Perform a paginated or infinite scrolling request using the host's shared React Query instance.
+ *
+ * @example
+ *   ;```tsx
+ *   const { data, fetchNextPage, hasNextPage } = useAddonInfiniteQuery<GifResponse, Error, number>({
+ *   path: (page) => `/trending?offset=${page * 20}`,
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage, allPages) => (lastPage.hasMore ? allPages.length : undefined)
+ *   })
+ *   ```
+ */
+declare function useAddonInfiniteQuery<TData = unknown, TError = Error, TPageParam = unknown>(options: UseAddonInfiniteQueryOptions<TData, TError, TPageParam>): UseInfiniteQueryResult<InfiniteData<TData, TPageParam>, TError>;
+/**
+ * Perform a declarative mutation using the host's shared React Query instance. Automatically
+ * executes the request and can invalidate specified query keys upon success.
+ *
+ * @example
+ *   ;```tsx
+ *   const { mutate, isPending } = useAddonMutation<Poll, CreatePollInput>({
+ *     path: "/polls",
+ *     method: "POST",
+ *     invalidateQueries: [["/polls"]],
+ *     onSuccess: () => sdk.toast("Poll created!", "success")
+ *   })
+ *   ```
+ */
+declare function useAddonMutation<TData = unknown, TVariables = unknown, TError = Error, TContext = unknown>(options: UseAddonMutationOptions<TData, TVariables, TError, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;
+//#endregion
 //#region src/index.d.ts
 type AddonJsonBody = Record<string, unknown> | unknown[] | null;
 /**
@@ -32,7 +196,7 @@ interface AddonUser {
   gender: string;
 }
 interface AddonRequestUser {
-  id?: string;
+  id: string;
   permissions?: string[];
   siteId?: string;
 }
@@ -41,6 +205,32 @@ interface AddonRequestUser {
  * 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">;
+/**
+ * Scoped caching and key-value client provided to addon server instances. Keys are automatically
+ * namespaced by the host as `addon:<addonId>:<key>`.
+ */
+interface AddonCacheClient {
+  /** Retrieve a string or JSON-parsed value by key */
+  get: <T = string>(key: string) => Promise<T | null>;
+  /** Store a value with an optional time-to-live in seconds */
+  set: (key: string, value: unknown, ttlSeconds?: number) => Promise<void>;
+  /** Delete one or more keys */
+  del: (...keys: string[]) => Promise<number>;
+  /** Atomically increment a numeric counter and return the new value */
+  incr: (key: string) => Promise<number>;
+  /** Set a timeout on a key in seconds */
+  expire: (key: string, ttlSeconds: number) => Promise<boolean>;
+  /** Get the remaining time-to-live of a key in seconds (-2 if key does not exist, -1 if no TTL) */
+  ttl: (key: string) => Promise<number>;
+}
+interface AddonServerEmitTarget {
+  /** Target a specific site (defaults to the request user's siteId) */
+  siteId?: string;
+  /** Target a specific chat room */
+  roomId?: string;
+  /** Target a specific user */
+  userId?: string;
+}
 /**
  * Context provided to an addon's server-side factory. Parameterize it with the addon's table
  * interface: `AddonServerContext<MyAddonDatabase>`.
@@ -62,13 +252,44 @@ interface AddonServerContext<TDatabase = Record<string, Record<string, unknown>>
    * @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;
+  hasPermission: (user: AddonRequestUser | null | undefined, permission: string) => 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>;
+  /** A secure, namespaced key-value cache client scoped to your addon (`addon:<addonId>:<key>`). */
+  cache: AddonCacheClient;
+  /**
+   * Broadcast a real-time event to connected clients across the site or room. Clients listen via
+   * `sdk.events.on('addon:<addonId>:<event>', callback)` or `sdk.events.on(event, callback)`.
+   */
+  emit: (event: string, payload: unknown, target?: AddonServerEmitTarget) => Promise<void>;
 }
+/**
+ * Elysia app instance provided to addon server endpoints with Jchat macro metadata (e.g.
+ * requirePermission) typed.
+ */
+type AddonApp = Elysia<"", {
+  decorator: {};
+  store: {};
+  derive: {};
+  resolve: {
+    user: AddonRequestUser;
+  };
+}, {
+  typebox: {};
+  error: {};
+}, {
+  schema: {};
+  standaloneSchema: {};
+  macro: {
+    requirePermission?: string | string[];
+  };
+  macroFn: {};
+  parser: {};
+  response: {};
+}>;
 /**
  * The entry point for your addon's server bundle. You should default-export a function matching
  * this signature.
@@ -83,7 +304,7 @@ interface AddonServerContext<TDatabase = Record<string, Record<string, unknown>>
  *   export default factory
  *   ```
  */
-type AddonServerFactory<TDatabase = Record<string, Record<string, unknown>>> = (ctx: AddonServerContext<TDatabase>, app: Elysia) => Elysia;
+type AddonServerFactory<TDatabase = Record<string, Record<string, unknown>>> = (ctx: AddonServerContext<TDatabase>, app: AddonApp) => 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') */
@@ -100,6 +321,10 @@ interface AddonProps {
   roomId?: string;
   /** The ID of the active Jchat site */
   siteId?: string;
+  /** The active user locale (e.g. 'en', 'ta', 'ar') */
+  locale?: string;
+  /** Text direction for the current locale */
+  dir?: "ltr" | "rtl";
 }
 interface AddonApi {
   get: <TResponse = unknown>(path: string) => Promise<TResponse>;
@@ -107,7 +332,27 @@ interface AddonApi {
   put: <TResponse = unknown>(path: string, body?: AddonJsonBody) => Promise<TResponse>;
   delete: <TResponse = unknown>(path: string) => Promise<TResponse>;
 }
+/** First-class addon settings management interface provided by the host. */
+interface AddonSettingsApi {
+  /** Fetch the current site's saved configuration for this addon */
+  get: <T = Record<string, unknown>>() => Promise<T | null>;
+  /** Save updated configuration for this addon for the current site */
+  save: <T = Record<string, unknown>>(settings: T) => Promise<void>;
+}
 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.
@@ -115,9 +360,15 @@ type AddonEventListener = (data: unknown) => void;
 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.
+   * automatically include the current user's sessionId and site validation headers. Relative paths
+   * are automatically prefixed with `/api/v1/addons/<addonId>`.
    */
   api: AddonApi;
+  /**
+   * First-class settings API to load and save addon configuration without boilerplate path
+   * construction.
+   */
+  settings: AddonSettingsApi;
   /**
    * Display a temporary notification toast in the host UI.
    *
@@ -172,6 +423,15 @@ interface AddonSDK {
     /** 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[];
+  /** The active user locale (e.g. 'en', 'ta', 'ar') */
+  locale: string;
+  /** Text direction for the active locale ('ltr' or 'rtl') */
+  dir: "ltr" | "rtl";
 }
 /**
  * Seed data for your addon's tables, provided inside the addon's isolated schema.
@@ -236,5 +496,19 @@ declare function useAddonSDK(): AddonSDK;
 declare function useIcons(): {
   Icons: IconPack;
 };
+/**
+ * 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;
 //#endregion
-export { AddonApi, AddonDatabase, AddonEventListener, AddonJsonBody, type AddonManifest, type AddonPermission, type AddonPermissionDefinition, AddonProps, AddonRequestUser, AddonSDK, AddonSeedDocument, AddonServerContext, AddonServerFactory, AddonUser, type ConfigSchemaField, MOUNT_POINTS, type MountPoint, defineAddonManifest, defineAddonServer, useAddonSDK, useIcons };
+export { AddonApi, AddonApp, AddonCacheClient, AddonDatabase, AddonEventListener, AddonFont, AddonJsonBody, AddonLocaleLoader, AddonLocaleValidationResult, type AddonManifest, type AddonPermissionDefinition, AddonProps, AddonRequestUser, AddonSDK, AddonSeedDocument, AddonServerContext, AddonServerEmitTarget, AddonServerFactory, AddonSettingsApi, AddonTranslationDictionary, AddonTranslationResources, AddonUser, HOST_LANGUAGES, HostLanguage, ICON_NAMES, type IconComponent, type IconName, type IconPack, type InfiniteData, LocaleContext, LocaleContextValue, MOUNT_POINTS, type MountPoint, type QueryKey, TranslateFunction, TranslatorOptions, UseAddonInfiniteQueryOptions, UseAddonMutationOptions, UseAddonQueryOptions, createTranslator, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonInfiniteQuery, useAddonMutation, useAddonQuery, useAddonSDK, useIcons, useLocale, useQueryClient, useTranslation, validateAddonLocales };