@servicemind.tis/angular-image-and-file-picker 1.0.0

package/lib/interfaces/socket-adapter.interface.d.ts

@@ -0,0 +1,315 @@
+import { Observable } from 'rxjs';
+/**
+ * Interface that the host application must implement to enable
+ * remote upload functionality via WebSocket.
+ *
+ * This allows the library to leverage an existing WebSocket connection
+ * from the host application instead of creating its own.
+ */
+export interface AngularSocketAdapter {
+    /**
+     * Subscribe to a channel and return an Observable of messages
+     * @param channelName - The channel name to subscribe to
+     * @returns Observable that emits messages received on the channel
+     */
+    subscribeToChannel(channelName: string): Observable<any>;
+    /**
+     * Subscribe to channels matching a prefix (optional)
+     * @param prefix - The prefix to match channel names
+     * @returns Observable that emits messages from matching channels
+     */
+    subscribeToChannelPrefix?(prefix: string): Observable<any>;
+    /**
+     * Unsubscribe from a channel
+     * @param channelName - The channel name to unsubscribe from
+     */
+    unsubscribeFromChannel?(channelName: string): void;
+    /**
+     * Get unique device/browser ID for pairing
+     * @returns Device ID string or Promise that resolves to device ID
+     */
+    getDeviceId(): string | Promise<string>;
+    /**
+     * Check if socket is currently connected
+     * @returns true if connected, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Observable that emits connection status changes
+     */
+    connectionStatus$: Observable<boolean>;
+    /**
+     * Get current auth token (for passing to mobile app)
+     * @returns Current access token or null
+     */
+    getAuthToken?(): string | null | Promise<string | null>;
+    /**
+     * Get current refresh token (for passing to mobile app)
+     * @returns Current refresh token or null
+     */
+    getRefreshToken?(): string | null | Promise<string | null>;
+    /**
+     * Get the WebSocket URL (for passing to mobile app)
+     * @returns WebSocket URL string
+     */
+    getSocketUrl?(): string;
+    /**
+     * Get the API base URL (for passing to mobile app)
+     * @returns API base URL string
+     */
+    getApiUrl?(): string;
+    /**
+     * Get the current user ID
+     * @returns User ID string
+     */
+    getUserId?(): string | Promise<string>;
+    /**
+     * Send a message directly via socket (for handshake and communication)
+     * @param message - The message to send { action: string; data: any }
+     */
+    sendViaSocket?(message: {
+        action: string;
+        data: any;
+    }): void;
+    /**
+     * Call API via socket and get response as Observable
+     * @param route - The API route to call
+     * @param body - The request body
+     * @returns Observable that emits the API response
+     */
+    callApiViaSocket?(route: string, body: any): Observable<any>;
+}
+/**
+ * Configuration for remote upload feature
+ */
+export interface AngularRemoteUploadConfig {
+    /**
+     * Enable/disable remote upload feature
+     */
+    enabled: boolean;
+    /**
+     * Socket adapter implementation from host app
+     */
+    socketAdapter?: AngularSocketAdapter;
+    /**
+     * API endpoints for remote upload operations
+     */
+    apiEndpoints?: AngularRemoteUploadApiEndpoints;
+    /**
+     * QR code configuration
+     */
+    qrCode?: AngularQrCodeConfig;
+    /**
+     * Pairing configuration
+     */
+    pairing?: AngularPairingConfig;
+    /**
+     * Auto-accept files from mobile without manual confirmation
+     * When true: Files are automatically shown in the component UI and attached to the form.
+     *            The onFileAccept callback is also called for additional processing.
+     * When false: Files are NOT shown in the component UI or attached to the form.
+     *             Only the onFileAccept callback is called, allowing the host app to
+     *             handle the file display and processing in a custom way.
+     * Default: false
+     */
+    autoAcceptFiles?: boolean;
+    /**
+     * Callback when a file is uploaded from mobile device
+     * - If autoAcceptFiles=true: Called after file is added to component UI and form
+     * - If autoAcceptFiles=false: Called immediately (only way to access the file)
+     * This allows the host app to handle the file (e.g., patch a form control, custom display)
+     * @param file - The uploaded file data
+     */
+    onFileAccept?: (file: AngularRemoteUploadedFile) => void;
+}
+/**
+ * API endpoints configuration for remote upload
+ */
+export interface AngularRemoteUploadApiEndpoints {
+    /**
+     * Endpoint to generate a mobile upload link token (UUID)
+     * POST request with deviceId, userId, returns { token, expiresAt }
+     * Default: {apiUrl}/ease-of-access/mobile-upload-link-token
+     */
+    generateMobileLinkToken?: string;
+    /**
+     * Endpoint to generate a pairing code (legacy)
+     * POST request with deviceId, returns { pairingCode, channel, expiresAt }
+     */
+    generatePairingCode?: string;
+    /**
+     * Endpoint to validate a pairing code (used by mobile)
+     * POST request with pairingCode, returns { valid, deviceId, channel }
+     */
+    validatePairingCode?: string;
+    /**
+     * Endpoint called by mobile after uploading to notify desktop
+     * POST request with { channel, uploadedFile }
+     */
+    notifyUpload?: string;
+    /**
+     * Channel prefix for receiving upload notifications
+     * Desktop subscribes to: {prefix}{deviceId}
+     */
+    uploadChannelPrefix: string;
+}
+/**
+ * QR code display configuration
+ */
+export interface AngularQrCodeConfig {
+    /**
+     * Base URL for the mobile upload page
+     * The full URL will be: {mobileUploadUrl}?code={pairingCode}&deviceId={deviceId}
+     */
+    mobileUploadUrl: string;
+    /**
+     * QR code expiry time in seconds (default: 300 = 5 minutes)
+     */
+    expirySeconds?: number;
+    /**
+     * Size of the QR code in pixels (default: 200)
+     */
+    size?: number;
+    /**
+     * Logo URL to display in the center of QR code (optional)
+     */
+    logoUrl?: string;
+}
+/**
+ * Pairing persistence configuration
+ */
+export interface AngularPairingConfig {
+    /**
+     * Whether to persist pairing in localStorage (default: true)
+     */
+    persistInStorage?: boolean;
+    /**
+     * Storage key for pairing data (default: 'angular-remote-upload-pairing')
+     */
+    storageKey?: string;
+    /**
+     * How long pairing remains valid in milliseconds (default: 24 hours)
+     * Set to 0 for session-only pairing
+     */
+    pairingTTL?: number;
+    /**
+     * Whether to auto-reconnect on page reload if pairing exists
+     */
+    autoReconnect?: boolean;
+}
+/**
+ * Pairing session data stored in localStorage
+ */
+export interface AngularPairingSession {
+    /**
+     * Unique pairing code
+     */
+    pairingCode: string;
+    /**
+     * Desktop device ID
+     */
+    desktopDeviceId: string;
+    /**
+     * Mobile device ID (set after mobile connects)
+     */
+    mobileDeviceId?: string;
+    /**
+     * WebSocket channel for communication
+     */
+    channel: string;
+    /**
+     * When the pairing was created
+     */
+    createdAt: number;
+    /**
+     * When the pairing expires
+     */
+    expiresAt: number;
+    /**
+     * Current pairing status
+     */
+    status: 'pending' | 'connected' | 'disconnected' | 'expired';
+    /**
+     * Last activity timestamp
+     */
+    lastActivity?: number;
+}
+/**
+ * Event emitted when a remote upload is received
+ */
+export interface AngularRemoteUploadEvent {
+    /**
+     * The uploaded file data
+     */
+    file: AngularRemoteUploadedFile;
+    /**
+     * Mobile device ID that uploaded the file
+     */
+    mobileDeviceId: string;
+    /**
+     * Timestamp of the upload
+     */
+    timestamp: number;
+    /**
+     * Session ID for grouping multiple uploads
+     */
+    sessionId?: string;
+}
+/**
+ * File data received from remote upload
+ */
+export interface AngularRemoteUploadedFile {
+    /**
+     * S3 or cloud storage URL of the uploaded file
+     */
+    s3Url: string;
+    /**
+     * Original filename
+     */
+    fileName: string;
+    /**
+     * File MIME type
+     */
+    mimeType: string;
+    /**
+     * File size in bytes
+     */
+    size: number;
+    /**
+     * Thumbnail URL (for images)
+     */
+    thumbnailUrl?: string;
+    /**
+     * Additional metadata from the upload
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Upload data from presigned URL response
+     */
+    uploadData?: any;
+}
+/**
+ * Message format for WebSocket communication
+ */
+export interface AngularRemoteUploadMessage {
+    /**
+     * Message type
+     */
+    type: 'pairing_request' | 'pairing_accepted' | 'upload_started' | 'upload_progress' | 'upload_complete' | 'upload_error' | 'disconnect';
+    /**
+     * Channel name
+     */
+    channel: string;
+    /**
+     * Message payload
+     */
+    payload: any;
+    /**
+     * Sender device ID
+     */
+    senderId: string;
+    /**
+     * Timestamp
+     */
+    timestamp: number;
+}

package/lib/pipes/time-ago.pipe.d.ts

@@ -0,0 +1,7 @@
+import { PipeTransform } from '@angular/core';
+import * as i0 from "@angular/core";
+export declare class TimeAgoPipe implements PipeTransform {
+    transform(timestamp: number | undefined, format?: 'short' | 'long'): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TimeAgoPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<TimeAgoPipe, "timeAgo", false>;
+}

package/lib/services/angular-helper.service.d.ts

@@ -0,0 +1,45 @@
+import { HttpClient, HttpErrorResponse } from '@angular/common/http';
+import { MatDialog, MatDialogRef } from '@angular/material/dialog';
+import { MatSnackBar, MatSnackBarRef, TextOnlySnackBar } from '@angular/material/snack-bar';
+import { AngularErrorDialogComponent } from '../angular-error-dialog/angular-error-dialog.component';
+import { Observable } from 'rxjs';
+import * as i0 from "@angular/core";
+export declare class AngularHelperService {
+    private snackBar;
+    private dialog;
+    private http;
+    constructor(snackBar: MatSnackBar, dialog: MatDialog, http: HttpClient);
+    showHttpErrorMsg(error: HttpErrorResponse, duration?: number): MatDialogRef<AngularErrorDialogComponent, any> | MatSnackBarRef<TextOnlySnackBar>;
+    showSuccessMsg(message: string, title: string, duration?: number): void;
+    showErrorMsg(message: string, title: string, duration?: number): void;
+    /**
+     * Compresses an image file to ensure it's under MAX_COMPRESSED_FILE_SIZE_MB.
+     * Uses iterative compression with decreasing quality levels while maintaining aspect ratio.
+     * @param image - Data URL string or File object
+     * @param mimeType - The MIME type of the image (e.g., 'image/jpeg', 'image/png')
+     * @returns Promise<Blob> - The compressed image as a Blob
+     */
+    compressFile(image: any, mimeType: string): Promise<Blob>;
+    /**
+     * Formats file size in human-readable format
+     */
+    private formatFileSize;
+    /**
+     * Checks if the given MIME type is a compressible image format
+     */
+    private isCompressibleImage;
+    /**
+     * Gets file extension from MIME type
+     */
+    private getExtensionFromMimeType;
+    dataURItoBlob(dataURI: string, mimeType: string): Blob;
+    getDataUrlFromFile(file: any): Promise<unknown>;
+    getUploadUrl(url: string, filename: string, mimeType: string, type: string): Observable<any>;
+    attachFilesToEntity(url: string, data: any, limit: number): Observable<any>;
+    updateTag(url: string, data: any): Observable<any>;
+    updateSequence(url: string, data: any): Observable<any>;
+    putFile(url: string, file: File | Blob | ArrayBuffer, contentType?: string): Observable<any>;
+    deleteUploadedFile(url: string, data: any): Observable<any>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AngularHelperService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AngularHelperService>;
+}

package/lib/services/angular-remote-upload.service.d.ts

@@ -0,0 +1,273 @@
+import { OnDestroy } from '@angular/core';
+import { Observable } from 'rxjs';
+import { HttpClient } from '@angular/common/http';
+import { AngularRemoteUploadConfig, AngularPairingSession, AngularRemoteUploadEvent } from '../interfaces/socket-adapter.interface';
+import * as i0 from "@angular/core";
+/**
+ * Mobile connection info stored in localStorage
+ */
+interface MobileConnectionInfo {
+    mobileDeviceId: string;
+    connectedAt: number;
+    lastActivity: number;
+}
+/**
+ * Field request info for tracking current upload request
+ */
+export interface FieldRequestInfo {
+    label: string;
+    accept: string;
+    type: 'image' | 'file';
+    entityType?: string;
+    entityId?: any;
+    isMultiple?: boolean;
+    limit?: number;
+    remainingSlots?: number;
+    isCompressed?: boolean;
+    requestId?: string;
+    requestedAt: number;
+}
+/**
+ * Device online status from health check API
+ */
+export interface DeviceOnlineStatus {
+    isOnline: boolean;
+    deviceId: string;
+    lastPing?: number;
+    connectionId?: string;
+}
+/**
+ * Combined device status for both desktop and mobile
+ */
+export interface DevicesOnlineStatus {
+    desktop: DeviceOnlineStatus;
+    mobile: DeviceOnlineStatus;
+    lastChecked: number;
+    isReadyForTransfer: boolean;
+}
+export declare class AngularRemoteUploadService implements OnDestroy {
+    private http;
+    private static readonly COMPONENT;
+    private static readonly MOBILE_CONNECTION_KEY;
+    private static readonly LEGACY_MOBILE_CONNECTION_KEY;
+    private destroy$;
+    private channelSubscription;
+    private healthCheckSubscription;
+    private config;
+    private socketAdapter;
+    private deviceId;
+    private userId;
+    private apiUrl;
+    private channelName;
+    private pairingSession$;
+    private connectionStatus$;
+    private mobileConnection$;
+    private remoteUpload$;
+    private error$;
+    private pendingFiles$;
+    private isWaitingForUpload$;
+    private currentFieldRequest$;
+    private devicesStatus$;
+    private isCheckingStatus$;
+    constructor(http: HttpClient);
+    /**
+     * Configure the remote upload service
+     */
+    configure(config: AngularRemoteUploadConfig): Promise<void>;
+    /**
+     * Get desktop device ID
+     */
+    getDesktopDeviceId(): string;
+    /**
+     * Get current mobile connection info
+     */
+    getMobileConnection(): Observable<MobileConnectionInfo | null>;
+    /**
+     * Get current mobile device ID (if connected)
+     */
+    getMobileDeviceId(): string | null;
+    /**
+     * Get current pairing session
+     */
+    getPairingSession(): Observable<AngularPairingSession | null>;
+    /**
+     * Get connection status
+     */
+    getConnectionStatus(): Observable<'disconnected' | 'pending' | 'connected'>;
+    /**
+     * Get remote upload events
+     */
+    getRemoteUploads(): Observable<AngularRemoteUploadEvent>;
+    /**
+     * Get error events
+     */
+    getErrors(): Observable<string>;
+    /**
+     * Check if remote upload is available (configured and socket connected)
+     */
+    isAvailable(): boolean;
+    /**
+     * Check if currently connected to a mobile device
+     */
+    isConnectedToMobile(): boolean;
+    /**
+     * Alias for isConnectedToMobile - Check if paired with mobile
+     */
+    isPaired(): boolean;
+    /**
+     * Get devices online status (both desktop and mobile)
+     */
+    getDevicesStatus(): Observable<DevicesOnlineStatus | null>;
+    /**
+     * Get current devices status value
+     */
+    getDevicesStatusValue(): DevicesOnlineStatus | null;
+    /**
+     * Check if currently verifying connection status (for blinking indicator)
+     */
+    getIsCheckingStatus(): Observable<boolean>;
+    /**
+     * Check if both devices are online and ready for transfer
+     */
+    isReadyForTransfer(): boolean;
+    /**
+     * Get pending files from mobile (waiting to be accepted/rejected)
+     */
+    getPendingFiles(): Observable<AngularRemoteUploadEvent[]>;
+    /**
+     * Get current pending files value
+     */
+    getPendingFilesValue(): AngularRemoteUploadEvent[];
+    /**
+     * Check if waiting for mobile upload
+     */
+    getIsWaitingForUpload(): Observable<boolean>;
+    /**
+     * Get current field request info
+     */
+    getCurrentFieldRequest(): Observable<FieldRequestInfo | null>;
+    /**
+     * Accept a pending file (emit to remoteUpload$ and call onFileAccept callback)
+     */
+    acceptPendingFile(file: AngularRemoteUploadEvent): void;
+    /**
+     * Reject/delete a pending file
+     */
+    rejectPendingFile(file: AngularRemoteUploadEvent): void;
+    /**
+     * Clear all pending files
+     */
+    clearPendingFiles(): void;
+    /**
+     * Generate QR code data for mobile app
+     * Flow:
+     * 1. Call API to get a short-lived link token (UUID)
+     * 2. Build QR URL with: apiUrl, deviceId, userId, token
+     */
+    generateQrCode(): Promise<{
+        qrData: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Build QR URL with minimal parameters
+     */
+    private buildQrUrl;
+    /**
+     * Call API via socket with timeout - helper method
+     */
+    private callApiWithTimeout;
+    /**
+     * Send field request to mobile - tells mobile to show upload UI for this field
+     */
+    sendFieldRequest(fieldInfo: {
+        label: string;
+        accept: string;
+        type: 'image' | 'file';
+        entityType?: string;
+        entityId?: any;
+        isMultiple?: boolean;
+        limit?: number;
+        remainingSlots?: number;
+        isCompressed?: boolean;
+    }): Promise<void>;
+    /**
+     * Cancel current field request
+     */
+    cancelFieldRequest(): Promise<void>;
+    /**
+     * Accept mobile connection - update local state
+     * Note: Backend already broadcasts mobile-link-established to both parties
+     */
+    private acceptMobileConnection;
+    /**
+     * Disconnect from mobile device - call API and clear local state
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Handle disconnect initiated from remote (mobile) side
+     */
+    private handleRemoteDisconnect;
+    /**
+     * Start periodic health check for device online status
+     * Should be called when connection is established
+     */
+    startHealthCheck(): void;
+    /**
+     * Stop health check
+     */
+    stopHealthCheck(): void;
+    /**
+     * Check if both devices are online via API
+     */
+    checkDevicesOnline(): Promise<DevicesOnlineStatus | null>;
+    /**
+     * Force an immediate health check
+     */
+    refreshDevicesStatus(): Promise<DevicesOnlineStatus | null>;
+    /**
+     * Subscribe to channel for receiving messages from mobile
+     */
+    private subscribeToChannel;
+    /**
+     * Handle incoming channel messages from mobile
+     */
+    private handleChannelMessage;
+    /**
+     * Handle mobile-link-established message
+     * This is sent when mobile successfully connects via the backend
+     */
+    private handleMobileLinkEstablished;
+    /**
+     * Handle connection state messages from mobile
+     */
+    private handleConnectionState;
+    /**
+     * Handle upload complete from mobile
+     * Files are either auto-accepted or added to pending queue based on config
+     */
+    private handleUploadComplete;
+    /**
+     * Handle mobile disconnect
+     */
+    private handleMobileDisconnect;
+    /**
+     * Save mobile connection to localStorage
+     */
+    private saveMobileConnection;
+    /**
+     * Restore mobile connection from localStorage
+     */
+    private restoreMobileConnection;
+    /**
+     * Clear mobile connection from localStorage
+     */
+    private clearMobileConnection;
+    /**
+     * Call HTTP API endpoint
+     */
+    private callHttpApi;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AngularRemoteUploadService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AngularRemoteUploadService>;
+}
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@servicemind.tis/angular-image-and-file-picker",
+  "version": "1.0.0",
+  "description": "Angular image and file upload component with drag-and-drop, pre-signed URL uploads, client-side compression, camera capture, and built-in preview for images, PDFs, video, and Excel.",
+  "keywords": [
+    "angular",
+    "angular-material",
+    "file-upload",
+    "image-upload",
+    "drag-and-drop",
+    "file-viewer",
+    "pdf-viewer",
+    "image-compression",
+    "camera-capture"
+  ],
+  "author": "Thai Informatics System",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Thai-Informatics-System/angular-image-and-file-picker.git"
+  },
+  "homepage": "https://github.com/Thai-Informatics-System/angular-image-and-file-picker#readme",
+  "bugs": {
+    "url": "https://github.com/Thai-Informatics-System/angular-image-and-file-picker/issues"
+  },
+  "peerDependencies": {
+    "@angular/common": "^19.2.0",
+    "@angular/core": "^19.2.0",
+    "@angular/material": "^19.2.8",
+    "@angular/cdk": "^19.2.8",
+    "ngx-extended-pdf-viewer": "^19.2.1",
+    "angularx-qrcode": "^19.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "browser-image-compression": "^2.0.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "fesm2022/servicemind.tis-angular-image-and-file-picker.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/servicemind.tis-angular-image-and-file-picker.mjs"
+    }
+  }
+}

package/public-api.d.ts

@@ -0,0 +1,7 @@
+export * from './lib/angular-image-and-file-picker.service';
+export * from './lib/angular-image-and-file-picker/angular-image-and-file-picker.component';
+export * from './lib/angular-image-and-file-picker.module';
+export * from './lib/interfaces';
+export * from './lib/services/angular-remote-upload.service';
+export * from './lib/angular-qr-code-dialog/angular-qr-code-dialog.component';
+export * from './lib/angular-camera-capture-dialog/angular-camera-capture-dialog.component';