craft-native 0.0.37

package/dist/api/windows-advanced.d.ts

@@ -0,0 +1,719 @@
+/**
+ * @fileoverview Windows Advanced Features API
+ * @description Advanced Windows-specific features including Jump Lists, Taskbar Progress,
+ * Toast Notifications, Windows Hello, Widgets, and Windows App SDK integration.
+ * @module @craft-native/api/windows-advanced
+ */
+/**
+ * Jump list task.
+ */
+export interface JumpListTask {
+    /** Task identifier */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Description */
+    description?: string;
+    /** Icon path or index */
+    icon?: string;
+    /** Icon index (for exe icons) */
+    iconIndex?: number;
+    /** Arguments to pass when launched */
+    arguments?: string;
+    /** Working directory */
+    workingDirectory?: string;
+}
+/**
+ * Jump list category.
+ */
+export interface JumpListCategory {
+    /** Category type */
+    type: 'tasks' | 'frequent' | 'recent' | 'custom';
+    /** Custom category title (for 'custom' type) */
+    title?: string;
+    /** Items in this category */
+    items: JumpListTask[];
+}
+/**
+ * Jump Lists API for Windows taskbar integration.
+ *
+ * @example
+ * // Set up jump list
+ * await jumpList.set([
+ *   {
+ *     type: 'tasks',
+ *     items: [
+ *       { id: 'new', title: 'New Window', icon: '%SystemRoot%\\system32\\shell32.dll', iconIndex: 1 },
+ *       { id: 'settings', title: 'Settings', arguments: '--settings' }
+ *     ]
+ *   },
+ *   {
+ *     type: 'custom',
+ *     title: 'Recent Projects',
+ *     items: recentProjects.map(p => ({ id: p.id, title: p.name, arguments: `--project ${p.id}` }))
+ *   }
+ * ])
+ *
+ * // Handle jump list item click
+ * jumpList.onItemClick((id, _args) => {
+ *   if (id === 'settings') openSettings()
+ * })
+ */
+export declare const jumpList: {
+    /**
+     * Check if Jump Lists are supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Set the jump list categories.
+     */
+    set(categories: JumpListCategory[]): Promise<void>;
+    /**
+     * Clear the jump list.
+     */
+    clear(): Promise<void>;
+    /**
+     * Add item to recent list.
+     */
+    addToRecent(filePath: string): Promise<void>;
+    /**
+     * Clear recent list.
+     */
+    clearRecent(): Promise<void>;
+    /**
+     * Add item to frequent list.
+     */
+    addToFrequent(filePath: string): Promise<void>;
+    /**
+     * Clear frequent list.
+     */
+    clearFrequent(): Promise<void>;
+    /**
+     * Handle jump list item click.
+     */
+    onItemClick(handler: (itemId: string, arguments_: string | null) => void): void;
+};
+/**
+ * Taskbar progress state.
+ */
+export type TaskbarProgressState = 'none' | 'indeterminate' | 'normal' | 'error' | 'paused';
+/**
+ * Taskbar Progress API for Windows taskbar.
+ *
+ * @example
+ * // Show download progress
+ * await taskbarProgress.setState('normal')
+ * await taskbarProgress.setProgress(0.5) // 50%
+ *
+ * // Show indeterminate progress
+ * await taskbarProgress.setState('indeterminate')
+ *
+ * // Show error state
+ * await taskbarProgress.setState('error')
+ *
+ * // Clear progress
+ * await taskbarProgress.setState('none')
+ */
+export declare const taskbarProgress: {
+    /**
+     * Set progress state.
+     */
+    setState(state: TaskbarProgressState): Promise<void>;
+    /**
+     * Set progress value (0-1).
+     */
+    setProgress(value: number): Promise<void>;
+    /**
+     * Clear progress.
+     */
+    clear(): Promise<void>;
+    /**
+     * Flash taskbar button.
+     */
+    flash(options?: {
+        count?: number;
+        interval?: number;
+        flags?: "all" | "caption" | "tray";
+    }): Promise<void>;
+    /**
+     * Stop flashing.
+     */
+    stopFlash(): Promise<void>;
+    /**
+     * Set overlay icon.
+     */
+    setOverlayIcon(iconPath: string | null, description?: string): Promise<void>;
+};
+/**
+ * Toast notification action.
+ */
+export interface ToastAction {
+    /** Action identifier */
+    id: string;
+    /** Button text */
+    content: string;
+    /** Action type */
+    type?: 'foreground' | 'background' | 'protocol';
+    /** Arguments to pass */
+    arguments?: string;
+    /** Image for button */
+    imageUri?: string;
+    /** Input ID to reference */
+    inputId?: string;
+}
+/**
+ * Toast notification input.
+ */
+export interface ToastInput {
+    /** Input identifier */
+    id: string;
+    /** Input type */
+    type: 'text' | 'selection';
+    /** Placeholder text (for text input) */
+    placeHolderContent?: string;
+    /** Default value */
+    defaultInput?: string;
+    /** Selection options (for selection input) */
+    selections?: Array<{
+        id: string;
+        content: string;
+    }>;
+}
+/**
+ * Toast notification content.
+ */
+export interface ToastContent {
+    /** Title text (first line) */
+    title: string;
+    /** Body text (second line) */
+    body?: string;
+    /** Additional body text (third line) */
+    body2?: string;
+    /** App logo override */
+    appLogoOverride?: {
+        uri: string;
+        hint?: 'circle' | 'none';
+    };
+    /** Hero image (full width) */
+    heroImage?: {
+        uri: string;
+    };
+    /** Inline image */
+    inlineImage?: {
+        uri: string;
+    };
+    /** Attribution text */
+    attribution?: string;
+    /** Audio */
+    audio?: {
+        src?: 'default' | 'im' | 'mail' | 'reminder' | 'sms' | 'alarm' | string;
+        loop?: boolean;
+        silent?: boolean;
+    };
+    /** Scenario type */
+    scenario?: 'default' | 'alarm' | 'reminder' | 'incomingCall' | 'urgent';
+    /** Expiration time */
+    expirationTime?: Date;
+    /** Actions */
+    actions?: ToastAction[];
+    /** Inputs */
+    inputs?: ToastInput[];
+    /** Progress bar */
+    progress?: {
+        value: number | 'indeterminate';
+        title?: string;
+        status?: string;
+        valueStringOverride?: string;
+    };
+}
+/**
+ * Toast Notifications API for Windows notifications.
+ *
+ * @example
+ * // Show simple notification
+ * await toastNotifications.show({
+ *   title: 'Download Complete',
+ *   body: 'Your file has been downloaded successfully.',
+ *   actions: [
+ *     { id: 'open', content: 'Open File' },
+ *     { id: 'folder', content: 'Open Folder' }
+ *   ]
+ * })
+ *
+ * // Show progress notification
+ * const tag = 'download-1'
+ * await toastNotifications.show({
+ *   title: 'Downloading...',
+ *   body: 'file.zip',
+ *   progress: { value: 0.5, status: '50% complete' }
+ * }, { tag })
+ *
+ * // Update progress
+ * await toastNotifications.update(tag, {
+ *   progress: { value: 1, status: 'Complete!' }
+ * })
+ *
+ * // Handle action
+ * toastNotifications.onActivated((args) => {
+ *   if (args.actionId === 'open') openFile()
+ * })
+ */
+export declare const toastNotifications: {
+    /**
+     * Check if toast notifications are supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Show a toast notification.
+     */
+    show(content: ToastContent, options?: {
+        tag?: string;
+        group?: string;
+        suppressPopup?: boolean;
+    }): Promise<void>;
+    /**
+     * Update an existing notification by tag.
+     */
+    update(tag: string, updates: Partial<ToastContent>): Promise<void>;
+    /**
+     * Hide a notification by tag.
+     */
+    hide(tag: string): Promise<void>;
+    /**
+     * Hide a notification group.
+     */
+    hideGroup(group: string): Promise<void>;
+    /**
+     * Clear all notifications.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get notification history.
+     */
+    getHistory(): Promise<Array<{
+        tag: string;
+        group: string;
+        deliveredTime: Date;
+    }>>;
+    /**
+     * Handle notification activation (click or action).
+     */
+    onActivated(handler: (args: {
+        tag?: string;
+        group?: string;
+        actionId?: string;
+        arguments?: string;
+        userInput?: Record<string, string>;
+    }) => void): void;
+    /**
+     * Handle notification dismissed.
+     */
+    onDismissed(handler: (args: {
+        tag?: string;
+        reason: "user" | "application" | "timeout";
+    }) => void): void;
+};
+/**
+ * Windows Hello availability.
+ */
+export interface WindowsHelloAvailability {
+    /** Whether Windows Hello is available */
+    isAvailable: boolean;
+    /** Available biometric types */
+    biometricTypes: Array<'face' | 'fingerprint' | 'iris'>;
+    /** Whether device supports companion devices */
+    supportsCompanionDevice: boolean;
+}
+/**
+ * Windows Hello API for biometric authentication.
+ *
+ * @example
+ * // Check availability
+ * const hello = await windowsHello.getAvailability()
+ * if (hello.isAvailable) {
+ *   // Authenticate
+ *   const result = await windowsHello.authenticate('Confirm your identity')
+ *   if (result.success) {
+ *     // User authenticated
+ *   }
+ * }
+ *
+ * // Create a credential
+ * const credential = await windowsHello.createCredential('user@example.com', 'Sign in to MyApp')
+ *
+ * // Verify credential
+ * const verified = await windowsHello.verifyCredential(credential.keyId, 'Sign in to MyApp')
+ */
+export declare const windowsHello: {
+    /**
+     * Check Windows Hello availability.
+     */
+    getAvailability(): Promise<WindowsHelloAvailability>;
+    /**
+     * Prompt for Windows Hello authentication.
+     */
+    authenticate(message: string): Promise<{
+        success: boolean;
+        error?: "canceled" | "notConfigured" | "notAllowed" | "unknown";
+    }>;
+    /**
+     * Create a Windows Hello credential.
+     */
+    createCredential(userId: string, message: string): Promise<{
+        success: boolean;
+        keyId?: string;
+        publicKey?: string;
+        attestation?: string;
+        error?: string;
+    }>;
+    /**
+     * Sign data with Windows Hello credential.
+     */
+    signWithCredential(keyId: string, challenge: string, message: string): Promise<{
+        success: boolean;
+        signature?: string;
+        error?: string;
+    }>;
+    /**
+     * Delete a Windows Hello credential.
+     */
+    deleteCredential(keyId: string): Promise<boolean>;
+    /**
+     * Check if a credential exists.
+     */
+    hasCredential(keyId: string): Promise<boolean>;
+};
+/**
+ * Widget template type.
+ */
+export type WidgetTemplateType = 'small' | 'medium' | 'large' | 'adaptive';
+/**
+ * Widget content.
+ */
+export interface WindowsWidgetContent {
+    /** Template JSON */
+    template: Record<string, any>;
+    /** Data to bind to template */
+    data: Record<string, any>;
+}
+/**
+ * Windows Widgets API (Windows 11).
+ *
+ * @example
+ * // Register widget provider
+ * windowsWidgets.register({
+ *   id: 'weather-widget',
+ *   name: 'Weather',
+ *   description: 'Shows current weather',
+ *   defaultTemplate: 'medium'
+ * })
+ *
+ * // Provide content
+ * windowsWidgets.onContentRequested('weather-widget', async (_context) => {
+ *   const weather = await fetchWeather()
+ *   return {
+ *     template: weatherTemplate,
+ *     data: { temp: weather.temp, condition: weather.condition }
+ *   }
+ * })
+ *
+ * // Handle customization
+ * windowsWidgets.onCustomize('weather-widget', async (settings) => {
+ *   // Save user settings
+ * })
+ */
+export declare const windowsWidgets: {
+    /**
+     * Check if Windows Widgets are supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Register a widget provider.
+     */
+    register(config: {
+        id: string;
+        name: string;
+        description: string;
+        defaultTemplate: WidgetTemplateType;
+        supportedTemplates?: WidgetTemplateType[];
+        hasCustomization?: boolean;
+    }): void;
+    /**
+     * Unregister a widget provider.
+     */
+    unregister(widgetId: string): void;
+    /**
+     * Handle content request.
+     */
+    onContentRequested(widgetId: string, handler: (context: {
+        templateType: WidgetTemplateType;
+        customData?: Record<string, any>;
+    }) => Promise<WindowsWidgetContent>): void;
+    /**
+     * Update widget content.
+     */
+    updateContent(widgetId: string, content: WindowsWidgetContent): Promise<void>;
+    /**
+     * Handle widget action.
+     */
+    onAction(widgetId: string, handler: (action: string, data?: Record<string, any>) => void): void;
+    /**
+     * Handle customization.
+     */
+    onCustomize(widgetId: string, handler: (settings: Record<string, any>) => Promise<void>): void;
+};
+/**
+ * Package version info.
+ */
+export interface PackageVersion {
+    /** Major version */
+    major: number;
+    /** Minor version */
+    minor: number;
+    /** Build version */
+    build: number;
+    /** Revision version */
+    revision: number;
+    /** Full version string */
+    full: string;
+}
+/**
+ * Update info.
+ */
+export interface UpdateInfo {
+    /** Whether update is available */
+    isAvailable: boolean;
+    /** Whether update is mandatory */
+    isMandatory: boolean;
+    /** New version */
+    version?: PackageVersion;
+    /** Update size in bytes */
+    updateSize?: number;
+}
+/**
+ * MSIX/Auto-Update API for Windows Store apps.
+ *
+ * @example
+ * // Check for updates
+ * const update = await msixUpdate.checkForUpdates()
+ * if (update.isAvailable) {
+ *   // Download and install
+ *   await msixUpdate.downloadAndInstall({
+ *     showProgress: true,
+ *     restartOnComplete: true
+ *   })
+ * }
+ */
+export declare const msixUpdate: {
+    /**
+     * Get current package version.
+     */
+    getCurrentVersion(): Promise<PackageVersion | null>;
+    /**
+     * Check for updates.
+     */
+    checkForUpdates(): Promise<UpdateInfo>;
+    /**
+     * Download and install update.
+     */
+    downloadAndInstall(options?: {
+        showProgress?: boolean;
+        restartOnComplete?: boolean;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get download progress.
+     */
+    onDownloadProgress(handler: (progress: {
+        bytesDownloaded: number;
+        totalBytes: number;
+        percentage: number;
+    }) => void): void;
+    /**
+     * Check if running as MSIX package.
+     */
+    isPackaged(): Promise<boolean>;
+    /**
+     * Get package install location.
+     */
+    getInstallLocation(): Promise<string | null>;
+};
+/**
+ * Shared data item.
+ */
+export interface SharedDataItem {
+    /** Data type */
+    type: 'text' | 'uri' | 'html' | 'bitmap' | 'file';
+    /** Text content */
+    text?: string;
+    /** URI */
+    uri?: string;
+    /** HTML content */
+    html?: string;
+    /** File path */
+    filePath?: string;
+    /** File name */
+    fileName?: string;
+    /** Content type */
+    contentType?: string;
+}
+/**
+ * Share Target API for Windows share integration.
+ *
+ * @example
+ * // Handle incoming share
+ * shareTarget.onShare(async (items, operation) => {
+ *   for (const item of items) {
+ *     if (item.type === 'uri') {
+ *       await saveBookmark(item.uri)
+ *     }
+else if (item.type === 'file') {
+ *       await importFile(item.filePath)
+ *     }
+ *   }
+ *   operation.complete()
+ * })
+ */
+export declare const shareTarget: {
+    /**
+     * Handle incoming share.
+     */
+    onShare(handler: (items: SharedDataItem[], operation: {
+        complete: () => void;
+        fail: (error: string) => void;
+    }) => Promise<void>): void;
+    /**
+     * Check if app was launched as share target.
+     */
+    wasLaunchedAsShareTarget(): Promise<boolean>;
+    /**
+     * Get shared data if launched as share target.
+     */
+    getSharedData(): Promise<SharedDataItem[]>;
+};
+/**
+ * Startup Task API for Windows launch at startup.
+ *
+ * @example
+ * // Check if startup is enabled
+ * const state = await startupTask.getState()
+ *
+ * // Request startup
+ * await startupTask.request()
+ *
+ * // Disable startup
+ * await startupTask.disable()
+ */
+export declare const startupTask: {
+    /**
+     * Get current startup state.
+     */
+    getState(): Promise<"disabled" | "disabledByUser" | "enabled" | "disabledByPolicy" | "enabledByPolicy">;
+    /**
+     * Request enabling startup.
+     */
+    request(): Promise<"disabled" | "disabledByUser" | "enabled" | "disabledByPolicy" | "enabledByPolicy">;
+    /**
+     * Disable startup.
+     */
+    disable(): Promise<void>;
+};
+/**
+ * Secondary tile configuration.
+ */
+export interface SecondaryTile {
+    /** Tile ID */
+    tileId: string;
+    /** Display name */
+    displayName: string;
+    /** Arguments when launched */
+    arguments: string;
+    /** Square 150x150 logo */
+    square150x150Logo: string;
+    /** Wide 310x150 logo */
+    wide310x150Logo?: string;
+    /** Square 310x310 logo */
+    square310x310Logo?: string;
+    /** Background color */
+    backgroundColor?: string;
+    /** Show name on tile */
+    showNameOnSquare150x150Logo?: boolean;
+    /** Show name on wide tile */
+    showNameOnWide310x150Logo?: boolean;
+}
+/**
+ * Secondary Tiles API for Windows Start menu tiles.
+ *
+ * @example
+ * // Pin a tile
+ * await secondaryTiles.pin({
+ *   tileId: 'project-123',
+ *   displayName: 'My Project',
+ *   arguments: '--project 123',
+ *   square150x150Logo: 'ms-appx:///Assets/ProjectTile.png'
+ * })
+ *
+ * // Check if pinned
+ * const isPinned = await secondaryTiles.exists('project-123')
+ *
+ * // Update tile
+ * await secondaryTiles.updateBadge('project-123', 5)
+ */
+export declare const secondaryTiles: {
+    /**
+     * Check if secondary tiles are supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Pin a secondary tile.
+     */
+    pin(tile: SecondaryTile): Promise<boolean>;
+    /**
+     * Unpin a secondary tile.
+     */
+    unpin(tileId: string): Promise<boolean>;
+    /**
+     * Check if a tile exists.
+     */
+    exists(tileId: string): Promise<boolean>;
+    /**
+     * Get all pinned tiles.
+     */
+    getAll(): Promise<string[]>;
+    /**
+     * Update tile content.
+     */
+    updateTile(tileId: string, content: {
+        text1?: string;
+        text2?: string;
+        text3?: string;
+        image?: string;
+    }): Promise<void>;
+    /**
+     * Update tile badge.
+     */
+    updateBadge(tileId: string, value: number | "none" | "activity" | "alert" | "attention" | "available" | "away" | "busy" | "newMessage" | "paused" | "playing" | "unavailable" | "error"): Promise<void>;
+    /**
+     * Clear tile notification.
+     */
+    clearTile(tileId: string): Promise<void>;
+    /**
+     * Handle tile launch.
+     */
+    onLaunch(handler: (tileId: string, arguments_: string) => void): void;
+};
+declare const windowsAdvanced: {
+    jumpList: typeof jumpList;
+    taskbarProgress: typeof taskbarProgress;
+    toastNotifications: typeof toastNotifications;
+    windowsHello: typeof windowsHello;
+    windowsWidgets: typeof windowsWidgets;
+    msixUpdate: typeof msixUpdate;
+    shareTarget: typeof shareTarget;
+    startupTask: typeof startupTask;
+    secondaryTiles: typeof secondaryTiles;
+};
+export default windowsAdvanced;
+//# sourceMappingURL=windows-advanced.d.ts.map