nativine 1.0.2

package/dist/modules/auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Auth Module
+ *
+ * Native Google Sign-In integration. Triggers the native Google Sign-In flow
+ * and returns user credentials to your web app.
+ */
+export interface GoogleSignInResult {
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    displayName: string;
+    /** Google ID token for backend verification */
+    idToken: string;
+    /** URL of user's profile photo */
+    photoUrl: string;
+    /** Google account ID */
+    id: string;
+}
+/**
+ * Trigger the native Google Sign-In flow.
+ * Returns user credentials when the user completes sign-in.
+ *
+ * @returns Promise resolving with Google user credentials
+ *
+ * @example
+ * ```js
+ * try {
+ *   const user = await nativine.auth.googleSignIn();
+ *   console.log(user.email); // "john@gmail.com"
+ *   console.log(user.idToken); // Send to your backend for verification
+ * } catch (err) {
+ *   console.log('Sign-in cancelled or failed');
+ * }
+ * ```
+ */
+export declare function googleSignIn(): Promise<GoogleSignInResult>;
+/**
+ * Sign out of the current Google account.
+ *
+ * @example
+ * ```js
+ * await nativine.auth.googleSignOut();
+ * ```
+ */
+export declare function googleSignOut(): void;

package/dist/modules/biometrics.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Biometrics Module
+ *
+ * Trigger native biometric authentication (fingerprint, face recognition, iris scan).
+ */
+export type BiometryType = 'fingerprint' | 'face' | 'iris' | 'none';
+export interface BiometricAvailability {
+    /** Whether biometric authentication is available on this device */
+    available: boolean;
+    /** The type of biometric sensor available */
+    biometryType: BiometryType;
+}
+export interface BiometricAuthOptions {
+    /** Reason displayed to the user for why authentication is needed */
+    reason?: string;
+    /** Title for the biometric dialog (Android only) */
+    title?: string;
+    /** Whether to allow device PIN/pattern as fallback */
+    allowFallback?: boolean;
+}
+export interface BiometricAuthResult {
+    /** Whether authentication was successful */
+    success: boolean;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Check if biometric authentication is available on this device.
+ *
+ * @returns Promise resolving with availability info
+ *
+ * @example
+ * ```js
+ * const { available, biometryType } = await nativine.biometrics.isAvailable();
+ * if (available) {
+ *   console.log(`Biometric type: ${biometryType}`); // "fingerprint"
+ * }
+ * ```
+ */
+export declare function isAvailable(): Promise<BiometricAvailability>;
+/**
+ * Trigger biometric authentication.
+ *
+ * @param options - Configuration for the authentication prompt
+ * @returns Promise resolving with the authentication result
+ *
+ * @example
+ * ```js
+ * const result = await nativine.biometrics.authenticate({
+ *   reason: 'Verify your identity to access settings',
+ *   allowFallback: true
+ * });
+ *
+ * if (result.success) {
+ *   // User authenticated
+ *   showSensitiveContent();
+ * }
+ * ```
+ */
+export declare function authenticate(options?: BiometricAuthOptions): Promise<BiometricAuthResult>;

package/dist/modules/cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cache Module
+ *
+ * Clear WebView cache and cookies.
+ */
+/**
+ * Clear the WebView cache (CSS, JS, images, etc.).
+ * Shows a confirmation dialog to the user.
+ *
+ * @example
+ * ```js
+ * nativine.cache.clear();
+ * ```
+ */
+export declare function clear(): void;
+/**
+ * Clear all WebView cookies.
+ * Useful for logout flows to ensure session data is wiped.
+ *
+ * @example
+ * ```js
+ * nativine.cache.clearCookies();
+ * ```
+ */
+export declare function clearCookies(): void;

package/dist/modules/camera.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Camera / Scanner Module
+ *
+ * Access the device camera for barcode and QR code scanning.
+ */
+export interface ScanResult {
+    /** The decoded content of the barcode/QR code */
+    value: string;
+    /** The format of the code (e.g., 'QR_CODE', 'EAN_13', 'CODE_128') */
+    format: string;
+}
+export interface ScanOptions {
+    /** Restrict scanning to specific formats */
+    formats?: string[];
+    /** Prompt text shown on the scanner UI */
+    prompt?: string;
+}
+/**
+ * Open the native barcode/QR code scanner.
+ *
+ * @param options - Scanner configuration
+ * @returns Promise resolving with the scanned code data
+ *
+ * @example
+ * ```js
+ * try {
+ *   const result = await nativine.scanner.scan();
+ *   console.log(result.value);  // "https://example.com"
+ *   console.log(result.format); // "QR_CODE"
+ * } catch (err) {
+ *   console.log('Scan cancelled');
+ * }
+ * ```
+ */
+export declare function scan(options?: ScanOptions): Promise<ScanResult>;

package/dist/modules/clipboard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Clipboard Module
+ *
+ * Read from and write to the device clipboard.
+ */
+/**
+ * Copy text to the device clipboard.
+ *
+ * @param text - The text to copy
+ *
+ * @example
+ * ```js
+ * await nativine.clipboard.copy('https://example.com/share/abc123');
+ * ```
+ */
+export declare function copy(text: string): Promise<void>;
+/**
+ * Read text from the device clipboard.
+ *
+ * @returns Promise resolving with the clipboard text content
+ *
+ * @example
+ * ```js
+ * const text = await nativine.clipboard.read();
+ * console.log('Clipboard:', text);
+ * ```
+ */
+export declare function read(): Promise<string>;

package/dist/modules/contacts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Contacts Module
+ *
+ * Access the device's native contact list (requires user permission).
+ */
+export interface Contact {
+    /** Contact display name */
+    name: string;
+    /** Phone number(s) */
+    phone: string;
+    /** Email address(es) */
+    email: string;
+}
+/**
+ * Retrieve the user's contacts from the native contact book.
+ * Prompts for permission if not already granted.
+ *
+ * @returns Promise resolving with an array of contacts
+ *
+ * @example
+ * ```js
+ * const contacts = await nativine.contacts.getAll();
+ * contacts.forEach(c => {
+ *   console.log(`${c.name}: ${c.phone}`);
+ * });
+ * ```
+ */
+export declare function getAll(): Promise<Contact[]>;

package/dist/modules/device.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Device Module
+ *
+ * Access device hardware/software information, safe area insets,
+ * app version, and anonymous device identifiers.
+ */
+export interface DeviceInfo {
+    /** Device model name (e.g., "Pixel 8", "iPhone 15") */
+    model: string;
+    /** Device manufacturer (e.g., "Google", "Apple") */
+    manufacturer: string;
+    /** Operating system version (e.g., "14", "17.2") */
+    osVersion: string;
+    /** Nativine app version name (e.g., "1.2.0") */
+    appVersion: string;
+    /** Nativine app version code (e.g., 12) */
+    appVersionCode: number;
+    /** App package name (e.g., "com.example.myapp") */
+    packageName: string;
+    /** Device locale (e.g., "en-US") */
+    locale: string;
+    /** Screen width in dp */
+    screenWidth: number;
+    /** Screen height in dp */
+    screenHeight: number;
+    /** Screen pixel density */
+    density: number;
+    /** Platform: 'android' or 'ios' */
+    platform: string;
+}
+export interface SafeAreaInsets {
+    /** Top safe area inset in px (e.g., status bar height) */
+    top: number;
+    /** Bottom safe area inset in px (e.g., navigation bar / home indicator) */
+    bottom: number;
+    /** Left safe area inset in px */
+    left: number;
+    /** Right safe area inset in px */
+    right: number;
+}
+/**
+ * Get comprehensive device information.
+ *
+ * @example
+ * ```js
+ * const info = await nativine.device.getInfo();
+ * console.log(info.model); // "Pixel 8"
+ * console.log(info.appVersion); // "1.2.0"
+ * ```
+ */
+export declare function getInfo(): Promise<DeviceInfo>;
+/**
+ * Get the current safe area insets.
+ * Useful for positioning UI elements to avoid notches and system bars.
+ *
+ * @example
+ * ```js
+ * const insets = await nativine.device.getSafeAreaInsets();
+ * element.style.paddingTop = `${insets.top}px`;
+ * ```
+ */
+export declare function getSafeAreaInsets(): Promise<SafeAreaInsets>;
+/**
+ * Get the app's version name string (e.g., "1.2.0").
+ *
+ * @example
+ * ```js
+ * const version = await nativine.device.getAppVersion();
+ * // "1.2.0"
+ * ```
+ */
+export declare function getAppVersion(): Promise<string>;
+/**
+ * Get an anonymous, persistent device identifier.
+ * This ID is unique per app installation (not a hardware ID).
+ * Resets when the app is reinstalled.
+ *
+ * @example
+ * ```js
+ * const id = await nativine.device.getDeviceId();
+ * // "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ * ```
+ */
+export declare function getDeviceId(): Promise<string>;

package/dist/modules/downloads.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Downloads Module
+ *
+ * Trigger native file downloads using the device's download manager.
+ */
+export interface DownloadFileOptions {
+    /** The URL of the file to download */
+    url: string;
+    /** Custom filename (optional, auto-detected from URL if not provided) */
+    filename?: string;
+    /** MIME type of the file */
+    mimeType?: string;
+    /** Whether to open the file after download completes */
+    openAfterDownload?: boolean;
+}
+/**
+ * Download a file using the native download manager.
+ * Shows a notification with download progress on Android.
+ *
+ * @param options - Download configuration
+ *
+ * @example
+ * ```js
+ * nativine.downloads.downloadFile({
+ *   url: 'https://example.com/report.pdf',
+ *   filename: 'monthly-report.pdf',
+ *   openAfterDownload: true
+ * });
+ * ```
+ */
+export declare function downloadFile(options: DownloadFileOptions): void;

package/dist/modules/events.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Events Module
+ *
+ * Subscribe to native app lifecycle events.
+ * The native side dispatches events by calling global handler functions.
+ */
+export type NativineEvent = 'appResume' | 'appPause' | 'pageReady' | 'keyboardShow' | 'keyboardHide' | 'stepUpdate';
+type EventCallback = (data?: any) => void;
+/**
+ * Subscribe to a native app lifecycle event.
+ *
+ * Available events:
+ * - `'appResume'` — App returned to foreground
+ * - `'appPause'` — App went to background
+ * - `'pageReady'` — Bridge is fully initialized and ready
+ * - `'keyboardShow'` — Software keyboard appeared (with height data)
+ * - `'keyboardHide'` — Software keyboard dismissed
+ *
+ * @param event - The event name to listen for
+ * @param callback - Function called when the event fires
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```js
+ * // Refresh data when user returns to app
+ * const unsubscribe = nativine.on('appResume', () => {
+ *   fetchLatestData();
+ * });
+ *
+ * // Listen for keyboard visibility
+ * nativine.on('keyboardShow', ({ height }) => {
+ *   adjustLayoutForKeyboard(height);
+ * });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ */
+export declare function on(event: NativineEvent, callback: EventCallback): () => void;
+/**
+ * Unsubscribe all listeners for a specific event, or all events.
+ *
+ * @param event - The event to clear listeners for (or omit to clear all)
+ *
+ * @example
+ * ```js
+ * // Remove all appResume listeners
+ * nativine.off('appResume');
+ *
+ * // Remove ALL event listeners
+ * nativine.off();
+ * ```
+ */
+export declare function off(event?: NativineEvent): void;
+export {};

package/dist/modules/haptics.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Haptics Module
+ *
+ * Trigger device vibrations and haptic feedback patterns.
+ */
+export type HapticFeedbackType = 'light' | 'medium' | 'heavy' | 'success' | 'error' | 'warning' | 'selection';
+/**
+ * Vibrate the device for a specified duration.
+ *
+ * @param durationMs - Duration in milliseconds (default: 100ms)
+ *
+ * @example
+ * ```js
+ * nativine.haptics.vibrate(200);
+ * ```
+ */
+export declare function vibrate(durationMs?: number): void;
+/**
+ * Trigger a predefined haptic feedback pattern.
+ *
+ * @param type - The type of haptic feedback
+ *
+ * Feedback types:
+ * - `'light'` — Subtle tap (e.g., toggle switch)
+ * - `'medium'` — Standard tap (e.g., button press)
+ * - `'heavy'` — Strong tap (e.g., action confirmation)
+ * - `'success'` — Success pattern (double tap)
+ * - `'error'` — Error pattern (triple tap)
+ * - `'warning'` — Warning pattern
+ * - `'selection'` — Selection change (lightest)
+ *
+ * @example
+ * ```js
+ * // On button click
+ * nativine.haptics.feedback('medium');
+ *
+ * // On form validation error
+ * nativine.haptics.feedback('error');
+ *
+ * // On successful payment
+ * nativine.haptics.feedback('success');
+ * ```
+ */
+export declare function feedback(type?: HapticFeedbackType): void;

package/dist/modules/location.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Location Module
+ *
+ * Access the device's GPS location.
+ */
+export interface LocationResult {
+    /** Latitude in degrees */
+    latitude: number;
+    /** Longitude in degrees */
+    longitude: number;
+    /** Accuracy in meters */
+    accuracy: number;
+    /** Altitude in meters (may be null on some devices) */
+    altitude?: number;
+    /** Speed in m/s (may be null) */
+    speed?: number;
+}
+/**
+ * Get the device's current GPS location.
+ * Prompts for location permission if not already granted.
+ *
+ * @returns Promise resolving with location coordinates
+ *
+ * @example
+ * ```js
+ * const loc = await nativine.location.getCurrent();
+ * console.log(`Lat: ${loc.latitude}, Lng: ${loc.longitude}`);
+ * console.log(`Accuracy: ${loc.accuracy}m`);
+ * ```
+ */
+export declare function getCurrent(): Promise<LocationResult>;

package/dist/modules/navigation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Navigation Module
+ *
+ * Control in-app navigation: go back, go forward, navigate to URLs,
+ * open external browser, and close the app.
+ */
+/**
+ * Navigate the WebView back one page in history.
+ * No-op if there's no back history.
+ *
+ * @example
+ * ```js
+ * nativine.navigation.goBack();
+ * ```
+ */
+export declare function goBack(): void;
+/**
+ * Navigate the WebView forward one page in history.
+ * No-op if there's no forward history.
+ *
+ * @example
+ * ```js
+ * nativine.navigation.goForward();
+ * ```
+ */
+export declare function goForward(): void;
+/**
+ * Navigate the WebView to a specific URL.
+ * Supports both absolute URLs and relative paths.
+ *
+ * @param url - The URL or path to navigate to
+ *
+ * @example
+ * ```js
+ * nativine.navigation.navigate('/products');
+ * nativine.navigation.navigate('https://example.com/page');
+ * ```
+ */
+export declare function navigate(url: string): void;
+/**
+ * Open a URL in the device's default external browser.
+ * The user leaves the app temporarily.
+ *
+ * @param url - The URL to open externally
+ *
+ * @example
+ * ```js
+ * nativine.navigation.openInBrowser('https://docs.nativine.com');
+ * ```
+ */
+export declare function openInBrowser(url: string): void;
+/**
+ * Close the app. On Android, this finishes the Activity.
+ *
+ * @example
+ * ```js
+ * nativine.navigation.closeApp();
+ * ```
+ */
+export declare function closeApp(): void;

package/dist/modules/network.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Network Module
+ *
+ * Check connectivity status and listen for network changes.
+ */
+export interface ConnectivityStatus {
+    /** Whether the device is online */
+    online: boolean;
+    /** Connection type: 'wifi', 'cellular', 'ethernet', 'none', 'unknown' */
+    type: 'wifi' | 'cellular' | 'ethernet' | 'none' | 'unknown';
+}
+type ConnectivityCallback = (status: ConnectivityStatus) => void;
+/**
+ * Check if the device currently has network connectivity.
+ *
+ * @returns Promise resolving with connectivity status
+ *
+ * @example
+ * ```js
+ * const status = await nativine.network.isOnline();
+ * if (!status.online) {
+ *   showOfflineBanner();
+ * }
+ * ```
+ */
+export declare function isOnline(): Promise<ConnectivityStatus>;
+/**
+ * Listen for network connectivity changes.
+ *
+ * @param callback - Function called when connectivity changes
+ * @returns Unsubscribe function to stop listening
+ *
+ * @example
+ * ```js
+ * const unsubscribe = nativine.network.onConnectivityChange((status) => {
+ *   if (!status.online) {
+ *     showOfflineBanner();
+ *   } else {
+ *     hideOfflineBanner();
+ *   }
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+export declare function onConnectivityChange(callback: ConnectivityCallback): () => void;
+/**
+ * Internal: Called by the native side when connectivity changes.
+ * Dispatches to all registered listeners.
+ * @internal
+ */
+export declare function _onConnectivityChanged(status: ConnectivityStatus): void;
+export {};

package/dist/modules/onesignal.d.ts

@@ -0,0 +1,70 @@
+/**
+ * OneSignal Module
+ *
+ * Interact with OneSignal push notification service from your web app.
+ * Requires the OneSignal addon to be enabled in your Nativine app.
+ */
+/**
+ * Set the OneSignal external user ID.
+ * Links the device's push subscription to your backend user ID.
+ *
+ * @param userId - Your app's user identifier
+ *
+ * @example
+ * ```js
+ * // After user logs in
+ * nativine.onesignal.setExternalUserId('user_12345');
+ * ```
+ */
+export declare function setExternalUserId(userId: string): void;
+/**
+ * Send a tag (key-value pair) to OneSignal for audience segmentation.
+ *
+ * @param key - Tag key
+ * @param value - Tag value
+ *
+ * @example
+ * ```js
+ * nativine.onesignal.sendTag('plan', 'premium');
+ * nativine.onesignal.sendTag('language', 'en');
+ * ```
+ */
+export declare function sendTag(key: string, value: string): void;
+/**
+ * Send multiple tags at once to OneSignal.
+ *
+ * @param tags - Object with tag key-value pairs
+ *
+ * @example
+ * ```js
+ * nativine.onesignal.sendTags({
+ *   plan: 'premium',
+ *   language: 'en',
+ *   onboarded: 'true'
+ * });
+ * ```
+ */
+export declare function sendTags(tags: Record<string, string>): void;
+/**
+ * Get the OneSignal Player ID (push subscription ID) for this device.
+ *
+ * @returns Promise resolving with the player ID string
+ *
+ * @example
+ * ```js
+ * const playerId = await nativine.onesignal.getPlayerId();
+ * // Send to your backend for targeted push notifications
+ * ```
+ */
+export declare function getPlayerId(): Promise<string>;
+/**
+ * Remove the external user ID association.
+ * Call this when the user logs out.
+ *
+ * @example
+ * ```js
+ * // On logout
+ * nativine.onesignal.removeExternalUserId();
+ * ```
+ */
+export declare function removeExternalUserId(): void;