craft-native 0.0.37

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

@@ -0,0 +1,833 @@
+/**
+ * @fileoverview iOS Advanced Features API
+ * @description Advanced iOS-specific features including CarPlay, App Clips, Live Activities,
+ * SharePlay, StoreKit 2, App Intents, TipKit, and Focus Filters.
+ * @module @craft-native/api/ios-advanced
+ */
+/**
+ * CarPlay template types.
+ */
+export type CarPlayTemplateType = 'list' | 'grid' | 'information' | 'point-of-interest' | 'tab-bar' | 'alert' | 'action-sheet' | 'now-playing' | 'voice-control' | 'search' | 'map';
+/**
+ * CarPlay list item.
+ */
+export interface CarPlayListItem {
+    /** Unique identifier */
+    id: string;
+    /** Display text */
+    text: string;
+    /** Detail text */
+    detailText?: string;
+    /** Image name or URL */
+    image?: string;
+    /** Whether item shows disclosure indicator */
+    showsDisclosureIndicator?: boolean;
+    /** Whether item is playing */
+    isPlaying?: boolean;
+    /** Playback progress (0-1) */
+    playbackProgress?: number;
+}
+/**
+ * CarPlay grid item.
+ */
+export interface CarPlayGridItem {
+    /** Unique identifier */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Image name or URL */
+    image: string;
+}
+/**
+ * CarPlay template configuration.
+ */
+export interface CarPlayTemplate {
+    /** Template type */
+    type: CarPlayTemplateType;
+    /** Template title */
+    title?: string;
+    /** List items (for list template) */
+    listItems?: CarPlayListItem[];
+    /** Grid items (for grid template) */
+    gridItems?: CarPlayGridItem[];
+    /** Sections for grouped lists */
+    sections?: Array<{
+        header?: string;
+        items: CarPlayListItem[];
+    }>;
+    /** Tab bar items */
+    tabs?: Array<{
+        title: string;
+        image: string;
+        template: CarPlayTemplate;
+    }>;
+}
+/**
+ * CarPlay API for automotive integration.
+ *
+ * @example
+ * // Set up CarPlay scene
+ * carplay.onConnect((_window) => {
+ *   carplay.pushTemplate({
+ *     type: 'list',
+ *     title: 'My Music',
+ *     listItems: [
+ *       { id: '1', text: 'Favorites', showsDisclosureIndicator: true },
+ *       { id: '2', text: 'Recently Played', showsDisclosureIndicator: true }
+ *     ]
+ *   })
+ * })
+ *
+ * carplay.onSelectListItem((item, _template) => {
+ *   console.log('Selected:', item.text)
+ * })
+ */
+export declare const carplay: {
+    /**
+     * Check if CarPlay is available.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Check if CarPlay is currently connected.
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Register CarPlay connection handler.
+     */
+    onConnect(handler: (window: any) => void): void;
+    /**
+     * Register CarPlay disconnection handler.
+     */
+    onDisconnect(handler: () => void): void;
+    /**
+     * Push a template to the CarPlay screen.
+     */
+    pushTemplate(template: CarPlayTemplate, animated?: boolean): Promise<void>;
+    /**
+     * Pop the current template.
+     */
+    popTemplate(animated?: boolean): Promise<void>;
+    /**
+     * Pop to root template.
+     */
+    popToRootTemplate(animated?: boolean): Promise<void>;
+    /**
+     * Present a template modally.
+     */
+    presentTemplate(template: CarPlayTemplate, animated?: boolean): Promise<void>;
+    /**
+     * Dismiss presented template.
+     */
+    dismissTemplate(animated?: boolean): Promise<void>;
+    /**
+     * Register list item selection handler.
+     */
+    onSelectListItem(handler: (item: CarPlayListItem, template: CarPlayTemplate) => void): void;
+    /**
+     * Register grid item selection handler.
+     */
+    onSelectGridItem(handler: (item: CarPlayGridItem, template: CarPlayTemplate) => void): void;
+    /**
+     * Update now playing information.
+     */
+    updateNowPlaying(info: {
+        title: string;
+        artist?: string;
+        album?: string;
+        artwork?: string;
+        duration?: number;
+        elapsedTime?: number;
+        playbackRate?: number;
+        isPlaying?: boolean;
+    }): Promise<void>;
+};
+/**
+ * App Clip invocation context.
+ */
+export interface AppClipInvocation {
+    /** Invocation URL */
+    url: string;
+    /** URL parameters */
+    parameters: Record<string, string>;
+    /** Physical location (if available) */
+    location?: {
+        latitude: number;
+        longitude: number;
+    };
+    /** Invocation source */
+    source: 'qr-code' | 'nfc' | 'safari' | 'messages' | 'maps' | 'smart-banner';
+}
+/**
+ * App Clips API for lightweight app experiences.
+ *
+ * @example
+ * // Handle App Clip launch
+ * appClips.onInvoke((invocation) => {
+ *   console.log('Launched from:', invocation.source)
+ *   console.log('URL:', invocation.url)
+ * })
+ *
+ * // Prompt to install full app
+ * await appClips.promptToInstallFullApp()
+ */
+export declare const appClips: {
+    /**
+     * Check if running as App Clip.
+     */
+    isAppClip(): boolean;
+    /**
+     * Register App Clip invocation handler.
+     */
+    onInvoke(handler: (invocation: AppClipInvocation) => void): void;
+    /**
+     * Get the invocation context.
+     */
+    getInvocation(): Promise<AppClipInvocation | null>;
+    /**
+     * Prompt user to install the full app.
+     */
+    promptToInstallFullApp(): Promise<void>;
+    /**
+     * Request ephemeral notification permission.
+     */
+    requestEphemeralNotificationPermission(): Promise<boolean>;
+    /**
+     * Request location confirmation.
+     * Used to verify user is at a specific location for App Clip experiences.
+     */
+    confirmLocation(regionIdentifier: string): Promise<boolean>;
+};
+/**
+ * Live Activity content state.
+ */
+export interface LiveActivityContentState {
+    [key: string]: string | number | boolean;
+}
+/**
+ * Live Activity attributes (static content).
+ */
+export interface LiveActivityAttributes {
+    [key: string]: string | number | boolean;
+}
+/**
+ * Live Activity configuration.
+ */
+export interface LiveActivityConfig {
+    /** Activity type identifier */
+    activityType: string;
+    /** Static attributes */
+    attributes: LiveActivityAttributes;
+    /** Initial content state */
+    contentState: LiveActivityContentState;
+    /** Stale date (when content becomes outdated) */
+    staleDate?: Date;
+    /** Relevance score (0-100) */
+    relevanceScore?: number;
+}
+/**
+ * Live Activities API for Dynamic Island and Lock Screen.
+ *
+ * @example
+ * // Start a delivery tracking activity
+ * const activity = await liveActivities.start({
+ *   activityType: 'DeliveryActivity',
+ *   attributes: { orderNumber: '12345', restaurant: 'Pizza Place' },
+ *   contentState: { status: 'preparing', eta: '15 min' }
+ * })
+ *
+ * // Update the activity
+ * await liveActivities.update(activity.id, {
+ *   status: 'on-the-way',
+ *   eta: '5 min',
+ *   driverName: 'John'
+ * })
+ *
+ * // End the activity
+ * await liveActivities.end(activity.id, { status: 'delivered' })
+ */
+export declare const liveActivities: {
+    /**
+     * Check if Live Activities are supported.
+     */
+    areSupported(): Promise<boolean>;
+    /**
+     * Check if Live Activities are enabled by user.
+     */
+    areEnabled(): Promise<boolean>;
+    /**
+     * Start a new Live Activity.
+     */
+    start(config: LiveActivityConfig): Promise<{
+        id: string;
+    }>;
+    /**
+     * Update an existing Live Activity.
+     */
+    update(activityId: string, contentState: LiveActivityContentState, alertConfig?: {
+        title: string;
+        body: string;
+        sound?: string;
+    }): Promise<void>;
+    /**
+     * End a Live Activity.
+     */
+    end(activityId: string, finalContentState?: LiveActivityContentState, dismissalPolicy?: "immediate" | "default" | "after"): Promise<void>;
+    /**
+     * Get all active Live Activities.
+     */
+    getAll(): Promise<Array<{
+        id: string;
+        activityType: string;
+        contentState: LiveActivityContentState;
+    }>>;
+    /**
+     * Request push token for remote Live Activity updates.
+     */
+    requestPushToken(activityId: string): Promise<string | null>;
+};
+/**
+ * SharePlay session state.
+ */
+export type SharePlaySessionState = 'waiting' | 'joined' | 'invalidated';
+/**
+ * SharePlay participant info.
+ */
+export interface SharePlayParticipant {
+    /** Participant identifier */
+    id: string;
+    /** Whether this is the local participant */
+    isLocal: boolean;
+}
+/**
+ * SharePlay activity configuration.
+ */
+export interface SharePlayActivity {
+    /** Activity identifier */
+    id: string;
+    /** Activity title */
+    title: string;
+    /** Activity subtitle */
+    subtitle?: string;
+    /** Activity image */
+    image?: string;
+    /** Whether activity supports picture-in-picture */
+    supportsPictureInPicture?: boolean;
+}
+/**
+ * SharePlay API for shared experiences during FaceTime calls.
+ *
+ * @example
+ * // Start a SharePlay activity
+ * await sharePlay.startActivity({
+ *   id: 'watch-together',
+ *   title: 'Watch Movie Together',
+ *   subtitle: 'Synchronized playback'
+ * })
+ *
+ * // Send synchronized message to all participants
+ * sharePlay.broadcast({ action: 'play', timestamp: 1234 })
+ *
+ * // Receive messages from other participants
+ * sharePlay.onMessage((message, participant) => {
+ *   console.log(`${participant.id}: ${message.action}`)
+ * })
+ */
+export declare const sharePlay: {
+    /**
+     * Check if SharePlay is available.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get the current session state.
+     */
+    getSessionState(): Promise<SharePlaySessionState | null>;
+    /**
+     * Get all participants in the current session.
+     */
+    getParticipants(): Promise<SharePlayParticipant[]>;
+    /**
+     * Start a SharePlay activity.
+     */
+    startActivity(activity: SharePlayActivity): Promise<boolean>;
+    /**
+     * End the current SharePlay activity.
+     */
+    endActivity(): Promise<void>;
+    /**
+     * Broadcast a message to all participants.
+     */
+    broadcast(message: Record<string, any>): Promise<void>;
+    /**
+     * Send a message to a specific participant.
+     */
+    send(participantId: string, message: Record<string, any>): Promise<void>;
+    /**
+     * Register message handler.
+     */
+    onMessage(handler: (message: Record<string, any>, participant: SharePlayParticipant) => void): void;
+    /**
+     * Register session state change handler.
+     */
+    onSessionStateChange(handler: (state: SharePlaySessionState) => void): void;
+    /**
+     * Register participant change handler.
+     */
+    onParticipantsChange(handler: (participants: SharePlayParticipant[]) => void): void;
+    /**
+     * Coordinate playback state across participants.
+     */
+    coordinatePlayback(state: {
+        isPlaying: boolean;
+        playbackRate: number;
+        currentTime: number;
+    }): Promise<void>;
+};
+/**
+ * Product type.
+ */
+export type ProductType = 'consumable' | 'non-consumable' | 'auto-renewable' | 'non-renewable';
+/**
+ * Product information.
+ */
+export interface Product {
+    /** Product identifier */
+    id: string;
+    /** Product type */
+    type: ProductType;
+    /** Display name */
+    displayName: string;
+    /** Description */
+    description: string;
+    /** Formatted price */
+    displayPrice: string;
+    /** Price in decimal */
+    price: number;
+    /** Currency code */
+    currencyCode: string;
+    /** Subscription info (for subscription products) */
+    subscription?: {
+        /** Subscription period */
+        subscriptionPeriod: {
+            unit: 'day' | 'week' | 'month' | 'year';
+            value: number;
+        };
+        /** Introductory offer */
+        introductoryOffer?: {
+            displayPrice: string;
+            period: {
+                unit: string;
+                value: number;
+            };
+            periodCount: number;
+            paymentMode: 'freeTrial' | 'payAsYouGo' | 'payUpFront';
+        };
+    };
+}
+/**
+ * Transaction information.
+ */
+export interface Transaction {
+    /** Transaction identifier */
+    id: string;
+    /** Original transaction ID (for renewals) */
+    originalId: string;
+    /** Product identifier */
+    productId: string;
+    /** Purchase date */
+    purchaseDate: Date;
+    /** Expiration date (for subscriptions) */
+    expirationDate?: Date;
+    /** Whether transaction is upgraded */
+    isUpgraded: boolean;
+    /** Revocation date (if revoked) */
+    revocationDate?: Date;
+    /** Revocation reason */
+    revocationReason?: 'developerIssue' | 'other';
+    /** Environment */
+    environment: 'production' | 'sandbox' | 'xcode';
+}
+/**
+ * StoreKit 2 API for in-app purchases and subscriptions.
+ *
+ * @example
+ * // Load products
+ * const products = await storeKit.getProducts(['premium_monthly', 'premium_yearly'])
+ *
+ * // Purchase a product
+ * const result = await storeKit.purchase(products[0].id)
+ * if (result.success) {
+ *   console.log('Purchase successful!')
+ * }
+ *
+ * // Check entitlements
+ * const hasAccess = await storeKit.isEntitled('premium')
+ */
+export declare const storeKit: {
+    /**
+     * Get products by identifiers.
+     */
+    getProducts(productIds: string[]): Promise<Product[]>;
+    /**
+     * Purchase a product.
+     */
+    purchase(productId: string, options?: {
+        quantity?: number;
+        appAccountToken?: string;
+        simulatesAskToBuyInSandbox?: boolean;
+    }): Promise<{
+        success: boolean;
+        transaction?: Transaction;
+        error?: string;
+    }>;
+    /**
+     * Check if user is entitled to a product/feature.
+     */
+    isEntitled(productId: string): Promise<boolean>;
+    /**
+     * Get current entitlements.
+     */
+    getCurrentEntitlements(): Promise<Transaction[]>;
+    /**
+     * Get transaction history.
+     */
+    getTransactionHistory(productId?: string): Promise<Transaction[]>;
+    /**
+     * Restore purchases.
+     */
+    restorePurchases(): Promise<void>;
+    /**
+     * Finish a transaction (required after delivering content).
+     */
+    finishTransaction(transactionId: string): Promise<void>;
+    /**
+     * Get subscription status.
+     */
+    getSubscriptionStatus(groupId: string): Promise<{
+        state: "subscribed" | "expired" | "inBillingRetry" | "inGracePeriod" | "revoked";
+        renewalInfo?: {
+            willAutoRenew: boolean;
+            autoRenewProductId: string;
+            expirationIntent?: "cancelled" | "billingError" | "priceIncrease" | "productNotAvailable";
+        };
+    } | null>;
+    /**
+     * Present offer code redemption sheet.
+     */
+    presentOfferCodeRedemption(): Promise<void>;
+    /**
+     * Present manage subscriptions sheet.
+     */
+    presentManageSubscriptions(): Promise<void>;
+    /**
+     * Present refund request sheet.
+     */
+    beginRefundRequest(transactionId: string): Promise<"success" | "userCancelled" | "failed">;
+    /**
+     * Listen for transaction updates.
+     */
+    onTransactionUpdate(handler: (transaction: Transaction) => void): void;
+    /**
+     * Show price consent sheet if needed.
+     */
+    showPriceConsentIfNeeded(): Promise<void>;
+};
+/**
+ * App Intent parameter type.
+ */
+export type IntentParameterType = 'string' | 'integer' | 'double' | 'boolean' | 'date' | 'url' | 'enum';
+/**
+ * App Intent parameter definition.
+ */
+export interface IntentParameter {
+    /** Parameter name */
+    name: string;
+    /** Parameter type */
+    type: IntentParameterType;
+    /** Display title */
+    title: string;
+    /** Description */
+    description?: string;
+    /** Whether required */
+    required?: boolean;
+    /** Default value */
+    defaultValue?: any;
+    /** Enum values (for enum type) */
+    enumValues?: Array<{
+        value: string;
+        displayName: string;
+    }>;
+}
+/**
+ * App Intent definition.
+ */
+export interface AppIntent {
+    /** Intent identifier */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Description */
+    description: string;
+    /** Parameters */
+    parameters?: IntentParameter[];
+    /** Suggested invocation phrase */
+    suggestedInvocationPhrase?: string;
+}
+/**
+ * App Intents API for Siri Shortcuts and Spotlight.
+ *
+ * @example
+ * // Register an intent
+ * appIntents.register({
+ *   id: 'com.myapp.order-coffee',
+ *   title: 'Order Coffee',
+ *   description: 'Order your favorite coffee',
+ *   parameters: [
+ *     { name: 'size', type: 'enum', title: 'Size', enumValues: [
+ *       { value: 'small', displayName: 'Small' },
+ *       { value: 'medium', displayName: 'Medium' },
+ *       { value: 'large', displayName: 'Large' }
+ *     ]}
+ *   ],
+ *   suggestedInvocationPhrase: 'Order my coffee'
+ * })
+ *
+ * // Handle intent execution
+ * appIntents.onPerform('com.myapp.order-coffee', async (params) => {
+ *   await orderCoffee(params.size)
+ *   return { success: true, message: 'Coffee ordered!' }
+ * })
+ */
+export declare const appIntents: {
+    /**
+     * Register an App Intent.
+     */
+    register(intent: AppIntent): void;
+    /**
+     * Unregister an App Intent.
+     */
+    unregister(intentId: string): void;
+    /**
+     * Register intent execution handler.
+     */
+    onPerform(intentId: string, handler: (parameters: Record<string, any>) => Promise<{
+        success: boolean;
+        message?: string;
+        value?: any;
+    }>): void;
+    /**
+     * Donate an intent for Siri suggestions.
+     */
+    donate(intentId: string, parameters?: Record<string, any>): Promise<void>;
+    /**
+     * Delete donated intents.
+     */
+    deleteDonations(intentId?: string): Promise<void>;
+    /**
+     * Update Spotlight index for intent.
+     */
+    updateSpotlightIndex(intentId: string, searchableItems: Array<{
+        uniqueIdentifier: string;
+        title: string;
+        contentDescription?: string;
+        keywords?: string[];
+        thumbnailUrl?: string;
+    }>): Promise<void>;
+};
+/**
+ * Tip display frequency.
+ */
+export type TipDisplayFrequency = 'immediate' | 'hourly' | 'daily' | 'weekly' | 'monthly';
+/**
+ * Tip configuration.
+ */
+export interface Tip {
+    /** Tip identifier */
+    id: string;
+    /** Title */
+    title: string;
+    /** Message */
+    message: string;
+    /** Image name (SF Symbol or asset) */
+    image?: string;
+    /** Action buttons */
+    actions?: Array<{
+        id: string;
+        title: string;
+    }>;
+    /** Display rules */
+    rules?: {
+        /** Show after event count */
+        eventCount?: {
+            event: string;
+            count: number;
+        };
+        /** Show after duration */
+        duration?: {
+            seconds: number;
+        };
+        /** Parameter-based conditions */
+        parameters?: Record<string, any>;
+    };
+    /** Display options */
+    options?: {
+        /** Maximum display count */
+        maxDisplayCount?: number;
+        /** Ignore display frequency */
+        ignoreDisplayFrequency?: boolean;
+    };
+}
+/**
+ * TipKit API for contextual hints and feature discovery.
+ *
+ * @example
+ * // Configure TipKit
+ * await tipKit.configure({ displayFrequency: 'daily' })
+ *
+ * // Register a tip
+ * tipKit.register({
+ *   id: 'new-feature-tip',
+ *   title: 'New Feature!',
+ *   message: 'Try our new sharing feature',
+ *   image: 'square.and.arrow.up',
+ *   rules: {
+ *     eventCount: { event: 'app-opened', count: 3 }
+ *   }
+ * })
+ *
+ * // Track events for tip rules
+ * tipKit.trackEvent('app-opened')
+ *
+ * // Show tip inline
+ * const shouldShow = await tipKit.shouldShow('new-feature-tip')
+ */
+export declare const tipKit: {
+    /**
+     * Configure TipKit.
+     */
+    configure(options: {
+        displayFrequency?: TipDisplayFrequency;
+        datastoreLocation?: "applicationDefault" | "groupContainer";
+    }): Promise<void>;
+    /**
+     * Register a tip.
+     */
+    register(tip: Tip): void;
+    /**
+     * Check if a tip should be displayed.
+     */
+    shouldShow(tipId: string): Promise<boolean>;
+    /**
+     * Invalidate a tip (permanently hide).
+     */
+    invalidate(tipId: string, reason?: string): Promise<void>;
+    /**
+     * Track an event for tip rules.
+     */
+    trackEvent(eventId: string): Promise<void>;
+    /**
+     * Set a parameter value for tip rules.
+     */
+    setParameter(name: string, value: any): Promise<void>;
+    /**
+     * Show a tip as a popover.
+     */
+    showPopover(tipId: string, sourceElement: string): Promise<void>;
+    /**
+     * Register tip action handler.
+     */
+    onAction(tipId: string, handler: (actionId: string) => void): void;
+    /**
+     * Reset all tips (for testing).
+     */
+    resetDatastore(): Promise<void>;
+};
+/**
+ * Focus status.
+ */
+export interface FocusStatus {
+    /** Whether Focus is active */
+    isFocusActive: boolean;
+    /** Current Focus name (if authorized) */
+    focusName?: string;
+}
+/**
+ * Focus filter configuration.
+ */
+export interface FocusFilter {
+    /** Filter identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Filter parameters */
+    parameters?: Array<{
+        name: string;
+        type: 'boolean' | 'string' | 'selection';
+        displayName: string;
+        options?: string[];
+    }>;
+}
+/**
+ * Focus Filters API for Focus mode integration.
+ *
+ * @example
+ * // Register a focus filter
+ * focusFilters.register({
+ *   id: 'work-mode',
+ *   name: 'Work Mode',
+ *   description: 'Show only work-related content',
+ *   parameters: [
+ *     { name: 'showNotifications', type: 'boolean', displayName: 'Show Notifications' }
+ *   ]
+ * })
+ *
+ * // Handle filter changes
+ * focusFilters.onFilterChange((filterSettings) => {
+ *   if (filterSettings.showNotifications === false) {
+ *     disableNotifications()
+ *   }
+ * })
+ */
+export declare const focusFilters: {
+    /**
+     * Check Focus authorization status.
+     */
+    getAuthorizationStatus(): Promise<"notDetermined" | "denied" | "authorized">;
+    /**
+     * Request Focus authorization.
+     */
+    requestAuthorization(): Promise<boolean>;
+    /**
+     * Get current Focus status.
+     */
+    getFocusStatus(): Promise<FocusStatus>;
+    /**
+     * Register a Focus filter.
+     */
+    register(filter: FocusFilter): void;
+    /**
+     * Get current filter settings.
+     */
+    getCurrentFilterSettings(): Promise<Record<string, any> | null>;
+    /**
+     * Register Focus status change handler.
+     */
+    onFocusChange(handler: (status: FocusStatus) => void): void;
+    /**
+     * Register filter settings change handler.
+     */
+    onFilterChange(handler: (settings: Record<string, any>) => void): void;
+};
+declare const iosAdvanced: {
+    carplay: typeof carplay;
+    appClips: typeof appClips;
+    liveActivities: typeof liveActivities;
+    sharePlay: typeof sharePlay;
+    storeKit: typeof storeKit;
+    appIntents: typeof appIntents;
+    tipKit: typeof tipKit;
+    focusFilters: typeof focusFilters;
+};
+export default iosAdvanced;
+//# sourceMappingURL=ios-advanced.d.ts.map