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

package/dist/index.d.mts

@@ -1,257 +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";
 };
+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, 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 };

package/dist/index.mjs

@@ -1,33 +1,98 @@
-//#region src/contracts.ts
-/** Valid locations where an addon can be rendered within the Jchat layout. */
-const MOUNT_POINTS = {
-	/** Top of the main chat column */
-	CHAT_HEADER: "chat-header",
-	/** Below the main chat header, above messages */
-	CHAT_TOOLBAR: "chat-toolbar",
-	/** The persistent right-side sidebar */
-	CHAT_SIDEBAR: "chat-sidebar",
-	/** Top of the left sidebar (room list) */
-	SIDEBAR_TOP: "sidebar-top",
-	/** Bottom of the left sidebar */
-	SIDEBAR_BOTTOM: "sidebar-bottom",
-	/** Action list shown when clicking a user's avatar */
-	USER_POPOVER_ACTIONS: "user-popover-actions",
-	/** Menu shown when right-clicking a message */
-	MESSAGE_CONTEXT_MENU: "message-context-menu",
-	/** Floating overlay rendered on top of the message stream */
-	MESSAGE_FEED_OVERLAY: "message-feed-overlay",
-	/** Main admin dashboard area */
-	ADMIN_PANEL: "admin-panel",
-	/** User or site settings dashboard area */
-	SETTINGS_PANEL: "settings-panel",
-	/** The 'plus' (+) menu in the message composer */
-	CHAT_PLUS_MENU: "chat-plus-menu",
-	/** Custom tab in the emoji/gif selection panel */
-	EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab",
-	/** Full-screen or modal dialog specifically for TubeScan */
-	TUBESCAN_DIALOG: "tubescan-dialog"
-};
+import { MOUNT_POINTS } from "./contracts.mjs";
+import { a as useTranslation, i as useLocale, n as LocaleContext, r as createTranslator, t as HOST_LANGUAGES } from "./i18n.mjs";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+//#region package.json
+var version = "1.0.0-alpha.21";
+//#endregion
+//#region src/query.ts
+/**
+* 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]
+*   })
+*   ```
+*/
+function useAddonQuery(options) {
+	const sdk = useAddonSDK();
+	const { path, queryKey = [], queryFn, ...queryOptions } = options;
+	const effectiveKey = path !== void 0 ? [path, ...queryKey] : queryKey;
+	const effectiveFn = queryFn ?? (() => {
+		if (!path) throw new Error("useAddonQuery requires either a `path` or a custom `queryFn`");
+		return sdk.api.get(path);
+	});
+	return useQuery({
+		...queryOptions,
+		queryKey: effectiveKey,
+		queryFn: effectiveFn
+	});
+}
+/**
+* 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)
+*   })
+*   ```
+*/
+function useAddonInfiniteQuery(options) {
+	const sdk = useAddonSDK();
+	const { path, queryKey = [], queryFn, ...infiniteOptions } = options;
+	const effectiveKey = [typeof path === "string" ? path : "infinite", ...queryKey];
+	const effectiveFn = queryFn ?? (async (context) => {
+		const pageParam = context.pageParam;
+		const resolvedPath = typeof path === "function" ? path(pageParam) : path;
+		if (!resolvedPath) throw new Error("useAddonInfiniteQuery requires either a `path` or a custom `queryFn`");
+		return sdk.api.get(resolvedPath);
+	});
+	return useInfiniteQuery({
+		...infiniteOptions,
+		queryKey: effectiveKey,
+		queryFn: effectiveFn
+	});
+}
+/**
+* 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")
+*   })
+*   ```
+*/
+function useAddonMutation(options) {
+	const sdk = useAddonSDK();
+	const queryClient = useQueryClient();
+	const { path, method = "POST", invalidateQueries = [], mutationFn, onSuccess, ...mutationOptions } = options;
+	const effectiveFn = mutationFn ?? (async (variables) => {
+		const resolvedPath = typeof path === "function" ? path(variables) : path ?? "";
+		if (!resolvedPath) throw new Error("useAddonMutation requires a valid 'path' or 'mutationFn'.");
+		if (method === "PUT") return sdk.api.put(resolvedPath, variables);
+		if (method === "DELETE") return sdk.api.delete(resolvedPath);
+		return sdk.api.post(resolvedPath, variables);
+	});
+	return useMutation({
+		...mutationOptions,
+		mutationFn: effectiveFn,
+		onSuccess: async (...args) => {
+			if (invalidateQueries.length > 0) await Promise.all(invalidateQueries.map((key) => queryClient.invalidateQueries({ queryKey: key })));
+			if (onSuccess) await onSuccess(...args);
+		}
+	});
+}
 //#endregion
 //#region src/index.ts
 /** Define a manifest with full validation-friendly typing while preserving literal values. */
@@ -60,27 +125,50 @@ function defineAddonServer(factory) {
 *   ```
 */
 function useAddonSDK() {
+	const hostUseAddonSDK = typeof window !== "undefined" ? window.__JCHAT_EXTERNALS__?.JchatAddonSDK?.useAddonSDK : void 0;
+	if (hostUseAddonSDK && hostUseAddonSDK !== useAddonSDK) return hostUseAddonSDK();
 	throw new Error("AddonSDK must be used within the Jchat host environment.");
 }
 /**
-* 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.
+* Get the version of the addon SDK. This is useful for checking compatibility with the host
+* application.
 *
 * @example
 *   ;```tsx
-*   import { useIcons } from "@jchat/addon-sdk"
+*   import { getAddonSdkVersion } from "@jchat/addon-sdk"
 *
-*   export default function MyAddon() {
-*     const { Icons } = useIcons()
-*     return <Icons.Send className="size-5" />
-*   }
+*   console.log(getAddonSdkVersion())
 *   ```
+*
+* @returns
+*/
+function getAddonSdkVersion() {
+	return version;
+}
+/**
+* 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 defineAddonServer((context, app) => {
+*   verifyAddonEntitlement("tubescanpro", context)
+*   return app.get("/trending", async () => { ... })
+*   })
+*   ```
+*
+* @param addonId - The canonical addon ID defined by the publisher (e.g. 'tubescanpro')
+* @param context - The AddonServerContext passed to the addon's server factory
+* @returns True if valid
+* @throws Error if entitlement verification fails
 */
-function useIcons() {
-	throw new Error("useIcons must be used within the Jchat host environment.");
+function verifyAddonEntitlement(addonId, context) {
+	if (context?.verifyEntitlement) {
+		if (!context.verifyEntitlement(addonId)) throw new Error(`addon_entitlement_verification_failed:${addonId}`);
+		return true;
+	}
+	return true;
 }
 //#endregion
-export { MOUNT_POINTS, defineAddonManifest, defineAddonServer, useAddonSDK, useIcons };
+export { HOST_LANGUAGES, LocaleContext, MOUNT_POINTS, createTranslator, defineAddonManifest, defineAddonServer, getAddonSdkVersion, useAddonInfiniteQuery, useAddonMutation, useAddonQuery, useAddonSDK, useLocale, useQueryClient, useTranslation, verifyAddonEntitlement };