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

package/dist/index.d.mts

@@ -1,14 +1,178 @@
-import { a as MountPoint, i as MOUNT_POINTS, n as AddonPermission, 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 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,6 +332,13 @@ 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 {
@@ -128,9 +360,15 @@ interface AddonFont {
 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.
    *
@@ -190,6 +428,10 @@ interface AddonSDK {
    * 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.
@@ -269,4 +511,4 @@ declare function useIcons(): {
  */
 declare function getAddonSdkVersion(): string;
 //#endregion
-export { AddonApi, AddonDatabase, AddonEventListener, AddonFont, AddonJsonBody, type AddonManifest, type AddonPermission, type AddonPermissionDefinition, AddonProps, AddonRequestUser, AddonSDK, AddonSeedDocument, AddonServerContext, AddonServerFactory, AddonUser, MOUNT_POINTS, type MountPoint, defineAddonManifest, defineAddonServer, getAddonSdkVersion, 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 };