@jchat/addon-sdk 1.0.0-alpha.27 → 1.0.0-alpha.29

package/dist/signing.mjs

@@ -1,20 +1,57 @@
 import crypto from "node:crypto";
 import * as path$1 from "node:path";
 //#region src/signing.ts
+/** Maximum allowable byte size for an addon distribution package archive (25 MB). */
 const MAX_ADDON_ARCHIVE_BYTES = 26214400;
+/**
+* Regular expression validating canonical kebab-case addon identifiers (e.g. `'soundboard'`,
+* `'dj-drop'`).
+*/
 const ADDON_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Regular expression validating semver compatibility range expressions. */
 const COMPATIBILITY_RANGE_PATTERN = /^[0-9A-Za-z*^~<>=|.\-\s]+$/;
+/**
+* Asserts that a file path is a safe relative path, guarding against directory traversal attacks,
+* absolute paths, and non-canonical path separators.
+*
+* @param value - File path string to validate.
+* @param label - Human-friendly field name used for error reporting (e.g. `'Logo path'`, `'Bundle
+*   path'`).
+* @throws {Error} When the path is empty, absolute, contains backslashes, or attempts directory
+*   traversal (`..`).
+*/
 function assertSafeRelativePath(value, label) {
 	if (!value || path$1.isAbsolute(value) || value.includes("\\") || value.split("/").includes("..")) throw new Error(`${label} must be a safe relative path`);
 }
+/**
+* Type guard verifying whether a value is a valid semver compatibility range string.
+*
+* @param value - The value to check.
+* @returns `true` if the value is a valid non-empty compatibility range string within 64
+*   characters.
+*/
 function isCompatibilityRange(value) {
 	return typeof value === "string" && value.length > 0 && value.length <= 64 && COMPATIBILITY_RANGE_PATTERN.test(value);
 }
+/**
+* Recursively sorts object keys alphabetically to guarantee deterministic, reproducible JSON
+* serialization for cryptographic signing and digest hashing.
+*
+* @param value - Object, array, or primitive value to normalize.
+* @returns A new structure with sorted keys at all nested levels.
+*/
 function sortValue(value) {
 	if (Array.isArray(value)) return value.map(sortValue);
 	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).toSorted(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortValue(child)]));
 	return value;
 }
+/**
+* Produces a canonical JSON string representation of an {@link AddonManifest} with signature fields
+* blanked and all object keys sorted deterministically.
+*
+* @param manifest - Addon manifest to canonicalize.
+* @returns Normalized JSON string representation.
+*/
 function canonicalManifest(manifest) {
 	const copy = structuredClone(manifest);
 	if (copy.signature) {
@@ -23,6 +60,16 @@ function canonicalManifest(manifest) {
 	}
 	return JSON.stringify(sortValue(copy));
 }
+/**
+* Computes a deterministic SHA-256 cryptographic digest across an addon archive's contents.
+*
+* Files are processed in lexicographical path order, with manifest signature fields sanitized,
+* producing a tamper-evident package fingerprint.
+*
+* @param manifest - Addon manifest containing metadata and package declarations.
+* @param files - Array of files packaged inside the addon archive.
+* @returns Hex-encoded SHA-256 digest string.
+*/
 function createCanonicalAddonDigest(manifest, files) {
 	const hash = crypto.createHash("sha256");
 	const sortedFiles = [...files].toSorted((left, right) => left.path.localeCompare(right.path));
@@ -34,6 +81,22 @@ function createCanonicalAddonDigest(manifest, files) {
 	}
 	return hash.digest("hex");
 }
+/**
+* Validates the structural, security, and schema integrity of an {@link AddonManifest}.
+*
+* Enforces:
+*
+* - Valid kebab-case identifier (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
+* - Non-empty name and version constraints
+* - Host and SDK compatibility range specifications
+* - Distribution model classification (`'free'` or `'commercial'`)
+* - Logo image file format (`.svg`, `.png`, `.webp`) and safe relative path
+* - Safe relative paths for client/server bundles, migrations, and seeds
+* - Canonical permission namespacing prefix (`addon.<id>.*`)
+*
+* @param manifest - Addon manifest object to inspect and validate.
+* @throws {Error} When any validation rule or security constraint is violated.
+*/
 function validateAddonManifest(manifest) {
 	if (!manifest.id || manifest.id.length > 40 || !ADDON_ID_PATTERN.test(manifest.id)) throw new Error("Manifest id must contain only lowercase letters, numbers, and hyphens");
 	if (!manifest.name || manifest.name.length > 120) throw new Error("Manifest name is invalid");

package/dist/signing2.d.mts

@@ -1,13 +1,76 @@
 import { l as AddonManifest, r as AddonArchiveFile } from "./contracts2.mjs";
 //#region src/signing.d.ts
+/** Maximum allowable byte size for an addon distribution package archive (25 MB). */
 declare const MAX_ADDON_ARCHIVE_BYTES: number;
+/**
+ * Regular expression validating canonical kebab-case addon identifiers (e.g. `'soundboard'`,
+ * `'dj-drop'`).
+ */
 declare const ADDON_ID_PATTERN: RegExp;
+/** Regular expression validating semver compatibility range expressions. */
 declare const COMPATIBILITY_RANGE_PATTERN: RegExp;
+/**
+ * Asserts that a file path is a safe relative path, guarding against directory traversal attacks,
+ * absolute paths, and non-canonical path separators.
+ *
+ * @param value - File path string to validate.
+ * @param label - Human-friendly field name used for error reporting (e.g. `'Logo path'`, `'Bundle
+ *   path'`).
+ * @throws {Error} When the path is empty, absolute, contains backslashes, or attempts directory
+ *   traversal (`..`).
+ */
 declare function assertSafeRelativePath(value: string, label: string): void;
+/**
+ * Type guard verifying whether a value is a valid semver compatibility range string.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid non-empty compatibility range string within 64
+ *   characters.
+ */
 declare function isCompatibilityRange(value: unknown): value is string;
+/**
+ * Recursively sorts object keys alphabetically to guarantee deterministic, reproducible JSON
+ * serialization for cryptographic signing and digest hashing.
+ *
+ * @param value - Object, array, or primitive value to normalize.
+ * @returns A new structure with sorted keys at all nested levels.
+ */
 declare function sortValue(value: unknown): unknown;
+/**
+ * Produces a canonical JSON string representation of an {@link AddonManifest} with signature fields
+ * blanked and all object keys sorted deterministically.
+ *
+ * @param manifest - Addon manifest to canonicalize.
+ * @returns Normalized JSON string representation.
+ */
 declare function canonicalManifest(manifest: AddonManifest): string;
+/**
+ * Computes a deterministic SHA-256 cryptographic digest across an addon archive's contents.
+ *
+ * Files are processed in lexicographical path order, with manifest signature fields sanitized,
+ * producing a tamper-evident package fingerprint.
+ *
+ * @param manifest - Addon manifest containing metadata and package declarations.
+ * @param files - Array of files packaged inside the addon archive.
+ * @returns Hex-encoded SHA-256 digest string.
+ */
 declare function createCanonicalAddonDigest(manifest: AddonManifest, files: readonly AddonArchiveFile[]): string;
+/**
+ * Validates the structural, security, and schema integrity of an {@link AddonManifest}.
+ *
+ * Enforces:
+ *
+ * - Valid kebab-case identifier (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
+ * - Non-empty name and version constraints
+ * - Host and SDK compatibility range specifications
+ * - Distribution model classification (`'free'` or `'commercial'`)
+ * - Logo image file format (`.svg`, `.png`, `.webp`) and safe relative path
+ * - Safe relative paths for client/server bundles, migrations, and seeds
+ * - Canonical permission namespacing prefix (`addon.<id>.*`)
+ *
+ * @param manifest - Addon manifest object to inspect and validate.
+ * @throws {Error} When any validation rule or security constraint is violated.
+ */
 declare function validateAddonManifest(manifest: AddonManifest): void;
 //#endregion
 export { canonicalManifest as a, sortValue as c, assertSafeRelativePath as i, validateAddonManifest as l, COMPATIBILITY_RANGE_PATTERN as n, createCanonicalAddonDigest as o, MAX_ADDON_ARCHIVE_BYTES as r, isCompatibilityRange as s, ADDON_ID_PATTERN as t };

package/dist/src.mjs

@@ -0,0 +1,467 @@
+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.29";
+//#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);
+		}
+	});
+}
+//#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: {},
+			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,
+			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 { hasPermission as _, useAddonSDK as a, useAddonInfiniteQuery as c, useQueryClient as d, AbilityBuilder as f, createMongoAbility as g, createAddonAbility as h, getAddonSdkVersion as i, useAddonMutation as l, authorizeResourceOwnership as m, defineAddonManifest as n, verifyAddonEntitlement as o, ForbiddenError as p, defineAddonServer as r, createMockAddonServerContext as s, AddonPipelineAbortError as t, useAddonQuery as u, subject as v };