react-native-frame-capture 1.0.1

package/android/src/main/java/com/framecapture/Constants.kt

@@ -0,0 +1,196 @@
+package com.framecapture
+
+/**
+ * Constants for the FrameCapture library
+ *
+ * Centralized configuration values including:
+ * - Capture constraints (intervals, quality, formats)
+ * - Storage thresholds
+ * - Notification configuration
+ * - Service actions and intent extras
+ * - Event names for JavaScript communication
+ * - Resource management timeouts
+ */
+object Constants {
+
+    // Capture interval constraints (in milliseconds)
+    const val MIN_INTERVAL = 100L
+    const val MAX_INTERVAL = 60000L
+    const val DEFAULT_INTERVAL = 1000L
+
+    // Image quality constraints (0-100)
+    const val MIN_QUALITY = 0
+    const val MAX_QUALITY = 100
+    const val DEFAULT_QUALITY = 80
+
+    // Default image format
+    const val DEFAULT_FORMAT = "jpeg"
+
+    // Capture mode strings
+    const val CAPTURE_MODE_INTERVAL = "interval"
+
+    // Storage warning threshold (100MB in bytes) - DEFAULT VALUE
+    const val DEFAULT_STORAGE_WARNING_THRESHOLD = 100L * 1024L * 1024L
+
+    // Storage location identifiers
+    const val STORAGE_LOCATION_PUBLIC = "public"
+    const val STORAGE_LOCATION_PRIVATE = "private"
+
+    // File naming - DEFAULT VALUES
+    const val DEFAULT_FILENAME_PREFIX = "capture_"
+    const val DEFAULT_FILENAME_DATE_FORMAT = "yyyyMMdd_HHmmss_SSS"
+    const val DEFAULT_FILENAME_FRAME_PADDING = 5 // Number of digits for frame number
+
+    // Image format extensions
+    const val FORMAT_EXTENSION_PNG = "png"
+    const val FORMAT_EXTENSION_JPEG = "jpg"
+
+    // MIME types
+    const val MIME_TYPE_PNG = "image/png"
+    const val MIME_TYPE_JPEG = "image/jpeg"
+
+    // Storage directories
+    const val TEMP_FRAMES_DIRECTORY = "captured_frames"
+
+    // Foreground service notification
+    const val NOTIFICATION_ID = 1001
+    const val CHANNEL_ID = "screen_capture_channel"
+    const val CHANNEL_NAME = "Screen Capture"
+    const val CHANNEL_DESCRIPTION = "Notifications for screen capture service"
+    const val CUSTOM_CHANNEL_ID_PREFIX = "screen_capture_custom_"
+
+    // Notification priority levels
+    const val NOTIFICATION_PRIORITY_HIGH = "high"
+    const val NOTIFICATION_PRIORITY_DEFAULT = "default"
+    const val NOTIFICATION_PRIORITY_LOW = "low"
+
+    // Notification action labels
+    const val NOTIFICATION_ACTION_PAUSE = "Pause"
+    const val NOTIFICATION_ACTION_RESUME = "Resume"
+    const val NOTIFICATION_ACTION_STOP = "Stop"
+
+    // Notification default values
+    const val NOTIFICATION_DEFAULT_TITLE = "Screen Capture Active"
+    const val NOTIFICATION_DEFAULT_DESCRIPTION = "Capturing frames..."
+    const val NOTIFICATION_DEFAULT_PAUSED_TITLE = "Screen Capture Paused"
+    const val NOTIFICATION_DEFAULT_PAUSED_DESCRIPTION = "{frameCount} frames captured"
+    const val NOTIFICATION_DEFAULT_UPDATE_INTERVAL = 10
+
+    // Notification action request codes
+    const val NOTIFICATION_REQUEST_CODE_STOP = 0
+    const val NOTIFICATION_REQUEST_CODE_PAUSE_RESUME = 1
+
+    // Notification template variable
+    const val NOTIFICATION_TEMPLATE_FRAME_COUNT = "{frameCount}"
+
+    // Service actions
+    const val ACTION_START_CAPTURE = "com.framecapture.START_CAPTURE"
+    const val ACTION_STOP_CAPTURE = "com.framecapture.STOP_CAPTURE"
+    const val ACTION_PAUSE_CAPTURE = "com.framecapture.PAUSE_CAPTURE"
+    const val ACTION_RESUME_CAPTURE = "com.framecapture.RESUME_CAPTURE"
+
+    // Intent extras
+    const val EXTRA_CAPTURE_OPTIONS = "capture_options"
+    const val EXTRA_PROJECTION_DATA = "projection_data"
+
+    // MediaProjection request code
+    const val REQUEST_MEDIA_PROJECTION = 1001
+
+    // Module name
+    const val MODULE_NAME = "FrameCapture"
+
+    // Event names
+    const val EVENT_FRAME_CAPTURED = "onFrameCaptured"
+    const val EVENT_CAPTURE_ERROR = "onCaptureError"
+    const val EVENT_CAPTURE_STOP = "onCaptureStop"
+    const val EVENT_CAPTURE_START = "onCaptureStart"
+    const val EVENT_STORAGE_WARNING = "onStorageWarning"
+    const val EVENT_CAPTURE_PAUSE = "onCapturePause"
+    const val EVENT_CAPTURE_RESUME = "onCaptureResume"
+    const val EVENT_OVERLAY_ERROR = "onOverlayError"
+
+    // Resource cleanup timeout (in milliseconds) - DEFAULT VALUES
+    const val DEFAULT_EXECUTOR_SHUTDOWN_TIMEOUT = 5000L
+    const val DEFAULT_EXECUTOR_FORCED_SHUTDOWN_TIMEOUT = 1000L
+
+    // ImageReader buffer count - DEFAULT VALUE
+    const val DEFAULT_IMAGE_READER_MAX_IMAGES = 2
+
+    // Image format constants
+    const val RGBA_BYTES_PER_PIXEL = 4
+
+    // Resolution scaling constraints
+    const val MIN_SCALE_RESOLUTION = 0.1f
+    const val MAX_SCALE_RESOLUTION = 1.0f
+
+    // Overlay rendering - DEFAULT VALUES
+    const val DEFAULT_OVERLAY_IMAGE_CACHE_SIZE = 10 * 1024 * 1024 // 10MB in bytes
+    const val OVERLAY_DEFAULT_PADDING = 10 // Padding from edges in pixels
+    const val MIN_OVERLAY_OPACITY = 0.0f
+    const val MAX_OVERLAY_OPACITY = 1.0f
+
+    // Overlay types
+    const val OVERLAY_TYPE_TEXT = "text"
+    const val OVERLAY_TYPE_IMAGE = "image"
+
+    // Overlay position presets
+    const val POSITION_TOP_LEFT = "top-left"
+    const val POSITION_TOP_RIGHT = "top-right"
+    const val POSITION_BOTTOM_LEFT = "bottom-left"
+    const val POSITION_BOTTOM_RIGHT = "bottom-right"
+    const val POSITION_CENTER = "center"
+
+    // Overlay position units
+    const val POSITION_UNIT_PERCENTAGE = "percentage"
+    const val POSITION_UNIT_PIXELS = "pixels"
+
+    // Template variables
+    const val TEMPLATE_VAR_FRAME_NUMBER = "{frameNumber}"
+    const val TEMPLATE_VAR_SESSION_ID = "{sessionId}"
+    const val TEMPLATE_VAR_TIMESTAMP = "{timestamp}"
+
+    // Timestamp format for overlays
+    const val OVERLAY_TIMESTAMP_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
+    const val OVERLAY_TIMESTAMP_TIMEZONE = "UTC"
+
+    // Text style values
+    const val TEXT_WEIGHT_BOLD = "bold"
+    const val TEXT_WEIGHT_NORMAL = "normal"
+    const val TEXT_ALIGN_LEFT = "left"
+    const val TEXT_ALIGN_CENTER = "center"
+    const val TEXT_ALIGN_RIGHT = "right"
+
+    // Text style defaults
+    const val TEXT_DEFAULT_FONT_SIZE = 14
+    const val TEXT_DEFAULT_COLOR = "#FFFFFF"
+    const val TEXT_DEFAULT_BACKGROUND_COLOR = "#00000080"
+    const val TEXT_DEFAULT_PADDING = 8
+
+    // Image overlay defaults
+    const val IMAGE_DEFAULT_OPACITY = 1.0f
+
+    // URI schemes
+    const val URI_SCHEME_FILE = "file"
+    const val URI_SCHEME_CONTENT = "content"
+
+    // Resource types
+    const val RESOURCE_TYPE_DRAWABLE = "drawable"
+
+    // Hex color validation
+    const val HEX_COLOR_LENGTH_SHORT = 3  // #RGB
+    const val HEX_COLOR_LENGTH_MEDIUM = 6 // #RRGGBB
+    const val HEX_COLOR_LENGTH_LONG = 8   // #AARRGGBB
+
+    // Error detail keys
+    const val ERROR_DETAIL_PERMISSION = "permission"
+    const val ERROR_DETAIL_CURRENT_STATE = "currentState"
+    const val ERROR_DETAIL_AVAILABLE_SPACE = "availableSpace"
+    const val ERROR_DETAIL_HEAP_SIZE = "heapSize"
+    const val ERROR_DETAIL_USED_MEMORY = "usedMemory"
+    const val ERROR_DETAIL_ERRORS = "errors"
+    const val ERROR_DETAIL_ERROR_TYPE = "errorType"
+
+    // Event payload keys
+    const val EVENT_KEY_AVAILABLE_SPACE = "availableSpace"
+    const val EVENT_KEY_THRESHOLD = "threshold"
+}

package/android/src/main/java/com/framecapture/ErrorHandler.kt

@@ -0,0 +1,165 @@
+package com.framecapture
+
+import android.util.Log
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.WritableMap
+import com.framecapture.models.CaptureState
+import com.framecapture.models.ErrorCode
+import java.io.IOException
+
+/**
+ * Handles error classification, formatting, and reporting
+ *
+ * Provides consistent error handling across the module by:
+ * - Classifying exceptions into appropriate ErrorCode values
+ * - Formatting error details for JavaScript consumption
+ * - Coordinating error emission and cleanup
+ *
+ * Uses dependency injection for storage space and capture state checks
+ * to avoid tight coupling with other components.
+ */
+class ErrorHandler(
+    private val getStorageSpace: () -> Long,
+    private val getCaptureState: () -> CaptureState
+) {
+
+    /**
+     * Classifies exception into error code, message, and details
+     *
+     * Maps common exceptions to appropriate ErrorCode values and provides
+     * contextual details for debugging (e.g., available storage, current state).
+     *
+     * @param error The exception to classify
+     * @return Triple of (ErrorCode, error message, optional details map)
+     */
+    fun classifyError(error: Exception): Triple<ErrorCode, String, Map<String, Any>?> {
+        return when (error) {
+            is SecurityException -> Triple(
+                ErrorCode.PERMISSION_DENIED,
+                "Required permission not granted: ${error.message}",
+                mapOf(Constants.ERROR_DETAIL_PERMISSION to "MEDIA_PROJECTION")
+            )
+
+            is IllegalStateException -> Triple(
+                ErrorCode.ALREADY_CAPTURING,
+                "Capture session is already active: ${error.message}",
+                mapOf(Constants.ERROR_DETAIL_CURRENT_STATE to getCaptureState().value)
+            )
+
+            is IllegalArgumentException -> Triple(
+                ErrorCode.INVALID_OPTIONS,
+                "Invalid configuration: ${error.message}",
+                null
+            )
+
+            is IOException -> Triple(
+                ErrorCode.STORAGE_ERROR,
+                "Failed to save frame: ${error.message}",
+                mapOf(Constants.ERROR_DETAIL_AVAILABLE_SPACE to getStorageSpace())
+            )
+
+            is OutOfMemoryError -> Triple(
+                ErrorCode.SYSTEM_ERROR,
+                "Out of memory during capture",
+                mapOf(Constants.ERROR_DETAIL_HEAP_SIZE to Runtime.getRuntime().maxMemory())
+            )
+
+            else -> Triple(
+                ErrorCode.SYSTEM_ERROR,
+                "Unexpected error: ${error.message ?: "Unknown error"}",
+                null
+            )
+        }
+    }
+
+    /**
+     * Creates error map for promise rejection and event emission
+     *
+     * Formats error information into a WritableMap that can be sent to JavaScript.
+     * Handles various data types in the details map (String, Int, Long, Boolean, List).
+     *
+     * @param code Error code enum value
+     * @param message Human-readable error message
+     * @param details Optional map of additional error context
+     * @return WritableMap formatted for React Native bridge
+     */
+    fun createErrorMap(
+        code: ErrorCode,
+        message: String,
+        details: Map<String, Any>?
+    ): WritableMap {
+        return Arguments.createMap().apply {
+            putString("code", code.value)
+            putString("message", message)
+            details?.let { detailsMap ->
+                val detailsWritableMap = Arguments.createMap()
+                detailsMap.forEach { (key, value) ->
+                    when (value) {
+                        is String -> detailsWritableMap.putString(key, value)
+                        is Int -> detailsWritableMap.putInt(key, value)
+                        is Double -> detailsWritableMap.putDouble(key, value)
+                        is Long -> detailsWritableMap.putDouble(key, value.toDouble())
+                        is Boolean -> detailsWritableMap.putBoolean(key, value)
+                        is List<*> -> {
+                            val array = Arguments.createArray()
+                            value.forEach { item ->
+                                when (item) {
+                                    is String -> array.pushString(item)
+                                    else -> array.pushString(item.toString())
+                                }
+                            }
+                            detailsWritableMap.putArray(key, array)
+                        }
+                        else -> detailsWritableMap.putString(key, value.toString())
+                    }
+                }
+                putMap("details", detailsWritableMap)
+            }
+        }
+    }
+
+    /**
+     * Handles error with logging, classification, and promise rejection
+     *
+     * Orchestrates the complete error handling flow:
+     * 1. Classifies the error
+     * 2. Logs for debugging
+     * 3. Performs cleanup via callback
+     * 4. Emits error event to JavaScript
+     * 5. Rejects promise if provided
+     *
+     * @param error The exception that occurred
+     * @param promise Optional promise to reject
+     * @param onEmitError Callback to emit error event
+     * @param onCleanup Callback to perform cleanup
+     */
+    fun handleError(
+        error: Exception,
+        promise: Promise?,
+        onEmitError: (ErrorCode, String, Map<String, Any>?) -> Unit,
+        onCleanup: () -> Unit
+    ) {
+        val (code, message, details) = classifyError(error)
+
+        // Log for debugging
+        Log.e(TAG, "Capture error: $message", error)
+
+        // Clean up resources on error
+        try {
+            onCleanup()
+        } catch (cleanupError: Exception) {
+            Log.e(TAG, "Error during cleanup: ${cleanupError.message}", cleanupError)
+        }
+
+        // Emit error event
+        onEmitError(code, message, details)
+
+        // Reject promise if provided
+        promise?.reject(code.value, message, createErrorMap(code, message, details))
+    }
+
+    companion object {
+        private const val TAG = "ErrorHandler"
+    }
+}