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

package/dist/contracts.d.mts

@@ -1,130 +1,2 @@
-//#region src/contracts.d.ts
-type AddonPermission = string;
-/**
- * Defines a single configuration field for an addon's settings panel. These are shown to site
- * admins in the Jchat dashboard.
- */
-interface ConfigSchemaField {
-  /** Unique key used to store and retrieve the value in `getConfig` */
-  key: string;
-  /** Data type for validation and UI rendering */
-  type: "string" | "number" | "boolean";
-  /** Human-readable label shown in the settings UI */
-  label: string;
-  /** If true, the admin must provide a value before saving */
-  required?: boolean;
-  /** Whether the value is sensitive (encrypted at rest and masked in the UI) */
-  secret?: boolean;
-  /** Default value pre-filled in the settings form for new installations */
-  default?: string | number | boolean;
-}
-/** Definition of a custom permission introduced by an addon. */
-interface AddonPermissionDefinition {
-  /** Permission identifier (recommended: `addon.<id>.<action>`) */
-  name: string;
-  /** Short, human-readable name for the permission */
-  label: string;
-  /** Detailed description of what the permission grants (shown in Rank editor) */
-  description: string;
-}
-/** Valid locations where an addon can be rendered within the Jchat layout. */
-declare const MOUNT_POINTS: {
-  /** Top of the main chat column */
-  readonly CHAT_HEADER: "chat-header";
-  /** Below the main chat header, above messages */
-  readonly CHAT_TOOLBAR: "chat-toolbar";
-  /** The persistent right-side sidebar */
-  readonly CHAT_SIDEBAR: "chat-sidebar";
-  /** Top of the left sidebar (room list) */
-  readonly SIDEBAR_TOP: "sidebar-top";
-  /** Bottom of the left sidebar */
-  readonly SIDEBAR_BOTTOM: "sidebar-bottom";
-  /** Action list shown when clicking a user's avatar */
-  readonly USER_POPOVER_ACTIONS: "user-popover-actions";
-  /** Menu shown when right-clicking a message */
-  readonly MESSAGE_CONTEXT_MENU: "message-context-menu";
-  /** Floating overlay rendered on top of the message stream */
-  readonly MESSAGE_FEED_OVERLAY: "message-feed-overlay";
-  /** Main admin dashboard area */
-  readonly ADMIN_PANEL: "admin-panel";
-  /** User or site settings dashboard area */
-  readonly SETTINGS_PANEL: "settings-panel";
-  /** The 'plus' (+) menu in the message composer */
-  readonly CHAT_PLUS_MENU: "chat-plus-menu";
-  /** Custom tab in the emoji/gif selection panel */
-  readonly EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab";
-  /** Full-screen or modal dialog specifically for TubeScan */
-  readonly TUBESCAN_DIALOG: "tubescan-dialog";
-};
-/** Union type of all valid addon mount points. */
-type MountPoint = (typeof MOUNT_POINTS)[keyof typeof MOUNT_POINTS];
-/**
- * The `manifest.json` schema required for every Jchat addon. This file describes how the addon is
- * identified and mounted.
- */
-interface AddonManifest {
-  /** Unique kebab-case addon identifier (must match the folder name) */
-  id: string;
-  /** Human-readable addon name */
-  name: string;
-  /** Semver version string (e.g. `1.2.0`) */
-  version: string;
-  /** Brief summary of what the addon does */
-  description?: string;
-  /** Author name, organization, or GitHub handle */
-  author?: string;
-  /** Support or documentation URL */
-  homepage?: string;
-  /** SPDX license identifier (e.g. `MIT`) */
-  license?: string;
-  /** Host and SDK versions this directly executed plugin was built and tested against */
-  compatibility: {
-    /** Supported JChat versions as a semantic-version range, for example `^1.0.0` */
-    jchat: string;
-    /** Supported `@jchat/addon-sdk` versions as a semantic-version range */
-    addonSdk: string;
-  };
-  /** Identity of the trusted publisher that signed this package. Required when migrations exist */
-  publisher?: {
-    id: string;
-  };
-  /** Signature over the canonical archive digest. Required when migrations exist */
-  signature?: {
-    algorithm: "rsa-sha256";
-    digest: string;
-    value: string;
-  };
-  /** Configuration for the React-based frontend bundle */
-  frontend?: {
-    /** Relative path to the pre-compiled ESM bundle (created by Vite) */
-    bundle: string;
-    /** List of UI locations where this addon should be active */
-    mountPoints: MountPoint[];
-    /** Optional path to a specific UI for the settings panel */
-    settings?: string;
-    /** Additional shared packages this addon imports from the host */
-    externals?: string[];
-  };
-  /** Configuration for the server-side API bundle */
-  server?: {
-    /** Relative path to the pre-compiled server bundle */
-    bundle?: string;
-    /** List of SQL files to run (in order) to set up the addon's database tables */
-    migrations?: string[];
-    /** List of declarative JSON master-data files to apply once, in order */
-    seeds?: string[];
-  };
-  /**
-   * The minimum permission required to see or use this addon. If provided, the host gates
-   * visibility in the UI and access to all server routes.
-   */
-  accessPermission?: AddonPermission;
-  /** Full list of all permissions used by this addon for informational purposes */
-  permissions?: AddonPermission[];
-  /** Custom permissions that should be registered with the host application on installation */
-  permissionDefinitions?: AddonPermissionDefinition[];
-  /** Settings form structure shown to site admins. Values are stored encrypted per site */
-  configSchema?: ConfigSchemaField[];
-}
-//#endregion
-export { MOUNT_POINTS as a, ConfigSchemaField as i, AddonPermission as n, MountPoint as o, AddonPermissionDefinition as r, AddonManifest as t };
+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";
+export { ActiveAddon, ActiveAddonFrontend, AddonArchiveFile, AddonAttachment, AddonChatMessage, AddonCommandDefinition, AddonCommandParameter, AddonDistribution, AddonManifest, AddonPermissionDefinition, AddonRequestUser, AddonResilientFetch, AddonRuntimeLog, AddonRuntimeLogFilter, AddonRuntimeLogLevel, AddonRuntimeLogSource, AddonUser, HOST_LOCALES, HostLocale, MOUNT_POINTS, MountPoint, ResilientFetchOptions };

package/dist/contracts.mjs

@@ -0,0 +1,64 @@
+//#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",
+	/** Custom tab in the emoji/sticker selection panel */
+	EMOJI_PICKER_STICKER_TAB: "emoji-picker-sticker-tab",
+	/** Dedicated settings panel rendered in the Owner Dashboard */
+	OWNER_SETTINGS: "owner-settings",
+	/** Dedicated settings panel rendered in the Site Admin Dashboard */
+	ADDON_SETTINGS: "addon-settings",
+	/** Custom interactive card rendered inside an enriched chat message */
+	CHAT_MESSAGE_CARD: "chat-message-card",
+	/** Custom badge, audio equalizer, or particle aura rendered on a chat bubble */
+	CHAT_MESSAGE_FLAIR: "chat-message-flair",
+	/** Custom interactive preview card rendered in the message composer */
+	CHAT_COMPOSER_PREVIEW: "chat-composer-preview"
+};
+const HOST_LOCALES = [
+	"ar",
+	"bg",
+	"hr",
+	"de",
+	"el",
+	"en",
+	"es",
+	"fr",
+	"he",
+	"hi",
+	"kn",
+	"ml",
+	"nl",
+	"pt",
+	"ro",
+	"ru",
+	"ta",
+	"te",
+	"tr",
+	"ur"
+];
+//#endregion
+export { HOST_LOCALES, MOUNT_POINTS };

package/dist/contracts2.d.mts

@@ -0,0 +1,282 @@
+//#region src/contracts.d.ts
+/** Definition of a custom permission introduced by an addon. */
+interface AddonPermissionDefinition {
+  /** Permission identifier (recommended: `addon.<id>.<action>`) */
+  name: string;
+  /** Short, human-readable name for the permission */
+  label: string;
+  /** Detailed description of what the permission grants (shown in Rank editor) */
+  description: string;
+}
+/** Valid locations where an addon can be rendered within the Jchat layout. */
+declare const MOUNT_POINTS: {
+  /** Top of the main chat column */
+  readonly CHAT_HEADER: "chat-header";
+  /** Below the main chat header, above messages */
+  readonly CHAT_TOOLBAR: "chat-toolbar";
+  /** The persistent right-side sidebar */
+  readonly CHAT_SIDEBAR: "chat-sidebar";
+  /** Top of the left sidebar (room list) */
+  readonly SIDEBAR_TOP: "sidebar-top";
+  /** Bottom of the left sidebar */
+  readonly SIDEBAR_BOTTOM: "sidebar-bottom";
+  /** Action list shown when clicking a user's avatar */
+  readonly USER_POPOVER_ACTIONS: "user-popover-actions";
+  /** Menu shown when right-clicking a message */
+  readonly MESSAGE_CONTEXT_MENU: "message-context-menu";
+  /** Floating overlay rendered on top of the message stream */
+  readonly MESSAGE_FEED_OVERLAY: "message-feed-overlay";
+  /** Main admin dashboard area */
+  readonly ADMIN_PANEL: "admin-panel";
+  /** User or site settings dashboard area */
+  readonly SETTINGS_PANEL: "settings-panel";
+  /** The 'plus' (+) menu in the message composer */
+  readonly CHAT_PLUS_MENU: "chat-plus-menu";
+  /** Custom tab in the emoji/gif selection panel */
+  readonly EMOJI_PICKER_GIF_TAB: "emoji-picker-gif-tab";
+  /** Custom tab in the emoji/sticker selection panel */
+  readonly EMOJI_PICKER_STICKER_TAB: "emoji-picker-sticker-tab";
+  /** Dedicated settings panel rendered in the Owner Dashboard */
+  readonly OWNER_SETTINGS: "owner-settings";
+  /** Dedicated settings panel rendered in the Site Admin Dashboard */
+  readonly ADDON_SETTINGS: "addon-settings";
+  /** Custom interactive card rendered inside an enriched chat message */
+  readonly CHAT_MESSAGE_CARD: "chat-message-card";
+  /** Custom badge, audio equalizer, or particle aura rendered on a chat bubble */
+  readonly CHAT_MESSAGE_FLAIR: "chat-message-flair";
+  /** Custom interactive preview card rendered in the message composer */
+  readonly CHAT_COMPOSER_PREVIEW: "chat-composer-preview";
+};
+/** Union type of all valid addon mount points. */
+type MountPoint = (typeof MOUNT_POINTS)[keyof typeof MOUNT_POINTS];
+/** Parameter specification for an addon slash command. */
+interface AddonCommandParameter {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+/** Declaration of an addon slash command available in the chat composer. */
+interface AddonCommandDefinition {
+  /** The command keyword without leading slash (e.g. 'yt', 'roll', 'poll') */
+  name: string;
+  /** Short summary of what the command does, displayed in autocomplete */
+  description: string;
+  /** Usage syntax displayed as a hint (e.g. '<query | url>') */
+  syntax?: string;
+  /** Parameters accepted by this command */
+  parameters?: AddonCommandParameter[];
+}
+/** Distribution model for an addon package. Defaults to `'free'` if omitted. */
+type AddonDistribution = "free" | "commercial";
+/**
+ * The `manifest.json` schema required for every Jchat addon. This file describes how the addon is
+ * identified and mounted.
+ */
+interface AddonManifest {
+  /** Unique kebab-case addon identifier (must match the folder name) */
+  id: string;
+  /** Human-readable addon name */
+  name: string;
+  /** Semver version string (e.g. `1.2.0`) */
+  version: string;
+  /**
+   * Relative path to the addon's logo image asset (e.g. `./assets/logo.svg`, `./assets/logo.png`,
+   * or `./assets/logo.webp`). Recommended square 1:1 aspect ratio, max 512 KB.
+   */
+  logo: string;
+  /** Brief summary of what the addon does */
+  description?: string;
+  /** Author name, organization, or GitHub handle */
+  author?: string;
+  /** Support or documentation URL */
+  homepage?: string;
+  /** SPDX license identifier (e.g. `MIT`) */
+  license?: string;
+  /**
+   * Distribution model: `'free'` (default) for open/free addons, or `'commercial'` for paid addons
+   * requiring purchase entitlement verification.
+   */
+  distribution?: AddonDistribution;
+  /**
+   * Supported language codes (e.g. ["ar", "de", "en", "es", "fr", "hi", "kn", "ml", "ta", "te",
+   * "ur"])
+   */
+  locales?: string[];
+  /** Default fallback language code (e.g. "en") */
+  defaultLocale?: string;
+  /** Host and SDK versions this directly executed plugin was built and tested against */
+  compatibility: {
+    /** Supported JChat versions as a semantic-version range, for example `^1.0.0` */
+    jchat: string;
+    /** Supported `@jchat/addon-sdk` versions as a semantic-version range */
+    addonSdk: string;
+  };
+  /** Identity of the trusted publisher that signed this package. Required when migrations exist */
+  publisher?: {
+    id: string;
+  };
+  /** Signature over the canonical archive digest. Required when migrations exist */
+  signature?: {
+    algorithm: "rsa-sha256";
+    digest: string;
+    value: string;
+  };
+  /** Configuration for the React-based frontend bundle */
+  frontend?: {
+    /** Relative path to the pre-compiled ESM bundle (created by Vite) */
+    bundle: string;
+    /** List of UI locations where this addon should be active */
+    mountPoints: MountPoint[];
+    /** Optional path to a specific UI for the settings panel */
+    settings?: string;
+    /** Additional shared packages this addon imports from the host */
+    externals?: string[];
+  };
+  /** Configuration for the server-side API bundle */
+  server?: {
+    /** Relative path to the pre-compiled server bundle */
+    bundle?: string;
+    /** List of SQL files to run (in order) to set up the addon's database tables */
+    migrations?: string[];
+    /** List of declarative JSON master-data files to apply once, in order */
+    seeds?: string[];
+  };
+  /**
+   * The minimum permission required to see or use this addon. If provided, the host gates
+   * visibility in the UI and access to all server routes.
+   */
+  accessPermission?: string;
+  /** Full list of all permissions used by this addon for informational purposes */
+  permissions?: string[];
+  /** Custom permissions that should be registered with the host application on installation */
+  permissionDefinitions?: AddonPermissionDefinition[];
+  /** Interactive slash commands exposed in the chat composer */
+  commands?: AddonCommandDefinition[];
+}
+declare const HOST_LOCALES: readonly ["ar", "bg", "hr", "de", "el", "en", "es", "fr", "he", "hi", "kn", "ml", "nl", "pt", "ro", "ru", "ta", "te", "tr", "ur"];
+type HostLocale = (typeof HOST_LOCALES)[number];
+/** Minimal user profile accessible to addon backends and UI slots. */
+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;
+}
+/** Options for resilient HTTP fetch requests issued by addons or host services. */
+interface ResilientFetchOptions extends RequestInit {
+  /** Maximum number of retry attempts on transient network or 5xx server errors. Defaults to 2. */
+  retries?: number;
+  /** Initial exponential retry backoff in milliseconds. Defaults to 150. */
+  initialDelayMs?: number;
+  /** Request timeout in milliseconds per attempt. Defaults to 10000. */
+  timeoutMs?: number;
+}
+/** Resilient fetch function type provided to addon server backends. */
+type AddonResilientFetch = (input: string | URL | Request, init?: ResilientFetchOptions) => Promise<Response>;
+/** Authenticated request user context passed to addon server routes and message pipeline hooks. */
+interface AddonRequestUser {
+  id: string;
+  permissions?: string[];
+  siteId?: string;
+  isOwner?: boolean;
+}
+/** Standard attachment contract for chat messages and addon file attachments. */
+interface AddonAttachment {
+  url: string;
+  name: string;
+  type: string;
+  id?: string;
+  isUploading?: boolean;
+}
+/** Domain-agnostic message contract passed to addon slots (CHAT_MESSAGE_CARD, CHAT_MESSAGE_FLAIR). */
+interface AddonChatMessage {
+  id: string;
+  roomId?: string;
+  senderId?: string;
+  sender?: Partial<AddonUser> & {
+    id: string;
+    name: string;
+    isOwner?: boolean;
+    isBot?: boolean;
+    rankName?: string;
+  };
+  content?: unknown;
+  attachments?: AddonAttachment[] | null;
+  metadata?: Record<string, unknown> | null;
+  createdAt?: string | Date;
+}
+/** Severity level classification for runtime addon logging. */
+type AddonRuntimeLogLevel = "error" | "info" | "warn";
+/** Operational lifecycle origin of a runtime log entry. */
+type AddonRuntimeLogSource = "request" | "startup";
+/** A diagnostic runtime log entry recorded during addon server startup or HTTP request execution. */
+interface AddonRuntimeLog {
+  /** Unique auto-incrementing log entry sequence identifier */
+  id: number;
+  /** ISO-8601 UTC timestamp when the event was recorded */
+  timestamp: string;
+  /** Canonical identifier of the emitting addon */
+  addonId: string;
+  /** Log severity classification */
+  level: AddonRuntimeLogLevel;
+  /** Lifecycle stage where the log originated */
+  source: AddonRuntimeLogSource;
+  /** Descriptive log message or error description */
+  message: string;
+  /** HTTP method if the log was generated during request execution */
+  method?: string;
+  /** Request pathname if the log was generated during request execution */
+  path?: string;
+  /** HTTP response status code if the log was generated during request execution */
+  status?: number;
+}
+/** Query parameters for filtering and bounding addon developer runtime logs. */
+interface AddonRuntimeLogFilter {
+  /** Filter logs by a specific addon identifier */
+  addonId?: string;
+  /** Filter logs by severity level */
+  level?: AddonRuntimeLogLevel;
+  /** Maximum number of recent log records to return */
+  limit?: number;
+}
+/** Frontend mounting and bundle distribution metadata for an active addon. */
+interface ActiveAddonFrontend extends Pick<NonNullable<AddonManifest["frontend"]>, "mountPoints"> {
+  /** Relative web-accessible path to the compiled frontend bundle */
+  bundlePath?: string;
+}
+/** Public host runtime representation of an installed, active addon. */
+interface ActiveAddon extends Pick<AddonManifest, "id" | "name" | "version" | "description" | "author" | "homepage" | "license" | "accessPermission" | "permissions" | "commands"> {
+  /** Whether the addon is globally activated on the host platform */
+  enabled: boolean;
+  /** Relative path to the compiled frontend bundle file */
+  bundlePath?: string;
+  /** Relative path or URL to the addon logo asset */
+  logoPath?: string | null;
+  /** Frontend mounting points and distribution information */
+  frontend?: ActiveAddonFrontend;
+  /** Timestamp when the addon was installed */
+  createdAt?: string | Date;
+  /** Timestamp when the addon configuration or files were last modified */
+  updatedAt?: string | Date;
+}
+/**
+ * In-memory representation of an archive file entry used in canonical digest creation and package
+ * verification.
+ */
+interface AddonArchiveFile {
+  /**
+   * Canonical relative path inside the addon archive (e.g., 'manifest.json',
+   * 'migrations/001_init.sql')
+   */
+  path: string;
+  /** Raw binary contents of the archive file */
+  contents: Buffer;
+}
+//#endregion
+export { ResilientFetchOptions as S, AddonUser as _, AddonChatMessage as a, MOUNT_POINTS as b, AddonDistribution as c, AddonRequestUser as d, AddonResilientFetch as f, AddonRuntimeLogSource as g, AddonRuntimeLogLevel as h, AddonAttachment as i, AddonManifest as l, AddonRuntimeLogFilter as m, ActiveAddonFrontend as n, AddonCommandDefinition as o, AddonRuntimeLog as p, AddonArchiveFile as r, AddonCommandParameter as s, ActiveAddon as t, AddonPermissionDefinition as u, HOST_LOCALES as v, MountPoint as x, HostLocale as y };

package/dist/diagnostics.d.mts

@@ -1,22 +1,68 @@
-import { t as AddonManifest } from "./contracts.mjs";
+import { l as AddonManifest } from "./contracts2.mjs";
 //#region src/diagnostics.d.ts
-type AddonDiagnosticStatus = "pass" | "warning" | "error";
-interface AddonPackageDiagnostic {
+/**
+ * Diagnostic result status indicator for addon validation checks. - `"pass"`: The diagnostic check
+ * passed successfully. - `"warning"`: Non-critical warning (e.g. source maps present in
+ * production). - `"error"`: Critical failure blocking addon installation or distribution.
+ */
+export type AddonDiagnosticStatus = "pass" | "warning" | "error";
+/** Represents an individual diagnostic check result for an addon package. */
+export interface AddonPackageDiagnostic {
+  /** Unique identifier for the diagnostic check (e.g. `"jchat"`, `"package-size"`). */
   id: string;
+  /** Human-readable title for the diagnostic check. */
   label: string;
+  /** Severity status outcome of the check. */
   status: AddonDiagnosticStatus;
+  /** Descriptive message or metric value providing check details. */
   message: string;
 }
-interface AddonPackageDiagnosticOptions {
+/** Options required to run diagnostic validation on an addon build package. */
+export interface AddonPackageDiagnosticOptions {
+  /** Absolute path to the compiled addon build output directory (`build/`). */
   buildDir: string;
+  /** Parsed addon manifest object (`manifest.json`). */
   manifest: AddonManifest;
+  /** Semantic version of the host JChat platform instance. */
   jchatVersion: string;
+  /** Semantic version of the `@jchat/addon-sdk` package. */
   addonSdkVersion: string;
+  /** Whether the diagnostic target is a production `.zip` package build. Defaults to `false`. */
   productionPackage?: boolean;
+  /** Maximum allowable package size in bytes. Defaults to 25MB (`26,214,400` bytes). */
   maxBytes?: number;
 }
-declare function createCompatibleMajorRange(version: string): string;
-declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
-declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;
-//#endregion
-export { AddonDiagnosticStatus, AddonPackageDiagnostic, AddonPackageDiagnosticOptions, createCompatibleMajorRange, diagnoseAddonPackage, hasAddonDiagnosticErrors };
+/**
+ * Constructs a semantic version compatibility range covering all minor/patch versions of the
+ * current major version.
+ *
+ * @example
+ *   ;```ts
+ *   createCompatibleMajorRange("1.4.2") // returns ">=1.4.2 <2.0.0"
+ *   ```
+ *
+ * @param version - Valid semver string (e.g. `"1.2.0"`).
+ * @returns Semver range string matching the current major series (e.g. `">=1.2.0 <2.0.0"`).
+ * @throws {@link Error} If the input is not a valid semantic version string.
+ */
+export declare function createCompatibleMajorRange(version: string): string;
+/**
+ * Performs comprehensive diagnostic validation checks on an addon package build directory.
+ *
+ * Validates version compatibility ranges, verifies required build files (frontend/server bundles,
+ * migrations, seeds), checks total package size limits, flags production source maps, and verifies
+ * publisher digital signatures.
+ *
+ * @param options - Configuration options specifying build directory, manifest, and environment
+ *   versions.
+ * @returns Array of {@link AddonPackageDiagnostic} results.
+ */
+export declare function diagnoseAddonPackage(options: AddonPackageDiagnosticOptions): AddonPackageDiagnostic[];
+/**
+ * Checks whether any diagnostic check in a diagnostic list returned a critical error.
+ *
+ * @param diagnostics - Array of diagnostic check results to evaluate.
+ * @returns `true` if at least one check has `status === "error"`, otherwise `false`.
+ */
+export declare function hasAddonDiagnosticErrors(diagnostics: readonly AddonPackageDiagnostic[]): boolean;
+//#endregion

package/dist/diagnostics.mjs

@@ -1,6 +1,19 @@
-import * as fs$1 from "node:fs";
 import * as path$1 from "node:path";
+import * as fs$1 from "node:fs";
 //#region src/diagnostics.ts
+/**
+* Constructs a semantic version compatibility range covering all minor/patch versions of the
+* current major version.
+*
+* @example
+*   ;```ts
+*   createCompatibleMajorRange("1.4.2") // returns ">=1.4.2 <2.0.0"
+*   ```
+*
+* @param version - Valid semver string (e.g. `"1.2.0"`).
+* @returns Semver range string matching the current major series (e.g. `">=1.2.0 <2.0.0"`).
+* @throws {@link Error} If the input is not a valid semantic version string.
+*/
 function createCompatibleMajorRange(version) {
 	try {
 		Bun.semver.order(version, version);
@@ -12,6 +25,17 @@ function createCompatibleMajorRange(version) {
 	if (!Number.isSafeInteger(major)) throw new Error(`Invalid semantic version: ${version}`);
 	return `>=${version} <${major + 1}.0.0`;
 }
+/**
+* Performs comprehensive diagnostic validation checks on an addon package build directory.
+*
+* Validates version compatibility ranges, verifies required build files (frontend/server bundles,
+* migrations, seeds), checks total package size limits, flags production source maps, and verifies
+* publisher digital signatures.
+*
+* @param options - Configuration options specifying build directory, manifest, and environment
+*   versions.
+* @returns Array of {@link AddonPackageDiagnostic} results.
+*/
 function diagnoseAddonPackage(options) {
 	const { buildDir, manifest } = options;
 	const diagnostics = [];
@@ -52,13 +76,25 @@ function diagnoseAddonPackage(options) {
 	const productionArchive = path$1.join(buildDir, `${manifest.id}-${manifest.version}.zip`);
 	const hasProductionArchive = fs$1.existsSync(productionArchive) && fs$1.statSync(productionArchive).isFile();
 	const totalBytes = options.productionPackage && hasProductionArchive ? fs$1.statSync(productionArchive).size : files.filter((file) => file !== productionArchive).reduce((total, file) => total + fs$1.statSync(file).size, 0);
-	const maxBytes = options.maxBytes ?? 25 * 1024 * 1024;
+	const maxBytes = options.maxBytes ?? 26214400;
 	diagnostics.push({
 		id: "package-size",
 		label: "Package size",
 		status: totalBytes <= maxBytes ? "pass" : "error",
 		message: `${totalBytes} of ${maxBytes} bytes`
 	});
+	const addonPermPrefix = `addon.${manifest.id}.`;
+	const invalidPerms = Array.from(/* @__PURE__ */ new Set([
+		...manifest.accessPermission ? [manifest.accessPermission] : [],
+		...manifest.permissions ?? [],
+		...manifest.permissionDefinitions?.map((d) => d.name) ?? []
+	])).filter((perm) => !perm.startsWith(addonPermPrefix));
+	diagnostics.push({
+		id: "permission-namespacing",
+		label: "Permission namespacing",
+		status: invalidPerms.length === 0 ? "pass" : "error",
+		message: invalidPerms.length === 0 ? `All declared permissions start with ${addonPermPrefix}` : `Permission(s) do not follow naming convention ${addonPermPrefix}*: ${invalidPerms.join(", ")}`
+	});
 	const sourceMaps = files.filter((file) => file.endsWith(".map"));
 	diagnostics.push({
 		id: "source-maps",
@@ -81,9 +117,24 @@ function diagnoseAddonPackage(options) {
 	});
 	return diagnostics;
 }
+/**
+* Checks whether any diagnostic check in a diagnostic list returned a critical error.
+*
+* @param diagnostics - Array of diagnostic check results to evaluate.
+* @returns `true` if at least one check has `status === "error"`, otherwise `false`.
+*/
 function hasAddonDiagnosticErrors(diagnostics) {
 	return diagnostics.some(({ status }) => status === "error");
 }
+/**
+* Evaluates semantic version compatibility between a target version and a semver range string.
+*
+* @param id - Diagnostic check identifier.
+* @param label - Diagnostic check label.
+* @param version - Environment component version string.
+* @param range - Expected semver range string from manifest compatibility declarations.
+* @returns An {@link AddonPackageDiagnostic} result object.
+*/
 function compatibilityDiagnostic(id, label, version, range) {
 	const compatible = Boolean(range && Bun.semver.satisfies(version, range));
 	return {
@@ -93,12 +144,26 @@ function compatibilityDiagnostic(id, label, version, range) {
 		message: range ? `${version} ${compatible ? "satisfies" : "does not satisfy"} ${range}` : "Compatibility range is missing"
 	};
 }
+/**
+* Safely resolves a relative build file reference within a target build directory, guarding against
+* directory traversal attacks.
+*
+* @param buildDir - Absolute path to the build directory.
+* @param reference - Relative file path declared in manifest.
+* @returns Resolved absolute file path if safe and inside `buildDir`, or `null` if unsafe.
+*/
 function resolveBuildFile(buildDir, reference) {
 	if (path$1.isAbsolute(reference) || reference.includes("\\") || reference.split("/").includes("..")) return null;
 	const target = path$1.resolve(buildDir, ...reference.replace(/^\.\//, "").split("/"));
 	const relative = path$1.relative(path$1.resolve(buildDir), target);
 	return relative && !relative.startsWith("..") && !path$1.isAbsolute(relative) ? target : null;
 }
+/**
+* Recursively lists all regular files within a root directory.
+*
+* @param root - Path to search.
+* @returns Array of absolute file paths.
+*/
 function listRegularFiles(root) {
 	if (!fs$1.existsSync(root)) return [];
 	return fs$1.readdirSync(root, {