react-native-frame-capture 1.0.1

package/src/types.ts

@@ -0,0 +1,327 @@
+/**
+ * Type definitions for React Native Frame Capture
+ * @module types
+ */
+
+// ============================================================================
+// Enums
+// ============================================================================
+
+/**
+ * Capture state values
+ */
+export enum CaptureState {
+  IDLE = 'idle',
+  CAPTURING = 'capturing',
+  PAUSED = 'paused',
+  STOPPING = 'stopping',
+}
+
+/**
+ * Permission status values
+ */
+export enum PermissionStatus {
+  GRANTED = 'granted',
+  DENIED = 'denied',
+  NOT_DETERMINED = 'not_determined',
+}
+
+/**
+ * Error codes for capture operations
+ */
+export enum CaptureErrorCode {
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  ALREADY_CAPTURING = 'ALREADY_CAPTURING',
+  INVALID_OPTIONS = 'INVALID_OPTIONS',
+  STORAGE_ERROR = 'STORAGE_ERROR',
+  SYSTEM_ERROR = 'SYSTEM_ERROR',
+  NOT_SUPPORTED = 'NOT_SUPPORTED',
+}
+
+/**
+ * Event types emitted by the capture system
+ */
+export enum CaptureEventType {
+  FRAME_CAPTURED = 'onFrameCaptured',
+  CAPTURE_ERROR = 'onCaptureError',
+  CAPTURE_STOP = 'onCaptureStop',
+  CAPTURE_START = 'onCaptureStart',
+  STORAGE_WARNING = 'onStorageWarning',
+  CAPTURE_PAUSE = 'onCapturePause',
+  CAPTURE_RESUME = 'onCaptureResume',
+  OVERLAY_ERROR = 'onOverlayError',
+}
+
+// ============================================================================
+// Basic Types
+// ============================================================================
+
+/**
+ * Unit type for capture region coordinates
+ */
+export type CaptureRegionUnit = 'pixels' | 'percentage';
+
+/**
+ * Position preset for overlay placement
+ */
+export type PositionPreset =
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'center';
+
+// ============================================================================
+// Capture Configuration
+// ============================================================================
+
+/**
+ * Custom capture region specification
+ */
+export interface CaptureRegion {
+  /** Left position (pixels or 0-1 for percentage) */
+  x: number;
+  /** Top position (pixels or 0-1 for percentage) */
+  y: number;
+  /** Width (pixels or 0-1 for percentage) */
+  width: number;
+  /** Height (pixels or 0-1 for percentage) */
+  height: number;
+  /** Unit type for coordinates (default: 'percentage') */
+  unit?: CaptureRegionUnit;
+}
+
+/**
+ * File naming configuration
+ */
+export interface FileNamingConfig {
+  /** Filename prefix (default: "capture_") */
+  prefix?: string;
+  /** Date format pattern (default: "yyyyMMdd_HHmmss_SSS") */
+  dateFormat?: string;
+  /** Frame number padding digits (default: 5) */
+  framePadding?: number;
+}
+
+/**
+ * Notification customization options for the foreground service
+ */
+export interface NotificationOptions {
+  title?: string;
+  description?: string;
+  icon?: string;
+  smallIcon?: string;
+  color?: string;
+  channelName?: string;
+  channelDescription?: string;
+  priority?: 'low' | 'default' | 'high';
+  showFrameCount?: boolean;
+  updateInterval?: number;
+  pausedTitle?: string;
+  pausedDescription?: string;
+  showStopAction?: boolean;
+  showPauseAction?: boolean;
+  showResumeAction?: boolean;
+}
+
+/**
+ * Capture behavior configuration
+ */
+export interface CaptureConfig {
+  /** Milliseconds between captures (100-60000) */
+  interval: number;
+}
+
+/**
+ * Image processing configuration
+ */
+export interface ImageConfig {
+  /** Image quality 0-100 */
+  quality: number;
+  /** Output format */
+  format: 'png' | 'jpeg';
+  /** Resolution scale factor 0.1-1.0 */
+  scaleResolution?: number;
+  /** Custom capture region */
+  region?: CaptureRegion;
+  /** Exclude status bar from capture */
+  excludeStatusBar?: boolean;
+}
+
+/**
+ * Storage configuration
+ */
+export interface StorageOptions {
+  /** Whether to save captured frames to device storage */
+  saveFrames?: boolean;
+  /** Storage location for captured frames */
+  location?: 'private' | 'public';
+  /** Custom output directory */
+  outputDirectory?: string;
+  /** Storage warning threshold in bytes (default: 100MB, set to 0 to disable) */
+  warningThreshold?: number;
+  /** File naming configuration */
+  fileNaming?: FileNamingConfig;
+}
+
+/**
+ * Performance tuning configuration
+ */
+export interface PerformanceOptions {
+  /** Overlay image cache size in bytes (default: 10MB) */
+  overlayCacheSize?: number;
+  /** ImageReader buffer count (default: 2) */
+  imageReaderBuffers?: number;
+  /** Executor shutdown timeout in milliseconds (default: 5000ms) */
+  executorShutdownTimeout?: number;
+  /** Forced executor shutdown timeout in milliseconds (default: 1000ms) */
+  executorForcedShutdownTimeout?: number;
+}
+
+/**
+ * Configuration options for screen capture
+ */
+export interface CaptureOptions {
+  /** Capture behavior configuration */
+  capture: CaptureConfig;
+  /** Image processing configuration */
+  image: ImageConfig;
+  /** Storage configuration */
+  storage?: StorageOptions;
+  /** Performance tuning configuration */
+  performance?: PerformanceOptions;
+  /** Notification customization options */
+  notification?: NotificationOptions;
+  /** Array of overlays to render on captured frames */
+  overlays?: OverlayConfig[];
+}
+
+// ============================================================================
+// Overlay Configuration
+// ============================================================================
+
+/**
+ * Custom position coordinates for overlay placement
+ */
+export interface PositionCoordinates {
+  x: number;
+  y: number;
+  unit?: 'pixels' | 'percentage';
+}
+
+/**
+ * Overlay position - either a preset string or custom coordinates
+ */
+export type OverlayPosition = PositionPreset | PositionCoordinates;
+
+/**
+ * Text overlay style configuration
+ */
+export interface TextStyle {
+  fontSize?: number;
+  color?: string;
+  backgroundColor?: string;
+  padding?: number;
+  fontWeight?: 'normal' | 'bold';
+  textAlign?: 'left' | 'center' | 'right';
+}
+
+/**
+ * Text overlay configuration
+ */
+export interface TextOverlay {
+  type: 'text';
+  content: string;
+  position: OverlayPosition;
+  style?: TextStyle;
+}
+
+/**
+ * Image size configuration
+ */
+export interface ImageSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Image overlay configuration
+ */
+export interface ImageOverlay {
+  type: 'image';
+  source: string;
+  position: OverlayPosition;
+  size?: ImageSize;
+  opacity?: number;
+}
+
+/**
+ * Union type for all overlay configurations
+ */
+export type OverlayConfig = TextOverlay | ImageOverlay;
+
+// ============================================================================
+// Session and Status
+// ============================================================================
+
+/**
+ * Information about an active capture session
+ */
+export interface CaptureSession {
+  id: string;
+  startTime: number;
+  frameCount: number;
+  options: CaptureOptions;
+}
+
+/**
+ * Current capture status
+ */
+export interface CaptureStatus {
+  state: CaptureState;
+  session: CaptureSession | null;
+  isPaused: boolean;
+}
+
+// ============================================================================
+// Event Interfaces
+// ============================================================================
+
+/**
+ * Re-export event types from NativeFrameCapture for consistency
+ * These are defined in NativeFrameCapture.ts for codegen compatibility
+ */
+import type {
+  FrameCapturedEvent,
+  CaptureErrorEvent,
+  CaptureStopEvent,
+  CaptureStartEvent,
+  StorageWarningEvent,
+  CapturePauseEvent,
+  CaptureResumeEvent,
+  OverlayErrorEvent,
+} from './NativeFrameCapture';
+
+export type {
+  FrameCapturedEvent,
+  CaptureErrorEvent,
+  CaptureStopEvent,
+  CaptureStartEvent,
+  StorageWarningEvent,
+  CapturePauseEvent,
+  CaptureResumeEvent,
+  OverlayErrorEvent,
+};
+
+/**
+ * Union type for all event callbacks
+ */
+export type CaptureEventCallback =
+  | ((event: FrameCapturedEvent) => void)
+  | ((event: CaptureErrorEvent) => void)
+  | ((event: CaptureStopEvent) => void)
+  | ((event: CaptureStartEvent) => void)
+  | ((event: StorageWarningEvent) => void)
+  | ((event: CapturePauseEvent) => void)
+  | ((event: CaptureResumeEvent) => void)
+  | ((event: OverlayErrorEvent) => void);

package/src/validation.ts

@@ -0,0 +1,321 @@
+/**
+ * Input validation utilities
+ * @module validation
+ */
+
+import { CaptureErrorCode } from './types';
+import { CaptureError } from './errors';
+import {
+  MIN_INTERVAL,
+  MAX_INTERVAL,
+  MIN_QUALITY,
+  MAX_QUALITY,
+} from './constants';
+import type { CaptureOptions } from './types';
+
+/**
+ * Validates capture options
+ * @throws {CaptureError} if validation fails
+ */
+export function validateOptions(options: Partial<CaptureOptions>): void {
+  // Validate capture config
+  if (options.capture) {
+    const { interval } = options.capture;
+
+    if (interval !== undefined) {
+      if (
+        typeof interval !== 'number' ||
+        interval < MIN_INTERVAL ||
+        interval > MAX_INTERVAL
+      ) {
+        throw new CaptureError(
+          CaptureErrorCode.INVALID_OPTIONS,
+          `capture.interval must be a number between ${MIN_INTERVAL} and ${MAX_INTERVAL} milliseconds`
+        );
+      }
+    }
+  }
+
+  // Validate image config
+  if (options.image) {
+    const { quality, format, scaleResolution, region, excludeStatusBar } =
+      options.image;
+
+    if (quality !== undefined) {
+      if (
+        typeof quality !== 'number' ||
+        quality < MIN_QUALITY ||
+        quality > MAX_QUALITY
+      ) {
+        throw new CaptureError(
+          CaptureErrorCode.INVALID_OPTIONS,
+          `image.quality must be a number between ${MIN_QUALITY} and ${MAX_QUALITY}`
+        );
+      }
+    }
+
+    if (format !== undefined) {
+      if (format !== 'png' && format !== 'jpeg') {
+        throw new CaptureError(
+          CaptureErrorCode.INVALID_OPTIONS,
+          `image.format must be either 'png' or 'jpeg'`
+        );
+      }
+    }
+
+    if (scaleResolution !== undefined) {
+      if (
+        typeof scaleResolution !== 'number' ||
+        scaleResolution < 0.1 ||
+        scaleResolution > 1.0
+      ) {
+        throw new CaptureError(
+          CaptureErrorCode.INVALID_OPTIONS,
+          `image.scaleResolution must be a number between 0.1 and 1.0`
+        );
+      }
+    }
+
+    if (region !== undefined) {
+      validateCaptureRegion(region);
+    }
+
+    if (
+      excludeStatusBar !== undefined &&
+      typeof excludeStatusBar !== 'boolean'
+    ) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `image.excludeStatusBar must be a boolean`
+      );
+    }
+  }
+
+  // Validate storage config
+  if (options.storage) {
+    const {
+      saveFrames,
+      location,
+      outputDirectory,
+      warningThreshold,
+      fileNaming,
+    } = options.storage;
+
+    if (saveFrames !== undefined && typeof saveFrames !== 'boolean') {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `storage.saveFrames must be a boolean`
+      );
+    }
+
+    if (location !== undefined) {
+      if (location !== 'private' && location !== 'public') {
+        throw new CaptureError(
+          CaptureErrorCode.INVALID_OPTIONS,
+          `storage.location must be either 'private' or 'public'`
+        );
+      }
+    }
+
+    if (outputDirectory !== undefined) {
+      if (
+        typeof outputDirectory !== 'string' ||
+        outputDirectory.trim() === ''
+      ) {
+        throw new CaptureError(
+          CaptureErrorCode.INVALID_OPTIONS,
+          `storage.outputDirectory must be a non-empty string`
+        );
+      }
+    }
+
+    if (warningThreshold !== undefined) {
+      if (typeof warningThreshold !== 'number' || warningThreshold < 0) {
+        throw new CaptureError(
+          CaptureErrorCode.INVALID_OPTIONS,
+          `storage.warningThreshold must be a non-negative number (bytes)`
+        );
+      }
+    }
+
+    if (fileNaming) {
+      validateFileNaming(fileNaming);
+    }
+  }
+
+  // Validate performance config
+  if (options.performance) {
+    validatePerformance(options.performance);
+  }
+}
+
+/**
+ * Validates file naming configuration
+ */
+function validateFileNaming(fn: any): void {
+  if (fn.prefix !== undefined) {
+    if (typeof fn.prefix !== 'string' || fn.prefix.trim() === '') {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `storage.fileNaming.prefix must be a non-empty string`
+      );
+    }
+    if (/[<>:"/\\|?*]/.test(fn.prefix)) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `storage.fileNaming.prefix contains invalid filename characters`
+      );
+    }
+  }
+
+  if (fn.dateFormat !== undefined) {
+    if (typeof fn.dateFormat !== 'string' || fn.dateFormat.trim() === '') {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `storage.fileNaming.dateFormat must be a non-empty string`
+      );
+    }
+  }
+
+  if (fn.framePadding !== undefined) {
+    if (
+      typeof fn.framePadding !== 'number' ||
+      fn.framePadding < 1 ||
+      fn.framePadding > 10
+    ) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `storage.fileNaming.framePadding must be between 1 and 10`
+      );
+    }
+  }
+}
+
+/**
+ * Validates performance configuration
+ */
+function validatePerformance(perf: any): void {
+  if (perf.overlayCacheSize !== undefined) {
+    if (
+      typeof perf.overlayCacheSize !== 'number' ||
+      perf.overlayCacheSize < 0
+    ) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `performance.overlayCacheSize must be a non-negative number (bytes)`
+      );
+    }
+  }
+
+  if (perf.imageReaderBuffers !== undefined) {
+    if (
+      typeof perf.imageReaderBuffers !== 'number' ||
+      perf.imageReaderBuffers < 1 ||
+      perf.imageReaderBuffers > 10
+    ) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `performance.imageReaderBuffers must be between 1 and 10`
+      );
+    }
+  }
+
+  if (perf.executorShutdownTimeout !== undefined) {
+    if (
+      typeof perf.executorShutdownTimeout !== 'number' ||
+      perf.executorShutdownTimeout < 100 ||
+      perf.executorShutdownTimeout > 30000
+    ) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `performance.executorShutdownTimeout must be between 100 and 30000ms`
+      );
+    }
+  }
+
+  if (perf.executorForcedShutdownTimeout !== undefined) {
+    if (
+      typeof perf.executorForcedShutdownTimeout !== 'number' ||
+      perf.executorForcedShutdownTimeout < 100 ||
+      perf.executorForcedShutdownTimeout > 10000
+    ) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `performance.executorForcedShutdownTimeout must be between 100 and 10000ms`
+      );
+    }
+  }
+}
+
+/**
+ * Validates capture region configuration
+ */
+function validateCaptureRegion(region: any): void {
+  const unit = region.unit || 'percentage';
+
+  if (
+    typeof region.x !== 'number' ||
+    typeof region.y !== 'number' ||
+    typeof region.width !== 'number' ||
+    typeof region.height !== 'number'
+  ) {
+    throw new CaptureError(
+      CaptureErrorCode.INVALID_OPTIONS,
+      `image.region coordinates must be numbers`
+    );
+  }
+
+  if (unit === 'percentage') {
+    if (
+      region.x < 0 ||
+      region.x > 1 ||
+      region.y < 0 ||
+      region.y > 1 ||
+      region.width < 0 ||
+      region.width > 1 ||
+      region.height < 0 ||
+      region.height > 1
+    ) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `image.region percentage values must be between 0 and 1`
+      );
+    }
+    if (region.x + region.width > 1 || region.y + region.height > 1) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `image.region extends beyond screen bounds (x + width or y + height > 1)`
+      );
+    }
+  } else if (unit === 'pixels') {
+    if (region.width <= 0 || region.height <= 0) {
+      throw new CaptureError(
+        CaptureErrorCode.INVALID_OPTIONS,
+        `image.region width and height must be positive`
+      );
+    }
+  }
+}
+
+/**
+ * Merges user options with defaults
+ */
+export function mergeOptions(
+  options?: Partial<CaptureOptions>
+): CaptureOptions {
+  return {
+    capture: {
+      interval: 1000,
+      ...options?.capture,
+    },
+    image: {
+      quality: 80,
+      format: 'jpeg',
+      ...options?.image,
+    },
+    storage: options?.storage,
+    performance: options?.performance,
+    notification: options?.notification,
+    overlays: options?.overlays,
+  };
+}