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

package/dist/index.d.mts

@@ -1,15 +1,333 @@
-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 { S as ResilientFetchOptions, _ as AddonUser, a as AddonChatMessage, b as MOUNT_POINTS, c as AddonDistribution, d as AddonRequestUser, f as AddonResilientFetch, g as AddonRuntimeLogSource, h as AddonRuntimeLogLevel, i as AddonAttachment, l as AddonManifest, m as AddonRuntimeLogFilter, n as ActiveAddonFrontend, o as AddonCommandDefinition, p as AddonRuntimeLog, r as AddonArchiveFile, s as AddonCommandParameter, t as ActiveAddon, u as AddonPermissionDefinition, v as HOST_LOCALES, x as MountPoint, y as HostLocale } from "./contracts2.mjs";
+import { a as canonicalManifest, c as sortValue, i as assertSafeRelativePath, l as validateAddonManifest, n as COMPATIBILITY_RANGE_PATTERN, o as createCanonicalAddonDigest, r as MAX_ADDON_ARCHIVE_BYTES, s as isCompatibilityRange, t as ADDON_ID_PATTERN } from "./signing2.mjs";
+import { AbilityBuilder, MongoAbility, createMongoAbility, subject } from "@casl/ability";
+import { InfiniteData, MutationFunction, QueryFunction, QueryFunctionContext, QueryKey, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryResult, useQueryClient } from "@tanstack/react-query";
+import { IconComponent, IconName, IconPack } from "@jchat/ui";
+import { Elysia, t } from "elysia";
+import { ColumnType, Generated, Insertable, JSONColumnType, Kysely, Selectable, Updateable } from "kysely";
+//#region src/permissions.d.ts
+/**
+ * Standard forbidden exception thrown when an actor lacks required permissions or fails ownership
+ * checks.
+ */
+export declare class ForbiddenError extends Error {
+  readonly status = 403;
+  readonly code = "FORBIDDEN";
+  /**
+   * Initializes a new ForbiddenError instance.
+   *
+   * @param message - User-friendly error message detailing the authorization failure.
+   */
+  constructor(message?: string);
+}
+/**
+ * Authorization scope granted when accessing or mutating a resource:
+ *
+ * - `"own"`: Actor is the author/owner possessing the `.own` permission (or platform owner).
+ * - `"any"`: Actor is an administrator/moderator overriding ownership via the `.any` permission.
+ */
+export type ResourceOwnershipScope = "own" | "any";
+/** Configuration payload supplied to {@link authorizeResourceOwnership}. */
+export interface ResourceOwnershipInput {
+  /** Unique identifier of the authenticated user performing the action. */
+  actorId: string;
+  /** Array of effective permission strings held by the actor in the current tenancy context. */
+  actorPermissions: string[];
+  /** Unique identifier of the user who owns or created the target resource. */
+  ownerId: string;
+  /**
+   * Permission string required if the actor is the resource owner (e.g.
+   * `'addon.pollwise.close.own'`).
+   */
+  ownPermission: string;
+  /**
+   * Permission string required if the actor is mutating another user's resource (e.g.
+   * `'addon.pollwise.close.any'`).
+   */
+  anyPermission: string;
+  /**
+   * Human-readable entity noun used in error messages (e.g. `"poll"`, `"story"`, `"comment"`).
+   * Defaults to `"resource"`.
+   */
+  resourceLabel?: string;
+  /**
+   * Optional factory function creating a custom error instance on authorization denial. Defaults to
+   * {@link ForbiddenError}.
+   */
+  errorFactory?: (message: string) => Error;
+  /**
+   * Whether the actor possesses site owner / super admin status, granting unconditional bypass.
+   * Defaults to `false`.
+   */
+  isOwner?: boolean;
+}
+/**
+ * Checks whether an actor holds a specific permission with wildcard support.
+ *
+ * Evaluation rules:
+ *
+ * 1. Exact match (`'addon.pollwise.close.own'` matches `'addon.pollwise.close.own'`).
+ * 2. Global wildcard (`'*'` grants all actions).
+ * 3. Segment wildcards (`'addon.pollwise.*'` grants `'addon.pollwise.close.own'`).
+ *
+ * @param userPermissions - Array of permissions possessed by the user.
+ * @param required - Permission string required for the requested action.
+ * @returns `true` if the user is granted the required permission, `false` otherwise.
+ */
+export declare function hasPermission(userPermissions: string[], required: string): boolean;
+/**
+ * Evaluates Attribute-Based Access Control (ABAC) ownership rules to prevent Broken Object-Level
+ * Authorization (BOLA / IDOR) vulnerabilities.
+ *
+ * Resolution flow:
+ *
+ * 1. **Site Owner Bypass**: If `isOwner === true` or holding `'*'`, access is granted unconditionally.
+ * 2. **Author Ownership**: If `actorId === ownerId` and actor holds `ownPermission`, grants `"own"`.
+ * 3. **Moderator Override**: If actor holds `anyPermission`, grants `"any"`.
+ * 4. **Denial**: Throws an error generated by `errorFactory` (defaults to {@link ForbiddenError}).
+ *
+ * @param input - Ownership parameters, actor credentials, and required permissions.
+ * @returns The resolved {@link ResourceOwnershipScope} (`"own"` or `"any"`).
+ * @throws {ForbiddenError} When the actor lacks required ownership or moderator privileges.
+ */
+export declare function authorizeResourceOwnership({ actorId, actorPermissions, ownerId, ownPermission, anyPermission, resourceLabel, errorFactory, isOwner: actorIsOwner }: ResourceOwnershipInput): ResourceOwnershipScope;
+/** CASL MongoAbility contract for Addon entities and attribute evaluation. */
+export type AddonAbility = MongoAbility<[string, string | Record<string, unknown>]>;
+/**
+ * Creates a CASL Ability instance for an addon actor with automated permission convention mapping
+ * and optional custom rule extensions.
+ *
+ * Convention mapping:
+ *
+ * - Global `'*'` or `isOwner: true` $\rightarrow$ `can('manage', 'all')`
+ * - `*.any` (e.g. `'addon.pollwise.close.any'`) $\rightarrow$ `can('close', 'all')`
+ * - `*.own` (e.g. `'addon.pollwise.close.own'`) $\rightarrow$ `can('close', 'all', { userId: actor.id
+ *   })`
+ *
+ * @param actor - Authenticated request user context.
+ * @param defineRules - Optional callback to register custom CASL ability rules.
+ * @returns A frozen CASL {@link AddonAbility} instance.
+ */
+export declare function createAddonAbility(actor: AddonRequestUser | null | undefined, defineRules?: (builder: AbilityBuilder<AddonAbility>) => void): AddonAbility;
+//#endregion
+//#region src/i18n.d.ts
+export type HostLanguage = HostLocale;
+export type AddonTranslationDictionary = Record<string, unknown>;
+export type AddonTranslationResources = Record<string, AddonTranslationDictionary>;
+export type AddonLocaleLoader = (locale: string) => Promise<AddonTranslationDictionary> | AddonTranslationDictionary;
+export interface LocaleContextValue {
+  locale: string;
+  dir: "ltr" | "rtl";
+}
+export declare const LocaleContext: import("react").Context<LocaleContextValue>;
+export interface TranslatorOptions {
+  resources?: AddonTranslationResources;
+  defaultLocale?: string;
+  fallbackLocale?: string;
+}
+export 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").
+ */
+export 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>
+ *   }
+ *   ```
+ */
+export 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").
+ */
+export 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
+export 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>;
+}
+export 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>;
+}
+export 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]
+ *   })
+ *   ```
+ */
+export 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)
+ *   })
+ *   ```
+ */
+export 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")
+ *   })
+ *   ```
+ */
+export declare function useAddonMutation<TData = unknown, TVariables = unknown, TError = Error, TContext = unknown>(options: UseAddonMutationOptions<TData, TVariables, TError, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;
+export interface UseAddonSettingsResult<TConfig> {
+  settings: TConfig | null;
+  isLoading: boolean;
+  isSaving: boolean;
+  error: Error | null;
+  saveSettings: (settings: TConfig) => void;
+  saveSettingsAsync: (settings: TConfig) => Promise<void>;
+  refetch: () => Promise<unknown>;
+}
+/**
+ * Ergonomic hook for loading and updating site configuration for an addon. Handles fetching,
+ * caching, pending states, and automatic query cache invalidation.
+ */
+export declare function useAddonSettings<TConfig = Record<string, unknown>>(siteId?: string): UseAddonSettingsResult<TConfig>;
+//#endregion
+//#region src/testing.d.ts
+/** Configuration options supplied to {@link createMockAddonServerContext}. */
+export interface MockAddonServerContextOptions {
+  /** Simulated tenant site identifier (defaults to `'site_test_123'`). */
+  siteId?: string;
+  /** Simulated addon configuration settings returned by `context.getConfig()`. */
+  config?: Record<string, unknown>;
+  /** Simulated user profile returned by `context.getUser()` and `context.getUsers()`. */
+  user?: Partial<AddonUser>;
+  /**
+   * Simulated commercial license entitlement status returned by `context.verifyEntitlement()`.
+   * Defaults to `true`.
+   */
+  isEntitled?: boolean;
+}
+/** Inspection fixtures and mock context returned by {@link createMockAddonServerContext}. */
+export interface MockAddonContextResult {
+  /** The fully functioning mock {@link AddonServerContext} instance. */
+  context: AddonServerContext;
+  /** Array capturing all events emitted via `context.emit()`, enabling assertions in unit tests. */
+  emittedEvents: Array<{
+    event: string;
+    payload: unknown;
+    target?: AddonServerEmitTarget;
+  }>;
+  /** Array capturing all pipeline hooks registered via `context.pipeline.register()`. */
+  registeredHooks: AddonPipelineHooks[];
+  /** In-memory Map of key-value cache entries written via `context.cache`. */
+  cacheEntries: Map<string, unknown>;
+  /** In-memory Map of Redis Set collections written via `context.cache.setAdd()` / `setRemove()`. */
+  cacheSets: Map<string, Set<string>>;
+}
+/**
+ * Creates an in-memory, zero-dependency {@link AddonServerContext} mock for testing addon server
+ * routes, lifecycle handlers, and pipeline hooks offline in CI without requiring live database
+ * connections or Redis.
+ *
+ * Provides complete mock implementations of:
+ *
+ * - **Key-Value & Set Cache**: Supports `get`, `set` (with TTL simulation), `del`, `incr`, `expire`,
+ *   `ttl`, `setAdd`, `setRemove`, and `setMembers` with automatic tenant/addon namespacing.
+ * - **Sliding-Window Rate Limiting**: In-memory timestamp-bucket rate limiting via `consume`.
+ * - **Event Capturing**: Records emitted events in {@link MockAddonContextResult.emittedEvents} with
+ *   canonical `addon:<addonId>:<event>` prefixing.
+ * - **Pipeline Hook Registration**: Inspects registered hook stages and handlers.
+ * - **Fine-Grained ABAC & Ownership**: Enforces CASL `can` attribute queries and BOLA protection via
+ *   `authorizeOwnership`.
+ * - **License Entitlement**: Deterministic commercial entitlement verification.
+ *
+ * @param addonId - Unique identifier of the addon under test.
+ * @param options - Optional mock configuration parameters.
+ * @returns A {@link MockAddonContextResult} containing the mock context and inspection fixtures.
+ */
+export declare function createMockAddonServerContext(addonId: string, options?: MockAddonServerContextOptions): MockAddonContextResult;
 //#endregion
 //#region src/index.d.ts
-type AddonJsonBody = Record<string, unknown> | unknown[] | null;
+export type AddonJsonBody = Record<string, unknown> | unknown[] | null;
 /**
  * @jchat/addon-sdk
  *
@@ -17,41 +335,158 @@ type AddonJsonBody = Record<string, unknown> | unknown[] | null;
  *   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;
+/** Standard error thrown or handled when an addon message pipeline hook aborts sending. */
+export declare class AddonPipelineAbortError extends Error {
+  readonly code: string;
+  readonly reason?: string;
+  constructor(error: {
+    code: string;
+    reason?: 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">;
+export 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>`.
+ */
+export 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>;
+  /** Add a member to a set stored at key */
+  setAdd: (key: string, member: string) => Promise<number>;
+  /** Remove a member from a set stored at key */
+  setRemove: (key: string, member: string) => Promise<number>;
+  /** Retrieve all members of a set stored at key */
+  setMembers: (key: string) => Promise<string[]>;
+}
+export interface AddonRateLimitOptions {
+  /** Maximum number of allowed requests within the sliding window */
+  limit: number;
+  /** Time window duration in milliseconds */
+  windowMs: number;
+}
+/**
+ * High-performance sliding-window rate limiter scoped to this addon. Keys are automatically
+ * prefixed by the host as `addon:<addonId>:ratelimit:<key>`.
+ */
+export interface AddonRateLimiter {
+  /**
+   * Consume a rate limit token using an atomic sliding window.
+   *
+   * @param key - Identifier within the addon (e.g. `user:${userId}:audio`, `command:${cmd}`)
+   * @param options - Limit and window duration in milliseconds
+   * @returns `true` if within the rate limit, `false` if limit exceeded
+   */
+  consume: (key: string, options: AddonRateLimitOptions) => Promise<boolean>;
+}
+export 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;
+}
+export interface AddonMessageMutableData {
+  /** Message content (can be Slate JSON structure or string) */
+  content: unknown;
+  /** Optional message attachments */
+  attachments?: AddonAttachment[] | unknown[] | null;
+  /**
+   * Namespaced metadata bucket for this addon. Keyed as `metadata["addon:<addonId>"]`. Storing data
+   * here automatically attaches it to the message broadcast and database record.
+   */
+  metadata: Record<string, unknown>;
+  /** Target specific user recipient for whispers/directed messages */
+  receiverId?: string | null;
+}
+export interface AddonMessageContext {
+  /** The site ID where the message is being sent */
+  siteId: string;
+  /** The chat room ID */
+  roomId: string;
+  /** The authenticated user sending the message (read-only) */
+  user: AddonRequestUser;
+  /** Mutable message payload */
+  message: AddonMessageMutableData;
+  /** Convenience method to set metadata under this addon's namespace */
+  setMetadata: (key: string, value: unknown) => void;
+  /**
+   * Abort the message sending pipeline with a user-facing error code and reason. Only active during
+   * `beforeValidate` and `transformContent`.
+   */
+  abort: (error: {
+    code: string;
+    reason?: string;
+  }) => never;
+  /**
+   * AbortSignal triggered if this interceptor times out or the message pipeline is cancelled. Can
+   * be passed to `fetch(url, { signal: context.signal })` or async operations.
+   */
+  signal?: AbortSignal;
+}
+export interface AddonMessageAfterSaveContext {
+  siteId: string;
+  roomId: string;
+  user: AddonRequestUser;
+  message: {
+    id: string;
+    content: unknown;
+    attachments?: AddonAttachment[] | unknown[] | null;
+    metadata?: Record<string, unknown> | null;
+    type: string;
+    createdAt: Date | string;
+  };
+  /** AbortSignal triggered if the observer times out or is cancelled. */
+  signal?: AbortSignal;
+}
+export interface AddonPipelineHooks {
+  /** Optional priority ordering. Lower numbers execute first (e.g. 10 runs before 100). Default is 100. */
+  priority?: number;
+  /**
+   * Run before validation to inspect or guard actions (rate-limits, permission gates). Throw or
+   * call `context.abort()` to reject the message.
+   */
+  beforeValidate?: (context: AddonMessageContext) => Promise<void> | void;
+  /** Run before persistence to mutate text, parse slash commands, or enrich metadata. */
+  transformContent?: (context: AddonMessageContext) => Promise<void> | void;
+  /** Run asynchronously after database save (fire-and-forget observers). */
+  afterSave?: (context: AddonMessageAfterSaveContext) => Promise<void> | void;
+}
 /**
  * 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>>> {
+export interface AddonServerContext<TDatabase = Record<string, Record<string, unknown>>> {
+  /**
+   * Elysia / TypeBox schema validator for defining route validation schemas (`body`, `query`,
+   * `params`, `headers`). Provided directly by the host runtime so your addon server bundle does
+   * not need to bundle Elysia.
+   */
+  t: typeof t;
   /**
    * 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>>;
+  getConfig: <T = Record<string, unknown>>(siteId: string) => Promise<T>;
   /** Fetch a specific user's public profile */
   getUser: (userId: string) => Promise<AddonUser | null>;
+  /** Find a user by their unique username */
+  findUserByName: (name: 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>>;
   /**
@@ -61,13 +496,99 @@ 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>;
+  /**
+   * Register lifecycle interception hooks for chat messages. Hooks run in the core chat execution
+   * path with strict 50ms timeout guards and fail-open fault tolerance.
+   */
+  pipeline?: {
+    register: (hooks: AddonPipelineHooks) => void;
+  };
+  /** An atomic sliding-window rate limiter scoped to your addon (`addon:<addonId>:ratelimit:<key>`). */
+  rateLimiter?: AddonRateLimiter;
+  /**
+   * Cryptographically verify that this addon instance holds a valid host license entitlement.
+   * Commercial paid addons should invoke this or call `verifyAddonEntitlement(addonId, context)`.
+   *
+   * @param expectedAddonId - The canonical addon ID defined by the publisher
+   * @returns True if valid, or false if entitlement is missing or invalid
+   */
+  verifyEntitlement?: (expectedAddonId?: string) => boolean;
+  /**
+   * Enforces resource ownership rules ('own' vs 'any' permissions). Prevents Broken Object-Level
+   * Authorization (BOLA/IDOR).
+   *
+   * @param params - The actor, owner ID, and permission requirements
+   * @returns "own" if the actor owns the resource, or "any" if granted via moderator/admin
+   *   privileges
+   * @throws ForbiddenError if neither condition is satisfied
+   */
+  authorizeOwnership: (params: {
+    actor: AddonRequestUser;
+    ownerId: string;
+    ownPermission: string;
+    anyPermission: string;
+    resourceLabel?: string;
+  }) => ResourceOwnershipScope;
+  /**
+   * Evaluates fine-grained Attribute-Based Access Control (ABAC) rules for custom addon entities.
+   *
+   * @param actor - The authenticated request user
+   * @param action - Action to perform (e.g. 'read', 'delete', 'close')
+   * @param subject - Entity name (e.g. 'poll', 'story', 'track')
+   * @param attributes - Resource attributes (e.g. { userId: poll.userId, status: 'open' })
+   * @returns True if allowed, false otherwise
+   */
+  can: (actor: AddonRequestUser | null | undefined, action: string, subject: string, attributes?: Record<string, unknown>) => boolean;
+  /**
+   * A resilient HTTP fetch client with built-in exponential backoff, jitter, and timeouts.
+   * Automatically retries on transient network disconnects and HTTP 5xx responses without requiring
+   * external dependencies in addons.
+   */
+  fetch: AddonResilientFetch;
 }
+/**
+ * Elysia app instance provided to addon server endpoints with Jchat macro metadata (e.g.
+ * requirePermission, requireOwnership) typed.
+ */
+export type AddonApp = Elysia<"", {
+  decorator: {};
+  store: {};
+  derive: {};
+  resolve: {
+    user: AddonRequestUser;
+  };
+}, {
+  typebox: {};
+  error: {};
+}, {
+  schema: {};
+  standaloneSchema: {};
+  macro: {
+    requirePermission?: string | string[];
+    requireOwnership?: {
+      resolveOwnerId: (context: unknown) => string | Promise<string | null | undefined>;
+      ownPermission: string;
+      anyPermission: string;
+      resourceLabel?: string;
+    };
+  };
+  macroFn: {};
+  parser: {};
+  response: {};
+}>;
 /**
  * The entry point for your addon's server bundle. You should default-export a function matching
  * this signature.
@@ -82,9 +603,9 @@ 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;
+export 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 {
+export 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) */
@@ -99,16 +620,33 @@ 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";
+  /** The message object when rendered inside 'chat-message-card' or 'chat-message-flair' */
+  message?: AddonChatMessage | unknown;
+  /** The addon's specific payload extracted from message.metadata */
+  addonData?: unknown;
+  /** List of active addon IDs enabled on the current site */
+  activeAddonIds?: string[];
 }
-interface AddonApi {
+export 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;
+/** First-class addon settings management interface provided by the host. */
+export 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>;
+}
+export type AddonEventListener = (data: unknown) => void;
 /** A font option provided by the JChat host. */
-interface AddonFont {
+export interface AddonFont {
   /** Display label shown to users (e.g. 'Modern', 'Elegant') */
   label: string;
   /** Font identifier stored in the database (e.g. 'poppins', 'lato') */
@@ -120,16 +658,75 @@ interface AddonFont {
   /** Relative size multiplier — apply this to base font sizes to match the host's rendering */
   scale: number;
 }
+export interface AddonEditorInsertImagePayload {
+  src: string;
+  altText: string;
+  emoji?: {
+    col: number;
+    row: number;
+    size: number;
+  };
+  className?: string;
+}
+export interface AddonEditorInsertEmojiPayload {
+  col: number;
+  row: number;
+  unicode: string;
+  shortcode?: string;
+}
+export interface AddonEditorCommandMap {
+  INSERT_YOUTUBE_COMMAND: string;
+  INSERT_TEXT: string;
+  INSERT_TEXT_COMMAND: string;
+  INSERT_MENTION_COMMAND: string;
+  INSERT_IMAGE_COMMAND: AddonEditorInsertImagePayload;
+  INSERT_EMOJI_COMMAND: AddonEditorInsertEmojiPayload;
+  CLEAR_EDITOR: void;
+  CLEAR_EDITOR_COMMAND: void;
+}
+export type AddonEditorCommand = keyof AddonEditorCommandMap;
+export interface AddonEditorApi {
+  /**
+   * Trigger a specialized editor command defined by the host.
+   *
+   * @example
+   *   sdk.editor.dispatchCommand("INSERT_YOUTUBE_COMMAND", "dQw4w9WgXcQ")
+   */
+  dispatchCommand: <C extends AddonEditorCommand>(command: C, ...args: AddonEditorCommandMap[C] extends void ? [payload?: undefined] : [payload: AddonEditorCommandMap[C]]) => 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: AddonAttachment | {
+    url: string;
+    name: string;
+    type: string;
+  }) => void;
+  /** Force the browser focus back to the editor input */
+  focus: () => void;
+}
 /**
  * The bridge between your addon and the Jchat host application. Use the `useAddonSDK()` hook to
  * access this interface in your components.
  */
-interface AddonSDK {
+export 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.
    *
@@ -147,32 +744,7 @@ interface AddonSDK {
    * 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;
-  };
+  editor: AddonEditorApi;
   /** Event Bus for reacting to real-time application state changes. */
   events: {
     /**
@@ -189,6 +761,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.
@@ -197,7 +773,7 @@ interface AddonSDK {
  * provide default values, references, or supporting data. The host guarantees that these documents
  * do not conflict with core schemas or other addons.
  */
-interface AddonSeedDocument {
+export 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. */
@@ -208,9 +784,9 @@ interface AddonSeedDocument {
   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;
+export 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>;
+export 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.
@@ -232,27 +808,7 @@ declare function defineAddonServer<TDatabase = Record<string, Record<string, unk
  *   }
  *   ```
  */
-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;
-};
+export declare function useAddonSDK(): AddonSDK;
 /**
  * Get the version of the addon SDK. This is useful for checking compatibility with the host
  * application.
@@ -266,6 +822,28 @@ declare function useIcons(): {
  *
  * @returns
  */
-declare function getAddonSdkVersion(): string;
+export declare function getAddonSdkVersion(): string;
+/**
+ * Verifies purchase entitlement and identity integrity for commercial addons. Throws an error if
+ * the addon fails entitlement verification or if its manifest ID has been tampered with to
+ * impersonate another addon.
+ *
+ * @example
+ *   ;```ts
+ *   export default ({ verifyEntitlement, db, t }: AddonServerContext, app: AddonApp) => {
+ *     verifyAddonEntitlement("tubescanpro", verifyEntitlement)
+ *     return app.get("/trending", async () => { ... })
+ *   }
+ *   ```
+ *
+ * @param addonId - The canonical addon ID defined by the publisher (e.g. 'tubescanpro')
+ * @param target - Either the `verifyEntitlement` function from context or the `AddonServerContext`
+ *   object itself
+ * @returns True if valid
+ * @throws Error if entitlement verification fails
+ */
+export declare function verifyAddonEntitlement(addonId: string, target?: ((expectedAddonId?: string) => boolean) | {
+  verifyEntitlement?: (expectedAddonId?: string) => boolean;
+}): boolean;
 //#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 { ADDON_ID_PATTERN, AbilityBuilder, type ActiveAddon, type ActiveAddonFrontend, type AddonArchiveFile, type AddonAttachment, type AddonChatMessage, type AddonCommandDefinition, type AddonCommandParameter, type AddonDistribution, type AddonManifest, type AddonPermissionDefinition, type AddonRequestUser, type AddonResilientFetch, type AddonRuntimeLog, type AddonRuntimeLogFilter, type AddonRuntimeLogLevel, type AddonRuntimeLogSource, type AddonUser, COMPATIBILITY_RANGE_PATTERN, type ColumnType, type Generated, HOST_LOCALES, type IconComponent, type IconName, type IconPack, type InfiniteData, type Insertable, type JSONColumnType, MAX_ADDON_ARCHIVE_BYTES, MOUNT_POINTS, type MongoAbility, type MountPoint, type QueryKey, type ResilientFetchOptions, type Selectable, type Updateable, assertSafeRelativePath, canonicalManifest, createCanonicalAddonDigest, createMongoAbility, isCompatibilityRange, sortValue, subject, useQueryClient, validateAddonManifest };