react-native-frame-capture 1.0.1

package/src/api.ts

@@ -0,0 +1,189 @@
+/**
+ * Core API functions for React Native Frame Capture
+ * @module api
+ */
+
+import NativeFrameCapture from './NativeFrameCapture';
+import { CaptureError } from './errors';
+import { validateOptions, mergeOptions } from './validation';
+import { normalizeOptions } from './normalize';
+import {
+  CaptureErrorCode,
+  PermissionStatus,
+  type CaptureOptions,
+  type CaptureSession,
+  type CaptureStatus,
+} from './types';
+
+/**
+ * Requests MediaProjection permission from the user
+ *
+ * @returns Promise resolving to permission status
+ * @throws {CaptureError} if permission request fails
+ */
+export async function requestPermission(): Promise<PermissionStatus> {
+  try {
+    const result = await NativeFrameCapture.requestPermission();
+    return result as PermissionStatus;
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to request permission',
+      error.details
+    );
+  }
+}
+
+/**
+ * Checks current permission status without requesting
+ *
+ * @returns Promise resolving to current permission status
+ */
+export async function checkPermission(): Promise<PermissionStatus> {
+  try {
+    const result = await NativeFrameCapture.checkPermission();
+    return result as PermissionStatus;
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to check permission',
+      error.details
+    );
+  }
+}
+
+/**
+ * Starts screen capture with the given options
+ *
+ * @param options - Capture configuration options (optional, uses defaults if not provided)
+ * @returns Promise resolving to capture session information
+ * @throws {CaptureError} if capture cannot be started
+ */
+export async function startCapture(
+  options?: Partial<CaptureOptions>
+): Promise<CaptureSession> {
+  if (options) {
+    validateOptions(options);
+  }
+
+  const finalOptions = mergeOptions(options);
+  const nativeOptions = normalizeOptions(finalOptions);
+
+  try {
+    const result = await NativeFrameCapture.startCapture(nativeOptions);
+    return result as CaptureSession;
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to start capture',
+      error.details
+    );
+  }
+}
+
+/**
+ * Stops the active capture session
+ *
+ * @returns Promise that resolves when capture is stopped
+ * @throws {CaptureError} if stop operation fails
+ */
+export async function stopCapture(): Promise<void> {
+  try {
+    await NativeFrameCapture.stopCapture();
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to stop capture',
+      error.details
+    );
+  }
+}
+
+/**
+ * Pauses the active capture session
+ *
+ * @returns Promise that resolves when capture is paused
+ * @throws {CaptureError} if pause operation fails
+ */
+export async function pauseCapture(): Promise<void> {
+  try {
+    await NativeFrameCapture.pauseCapture();
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to pause capture',
+      error.details
+    );
+  }
+}
+
+/**
+ * Resumes a paused capture session
+ *
+ * @returns Promise that resolves when capture is resumed
+ * @throws {CaptureError} if resume operation fails
+ */
+export async function resumeCapture(): Promise<void> {
+  try {
+    await NativeFrameCapture.resumeCapture();
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to resume capture',
+      error.details
+    );
+  }
+}
+
+/**
+ * Gets the current capture status
+ *
+ * @returns Promise resolving to current capture status
+ */
+export async function getCaptureStatus(): Promise<CaptureStatus> {
+  try {
+    const result = await NativeFrameCapture.getCaptureStatus();
+    return result as CaptureStatus;
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to get capture status',
+      error.details
+    );
+  }
+}
+
+/**
+ * Checks if notification permission is granted (Android 13+)
+ *
+ * @returns Promise resolving to permission status
+ */
+export async function checkNotificationPermission(): Promise<PermissionStatus> {
+  try {
+    const result = await NativeFrameCapture.checkNotificationPermission();
+    return result as PermissionStatus;
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to check notification permission',
+      error.details
+    );
+  }
+}
+
+/**
+ * Manually cleans up all temporary frame files
+ *
+ * @returns Promise that resolves when cleanup is complete
+ */
+export async function cleanupTempFrames(): Promise<void> {
+  try {
+    await NativeFrameCapture.cleanupTempFrames();
+  } catch (error: any) {
+    throw new CaptureError(
+      error.code || CaptureErrorCode.SYSTEM_ERROR,
+      error.message || 'Failed to cleanup temp frames',
+      error.details
+    );
+  }
+}

package/src/constants.ts

@@ -0,0 +1,69 @@
+/**
+ * Constants for React Native Frame Capture
+ * @module constants
+ */
+
+import type {
+  CaptureOptions,
+  FileNamingConfig,
+  PerformanceOptions,
+} from './types';
+
+/**
+ * Default configuration options
+ */
+export const DEFAULT_OPTIONS: CaptureOptions = {
+  capture: {
+    interval: 1000,
+  },
+  image: {
+    quality: 80,
+    format: 'jpeg',
+  },
+};
+
+/**
+ * Default advanced configuration (for validation fallbacks)
+ */
+export const DEFAULT_ADVANCED_CONFIG = {
+  storage: {
+    warningThreshold: 100 * 1024 * 1024, // 100MB
+  },
+  fileNaming: {
+    prefix: 'capture_',
+    dateFormat: 'yyyyMMdd_HHmmss_SSS',
+    framePadding: 5,
+  } as Required<FileNamingConfig>,
+  performance: {
+    overlayCacheSize: 10 * 1024 * 1024, // 10MB
+    imageReaderBuffers: 2,
+    executorShutdownTimeout: 5000,
+    executorForcedShutdownTimeout: 1000,
+  } as Required<PerformanceOptions>,
+};
+
+/**
+ * Minimum interval between captures (milliseconds)
+ */
+export const MIN_INTERVAL = 100;
+
+/**
+ * Maximum interval between captures (milliseconds)
+ */
+export const MAX_INTERVAL = 60000;
+
+/**
+ * Minimum image quality value
+ */
+export const MIN_QUALITY = 0;
+
+/**
+ * Maximum image quality value
+ */
+export const MAX_QUALITY = 100;
+
+/**
+ * Storage warning threshold (bytes)
+ * @deprecated Use advanced.storage.warningThreshold in CaptureOptions instead
+ */
+export const STORAGE_WARNING_THRESHOLD = 100 * 1024 * 1024; // 100MB

package/src/errors.ts

@@ -0,0 +1,21 @@
+/**
+ * Error handling for React Native Frame Capture
+ * @module errors
+ */
+
+import { CaptureErrorCode } from './types';
+
+/**
+ * Custom error class for capture operations
+ */
+export class CaptureError extends Error {
+  code: CaptureErrorCode;
+  details?: any;
+
+  constructor(code: CaptureErrorCode, message: string, details?: any) {
+    super(message);
+    this.name = 'CaptureError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/src/events.ts

@@ -0,0 +1,61 @@
+/**
+ * Event handling for React Native Frame Capture
+ * @module events
+ */
+
+import type { EventSubscription } from 'react-native';
+import NativeFrameCapture from './NativeFrameCapture';
+import { CaptureEventType, type CaptureEventCallback } from './types';
+
+/**
+ * Adds an event listener for capture events
+ *
+ * @param event - Event type to listen for
+ * @param callback - Function to call when event is emitted
+ * @returns Subscription object that can be used to remove the listener
+ *
+ * @example
+ * ```typescript
+ * const subscription = addListener(
+ *   CaptureEventType.FRAME_CAPTURED,
+ *   (event) => console.log('Frame captured:', event.filePath)
+ * );
+ *
+ * // Later, remove the listener
+ * subscription.remove();
+ * ```
+ */
+export function addListener(
+  event: CaptureEventType,
+  callback: CaptureEventCallback
+): EventSubscription {
+  switch (event) {
+    case CaptureEventType.FRAME_CAPTURED:
+      return NativeFrameCapture.onFrameCaptured(callback as any);
+    case CaptureEventType.CAPTURE_ERROR:
+      return NativeFrameCapture.onCaptureError(callback as any);
+    case CaptureEventType.CAPTURE_STOP:
+      return NativeFrameCapture.onCaptureStop(callback as any);
+    case CaptureEventType.CAPTURE_START:
+      return NativeFrameCapture.onCaptureStart(callback as any);
+    case CaptureEventType.STORAGE_WARNING:
+      return NativeFrameCapture.onStorageWarning(callback as any);
+    case CaptureEventType.CAPTURE_PAUSE:
+      return NativeFrameCapture.onCapturePause(callback as any);
+    case CaptureEventType.CAPTURE_RESUME:
+      return NativeFrameCapture.onCaptureResume(callback as any);
+    case CaptureEventType.OVERLAY_ERROR:
+      return NativeFrameCapture.onOverlayError(callback as any);
+    default:
+      throw new Error(`Unknown event type: ${event}`);
+  }
+}
+
+/**
+ * @deprecated Use subscription.remove() instead
+ */
+export function removeAllListeners(_event: CaptureEventType): void {
+  console.warn(
+    'removeAllListeners is deprecated in New Architecture. Use subscription.remove() instead.'
+  );
+}

package/src/index.tsx

@@ -0,0 +1,31 @@
+/**
+ * React Native Frame Capture
+ * Production-grade screen capture library for React Native Android
+ *
+ * @packageDocumentation
+ */
+
+// Export types
+export * from './types';
+
+// Export constants
+export * from './constants';
+
+// Export errors
+export { CaptureError } from './errors';
+
+// Export API functions
+export {
+  requestPermission,
+  checkPermission,
+  startCapture,
+  stopCapture,
+  pauseCapture,
+  resumeCapture,
+  getCaptureStatus,
+  checkNotificationPermission,
+  cleanupTempFrames,
+} from './api';
+
+// Export event functions
+export { addListener, removeAllListeners } from './events';

package/src/normalize.ts

@@ -0,0 +1,81 @@
+/**
+ * Normalization utilities for converting organized CaptureOptions
+ * to the flat structure expected by native code
+ * @module normalize
+ */
+
+import type { CaptureOptions } from './types';
+
+/**
+ * Flat options structure expected by native code
+ */
+export interface NativeCaptureOptions {
+  interval: number;
+  quality: number;
+  format: 'png' | 'jpeg';
+  saveFrames?: boolean;
+  storageLocation?: 'private' | 'public';
+  outputDirectory?: string;
+  scaleResolution?: number;
+  captureRegion?: any;
+  excludeStatusBar?: boolean;
+  notification?: any;
+  overlays?: any[];
+  advanced?: {
+    storage?: {
+      warningThreshold?: number;
+    };
+    fileNaming?: {
+      prefix?: string;
+      dateFormat?: string;
+      framePadding?: number;
+    };
+    performance?: {
+      overlayCacheSize?: number;
+      imageReaderBuffers?: number;
+      executorShutdownTimeout?: number;
+      executorForcedShutdownTimeout?: number;
+    };
+  };
+}
+
+/**
+ * Normalizes organized CaptureOptions to flat structure for native code
+ */
+export function normalizeOptions(
+  options: CaptureOptions
+): NativeCaptureOptions {
+  const { capture, image, storage, performance, notification, overlays } =
+    options;
+
+  return {
+    // Capture config
+    interval: capture.interval,
+
+    // Image config
+    quality: image.quality,
+    format: image.format,
+    scaleResolution: image.scaleResolution,
+    captureRegion: image.region,
+    excludeStatusBar: image.excludeStatusBar,
+
+    // Storage config
+    saveFrames: storage?.saveFrames,
+    storageLocation: storage?.location,
+    outputDirectory: storage?.outputDirectory,
+
+    // Pass through as-is
+    notification,
+    overlays,
+
+    // Advanced config (nested structure for native)
+    advanced: {
+      storage:
+        storage?.warningThreshold !== undefined
+          ? { warningThreshold: storage.warningThreshold }
+          : undefined,
+      fileNaming: storage?.fileNaming,
+      performance,
+    },
+  };
+}