@uploadista/react-native-core 0.0.3

package/src/types/types.ts

@@ -0,0 +1,359 @@
+/**
+ * Core types for React Native Uploadista client
+ */
+
+/**
+ * Options for file picker operations
+ */
+export interface PickerOptions {
+  /** Allowed file types/MIME types */
+  allowedTypes?: string[];
+  /** Allow multiple selection */
+  allowMultiple?: boolean;
+  /** Maximum file size in bytes */
+  maxSize?: number;
+}
+
+/**
+ * Options for camera operations
+ */
+export interface CameraOptions {
+  /** Camera to use: 'front' or 'back' */
+  cameraType?: "front" | "back";
+  /** Image quality (0-1) */
+  quality?: number;
+  /** Maximum width for captured image */
+  maxWidth?: number;
+  /** Maximum height for captured image */
+  maxHeight?: number;
+}
+
+/**
+ * Result from a file pick operation
+ */
+export interface FilePickResult {
+  /** URI to the file (platform-specific format) */
+  uri: string;
+  /** File name with extension */
+  name: string;
+  /** File size in bytes */
+  size: number;
+  /** MIME type of the file (if available) */
+  mimeType?: string;
+  /** Local file path (if available) */
+  localPath?: string;
+}
+
+/**
+ * Information about a file
+ */
+export interface FileInfo {
+  /** URI to the file */
+  uri: string;
+  /** File name */
+  name: string;
+  /** File size in bytes */
+  size: number;
+  /** MIME type (if available) */
+  mimeType?: string;
+  /** Last modified timestamp */
+  modificationTime?: number;
+}
+
+/**
+ * Interface for file system abstraction layer
+ * Provides pluggable access to file system APIs across different RN environments
+ */
+export interface FileSystemProvider {
+  /**
+   * Opens a document picker for selecting files
+   * @param options - Configuration for the picker
+   * @returns Promise resolving to picked file information
+   */
+  pickDocument(options?: PickerOptions): Promise<FilePickResult>;
+
+  /**
+   * Opens an image picker for selecting images from gallery
+   * @param options - Configuration for the picker
+   * @returns Promise resolving to picked image information
+   */
+  pickImage(options?: PickerOptions): Promise<FilePickResult>;
+
+  /**
+   * Opens a video picker for selecting videos from gallery
+   * @param options - Configuration for the picker
+   * @returns Promise resolving to picked video information
+   */
+  pickVideo(options?: PickerOptions): Promise<FilePickResult>;
+
+  /**
+   * Captures a photo using the device camera
+   * @param options - Configuration for camera
+   * @returns Promise resolving to captured photo information
+   */
+  pickCamera(options?: CameraOptions): Promise<FilePickResult>;
+
+  /**
+   * Gets a URI for a document that can be read
+   * @param filePath - Path to the document
+   * @returns Promise resolving to accessible URI
+   */
+  getDocumentUri(filePath: string): Promise<string>;
+
+  /**
+   * Reads file contents as ArrayBuffer
+   * @param uri - URI to read from
+   * @returns Promise resolving to file contents as ArrayBuffer
+   */
+  readFile(uri: string): Promise<ArrayBuffer>;
+
+  /**
+   * Gets information about a file
+   * @param uri - URI of the file
+   * @returns Promise resolving to file information
+   */
+  getFileInfo(uri: string): Promise<FileInfo>;
+}
+
+/**
+ * Configuration for file system provider
+ */
+export interface FileSystemProviderConfig {
+  /** Type of provider: 'expo' or 'native' */
+  type?: "expo" | "native";
+  /** Custom provider instance */
+  provider?: FileSystemProvider;
+}
+
+/**
+ * Upload state
+ */
+export type UploadState =
+  | "idle"
+  | "pending"
+  | "uploading"
+  | "success"
+  | "error"
+  | "cancelled";
+
+/**
+ * Upload progress information
+ */
+export interface UploadProgress {
+  /** Current state of upload */
+  state: UploadState;
+  /** Progress percentage (0-100) */
+  progress: number;
+  /** Bytes uploaded */
+  uploadedBytes: number;
+  /** Total bytes to upload */
+  totalBytes: number;
+  /** Upload speed in bytes per second */
+  uploadSpeed?: number;
+  /** Estimated time remaining in milliseconds */
+  timeRemaining?: number;
+  /** Error message if state is 'error' */
+  error?: Error;
+}
+
+/**
+ * Single file upload state
+ */
+export interface SingleUploadState extends UploadProgress {
+  /** File name */
+  fileName: string;
+  /** File size */
+  fileSize: number;
+  /** Result from server after successful upload */
+  result?: unknown;
+}
+
+/**
+ * Multi-file upload item
+ */
+export interface UploadItem {
+  /** Unique identifier for this upload */
+  id: string;
+  /** File information */
+  file: FilePickResult;
+  /** Upload progress */
+  progress: UploadProgress;
+  /** Result from server if successful */
+  result?: unknown;
+}
+
+/**
+ * Multi-file upload state
+ */
+export interface MultiUploadState {
+  /** All upload items */
+  items: UploadItem[];
+  /** Aggregate progress */
+  progress: number;
+  /** Total uploads */
+  total: number;
+  /** Completed uploads */
+  completed: number;
+  /** Failed uploads */
+  failed: number;
+}
+
+/**
+ * Flow upload state
+ */
+export interface FlowUploadState {
+  /** Job ID for the flow */
+  jobId?: string;
+  /** Overall state */
+  state: UploadState;
+  /** Progress percentage */
+  progress: number;
+  /** Flow execution results */
+  result?: unknown;
+  /** Error if failed */
+  error?: Error;
+}
+
+/**
+ * Options for single upload hook
+ */
+export interface UseSingleUploadOptions {
+  /** Flow ID to use for upload */
+  flowId?: string;
+  /** Field name for file */
+  fieldName?: string;
+  /** Additional form data */
+  metadata?: Record<string, string>;
+  /** Enable retry on failure */
+  autoRetry?: boolean;
+  /** Maximum retry attempts */
+  maxRetries?: number;
+}
+
+/**
+ * Options for multi-upload hook
+ */
+export interface UseMultiUploadOptions {
+  /** Max concurrent uploads */
+  maxConcurrent?: number;
+  /** Additional form data for all uploads */
+  metadata?: Record<string, string>;
+  /** Called when a file upload succeeds */
+  onSuccess?: (result: unknown) => void;
+  /** Called when a file upload fails */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Options for flow upload hook
+ */
+export interface UseFlowUploadOptions {
+  /** Flow ID to execute */
+  flowId: string;
+  /** Storage ID for the upload */
+  storageId: string;
+  /** Output node ID for the flow */
+  outputNodeId?: string;
+  /** Metadata to pass to flow */
+  metadata?: Record<string, unknown>;
+  /** Called when upload succeeds */
+  onSuccess?: (result: unknown) => void;
+  /** Called when upload fails */
+  onError?: (error: Error) => void;
+  /** Called when upload progress updates */
+  onProgress?: (
+    progress: number,
+    bytesUploaded: number,
+    totalBytes: number | null,
+  ) => void;
+  /** Called when a chunk completes */
+  onChunkComplete?: (
+    chunkSize: number,
+    bytesAccepted: number,
+    bytesTotal: number | null,
+  ) => void;
+}
+
+/**
+ * Options for camera upload hook
+ */
+export interface UseCameraUploadOptions {
+  /** Flow ID to use */
+  flowId?: string;
+  /** Camera options */
+  cameraOptions?: CameraOptions;
+  /** Additional metadata */
+  metadata?: Record<string, string>;
+  /** Called when upload succeeds */
+  onSuccess?: (result: unknown) => void;
+  /** Called when upload fails */
+  onError?: (error: Error) => void;
+  /** Called when upload progress updates */
+  onProgress?: (
+    progress: number,
+    bytesUploaded: number,
+    totalBytes: number | null,
+  ) => void;
+}
+
+/**
+ * Options for gallery upload hook
+ */
+export interface UseGalleryUploadOptions {
+  /** Flow ID to use */
+  flowId?: string;
+  /** Allow multiple selection */
+  allowMultiple?: boolean;
+  /** Media type: 'photo', 'video', or 'mixed' */
+  mediaType?: "photo" | "video" | "mixed";
+  /** Additional metadata */
+  metadata?: Record<string, string>;
+  /** Called when upload succeeds */
+  onSuccess?: (result: unknown) => void;
+  /** Called when upload fails */
+  onError?: (error: Error) => void;
+  /** Called when upload progress updates */
+  onProgress?: (
+    progress: number,
+    bytesUploaded: number,
+    totalBytes: number | null,
+  ) => void;
+}
+
+/**
+ * Options for file upload hook
+ */
+export interface UseFileUploadOptions {
+  /** Flow ID to use */
+  flowId?: string;
+  /** Allowed file types */
+  allowedTypes?: string[];
+  /** Additional metadata */
+  metadata?: Record<string, string>;
+  /** Called when upload succeeds */
+  onSuccess?: (result: unknown) => void;
+  /** Called when upload fails */
+  onError?: (error: Error) => void;
+  /** Called when upload progress updates */
+  onProgress?: (
+    progress: number,
+    bytesUploaded: number,
+    totalBytes: number | null,
+  ) => void;
+}
+
+/**
+ * Metrics for upload performance
+ */
+export interface UploadMetrics {
+  /** Total bytes uploaded */
+  totalBytes: number;
+  /** Total upload duration in milliseconds */
+  durationMs: number;
+  /** Average upload speed in bytes/second */
+  avgSpeed: number;
+  /** Peak upload speed in bytes/second */
+  peakSpeed: number;
+  /** Number of retries */
+  retries: number;
+}

package/src/types/upload-input.ts

@@ -0,0 +1 @@
+export type ReactNativeUploadInput = Blob | File | string | { uri: string };

package/src/utils/fileHelpers.ts

@@ -0,0 +1,201 @@
+/**
+ * File utility functions for React Native uploads
+ */
+
+/**
+ * Format file size to human readable string
+ * @param bytes - Size in bytes
+ * @returns Formatted size string (e.g., "1.5 MB")
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return "0 Bytes";
+
+  const k = 1024;
+  const sizes = ["Bytes", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${Math.round((bytes / k ** i) * 100) / 100} ${sizes[i]}`;
+}
+
+/**
+ * Get MIME type from file name
+ * @param fileName - File name with extension
+ * @returns MIME type or 'application/octet-stream' as fallback
+ */
+export function getMimeTypeFromFileName(fileName: string): string {
+  const mimeTypes: Record<string, string> = {
+    // Images
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+
+    // Videos
+    ".mp4": "video/mp4",
+    ".avi": "video/x-msvideo",
+    ".mov": "video/quicktime",
+    ".wmv": "video/x-ms-wmv",
+    ".flv": "video/x-flv",
+    ".mkv": "video/x-matroska",
+    ".webm": "video/webm",
+
+    // Audio
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".aac": "audio/aac",
+    ".flac": "audio/flac",
+    ".m4a": "audio/mp4",
+
+    // Documents
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx":
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx":
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx":
+      "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".txt": "text/plain",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".zip": "application/zip",
+  };
+
+  const ext = fileName.toLowerCase().slice(fileName.lastIndexOf("."));
+  return mimeTypes[ext] || "application/octet-stream";
+}
+
+/**
+ * Check if file type is allowed
+ * @param fileName - File name to check
+ * @param allowedTypes - Array of allowed MIME types (e.g., ['image/jpeg', 'image/png'])
+ * @returns True if file type is allowed
+ */
+export function isFileTypeAllowed(
+  fileName: string,
+  allowedTypes: string[],
+): boolean {
+  if (!allowedTypes || allowedTypes.length === 0) {
+    return true;
+  }
+
+  const mimeType = getMimeTypeFromFileName(fileName);
+  return allowedTypes.some((allowed) => {
+    if (allowed.endsWith("/*")) {
+      // Handle wildcard patterns like 'image/*'
+      const [type] = allowed.split("/");
+      return mimeType.startsWith(`${type}/`);
+    }
+    return allowed === mimeType;
+  });
+}
+
+/**
+ * Check if file size is within limits
+ * @param fileSize - File size in bytes
+ * @param maxSize - Maximum allowed size in bytes (optional)
+ * @param minSize - Minimum allowed size in bytes (optional)
+ * @returns True if file size is within limits
+ */
+export function isFileSizeValid(
+  fileSize: number,
+  maxSize?: number,
+  minSize?: number,
+): boolean {
+  if (maxSize !== undefined && fileSize > maxSize) {
+    return false;
+  }
+
+  if (minSize !== undefined && fileSize < minSize) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Get file extension
+ * @param fileName - File name
+ * @returns File extension without dot (e.g., 'pdf' for 'document.pdf')
+ */
+export function getFileExtension(fileName: string): string {
+  const lastDot = fileName.lastIndexOf(".");
+  if (lastDot === -1) return "";
+  return fileName.slice(lastDot + 1).toLowerCase();
+}
+
+/**
+ * Get file name without extension
+ * @param fileName - File name
+ * @returns File name without extension
+ */
+export function getFileNameWithoutExtension(fileName: string): string {
+  const lastDot = fileName.lastIndexOf(".");
+  if (lastDot === -1) return fileName;
+  return fileName.slice(0, lastDot);
+}
+
+/**
+ * Check if file is an image
+ * @param fileName - File name
+ * @returns True if file is an image
+ */
+export function isImageFile(fileName: string): boolean {
+  const imageExtensions = [
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".webp",
+    ".svg",
+  ];
+  const ext = fileName.toLowerCase().slice(fileName.lastIndexOf("."));
+  return imageExtensions.includes(ext);
+}
+
+/**
+ * Check if file is a video
+ * @param fileName - File name
+ * @returns True if file is a video
+ */
+export function isVideoFile(fileName: string): boolean {
+  const videoExtensions = [
+    ".mp4",
+    ".avi",
+    ".mov",
+    ".wmv",
+    ".flv",
+    ".mkv",
+    ".webm",
+  ];
+  const ext = fileName.toLowerCase().slice(fileName.lastIndexOf("."));
+  return videoExtensions.includes(ext);
+}
+
+/**
+ * Check if file is a document
+ * @param fileName - File name
+ * @returns True if file is a document
+ */
+export function isDocumentFile(fileName: string): boolean {
+  const docExtensions = [
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".xls",
+    ".xlsx",
+    ".ppt",
+    ".pptx",
+    ".txt",
+    ".csv",
+  ];
+  const ext = fileName.toLowerCase().slice(fileName.lastIndexOf("."));
+  return docExtensions.includes(ext);
+}

package/src/utils/index.ts

@@ -0,0 +1,36 @@
+// File helpers
+export {
+  formatFileSize,
+  getFileExtension,
+  getFileNameWithoutExtension,
+  getMimeTypeFromFileName,
+  isDocumentFile,
+  isFileSizeValid,
+  isFileTypeAllowed,
+  isImageFile,
+  isVideoFile,
+} from "./fileHelpers";
+// Permission helpers
+export {
+  getPermissionStatus,
+  hasPermissions,
+  openAppSettings,
+  PermissionStatus,
+  PermissionType,
+  requestCameraPermission,
+  requestPermissions,
+  requestPhotoLibraryPermission,
+  requestStorageReadPermission,
+  requestStorageWritePermission,
+} from "./permissions";
+// URI helpers
+export {
+  getDirectoryFromUri,
+  getFileNameFromUri,
+  getMimeTypeFromUri,
+  isContentUri,
+  isFileUri,
+  normalizeUri,
+  pathToUri,
+  uriToPath,
+} from "./uriHelpers";