@mywallpaper/addon-sdk 2.0.0

package/dist/manifest.d.mts

@@ -0,0 +1,851 @@
+/**
+ * @mywallpaper/addon-sdk - TypeScript Types v2.0
+ *
+ * Complete type definitions for building MyWallpaper addons.
+ * These types describe the runtime API available via window.MyWallpaper
+ *
+ * @example
+ * ```typescript
+ * import type { MyWallpaperAPI, SystemEventType } from '@mywallpaper/addon-sdk'
+ *
+ * // Type-safe event handling
+ * const api = window.MyWallpaper
+ * api.onEvent('viewport:resize', ({ width, height }) => {
+ *   console.log(`Resized to ${width}x${height}`)
+ * })
+ * ```
+ */
+/**
+ * System events that addons can subscribe to.
+ * Subscribe via `window.MyWallpaper.onEvent(eventType, callback)`
+ */
+type SystemEventType = 'viewport:resize' | 'theme:change' | 'visibility:change' | 'layer:focus' | 'layer:blur' | 'app:idle' | 'app:active';
+/**
+ * Event data payloads for each system event type.
+ * TypeScript will infer the correct payload type based on event name.
+ */
+interface SystemEventData {
+    'viewport:resize': {
+        width: number;
+        height: number;
+        aspectRatio: string;
+    };
+    'theme:change': {
+        theme: 'light' | 'dark' | 'system';
+    };
+    'visibility:change': {
+        visible: boolean;
+    };
+    'layer:focus': {
+        layerId: string;
+    };
+    'layer:blur': {
+        layerId: string;
+    };
+    'app:idle': {
+        idleSeconds: number;
+    };
+    'app:active': Record<string, never>;
+}
+/**
+ * Capabilities that an addon can declare.
+ * Declared in `manifest.json` and sent via `ready()` call.
+ */
+type AddonCapability = 'hot-reload' | 'system-events' | 'storage' | 'audio' | 'network';
+/**
+ * OAuth providers supported for addon API access.
+ * Use with `oauth:{provider}` permission format.
+ */
+type OAuthProvider = 'github' | 'google' | 'discord' | 'spotify' | 'twitch';
+/**
+ * OAuth permission types for accessing provider APIs.
+ * Format: `oauth:{provider}`
+ *
+ * @example
+ * ```typescript
+ * const permission: OAuthPermissionType = 'oauth:github'
+ * await api.requestPermission(permission, 'Display your GitHub profile')
+ * ```
+ */
+type OAuthPermissionType = 'oauth:github' | 'oauth:google' | 'oauth:discord' | 'oauth:spotify' | 'oauth:twitch';
+/**
+ * Permission types that addons can request.
+ * Requested via `window.MyWallpaper.requestPermission(type, reason)`
+ */
+type PermissionType = 'storage' | 'cpu-high' | 'network' | 'audio' | 'notifications' | OAuthPermissionType;
+/**
+ * Storage API for persistent key-value data.
+ * Access via `window.MyWallpaper.storage`
+ *
+ * @example
+ * ```typescript
+ * const { storage } = window.MyWallpaper
+ *
+ * // Save user preferences
+ * await storage.set('preferences', { darkMode: true, fontSize: 14 })
+ *
+ * // Retrieve data
+ * const prefs = await storage.get<{ darkMode: boolean; fontSize: number }>('preferences')
+ *
+ * // Check storage usage
+ * const usedBytes = await storage.size()
+ * console.log(`Using ${usedBytes} bytes of storage`)
+ * ```
+ */
+interface StorageAPI {
+    /**
+     * Get a value by key.
+     * Returns null if key doesn't exist.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set a value for a key.
+     * Throws if quota exceeded (default 1MB per addon).
+     */
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    /**
+     * Delete a key and its value.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all stored data for this addon.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all storage keys.
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get total storage usage in bytes.
+     */
+    size(): Promise<number>;
+}
+/**
+ * Response from network.fetch() requests.
+ * Similar to native Response but with pre-parsed data.
+ */
+interface NetworkResponse {
+    /** Whether the request was successful (status 200-299) */
+    ok: boolean;
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response data (auto-parsed JSON, text, or base64 for binary) */
+    data: unknown;
+}
+/**
+ * Network API for making HTTP requests through the secure host proxy.
+ * Access via `window.MyWallpaper.network`
+ *
+ * **IMPORTANT:** Direct `fetch()` and `XMLHttpRequest` are blocked for security.
+ * All network requests MUST go through this API.
+ *
+ * **IMPORTANT:** Domains must be declared in your manifest.json:
+ * ```json
+ * {
+ *   "permissions": {
+ *     "network": { "domains": ["api.example.com"] }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const { network } = window.MyWallpaper
+ *
+ * // Simple GET request
+ * const response = await network.fetch('https://api.weather.com/current')
+ * if (response.ok) {
+ *   console.log(response.data)
+ * }
+ *
+ * // POST request with JSON body
+ * const result = await network.fetch('https://api.example.com/data', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ key: 'value' })
+ * })
+ * ```
+ */
+interface NetworkAPI {
+    /**
+     * Make an HTTP request through the secure host proxy.
+     * Domain must be whitelisted in manifest.json permissions.
+     *
+     * @param url - Full URL to fetch (must be in allowed domains)
+     * @param options - Optional request options
+     * @returns Promise resolving to NetworkResponse
+     * @throws Error if domain not allowed or network permission not granted
+     */
+    fetch(url: string, options?: {
+        /** HTTP method (default: GET) */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        /** Request headers */
+        headers?: Record<string, string>;
+        /** Request body (for POST/PUT/PATCH) */
+        body?: string;
+    }): Promise<NetworkResponse>;
+}
+/**
+ * Response from OAuth API proxy requests.
+ */
+interface OAuthResponse {
+    /** Whether the request was successful (status 200-299) */
+    ok: boolean;
+    /** HTTP status code from the provider API */
+    status: number;
+    /** Response headers from the provider API */
+    headers: Record<string, string>;
+    /** Response data (auto-parsed JSON) */
+    data: unknown;
+}
+/**
+ * Error when OAuth scopes are insufficient.
+ * Returned when the addon needs scopes the current token doesn't have.
+ */
+interface OAuthScopesError {
+    /** Error code: 'insufficient_scopes' */
+    error: 'insufficient_scopes';
+    /** Human-readable error message */
+    message: string;
+    /** The OAuth provider that needs re-authorization */
+    provider: OAuthProvider;
+    /** Scopes that are missing from the current token */
+    missingScopes: string[];
+    /** All scopes needed for this request */
+    requiredScopes: string[];
+}
+/**
+ * OAuth API for making authenticated requests to provider APIs.
+ * Access via `window.MyWallpaper.oauth`
+ *
+ * **How it works:**
+ * 1. User connects their OAuth provider in MyWallpaper settings
+ * 2. Your addon requests permission (e.g., `oauth:github`)
+ * 3. API calls are proxied through the host - your addon never sees the token
+ * 4. The host handles token refresh automatically
+ *
+ * **SECURITY:** Your addon NEVER sees OAuth tokens. All requests are proxied
+ * through the backend, which adds authentication headers server-side.
+ *
+ * @example
+ * ```typescript
+ * const api = window.MyWallpaper
+ *
+ * // Request GitHub permission
+ * const granted = await api.requestPermission(
+ *   'oauth:github',
+ *   'Display your GitHub profile and repositories'
+ * )
+ *
+ * if (granted) {
+ *   // Make API calls through the proxy
+ *   const response = await api.oauth.request('github', '/user')
+ *   if (response.ok) {
+ *     console.log('Username:', response.data.login)
+ *   }
+ * }
+ * ```
+ */
+interface OAuthAPI {
+    /**
+     * Make an authenticated request to an OAuth provider's API.
+     *
+     * @param provider - The OAuth provider (github, google, etc.)
+     * @param endpoint - The API endpoint path (e.g., '/user', '/user/repos')
+     * @param options - Optional request options
+     * @returns Promise resolving to OAuthResponse or OAuthScopesError
+     *
+     * @example
+     * ```typescript
+     * // GET request
+     * const profile = await api.oauth.request('github', '/user')
+     *
+     * // POST request
+     * const repo = await api.oauth.request('github', '/user/repos', {
+     *   method: 'POST',
+     *   body: { name: 'new-repo', private: true }
+     * })
+     * ```
+     */
+    request(provider: OAuthProvider, endpoint: string, options?: {
+        /** HTTP method (default: GET) */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        /** Request body (for POST/PUT/PATCH) - will be JSON serialized */
+        body?: unknown;
+        /** Additional headers (Authorization is added automatically) */
+        headers?: Record<string, string>;
+        /** Required scopes for this request - triggers re-auth if missing */
+        requiredScopes?: string[];
+    }): Promise<OAuthResponse | OAuthScopesError>;
+    /**
+     * Check if the user has connected a specific OAuth provider.
+     *
+     * @param provider - The OAuth provider to check
+     * @returns Promise resolving to true if connected
+     *
+     * @example
+     * ```typescript
+     * if (await api.oauth.isConnected('github')) {
+     *   console.log('GitHub is connected')
+     * } else {
+     *   console.log('Please connect your GitHub account')
+     * }
+     * ```
+     */
+    isConnected(provider: OAuthProvider): Promise<boolean>;
+    /**
+     * Get the scopes granted for a connected OAuth provider.
+     *
+     * @param provider - The OAuth provider
+     * @returns Promise resolving to array of granted scopes
+     *
+     * @example
+     * ```typescript
+     * const scopes = await api.oauth.getScopes('github')
+     * if (scopes.includes('repo')) {
+     *   // Can access private repos
+     * }
+     * ```
+     */
+    getScopes(provider: OAuthProvider): Promise<string[]>;
+    /**
+     * Request re-authorization with additional scopes.
+     * Opens the OAuth flow with the new scopes, preserving existing ones.
+     *
+     * @param provider - The OAuth provider
+     * @param scopes - Additional scopes to request
+     * @param reason - User-friendly explanation of why scopes are needed
+     * @returns Promise resolving to true if re-auth was successful
+     *
+     * @example
+     * ```typescript
+     * // Request repo scope for private repository access
+     * const granted = await api.oauth.requestScopes(
+     *   'github',
+     *   ['repo'],
+     *   'Access your private repositories to display commit stats'
+     * )
+     *
+     * if (granted) {
+     *   // Now we can access private repos
+     *   const repos = await api.oauth.request('github', '/user/repos')
+     * }
+     * ```
+     */
+    requestScopes(provider: OAuthProvider, scopes: string[], reason: string): Promise<boolean>;
+}
+/**
+ * Callback for settings changes (hot-reload).
+ * @param settings - Complete settings object with new values
+ * @param changedKeys - Array of keys that changed (for optimization)
+ */
+interface SettingsCallback {
+    (settings: Record<string, unknown>, changedKeys: string[]): void;
+}
+/**
+ * Generic callback for system events.
+ * @param data - Event-specific payload
+ */
+interface EventCallback<T = unknown> {
+    (data: T): void;
+}
+/**
+ * Options passed to `ready()` call.
+ */
+interface ReadyOptions {
+    /** Capabilities this addon supports */
+    capabilities?: AddonCapability[];
+    /** System events this addon wants to receive */
+    subscribedEvents?: SystemEventType[];
+}
+/**
+ * The main MyWallpaper API available on `window.MyWallpaper`.
+ *
+ * This API is automatically injected when your addon loads.
+ * No imports needed - just use `window.MyWallpaper` in your code.
+ *
+ * @example
+ * ```typescript
+ * // Type-safe access
+ * declare const window: Window & { MyWallpaper: MyWallpaperAPI }
+ *
+ * const { config, storage } = window.MyWallpaper
+ *
+ * // React to settings changes
+ * window.MyWallpaper.onSettingsChange((settings, changedKeys) => {
+ *   if (changedKeys.includes('primaryColor')) {
+ *     updateTheme(settings.primaryColor as string)
+ *   }
+ * })
+ *
+ * // Signal addon is ready
+ * window.MyWallpaper.ready({
+ *   capabilities: ['hot-reload', 'storage'],
+ *   subscribedEvents: ['viewport:resize', 'theme:change']
+ * })
+ * ```
+ */
+interface MyWallpaperAPI {
+    /**
+     * Current configuration values from user settings.
+     * Updated automatically when settings change.
+     */
+    readonly config: Record<string, unknown>;
+    /**
+     * Unique identifier for this addon layer instance.
+     * Useful for multi-instance scenarios.
+     */
+    readonly layerId: string;
+    /**
+     * SDK version. Always '2.0' for current API.
+     */
+    readonly version: '2.0';
+    /**
+     * Register callback for settings changes (hot-reload).
+     * Called when user modifies addon settings in the UI.
+     *
+     * @param callback - Function called with new settings and changed keys
+     */
+    onSettingsChange(callback: SettingsCallback): void;
+    /**
+     * Subscribe to a system event.
+     * @param event - Event type to subscribe to
+     * @param callback - Function called when event fires
+     */
+    onEvent<E extends SystemEventType>(event: E, callback: EventCallback<SystemEventData[E]>): void;
+    /**
+     * Unsubscribe from a system event.
+     * @param event - Event type to unsubscribe from
+     * @param callback - Same callback function passed to onEvent
+     */
+    offEvent<E extends SystemEventType>(event: E, callback: EventCallback<SystemEventData[E]>): void;
+    /**
+     * Called when addon is mounted (first load).
+     */
+    onMount(callback: () => void): void;
+    /**
+     * Called when addon is unmounted (removed from page).
+     * Use for cleanup (event listeners, timers, etc.).
+     */
+    onUnmount(callback: () => void): void;
+    /**
+     * Called when addon is paused (hidden, tab inactive).
+     * Use to pause animations and reduce resource usage.
+     */
+    onPause(callback: () => void): void;
+    /**
+     * Called when addon is resumed (visible again).
+     * Use to restart animations and refresh data.
+     */
+    onResume(callback: () => void): void;
+    /**
+     * Signal that the addon is ready and initialized.
+     * **Must be called** after your addon loads and initializes.
+     *
+     * @param options - Capabilities and event subscriptions
+     *
+     * @example
+     * ```typescript
+     * // After DOM is ready and addon is initialized
+     * window.MyWallpaper.ready({
+     *   capabilities: ['hot-reload'],
+     *   subscribedEvents: ['viewport:resize']
+     * })
+     * ```
+     */
+    ready(options?: ReadyOptions): void;
+    /**
+     * Signal that visual rendering is complete.
+     * Call after images are loaded, canvas drawn, animations ready.
+     * Used by screenshot service to capture addon at right moment.
+     *
+     * @example
+     * ```typescript
+     * async function init() {
+     *   await loadAllImages()
+     *   drawCanvas()
+     *   window.MyWallpaper.renderComplete()
+     * }
+     * ```
+     */
+    renderComplete(): void;
+    /**
+     * Request a permission from the user.
+     * Shows a permission modal explaining why the permission is needed.
+     *
+     * @param permission - Permission type to request
+     * @param reason - User-friendly explanation of why permission is needed
+     * @returns Promise resolving to true if granted, false if denied
+     *
+     * @example
+     * ```typescript
+     * const granted = await window.MyWallpaper.requestPermission(
+     *   'storage',
+     *   'Save your preferences across sessions'
+     * )
+     * if (granted) {
+     *   await window.MyWallpaper.storage.set('initialized', true)
+     * }
+     * ```
+     */
+    requestPermission(permission: PermissionType, reason: string): Promise<boolean>;
+    /**
+     * Persistent key-value storage API.
+     * Requires 'storage' permission to be granted first.
+     * Data syncs across devices for logged-in users.
+     */
+    storage: StorageAPI;
+    /**
+     * Network API for making HTTP requests through the secure host proxy.
+     * Requires 'network' permission and domains declared in manifest.
+     *
+     * **SECURITY:** Direct `fetch()` and `XMLHttpRequest` are blocked.
+     * This is the ONLY way to make network requests from addons.
+     *
+     * @example
+     * ```typescript
+     * // First, request permission
+     * const granted = await MyWallpaper.requestPermission('network', 'Fetch weather data')
+     * if (granted) {
+     *   const response = await MyWallpaper.network.fetch('https://api.weather.com/current')
+     *   if (response.ok) {
+     *     console.log(response.data)
+     *   }
+     * }
+     * ```
+     */
+    network: NetworkAPI;
+    /**
+     * OAuth API for making authenticated requests to provider APIs.
+     * Requires corresponding oauth permission (e.g., 'oauth:github').
+     *
+     * **SECURITY:** Your addon NEVER sees OAuth tokens. All requests are
+     * proxied through the backend which adds authentication server-side.
+     *
+     * **How it works:**
+     * 1. User connects their OAuth provider in MyWallpaper settings
+     * 2. Your addon requests permission (e.g., `oauth:github`)
+     * 3. API calls are proxied through the host
+     * 4. The host handles token refresh automatically
+     *
+     * @example
+     * ```typescript
+     * // First, request GitHub permission
+     * const granted = await MyWallpaper.requestPermission(
+     *   'oauth:github',
+     *   'Display your GitHub profile'
+     * )
+     *
+     * if (granted) {
+     *   // Make authenticated API calls
+     *   const response = await MyWallpaper.oauth.request('github', '/user')
+     *   if (response.ok) {
+     *     console.log('GitHub username:', response.data.login)
+     *   }
+     * }
+     * ```
+     */
+    oauth: OAuthAPI;
+}
+/**
+ * Augments the global Window interface with MyWallpaper API.
+ * Allows `window.MyWallpaper` to be used without type assertions.
+ */
+declare global {
+    interface Window {
+        /** Layer ID injected before addon loads */
+        __MYWALLPAPER_LAYER_ID__?: string;
+        /** Initial config injected before addon loads */
+        __MYWALLPAPER_INITIAL_CONFIG__?: Record<string, unknown>;
+        /** The main MyWallpaper API */
+        MyWallpaper: MyWallpaperAPI;
+    }
+}
+
+/**
+ * @mywallpaper/addon-sdk - Manifest Schema & Validation
+ *
+ * Defines the addon manifest format (manifest.json) and provides
+ * Zod-based validation for type safety at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { validateManifest, type AddonManifest } from '@mywallpaper/addon-sdk/manifest'
+ *
+ * const manifest: AddonManifest = {
+ *   name: 'My Addon',
+ *   version: '1.0.0',
+ *   description: 'A cool addon',
+ *   settings: {
+ *     primaryColor: { type: 'color', default: '#ffffff', label: 'Primary Color' }
+ *   }
+ * }
+ *
+ * // Validate at runtime
+ * const result = validateManifest(manifest)
+ * if (!result.success) {
+ *   console.error('Invalid manifest:', result.errors)
+ * }
+ * ```
+ */
+
+/**
+ * Available setting types for addon configuration.
+ */
+type SettingType = 'string' | 'number' | 'boolean' | 'color' | 'select' | 'range' | 'image' | 'section' | 'textarea' | 'radio' | 'gradient' | 'vector2' | 'button' | 'multi-select';
+/**
+ * Definition for a single addon setting.
+ *
+ * @example
+ * ```typescript
+ * const colorSetting: SettingDefinition = {
+ *   type: 'color',
+ *   label: 'Background Color',
+ *   description: 'Choose a background color',
+ *   default: '#000000'
+ * }
+ *
+ * const speedSetting: SettingDefinition = {
+ *   type: 'range',
+ *   label: 'Animation Speed',
+ *   min: 0.1,
+ *   max: 10,
+ *   step: 0.1,
+ *   default: 1
+ * }
+ * ```
+ */
+interface SettingDefinition {
+    /** Setting type determines the UI control */
+    type: SettingType;
+    /** Human-readable label */
+    label?: string;
+    /** Help text shown below the control */
+    description?: string;
+    /** Default value (type depends on setting type) */
+    default?: unknown;
+    /** Options for select, radio, multi-select types */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Minimum value for range type */
+    min?: number;
+    /** Maximum value for range type */
+    max?: number;
+    /** Step increment for range type */
+    step?: number;
+    /** Label text on button */
+    buttonLabel?: string;
+    /** Axis labels for vector types, e.g., ['X', 'Y'] */
+    axisLabels?: [string, string] | [string, string, string];
+    /** Maximum number of selections */
+    maxItems?: number;
+    /** Only show if another setting has a specific value */
+    showIf?: {
+        setting: string;
+        equals: unknown;
+    };
+}
+/**
+ * Default layout configuration for addon positioning.
+ */
+interface AddonDefaultLayout {
+    /** X position as percentage of viewport width (0-100) */
+    xPercent?: number;
+    /** Y position as percentage of viewport height (0-100) */
+    yPercent?: number;
+    /** Width as percentage of viewport width (0-100) */
+    widthPercent?: number;
+    /** Height as percentage of viewport height (0-100) */
+    heightPercent?: number;
+    /** Rotation in degrees */
+    rotation?: number;
+}
+/**
+ * The complete addon manifest schema.
+ * This defines your addon's identity, settings, and capabilities.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "Weather Widget",
+ *   "version": "1.2.0",
+ *   "description": "Displays current weather conditions",
+ *   "author": "Jane Developer",
+ *   "categories": ["utilities", "weather"],
+ *   "capabilities": {
+ *     "hotReload": true,
+ *     "systemEvents": ["viewport:resize", "theme:change"]
+ *   },
+ *   "permissions": {
+ *     "storage": { "quota": 512 },
+ *     "network": { "domains": ["api.openweathermap.org"] }
+ *   },
+ *   "settings": {
+ *     "apiKey": {
+ *       "type": "string",
+ *       "label": "API Key",
+ *       "description": "Get your key at openweathermap.org"
+ *     },
+ *     "unit": {
+ *       "type": "select",
+ *       "label": "Temperature Unit",
+ *       "default": "celsius",
+ *       "options": [
+ *         { "value": "celsius", "label": "Celsius" },
+ *         { "value": "fahrenheit", "label": "Fahrenheit" }
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface AddonManifest {
+    /** Addon name (displayed in UI) */
+    name: string;
+    /** Semantic version (e.g., "1.0.0") */
+    version: string;
+    /** Short description of the addon */
+    description?: string;
+    /** Author name or organization */
+    author?: string;
+    /** Addon type/category for filtering */
+    type?: string;
+    /** Categories for discoverability */
+    categories?: string[];
+    /** License (e.g., "MIT", "Apache-2.0") */
+    license?: string;
+    /** Homepage or documentation URL */
+    homepage?: string;
+    /** Repository URL */
+    repository?: string;
+    /**
+     * User-configurable settings.
+     * Key is the setting ID, value is the definition.
+     */
+    settings?: Record<string, SettingDefinition>;
+    /**
+     * Addon capabilities and event subscriptions.
+     */
+    capabilities?: {
+        /** Supports settings changes without full reload */
+        hotReload?: boolean;
+        /** System events the addon wants to receive */
+        systemEvents?: SystemEventType[];
+    };
+    /**
+     * Permissions the addon will request.
+     * Declaring them here improves UX by showing upfront.
+     */
+    permissions?: {
+        /** Storage permission with quota in KB */
+        storage?: {
+            quota: number;
+        };
+        /** CPU usage limit */
+        cpu?: {
+            limit: 'low' | 'medium' | 'high';
+        };
+        /** Network access with allowed domains */
+        network?: {
+            domains: string[];
+        };
+        /** Audio playback permission */
+        audio?: boolean;
+        /** Notification permission */
+        notifications?: boolean;
+    };
+    /**
+     * Default layout for automatic positioning.
+     * Used when addon is first added to a wallpaper.
+     */
+    defaultLayout?: AddonDefaultLayout;
+    /**
+     * OAuth providers and scopes for authenticated addons.
+     *
+     * Declare the OAuth providers your addon needs and the scopes it requires.
+     * Scopes are requested incrementally - users can connect with basic scopes
+     * first, and your addon can request additional scopes when needed.
+     *
+     * @example
+     * ```json
+     * {
+     *   "permissions": {
+     *     "oauth": {
+     *       "required": [
+     *         { "provider": "github", "scopes": ["read:user"] }
+     *       ],
+     *       "optional": [
+     *         { "provider": "github", "scopes": ["repo"] }
+     *       ]
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    oauth?: {
+        /** OAuth providers required for the addon to function */
+        required?: Array<{
+            provider: OAuthProvider;
+            scopes: string[];
+            /** Reason shown to user when requesting this permission */
+            reason?: string;
+        }>;
+        /** OAuth providers that enhance functionality but aren't required */
+        optional?: Array<{
+            provider: OAuthProvider;
+            scopes: string[];
+            /** Reason shown to user when requesting this permission */
+            reason?: string;
+        }>;
+    };
+}
+/**
+ * Validation result type.
+ */
+interface ValidationResult {
+    success: boolean;
+    errors?: string[];
+    manifest?: AddonManifest;
+}
+/**
+ * Validates an addon manifest object.
+ *
+ * @param input - The manifest object to validate
+ * @returns ValidationResult with success status and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateManifest(myManifest)
+ * if (!result.success) {
+ *   result.errors?.forEach(err => console.error(err))
+ * }
+ * ```
+ */
+declare function validateManifest(input: unknown): ValidationResult;
+/**
+ * Type guard to check if an object is a valid AddonManifest.
+ *
+ * @param input - Object to check
+ * @returns True if input is a valid AddonManifest
+ */
+declare function isValidManifest(input: unknown): input is AddonManifest;
+/**
+ * Check if manifest declares hot-reload capability.
+ */
+declare function supportsHotReload(manifest: AddonManifest): boolean;
+/**
+ * Get system events the addon subscribes to.
+ */
+declare function getSubscribedEvents(manifest: AddonManifest): SystemEventType[];
+/**
+ * Get required permissions from manifest.
+ */
+declare function getRequiredPermissions(manifest: AddonManifest): PermissionType[];
+
+export { type AddonDefaultLayout, type AddonManifest, type SettingDefinition, type SettingType, type ValidationResult, getRequiredPermissions, getSubscribedEvents, isValidManifest, supportsHotReload, validateManifest };