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

package/dist/src.mjs

@@ -0,0 +1,493 @@
+import "./i18n.mjs";
+import { AbilityBuilder, createMongoAbility, subject } from "@casl/ability";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+//#region package.json
+var version = "1.0.0-alpha.31";
+//#endregion
+//#region src/permissions.ts
+/**
+* Standard forbidden exception thrown when an actor lacks required permissions or fails ownership
+* checks.
+*/
+var ForbiddenError = class extends Error {
+	status = 403;
+	code = "FORBIDDEN";
+	/**
+	* Initializes a new ForbiddenError instance.
+	*
+	* @param message - User-friendly error message detailing the authorization failure.
+	*/
+	constructor(message = "Forbidden") {
+		super(message);
+		this.name = "FORBIDDEN";
+	}
+};
+/**
+* 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.
+*/
+function hasPermission(userPermissions, required) {
+	if (userPermissions.includes(required)) return true;
+	if (userPermissions.includes("*")) return true;
+	const parts = required.split(".");
+	for (let i = parts.length - 1; i > 0; i--) {
+		const wildcard = parts.slice(0, i).join(".") + ".*";
+		if (userPermissions.includes(wildcard)) return true;
+	}
+	return false;
+}
+/**
+* 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.
+*/
+function authorizeResourceOwnership({ actorId, actorPermissions, ownerId, ownPermission, anyPermission, resourceLabel = "resource", errorFactory = (msg) => new ForbiddenError(msg), isOwner: actorIsOwner = false }) {
+	const isResourceOwner = actorId === ownerId;
+	if (actorIsOwner || hasPermission(actorPermissions, "*")) return isResourceOwner ? "own" : "any";
+	if (isResourceOwner && hasPermission(actorPermissions, ownPermission)) return "own";
+	if (hasPermission(actorPermissions, anyPermission)) return "any";
+	if (isResourceOwner) throw errorFactory(`Missing required permission to modify this ${resourceLabel}`);
+	throw errorFactory(`Missing required permission to modify another user's ${resourceLabel}`);
+}
+/**
+* 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.
+*/
+function createAddonAbility(actor, defineRules) {
+	const builder = new AbilityBuilder(createMongoAbility);
+	const perms = actor?.permissions ?? [];
+	if (actor?.isOwner || perms.includes("*")) {
+		builder.can("manage", "all");
+		return builder.build();
+	}
+	for (const perm of perms) if (perm.endsWith(".any")) {
+		const parts = perm.split(".");
+		const action = parts[parts.length - 2] || "manage";
+		builder.can(action, "all");
+	} else if (perm.endsWith(".own") && actor?.id) {
+		const parts = perm.split(".");
+		const action = parts[parts.length - 2] || "manage";
+		builder.can(action, "all", { userId: actor.id });
+	}
+	if (defineRules) defineRules(builder);
+	return builder.build();
+}
+//#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);
+		}
+	});
+}
+/**
+* Ergonomic hook for loading and updating site configuration for an addon. Handles fetching,
+* caching, pending states, and automatic query cache invalidation.
+*/
+function useAddonSettings(siteId) {
+	const sdk = useAddonSDK();
+	const query = useAddonQuery({
+		queryKey: ["settings", siteId],
+		queryFn: () => sdk.settings.get()
+	});
+	const mutation = useAddonMutation({
+		mutationFn: (settings) => sdk.settings.save(settings),
+		invalidateQueries: [["settings", siteId]]
+	});
+	return {
+		settings: query.data ?? null,
+		isLoading: query.isLoading,
+		isSaving: mutation.isPending,
+		error: query.error ?? mutation.error,
+		saveSettings: mutation.mutate,
+		saveSettingsAsync: mutation.mutateAsync,
+		refetch: query.refetch
+	};
+}
+//#endregion
+//#region src/testing.ts
+/**
+* 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.
+*/
+function createMockAddonServerContext(addonId, options = {}) {
+	const { config = {}, user = {}, isEntitled = true } = options;
+	const emittedEvents = [];
+	const registeredHooks = [];
+	const cacheEntries = /* @__PURE__ */ new Map();
+	const cacheSets = /* @__PURE__ */ new Map();
+	const cacheTtld = /* @__PURE__ */ new Map();
+	const rateLimitTimestamps = /* @__PURE__ */ new Map();
+	const prefix = `addon:${addonId}:`;
+	const cache = {
+		async get(key) {
+			const fullKey = prefix + key;
+			const exp = cacheTtld.get(fullKey);
+			if (exp && Date.now() > exp) {
+				cacheEntries.delete(fullKey);
+				cacheTtld.delete(fullKey);
+				return null;
+			}
+			const val = cacheEntries.get(fullKey);
+			return val !== void 0 ? val : null;
+		},
+		async set(key, value, ttlSeconds) {
+			const fullKey = prefix + key;
+			cacheEntries.set(fullKey, value);
+			if (ttlSeconds && ttlSeconds > 0) cacheTtld.set(fullKey, Date.now() + ttlSeconds * 1e3);
+			else cacheTtld.delete(fullKey);
+		},
+		async del(...keys) {
+			let count = 0;
+			for (const k of keys) {
+				const fullKey = prefix + k;
+				if (cacheEntries.delete(fullKey)) count++;
+				cacheTtld.delete(fullKey);
+				cacheSets.delete(fullKey);
+			}
+			return count;
+		},
+		async incr(key) {
+			const fullKey = prefix + key;
+			const next = (Number(cacheEntries.get(fullKey)) || 0) + 1;
+			cacheEntries.set(fullKey, next);
+			return next;
+		},
+		async expire(key, ttlSeconds) {
+			const fullKey = prefix + key;
+			if (!cacheEntries.has(fullKey) && !cacheSets.has(fullKey)) return false;
+			cacheTtld.set(fullKey, Date.now() + ttlSeconds * 1e3);
+			return true;
+		},
+		async ttl(key) {
+			const fullKey = prefix + key;
+			if (!cacheEntries.has(fullKey) && !cacheSets.has(fullKey)) return -2;
+			const exp = cacheTtld.get(fullKey);
+			if (!exp) return -1;
+			const remaining = Math.ceil((exp - Date.now()) / 1e3);
+			return remaining > 0 ? remaining : -2;
+		},
+		async setAdd(key, member) {
+			const fullKey = prefix + key;
+			let set = cacheSets.get(fullKey);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				cacheSets.set(fullKey, set);
+			}
+			const initialSize = set.size;
+			set.add(member);
+			return set.size > initialSize ? 1 : 0;
+		},
+		async setRemove(key, member) {
+			const fullKey = prefix + key;
+			const set = cacheSets.get(fullKey);
+			if (!set) return 0;
+			return set.delete(member) ? 1 : 0;
+		},
+		async setMembers(key) {
+			const fullKey = prefix + key;
+			const set = cacheSets.get(fullKey);
+			return set ? Array.from(set) : [];
+		}
+	};
+	const rateLimiter = { async consume(key, opts) {
+		const fullKey = `addon:${addonId}:ratelimit:${key}`;
+		const now = Date.now();
+		const windowStart = now - opts.windowMs;
+		const valid = (rateLimitTimestamps.get(fullKey) ?? []).filter((t) => t > windowStart);
+		if (valid.length >= opts.limit) {
+			rateLimitTimestamps.set(fullKey, valid);
+			return false;
+		}
+		valid.push(now);
+		rateLimitTimestamps.set(fullKey, valid);
+		return true;
+	} };
+	const defaultUser = {
+		id: user.id ?? "mock-user-1",
+		name: user.name ?? "Mock User",
+		displayName: user.displayName ?? "Mock User",
+		avatar: user.avatar ?? "https://example.com/avatar.png",
+		gender: user.gender ?? "neutral"
+	};
+	return {
+		context: {
+			t: {},
+			fetch: async (input, init) => globalThis.fetch(input, init),
+			db: {},
+			cache,
+			rateLimiter,
+			emit: async (event, payload, target) => {
+				emittedEvents.push({
+					event: `addon:${addonId}:${event}`,
+					payload,
+					target
+				});
+			},
+			pipeline: { register: (hooks) => {
+				registeredHooks.push(hooks);
+			} },
+			getConfig: async (_targetSiteId) => config,
+			getUser: async (userId) => userId === defaultUser.id ? defaultUser : null,
+			findUserByName: async (name) => name === defaultUser.name ? defaultUser : null,
+			getUsers: async (userIds) => {
+				const map = /* @__PURE__ */ new Map();
+				for (const id of userIds) if (id === defaultUser.id) map.set(id, defaultUser);
+				return map;
+			},
+			hasPermission: (reqUser, permission) => {
+				return hasPermission(reqUser?.permissions ?? [], permission);
+			},
+			authorizeOwnership: ({ actor, ownerId, ownPermission, anyPermission, resourceLabel }) => {
+				return authorizeResourceOwnership({
+					actorId: actor.id,
+					actorPermissions: actor.permissions ?? [],
+					ownerId,
+					ownPermission,
+					anyPermission,
+					resourceLabel
+				});
+			},
+			can: (actor, action, subjectName, attributes) => {
+				if (!actor) return false;
+				return createAddonAbility(actor).can(action, attributes ? subject(subjectName, attributes) : subjectName);
+			},
+			verifyEntitlement: (expectedAddonId) => {
+				if (expectedAddonId && expectedAddonId !== addonId) return false;
+				return isEntitled;
+			}
+		},
+		emittedEvents,
+		registeredHooks,
+		cacheEntries,
+		cacheSets
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* @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.
+*/
+/** Standard error thrown or handled when an addon message pipeline hook aborts sending. */
+var AddonPipelineAbortError = class extends Error {
+	code;
+	reason;
+	constructor(error) {
+		super(error.reason || error.code);
+		this.name = "AddonPipelineAbortError";
+		this.code = error.code;
+		this.reason = error.reason;
+	}
+};
+/** Define a manifest with full validation-friendly typing while preserving literal values. */
+function defineAddonManifest(manifest) {
+	return manifest;
+}
+/** Define a typed server factory without widening its addon database interface. */
+function defineAddonServer(factory) {
+	return factory;
+}
+/**
+* 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")
+*     }
+*   }
+*   ```
+*/
+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.");
+}
+/**
+* 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
+*/
+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 ({ 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
+*/
+function verifyAddonEntitlement(addonId, target) {
+	const verifyFn = typeof target === "function" ? target : target?.verifyEntitlement;
+	if (verifyFn) {
+		if (!verifyFn(addonId)) throw new Error(`addon_entitlement_verification_failed:${addonId}`);
+		return true;
+	}
+	return true;
+}
+//#endregion
+export { createMongoAbility as _, useAddonSDK as a, useAddonInfiniteQuery as c, useAddonSettings as d, useQueryClient as f, createAddonAbility as g, authorizeResourceOwnership as h, getAddonSdkVersion as i, useAddonMutation as l, ForbiddenError as m, defineAddonManifest as n, verifyAddonEntitlement as o, AbilityBuilder as p, defineAddonServer as r, createMockAddonServerContext as s, AddonPipelineAbortError as t, useAddonQuery as u, hasPermission as v, subject as y };

package/dist/state.d.mts

@@ -0,0 +1 @@
+export * from "jotai";

package/dist/state.mjs

@@ -0,0 +1,2 @@
+export * from "jotai";
+export {};

package/dist/testing.d.mts

@@ -0,0 +1,2 @@
+import { MockAddonContextResult, MockAddonServerContextOptions, createMockAddonServerContext } from "./index.mjs";
+export { MockAddonContextResult, MockAddonServerContextOptions, createMockAddonServerContext };

package/dist/testing.mjs

@@ -0,0 +1,2 @@
+import { s as createMockAddonServerContext } from "./src.mjs";
+export { createMockAddonServerContext };

package/dist/ui.d.mts

@@ -0,0 +1,48 @@
+import { _ as AddonUser, d as AddonRequestUser } from "./contracts2.mjs";
+import React from "react";
+import ui_default from "@jchat/ui";
+import { Can } from "@casl/react";
+export * from "@jchat/ui";
+//#region src/ui.d.ts
+export interface AddonCanProps {
+  /** The current user attempting the action */
+  actor?: (Partial<AddonRequestUser | AddonUser> & {
+    permissions?: string[];
+    isOwner?: boolean;
+  }) | null;
+  /** The owner ID of the target resource, if evaluating an ownership-restricted action */
+  ownerId?: string;
+  /** Permission required if actor is the resource owner (e.g. 'addon.pollwise.close.own') */
+  ownPermission?: string;
+  /** Permission required if actor is NOT the resource owner (e.g. 'addon.pollwise.close.any') */
+  anyPermission?: string;
+  /** Simple permission string when not evaluating ownership (e.g. 'addon.pollwise.create') */
+  permission?: string;
+  /** Fallback content rendered when permission is denied (defaults to null) */
+  fallback?: React.ReactNode;
+  /** Content rendered when access is granted */
+  children: React.ReactNode;
+}
+/**
+ * Declarative component for conditional UI rendering based on RBAC/ABAC permissions and resource
+ * ownership.
+ *
+ * @param actor The current user attempting the action
+ * @param ownerId The owner ID of the target resource, if evaluating an ownership-restricted action
+ * @param ownPermission Permission required if actor is the resource owner (e.g.
+ *   'addon.pollwise.close.own')
+ * @param anyPermission Permission required if actor is NOT the resource owner (e.g.
+ *   'addon.pollwise.close.any')
+ * @param permission Simple permission string when not evaluating ownership (e.g.
+ *   'addon.pollwise.create')
+ * @param fallback Fallback content rendered when permission is denied (defaults to null)
+ * @param children Content rendered when access is granted
+ */
+export declare function AddonCan({ actor, ownerId, ownPermission, anyPermission, permission, fallback, children }: AddonCanProps): React.ReactElement | null;
+/** Standard loading spinner for addon settings views. */
+export declare function AddonSettingsLoading({ message, className }: {
+  message?: string;
+  className?: string;
+}): React.ReactElement;
+//#endregion
+export { Can, ui_default as default };

package/dist/ui.mjs

@@ -0,0 +1,39 @@
+import { v as hasPermission } from "./src.mjs";
+import React from "react";
+import ui_default from "@jchat/ui";
+import { Can } from "@casl/react";
+export * from "@jchat/ui";
+//#region src/ui.ts
+/**
+* Declarative component for conditional UI rendering based on RBAC/ABAC permissions and resource
+* ownership.
+*
+* @param actor The current user attempting the action
+* @param ownerId The owner ID of the target resource, if evaluating an ownership-restricted action
+* @param ownPermission Permission required if actor is the resource owner (e.g.
+*   'addon.pollwise.close.own')
+* @param anyPermission Permission required if actor is NOT the resource owner (e.g.
+*   'addon.pollwise.close.any')
+* @param permission Simple permission string when not evaluating ownership (e.g.
+*   'addon.pollwise.create')
+* @param fallback Fallback content rendered when permission is denied (defaults to null)
+* @param children Content rendered when access is granted
+*/
+function AddonCan({ actor, ownerId, ownPermission, anyPermission, permission, fallback = null, children }) {
+	if (!actor) return fallback;
+	const perms = actor.permissions ?? [];
+	if (actor.isOwner || hasPermission(perms, "*")) return children;
+	if (permission && !hasPermission(perms, permission)) return fallback;
+	if (ownPermission || anyPermission) {
+		if (Boolean(actor.id && ownerId && actor.id === ownerId) && ownPermission && hasPermission(perms, ownPermission)) return children;
+		if (anyPermission && hasPermission(perms, anyPermission)) return children;
+		return fallback;
+	}
+	return children;
+}
+/** Standard loading spinner for addon settings views. */
+function AddonSettingsLoading({ message = "Loading configuration...", className }) {
+	return React.createElement("div", { className: "flex items-center justify-center p-8 text-sm text-muted-foreground" + (className ? ` ${className}` : "") }, React.createElement("span", { className: "me-2 inline-block size-4 animate-spin rounded-full border-2 border-primary border-t-transparent" }), message);
+}
+//#endregion
+export { AddonCan, AddonSettingsLoading, Can, ui_default as default };

package/dist/vite.d.mts

@@ -1,14 +1,44 @@
-import { t as AddonManifest } from "./contracts.mjs";
+import { l as AddonManifest } from "./contracts2.mjs";
 import { Plugin } from "vite";
 //#region src/vite.d.ts
 /**
- * Vite plugin to configure Jchat addon manifest generation, bundle backend scripts, copy
- * migrations, declarative seed data, and zip production build artifacts.
+ * Vite plugin for building JChat sandboxed addon extensions.
+ *
+ * Configures automatic manifest generation (`manifest.json`), bundles server-side API scripts
+ * (`src/api.ts`), embeds scoped Tailwind CSS into the frontend bundle, packages database migrations
+ * and seed files, copies documentation (`README.md`), signs database-bearing addon manifests, and
+ * zips production build artifacts.
+ *
+ * @example
+ *   ;```ts
+ *   import { jchatAddon } from "@jchat/addon-sdk/vite"
+ *   import manifest from "./src/manifest"
+ *   import { defineConfig } from "vite"
+ *
+ *   export default defineConfig({
+ *     plugins: [jchatAddon({ manifest })]
+ *   })
+ *   ```
+ *
+ * @param options - Configuration options for the JChat addon Vite plugin.
+ * @returns A Vite {@link Plugin} instance configured for addon compilation.
  */
-declare function jchatAddon(options: JchatAddonPluginOptions): Plugin;
-interface JchatAddonPluginOptions {
+export declare function jchatAddon(options: JchatAddonPluginOptions): Plugin;
+/** Configuration options for the {@link jchatAddon} Vite plugin. */
+export interface JchatAddonPluginOptions {
+  /** The base manifest specification for the addon. */
   manifest: AddonManifest;
+  /** Explicitly declare development mode to permit unsigned database-bearing builds. */
+  development?: boolean;
+  /**
+   * Whether to package the build output into a `.zip` archive upon build completion. Defaults to
+   * `true` during production builds and `false` during development builds.
+   */
   zip?: boolean;
+  /**
+   * Optional RSA private key string used to cryptographically sign database-bearing addons. If
+   * omitted, falls back to the `JCHAT_ADDON_SIGNING_PRIVATE_KEY` environment variable.
+   */
   signingPrivateKey?: string;
   /**
    * Embed Tailwind CSS output into the JS bundle and scope it to the addon's DOM container.
@@ -16,11 +46,35 @@ interface JchatAddonPluginOptions {
    */
   css?: boolean;
 }
-declare function createAddonServerBuildArguments(entryPath: string, outputPath: string, developmentBuild: boolean): string[];
-declare function signAddonManifest(manifest: AddonManifest, files: readonly {
+/**
+ * Generates CLI argument parameters for bundling server-side Elysia API scripts (`src/api.ts`) via
+ * Bun.
+ *
+ * @param entryPath - Absolute file path to the server entry script (`src/api.ts`).
+ * @param outputPath - Absolute destination file path for the bundled output (`build/api.js`).
+ * @param developmentBuild - Indicates whether to enable external sourcemaps or minification.
+ * @returns Array of command line arguments for running `bun build`.
+ */
+export declare function createAddonServerBuildArguments(entryPath: string, outputPath: string, developmentBuild: boolean): string[];
+/**
+ * Cryptographically signs an addon manifest using RSA-SHA256 over all archive file contents.
+ *
+ * @param manifest - Unsigned or base addon manifest.
+ * @param files - List of archive file paths and raw contents to digest.
+ * @param privateKey - RSA private key in PEM format.
+ * @returns Updated {@link AddonManifest} containing an RSA signature block.
+ */
+export declare function signAddonManifest(manifest: AddonManifest, files: readonly {
   path: string;
   contents: Buffer;
 }[], privateKey: string): AddonManifest;
-declare function requireAddonSigningKey(signingPrivateKey: string | undefined, developmentBuild: boolean): string | undefined;
-//#endregion
-export { JchatAddonPluginOptions, createAddonServerBuildArguments, jchatAddon, requireAddonSigningKey, signAddonManifest };
+/**
+ * Resolves the required RSA signing key for database-bearing addons.
+ *
+ * @param signingPrivateKey - Provided signing key or undefined.
+ * @param developmentBuild - Whether the current build is targeting development mode.
+ * @returns Resolved signing key string or undefined (in dev builds).
+ * @throws {@link Error} If building a database-bearing addon in production without a signing key.
+ */
+export declare function requireAddonSigningKey(signingPrivateKey: string | undefined, developmentBuild: boolean): string | undefined;
+//#endregion