craft-native 0.0.37

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

@@ -0,0 +1,737 @@
+/**
+ * @fileoverview Android Advanced Features API
+ * @description Advanced Android-specific features including Jetpack Compose integration,
+ * Material You dynamic colors, Photo Picker, Work Manager, Foreground Services, and more.
+ * @module @craft-native/api/android-advanced
+ */
+/**
+ * Material You color scheme.
+ */
+export interface MaterialYouColors {
+    /** Primary color */
+    primary: string;
+    /** On primary color */
+    onPrimary: string;
+    /** Primary container */
+    primaryContainer: string;
+    /** On primary container */
+    onPrimaryContainer: string;
+    /** Secondary color */
+    secondary: string;
+    /** On secondary */
+    onSecondary: string;
+    /** Secondary container */
+    secondaryContainer: string;
+    /** On secondary container */
+    onSecondaryContainer: string;
+    /** Tertiary color */
+    tertiary: string;
+    /** On tertiary */
+    onTertiary: string;
+    /** Tertiary container */
+    tertiaryContainer: string;
+    /** On tertiary container */
+    onTertiaryContainer: string;
+    /** Error color */
+    error: string;
+    /** On error */
+    onError: string;
+    /** Error container */
+    errorContainer: string;
+    /** On error container */
+    onErrorContainer: string;
+    /** Background */
+    background: string;
+    /** On background */
+    onBackground: string;
+    /** Surface */
+    surface: string;
+    /** On surface */
+    onSurface: string;
+    /** Surface variant */
+    surfaceVariant: string;
+    /** On surface variant */
+    onSurfaceVariant: string;
+    /** Outline */
+    outline: string;
+    /** Outline variant */
+    outlineVariant: string;
+}
+/**
+ * Material You API for dynamic theming.
+ *
+ * @example
+ * // Get current dynamic colors
+ * const colors = await materialYou.getColors()
+ * document.body.style.backgroundColor = colors.background
+ *
+ * // Listen for wallpaper changes
+ * materialYou.onColorsChange((colors) => {
+ *   applyTheme(colors)
+ * })
+ */
+export declare const materialYou: {
+    /**
+     * Check if Material You is supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Get current dynamic colors.
+     */
+    getColors(darkMode?: boolean): Promise<MaterialYouColors | null>;
+    /**
+     * Get colors from a specific source.
+     */
+    getColorsFromSource(source: "wallpaper" | "content"): Promise<MaterialYouColors | null>;
+    /**
+     * Listen for color changes.
+     */
+    onColorsChange(handler: (colors: MaterialYouColors) => void): void;
+    /**
+     * Apply dynamic colors to system bars.
+     */
+    applyToSystemBars(colors?: {
+        statusBarColor?: string;
+        navigationBarColor?: string;
+        lightStatusBar?: boolean;
+        lightNavigationBar?: boolean;
+    }): Promise<void>;
+    /**
+     * Generate color scheme from seed color.
+     */
+    generateScheme(seedColor: string, darkMode?: boolean): Promise<MaterialYouColors | null>;
+};
+/**
+ * Photo picker media type.
+ */
+export type PhotoPickerMediaType = 'images' | 'videos' | 'all';
+/**
+ * Selected media item.
+ */
+export interface PhotoPickerResult {
+    /** Content URI */
+    uri: string;
+    /** MIME type */
+    mimeType: string;
+    /** File name */
+    name: string;
+    /** File size in bytes */
+    size: number;
+    /** Width (for images/videos) */
+    width?: number;
+    /** Height (for images/videos) */
+    height?: number;
+    /** Duration in ms (for videos) */
+    duration?: number;
+    /** Date taken */
+    dateTaken?: Date;
+}
+/**
+ * Photo Picker API for Android 13+ privacy-preserving media selection.
+ *
+ * @example
+ * // Pick a single image
+ * const photo = await photoPicker.pickImage()
+ *
+ * // Pick multiple images (up to 10)
+ * const photos = await photoPicker.pickImages(10)
+ *
+ * // Pick a video
+ * const video = await photoPicker.pickVideo()
+ */
+export declare const photoPicker: {
+    /**
+     * Check if Photo Picker is available (Android 13+).
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Pick a single image.
+     */
+    pickImage(): Promise<PhotoPickerResult | null>;
+    /**
+     * Pick multiple images.
+     */
+    pickImages(maxCount?: number): Promise<PhotoPickerResult[]>;
+    /**
+     * Pick a single video.
+     */
+    pickVideo(): Promise<PhotoPickerResult | null>;
+    /**
+     * Pick multiple videos.
+     */
+    pickVideos(maxCount?: number): Promise<PhotoPickerResult[]>;
+    /**
+     * Pick mixed media (images and videos).
+     */
+    pickMedia(options?: {
+        maxCount?: number;
+        mediaType?: PhotoPickerMediaType;
+    }): Promise<PhotoPickerResult[]>;
+    /**
+     * Get a persistent URI for the selected media.
+     * Takes a content URI and returns a file path that can be used after app restart.
+     */
+    getPersistedUri(uri: string): Promise<string | null>;
+};
+/**
+ * Work request constraints.
+ */
+export interface WorkConstraints {
+    /** Require network connectivity */
+    requiresNetwork?: 'connected' | 'unmetered' | 'not_roaming' | 'metered';
+    /** Require charging */
+    requiresCharging?: boolean;
+    /** Require device idle */
+    requiresDeviceIdle?: boolean;
+    /** Require battery not low */
+    requiresBatteryNotLow?: boolean;
+    /** Require storage not low */
+    requiresStorageNotLow?: boolean;
+}
+/**
+ * Work request configuration.
+ */
+export interface WorkRequest {
+    /** Unique work name */
+    name: string;
+    /** Work type */
+    type: 'oneTime' | 'periodic';
+    /** Input data */
+    inputData?: Record<string, string | number | boolean>;
+    /** Constraints */
+    constraints?: WorkConstraints;
+    /** Initial delay in milliseconds */
+    initialDelay?: number;
+    /** Repeat interval in milliseconds (for periodic work) */
+    repeatInterval?: number;
+    /** Flex interval in milliseconds (for periodic work) */
+    flexInterval?: number;
+    /** Backoff policy */
+    backoffPolicy?: {
+        policy: 'linear' | 'exponential';
+        delayMs: number;
+    };
+    /** Tags for grouping */
+    tags?: string[];
+    /** Expedited work (Android 12+) */
+    expedited?: boolean;
+}
+/**
+ * Work info.
+ */
+export interface WorkInfo {
+    /** Work ID */
+    id: string;
+    /** Work name */
+    name: string;
+    /** Current state */
+    state: 'enqueued' | 'running' | 'succeeded' | 'failed' | 'blocked' | 'cancelled';
+    /** Output data */
+    outputData?: Record<string, any>;
+    /** Run attempt count */
+    runAttemptCount: number;
+    /** Tags */
+    tags: string[];
+    /** Progress (0-100) */
+    progress?: number;
+}
+/**
+ * Work Manager API for background task scheduling.
+ *
+ * @example
+ * // Schedule a one-time sync task
+ * await workManager.enqueue({
+ *   name: 'sync-data',
+ *   type: 'oneTime',
+ *   constraints: {
+ *     requiresNetwork: 'connected'
+ *   },
+ *   inputData: { userId: '123' }
+ * })
+ *
+ * // Schedule periodic cleanup
+ * await workManager.enqueue({
+ *   name: 'cleanup',
+ *   type: 'periodic',
+ *   repeatInterval: 24 * 60 * 60 * 1000, // Daily
+ *   constraints: {
+ *     requiresCharging: true,
+ *     requiresDeviceIdle: true
+ *   }
+ * })
+ *
+ * // Monitor work progress
+ * workManager.observeWork('sync-data', (info) => {
+ *   console.log('State:', info.state, 'Progress:', info.progress)
+ * })
+ */
+export declare const workManager: {
+    /**
+     * Enqueue a work request.
+     */
+    enqueue(request: WorkRequest): Promise<string>;
+    /**
+     * Enqueue unique work (replaces existing work with same name).
+     */
+    enqueueUnique(request: WorkRequest, existingWorkPolicy: "replace" | "keep" | "append" | "update"): Promise<string>;
+    /**
+     * Cancel work by name.
+     */
+    cancelByName(name: string): Promise<void>;
+    /**
+     * Cancel work by ID.
+     */
+    cancelById(id: string): Promise<void>;
+    /**
+     * Cancel work by tag.
+     */
+    cancelByTag(tag: string): Promise<void>;
+    /**
+     * Cancel all work.
+     */
+    cancelAll(): Promise<void>;
+    /**
+     * Get work info by name.
+     */
+    getWorkInfo(name: string): Promise<WorkInfo | null>;
+    /**
+     * Get work info by ID.
+     */
+    getWorkInfoById(id: string): Promise<WorkInfo | null>;
+    /**
+     * Get work info by tag.
+     */
+    getWorkInfoByTag(tag: string): Promise<WorkInfo[]>;
+    /**
+     * Observe work by name.
+     */
+    observeWork(name: string, handler: (info: WorkInfo) => void): () => void;
+    /**
+     * Prune finished work from database.
+     */
+    pruneWork(): Promise<void>;
+    /**
+     * Register work handler (called when work executes).
+     */
+    onWork(name: string, handler: (inputData: Record<string, any>, setProgress: (progress: number) => void) => Promise<{
+        success: boolean;
+        outputData?: Record<string, any>;
+    }>): void;
+};
+/**
+ * Foreground service type.
+ */
+export type ForegroundServiceType = 'camera' | 'connectedDevice' | 'dataSync' | 'health' | 'location' | 'mediaPlayback' | 'mediaProjection' | 'microphone' | 'phoneCall' | 'remoteMessaging' | 'shortService' | 'specialUse' | 'systemExempted';
+/**
+ * Notification configuration for foreground service.
+ */
+export interface ForegroundNotification {
+    /** Notification channel ID */
+    channelId: string;
+    /** Notification ID */
+    notificationId: number;
+    /** Title */
+    title: string;
+    /** Content text */
+    content: string;
+    /** Small icon resource name */
+    smallIcon: string;
+    /** Large icon URL */
+    largeIcon?: string;
+    /** Ongoing (can't be dismissed) */
+    ongoing?: boolean;
+    /** Actions */
+    actions?: Array<{
+        id: string;
+        title: string;
+        icon?: string;
+    }>;
+    /** Progress (for determinate progress) */
+    progress?: {
+        max: number;
+        current: number;
+        indeterminate?: boolean;
+    };
+}
+/**
+ * Foreground Services API for long-running operations.
+ *
+ * @example
+ * // Start a media playback service
+ * await foregroundService.start({
+ *   type: 'mediaPlayback',
+ *   notification: {
+ *     channelId: 'playback',
+ *     notificationId: 1,
+ *     title: 'Now Playing',
+ *     content: 'Song Name - Artist',
+ *     smallIcon: 'ic_music_note',
+ *     actions: [
+ *       { id: 'pause', title: 'Pause', icon: 'ic_pause' },
+ *       { id: 'next', title: 'Next', icon: 'ic_skip_next' }
+ *     ]
+ *   }
+ * })
+ *
+ * // Handle notification actions
+ * foregroundService.onAction((actionId) => {
+ *   if (actionId === 'pause') pausePlayback()
+ * })
+ *
+ * // Stop the service
+ * await foregroundService.stop()
+ */
+export declare const foregroundService: {
+    /**
+     * Start a foreground service.
+     */
+    start(config: {
+        type: ForegroundServiceType;
+        notification: ForegroundNotification;
+    }): Promise<void>;
+    /**
+     * Stop the foreground service.
+     */
+    stop(): Promise<void>;
+    /**
+     * Update notification.
+     */
+    updateNotification(notification: Partial<ForegroundNotification>): Promise<void>;
+    /**
+     * Check if service is running.
+     */
+    isRunning(): Promise<boolean>;
+    /**
+     * Register notification action handler.
+     */
+    onAction(handler: (actionId: string) => void): void;
+};
+/**
+ * Back event info.
+ */
+export interface BackEvent {
+    /** Touch X position */
+    touchX: number;
+    /** Touch Y position */
+    touchY: number;
+    /** Progress of the back gesture (0-1) */
+    progress: number;
+    /** Swipe edge: 0 = left, 1 = right */
+    swipeEdge: 0 | 1;
+}
+/**
+ * Predictive Back API for Android 13+ back gesture handling.
+ *
+ * @example
+ * // Enable predictive back
+ * predictiveBack.enable()
+ *
+ * // Handle back progress for animations
+ * predictiveBack.onProgress((event) => {
+ *   // Animate UI based on progress
+ *   element.style.transform = `translateX(${event.progress * -100}px)`
+ * })
+ *
+ * // Handle back committed
+ * predictiveBack.onCommit(() => {
+ *   navigateBack()
+ * })
+ */
+export declare const predictiveBack: {
+    /**
+     * Check if predictive back is supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Enable predictive back handling.
+     */
+    enable(): void;
+    /**
+     * Disable predictive back handling.
+     */
+    disable(): void;
+    /**
+     * Register back started handler.
+     */
+    onStart(handler: (event: BackEvent) => void): void;
+    /**
+     * Register back progress handler.
+     */
+    onProgress(handler: (event: BackEvent) => void): void;
+    /**
+     * Register back committed handler.
+     */
+    onCommit(handler: () => void): void;
+    /**
+     * Register back cancelled handler.
+     */
+    onCancel(handler: () => void): void;
+};
+/**
+ * Language Preferences API for per-app language settings (Android 13+).
+ *
+ * @example
+ * // Get available languages
+ * const languages = await appLanguage.getAvailableLanguages()
+ *
+ * // Set app language
+ * await appLanguage.setLanguage('es')
+ *
+ * // Get current language
+ * const current = await appLanguage.getCurrentLanguage()
+ */
+export declare const appLanguage: {
+    /**
+     * Check if per-app language is supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Get available languages defined in app.
+     */
+    getAvailableLanguages(): Promise<string[]>;
+    /**
+     * Get current app language.
+     */
+    getCurrentLanguage(): Promise<string | null>;
+    /**
+     * Set app language.
+     */
+    setLanguage(languageTag: string): Promise<void>;
+    /**
+     * Reset to system language.
+     */
+    resetToSystem(): Promise<void>;
+    /**
+     * Open system language settings for this app.
+     */
+    openSettings(): Promise<void>;
+};
+/**
+ * Widget size class.
+ */
+export type WidgetSizeClass = 'small' | 'medium' | 'large' | 'extraLarge';
+/**
+ * Widget configuration.
+ */
+export interface WidgetConfig {
+    /** Widget class name */
+    widgetClass: string;
+    /** Minimum width in dp */
+    minWidth: number;
+    /** Minimum height in dp */
+    minHeight: number;
+    /** Target cell width */
+    targetCellWidth?: number;
+    /** Target cell height */
+    targetCellHeight?: number;
+    /** Maximum resize width */
+    maxResizeWidth?: number;
+    /** Maximum resize height */
+    maxResizeHeight?: number;
+    /** Update period in milliseconds (minimum 30 minutes) */
+    updatePeriodMs?: number;
+    /** Whether widget is resizable */
+    resizable?: boolean;
+    /** Widget category */
+    category?: 'homeScreen' | 'keyguard' | 'searchBox';
+}
+/**
+ * Widget data.
+ */
+export interface WidgetData {
+    /** Widget ID */
+    widgetId: number;
+    /** Widget data */
+    data: Record<string, any>;
+}
+/**
+ * App Widgets API for home screen widgets.
+ *
+ * @example
+ * // Update widget content
+ * await widgets.updateWidget(widgetId, {
+ *   title: 'Weather',
+ *   temperature: '72°F',
+ *   icon: 'sunny'
+ * })
+ *
+ * // Request widget pin
+ * await widgets.requestPin('WeatherWidget')
+ *
+ * // Handle widget interactions
+ * widgets.onInteraction((_widgetId, action) => {
+ *   if (action === 'refresh') {
+ *     refreshWeatherData()
+ *   }
+ * })
+ */
+export declare const widgets: {
+    /**
+     * Get all active widget IDs for a widget class.
+     */
+    getActiveWidgets(widgetClass: string): Promise<number[]>;
+    /**
+     * Update a widget.
+     */
+    updateWidget(widgetId: number, data: Record<string, any>): Promise<void>;
+    /**
+     * Update all widgets of a class.
+     */
+    updateAllWidgets(widgetClass: string, data: Record<string, any>): Promise<void>;
+    /**
+     * Request to pin a widget to home screen.
+     */
+    requestPin(widgetClass: string): Promise<boolean>;
+    /**
+     * Check if app widgets are supported.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Register widget update handler.
+     */
+    onUpdate(widgetClass: string, handler: (widgetIds: number[]) => void): void;
+    /**
+     * Register widget interaction handler.
+     */
+    onInteraction(handler: (widgetId: number, action: string, extras?: Record<string, any>) => void): void;
+    /**
+     * Register widget resize handler.
+     */
+    onResize(handler: (widgetId: number, width: number, height: number) => void): void;
+    /**
+     * Register widget delete handler.
+     */
+    onDelete(handler: (widgetId: number) => void): void;
+};
+/**
+ * Product details from Google Play.
+ */
+export interface PlayProduct {
+    /** Product ID */
+    productId: string;
+    /** Product type */
+    productType: 'inapp' | 'subs';
+    /** Title */
+    title: string;
+    /** Name */
+    name: string;
+    /** Description */
+    description: string;
+    /** One-time purchase offer (for inapp) */
+    oneTimePurchaseOfferDetails?: {
+        formattedPrice: string;
+        priceAmountMicros: number;
+        priceCurrencyCode: string;
+    };
+    /** Subscription offer details (for subs) */
+    subscriptionOfferDetails?: Array<{
+        offerId: string;
+        basePlanId: string;
+        offerTags: string[];
+        pricingPhases: Array<{
+            formattedPrice: string;
+            priceAmountMicros: number;
+            priceCurrencyCode: string;
+            billingPeriod: string;
+            billingCycleCount: number;
+            recurrenceMode: 'infinite' | 'finite' | 'nonRecurring';
+        }>;
+    }>;
+}
+/**
+ * Purchase result.
+ */
+export interface PlayPurchase {
+    /** Order ID */
+    orderId: string;
+    /** Package name */
+    packageName: string;
+    /** Product IDs */
+    products: string[];
+    /** Purchase time */
+    purchaseTime: number;
+    /** Purchase state */
+    purchaseState: 'purchased' | 'pending' | 'unspecified';
+    /** Purchase token */
+    purchaseToken: string;
+    /** Whether acknowledged */
+    isAcknowledged: boolean;
+    /** Whether auto-renewing */
+    isAutoRenewing: boolean;
+}
+/**
+ * Google Play Billing API.
+ *
+ * @example
+ * // Query products
+ * const products = await playBilling.getProducts(['premium', 'coins_100'], 'inapp')
+ *
+ * // Launch purchase flow
+ * const result = await playBilling.purchase('premium')
+ *
+ * // Check purchases
+ * const purchases = await playBilling.getPurchases('inapp')
+ */
+export declare const playBilling: {
+    /**
+     * Connect to billing service.
+     */
+    connect(): Promise<boolean>;
+    /**
+     * Disconnect from billing service.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Query product details.
+     */
+    getProducts(productIds: string[], productType: "inapp" | "subs"): Promise<PlayProduct[]>;
+    /**
+     * Launch purchase flow.
+     */
+    purchase(productId: string, options?: {
+        offerToken?: string;
+        isOfferPersonalized?: boolean;
+        oldPurchaseToken?: string;
+        replacementMode?: "charge_prorated_price" | "charge_full_price" | "without_proration" | "deferred";
+    }): Promise<{
+        success: boolean;
+        purchase?: PlayPurchase;
+        error?: string;
+    }>;
+    /**
+     * Get purchases.
+     */
+    getPurchases(productType: "inapp" | "subs"): Promise<PlayPurchase[]>;
+    /**
+     * Acknowledge a purchase.
+     */
+    acknowledgePurchase(purchaseToken: string): Promise<boolean>;
+    /**
+     * Consume a purchase (for consumables).
+     */
+    consumePurchase(purchaseToken: string): Promise<boolean>;
+    /**
+     * Check subscription status.
+     */
+    isSubscribed(productId: string): Promise<boolean>;
+    /**
+     * Listen for purchases updates.
+     */
+    onPurchasesUpdated(handler: (purchases: PlayPurchase[]) => void): void;
+    /**
+     * Show subscription management.
+     */
+    showSubscriptionManagement(productId?: string): Promise<void>;
+};
+declare const androidAdvanced: {
+    materialYou: typeof materialYou;
+    photoPicker: typeof photoPicker;
+    workManager: typeof workManager;
+    foregroundService: typeof foregroundService;
+    predictiveBack: typeof predictiveBack;
+    appLanguage: typeof appLanguage;
+    widgets: typeof widgets;
+    playBilling: typeof playBilling;
+};
+export default androidAdvanced;
+//# sourceMappingURL=android-advanced.d.ts.map