@angular-helpers/browser-web-apis 21.0.1 → 21.1.0

package/package.json

@@ -1,12 +1,7 @@
 {
   "name": "@angular-helpers/browser-web-apis",
-  "version": "21.0.1",
+  "version": "21.1.0",
   "description": "Sistema de servicios Angular para acceso formalizado a Browser Web APIs (cámara, permisos, geolocalización, etc.)",
-  "main": "dist/browser-web-apis/browser-web-apis.d.ts",
-  "types": "dist/browser-web-apis/browser-web-apis.d.ts",
-  "files": [
-    "dist"
-  ],
   "keywords": [
     "angular",
     "typescript",

package/types/angular-helpers-browser-web-apis.d.ts

@@ -0,0 +1,537 @@
+import { Observable } from 'rxjs';
+import * as i0 from '@angular/core';
+import { DestroyRef, EnvironmentProviders } from '@angular/core';
+import { CanActivateFn } from '@angular/router';
+
+type PermissionNameExt = PermissionName | 'clipboard-read' | 'clipboard-write';
+interface PermissionRequest {
+    name: PermissionNameExt;
+    state: PermissionState;
+}
+interface BrowserPermissions {
+    query(descriptor: PermissionDescriptor): Promise<PermissionStatus>;
+    isSupported(): boolean;
+}
+
+declare class PermissionsService implements BrowserPermissions {
+    query(descriptor: PermissionDescriptor): Promise<PermissionStatus>;
+    isSupported(): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PermissionsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PermissionsService>;
+}
+
+/**
+ * Base class for all Browser Web API services
+ * Provides common functionality for:
+ * - Support checking
+ * - Permission management
+ * - Error handling
+ * - Lifecycle management with destroyRef
+ * - Logging
+ */
+declare abstract class BrowserApiBaseService {
+    protected permissionsService: PermissionsService;
+    protected destroyRef: DestroyRef;
+    protected platformId: Object;
+    /**
+     * Abstract method that must be implemented by child services
+     * Returns the API name for support checking
+     */
+    protected abstract getApiName(): string;
+    /**
+     * Check if running in browser environment using Angular's platform detection
+     */
+    protected isBrowserEnvironment(): boolean;
+    /**
+     * Check if running in server environment using Angular's platform detection
+     */
+    protected isServerEnvironment(): boolean;
+    /**
+     * Request a permission
+     */
+    protected requestPermission(permission: PermissionNameExt): Promise<boolean>;
+    /**
+     * Create an error with proper cause chaining
+     */
+    protected createError(message: string, cause?: unknown): Error;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BrowserApiBaseService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BrowserApiBaseService>;
+}
+
+declare class CameraService extends BrowserApiBaseService {
+    private currentStream;
+    protected getApiName(): string;
+    private ensureCameraSupport;
+    startCamera(constraints?: MediaStreamConstraints): Promise<MediaStream>;
+    stopCamera(): void;
+    switchCamera(deviceId: string, constraints?: MediaStreamConstraints): Promise<MediaStream>;
+    getCameraCapabilities(deviceId: string): Promise<MediaTrackCapabilities | null>;
+    getCurrentStream(): MediaStream | null;
+    isStreaming(): boolean;
+    getVideoInputDevices(): Promise<MediaDeviceInfo[]>;
+    getNativeMediaDevices(): MediaDevices;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CameraService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CameraService>;
+}
+
+declare class GeolocationService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    private ensureGeolocationSupport;
+    getCurrentPosition(options?: PositionOptions): Promise<GeolocationPosition>;
+    watchPosition(options?: PositionOptions): Observable<GeolocationPosition>;
+    clearWatch(watchId: number): void;
+    getNativeGeolocation(): Geolocation;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GeolocationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<GeolocationService>;
+}
+
+interface DisplayMediaConstraints {
+    video?: boolean | MediaTrackConstraints;
+    audio?: boolean | MediaTrackConstraints;
+}
+declare class MediaDevicesService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    private ensureMediaDevicesSupport;
+    getDevices(): Promise<MediaDeviceInfo[]>;
+    getUserMedia(constraints?: MediaStreamConstraints): Promise<MediaStream>;
+    getDisplayMedia(constraints?: DisplayMediaConstraints): Promise<MediaStream>;
+    watchDeviceChanges(): Observable<MediaDeviceInfo[]>;
+    getVideoInputDevices(): Promise<MediaDeviceInfo[]>;
+    getAudioInputDevices(): Promise<MediaDeviceInfo[]>;
+    getAudioOutputDevices(): Promise<MediaDeviceInfo[]>;
+    private getDevicesByKind;
+    private handleMediaError;
+    getNativeMediaDevices(): MediaDevices;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MediaDevicesService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MediaDevicesService>;
+}
+
+declare class NotificationService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    get permission(): NotificationPermission;
+    isSupported(): boolean;
+    requestNotificationPermission(): Promise<NotificationPermission>;
+    showNotification(title: string, options?: NotificationOptions): Promise<Notification>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NotificationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NotificationService>;
+}
+
+declare class ClipboardService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    private ensureClipboardPermission;
+    writeText(text: string): Promise<void>;
+    readText(): Promise<string>;
+    writeTextSecure(text: string): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ClipboardService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ClipboardService>;
+}
+
+type BrowserCapabilityId = 'permissions' | 'geolocation' | 'clipboard' | 'notification' | 'mediaDevices' | 'camera' | 'webWorker' | 'regexSecurity' | 'webStorage' | 'webShare' | 'battery' | 'webSocket';
+declare class BrowserCapabilityService {
+    getCapabilities(): readonly [{
+        readonly id: "permissions";
+        readonly label: "Permissions API";
+        readonly requiresSecureContext: false;
+    }, {
+        readonly id: "geolocation";
+        readonly label: "Geolocation API";
+        readonly requiresSecureContext: true;
+    }, {
+        readonly id: "clipboard";
+        readonly label: "Clipboard API";
+        readonly requiresSecureContext: true;
+    }, {
+        readonly id: "notification";
+        readonly label: "Notification API";
+        readonly requiresSecureContext: true;
+    }, {
+        readonly id: "mediaDevices";
+        readonly label: "MediaDevices API";
+        readonly requiresSecureContext: true;
+    }, {
+        readonly id: "camera";
+        readonly label: "Camera API";
+        readonly requiresSecureContext: true;
+    }, {
+        readonly id: "webWorker";
+        readonly label: "Web Worker API";
+        readonly requiresSecureContext: false;
+    }, {
+        readonly id: "regexSecurity";
+        readonly label: "Regex Security";
+        readonly requiresSecureContext: false;
+    }, {
+        readonly id: "webStorage";
+        readonly label: "Web Storage";
+        readonly requiresSecureContext: false;
+    }, {
+        readonly id: "webShare";
+        readonly label: "Web Share";
+        readonly requiresSecureContext: true;
+    }, {
+        readonly id: "battery";
+        readonly label: "Battery API";
+        readonly requiresSecureContext: false;
+    }, {
+        readonly id: "webSocket";
+        readonly label: "WebSocket API";
+        readonly requiresSecureContext: false;
+    }];
+    isSecureContext(): boolean;
+    isSupported(capability: BrowserCapabilityId): boolean;
+    getAllStatuses(): {
+        id: "camera" | "geolocation" | "permissions" | "mediaDevices" | "clipboard" | "notification" | "webWorker" | "regexSecurity" | "webStorage" | "webShare" | "battery" | "webSocket";
+        label: "Permissions API" | "Geolocation API" | "Clipboard API" | "Notification API" | "MediaDevices API" | "Camera API" | "Web Worker API" | "Regex Security" | "Web Storage" | "Web Share" | "Battery API" | "WebSocket API";
+        supported: boolean;
+        secureContext: boolean;
+        requiresSecureContext: boolean;
+    }[];
+    getPermissionState(permission: PermissionName): Promise<PermissionState | 'unknown'>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BrowserCapabilityService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BrowserCapabilityService>;
+}
+
+interface BatteryInfo {
+    charging: boolean;
+    chargingTime: number;
+    dischargingTime: number;
+    level: number;
+}
+interface BatteryManager extends EventTarget {
+    readonly charging: boolean;
+    readonly chargingTime: number;
+    readonly dischargingTime: number;
+    readonly level: number;
+    addEventListener(type: 'chargingchange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: 'levelchange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: 'chargingtimechange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: 'dischargingtimechange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: 'chargingchange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: 'levelchange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: 'chargingtimechange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: 'dischargingtimechange', listener: (this: BatteryManager, ev: Event) => void, options?: boolean | EventListenerOptions): void;
+}
+declare global {
+    interface Navigator {
+        getBattery?: () => Promise<BatteryManager>;
+    }
+}
+
+declare class BatteryService extends BrowserApiBaseService {
+    private batteryManager;
+    protected getApiName(): string;
+    private ensureBatterySupport;
+    initialize(): Promise<BatteryInfo>;
+    getBatteryInfo(): BatteryInfo;
+    watchBatteryInfo(): Observable<BatteryInfo>;
+    private setupEventListeners;
+    getNativeBatteryManager(): BatteryManager;
+    isCharging(): boolean;
+    getLevel(): number;
+    getChargingTime(): number;
+    getDischargingTime(): number;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BatteryService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BatteryService>;
+}
+
+interface ShareResult {
+    shared: boolean;
+    error?: string;
+}
+declare class WebShareService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    private ensureWebShareSupport;
+    share(data: ShareData): Promise<ShareResult>;
+    canShare(): boolean;
+    canShareFiles(): boolean;
+    getNativeShare(): typeof navigator.share;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WebShareService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WebShareService>;
+}
+
+type BrowserError = Error & {
+    name?: string;
+    message?: string;
+};
+type EventHandler<T = Event> = (event: T) => void;
+type StorageValue = string | number | boolean | object | null;
+type ErrorCallback = (error: BrowserError) => void;
+
+interface StorageOptions {
+    prefix?: string;
+    serialize?: (value: StorageValue) => string;
+    deserialize?: (value: string) => StorageValue;
+}
+interface StorageEvent {
+    key: string;
+    newValue: StorageValue | null;
+    oldValue: StorageValue | null;
+    storageArea: 'localStorage' | 'sessionStorage';
+}
+declare class WebStorageService extends BrowserApiBaseService {
+    private storageEvents;
+    protected destroyRef: DestroyRef;
+    constructor();
+    protected getApiName(): string;
+    private ensureStorageSupport;
+    private setupEventListeners;
+    private serializeValue;
+    private deserializeValue;
+    private getKey;
+    setLocalStorage<T extends StorageValue>(key: string, value: T, options?: StorageOptions): boolean;
+    getLocalStorage<T extends StorageValue>(key: string, defaultValue?: T | null, options?: StorageOptions): T | null;
+    removeLocalStorage(key: string, options?: StorageOptions): boolean;
+    clearLocalStorage(options?: StorageOptions): boolean;
+    setSessionStorage<T extends StorageValue>(key: string, value: T, options?: StorageOptions): boolean;
+    getSessionStorage<T extends StorageValue>(key: string, defaultValue?: T | null, options?: StorageOptions): T | null;
+    removeSessionStorage(key: string, options?: StorageOptions): boolean;
+    clearSessionStorage(options?: StorageOptions): boolean;
+    getLocalStorageSize(options?: StorageOptions): number;
+    getSessionStorageSize(options?: StorageOptions): number;
+    getStorageEvents(): Observable<StorageEvent>;
+    watchLocalStorage<T extends StorageValue>(key: string, options?: StorageOptions): Observable<T | null>;
+    watchSessionStorage<T extends StorageValue>(key: string, options?: StorageOptions): Observable<T | null>;
+    getNativeLocalStorage(): Storage;
+    getNativeSessionStorage(): Storage;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WebStorageService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WebStorageService>;
+}
+
+interface WebSocketConfig {
+    url: string;
+    protocols?: string | string[];
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+    heartbeatInterval?: number;
+    heartbeatMessage?: unknown;
+}
+interface WebSocketMessage<T = unknown> {
+    type: string;
+    data: T;
+    timestamp?: number;
+}
+interface WebSocketStatus {
+    connected: boolean;
+    connecting: boolean;
+    reconnecting: boolean;
+    error?: string;
+    reconnectAttempts: number;
+}
+declare class WebSocketService extends BrowserApiBaseService {
+    private webSocket;
+    private statusSubject;
+    private messageSubject;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private heartbeatTimer;
+    protected getApiName(): string;
+    private ensureWebSocketSupport;
+    connect(config: WebSocketConfig): Observable<WebSocketStatus>;
+    disconnect(): void;
+    send<T>(message: WebSocketMessage<T>): void;
+    sendRaw(data: string): void;
+    getStatus(): Observable<WebSocketStatus>;
+    getMessages<T = unknown>(): Observable<WebSocketMessage<T>>;
+    private setupWebSocketHandlers;
+    private startHeartbeat;
+    private attemptReconnect;
+    private updateStatus;
+    private getCurrentStatus;
+    getNativeWebSocket(): WebSocket | null;
+    isConnected(): boolean;
+    getReadyState(): number;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WebSocketService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WebSocketService>;
+}
+
+interface WorkerMessage<T = unknown> {
+    id: string;
+    type: string;
+    data: T;
+    timestamp: number;
+}
+interface WorkerStatus {
+    initialized: boolean;
+    running: boolean;
+    error?: string;
+    messageCount: number;
+}
+interface WorkerTask<T = unknown> {
+    id: string;
+    type: string;
+    data: T;
+    transferable?: Transferable[];
+}
+declare class WebWorkerService extends BrowserApiBaseService {
+    protected destroyRef: DestroyRef;
+    private workers;
+    private workerStatuses;
+    private workerMessages;
+    private currentWorkerStatuses;
+    protected getApiName(): string;
+    private ensureWorkerSupport;
+    createWorker(name: string, scriptUrl: string): Observable<WorkerStatus>;
+    terminateWorker(name: string): void;
+    terminateAllWorkers(): void;
+    postMessage(workerName: string, task: WorkerTask): void;
+    getMessages(workerName: string): Observable<WorkerMessage>;
+    getStatus(workerName: string): Observable<WorkerStatus>;
+    getCurrentStatus(workerName: string): WorkerStatus | undefined;
+    getAllStatuses(): Map<string, WorkerStatus>;
+    isWorkerRunning(workerName: string): boolean;
+    private setupWorker;
+    private updateWorkerStatus;
+    getNativeWorker(name: string): Worker | undefined;
+    getAllWorkers(): Map<string, Worker>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WebWorkerService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WebWorkerService>;
+}
+
+interface MediaDevice {
+    deviceId: string;
+    groupId: string;
+    kind: MediaDeviceKind;
+    label: string;
+}
+type MediaDeviceKind = 'videoinput' | 'audioinput' | 'audiooutput';
+interface MediaStreamConstraints$1 {
+    video?: boolean | MediaTrackConstraints$1;
+    audio?: boolean | MediaTrackConstraints$1;
+}
+interface MediaTrackConstraints$1 {
+    width?: number | ConstrainULong;
+    height?: number | ConstrainULong;
+    facingMode?: string | ConstrainDOMString;
+    deviceId?: string | ConstrainDOMString;
+    groupId?: string | ConstrainDOMString;
+    frameRate?: number | ConstrainDouble;
+    aspectRatio?: number | ConstrainDouble;
+    sampleRate?: number | ConstrainULong;
+    sampleSize?: number | ConstrainULong;
+    echoCancellation?: boolean | ConstrainBoolean;
+    noiseSuppression?: boolean | ConstrainBoolean;
+    autoGainControl?: boolean | ConstrainBoolean;
+}
+interface CameraCapabilities {
+    width: {
+        min: number;
+        max: number;
+        step: number;
+    };
+    height: {
+        min: number;
+        max: number;
+        step: number;
+    };
+    aspectRatio: {
+        min: number;
+        max: number;
+        step: number;
+    };
+    frameRate: {
+        min: number;
+        max: number;
+        step: number;
+    };
+    facingMode: string[];
+}
+interface CameraInfo {
+    deviceId: string;
+    label: string;
+    capabilities?: CameraCapabilities;
+    kind: 'videoinput';
+}
+interface MediaDevicesInfo {
+    videoInputs: CameraInfo[];
+    audioInputs: MediaDevice[];
+    audioOutputs: MediaDevice[];
+}
+
+interface GeolocationPosition$1 {
+    coords: GeolocationCoordinates;
+    timestamp: number;
+}
+interface GeolocationCoordinates {
+    latitude: number;
+    longitude: number;
+    altitude: number | null;
+    accuracy: number;
+    altitudeAccuracy: number | null;
+    heading: number | null;
+    speed: number | null;
+}
+interface GeolocationOptions {
+    enableHighAccuracy?: boolean;
+    timeout?: number;
+    maximumAge?: number;
+}
+interface GeolocationError {
+    code: number;
+    message: string;
+    PERMISSION_DENIED: number;
+    POSITION_UNAVAILABLE: number;
+    TIMEOUT: number;
+}
+interface GeolocationWatchOptions extends GeolocationOptions {
+    maximumAge?: number;
+}
+
+declare class BrowserSupportUtil {
+    static isSupported(feature: string): boolean;
+    static getUnsupportedFeatures(): string[];
+    static isSecureContext(): boolean;
+    static getUserAgent(): string;
+    static isMobile(): boolean;
+    static isDesktop(): boolean;
+    static getBrowserInfo(): {
+        name: string;
+        version: string;
+        isChrome: boolean;
+        isFirefox: boolean;
+        isSafari: boolean;
+        isEdge: boolean;
+    };
+    private static getBrowserName;
+    private static getBrowserVersion;
+}
+
+/**
+ * Functional guard that checks if the user has the required permission.
+ * Usage in routes: { canActivate: [permissionGuard('camera')] }
+ */
+declare const permissionGuard: (permission: PermissionNameExt) => CanActivateFn;
+
+interface BrowserWebApisConfig {
+    enableCamera?: boolean;
+    enableGeolocation?: boolean;
+    enableNotifications?: boolean;
+    enableClipboard?: boolean;
+    enableMediaDevices?: boolean;
+    enableBattery?: boolean;
+    enableWebShare?: boolean;
+    enableWebStorage?: boolean;
+    enableWebSocket?: boolean;
+    enableWebWorker?: boolean;
+}
+declare const defaultBrowserWebApisConfig: BrowserWebApisConfig;
+declare function provideBrowserWebApis(config?: BrowserWebApisConfig): EnvironmentProviders;
+declare function provideCamera(): EnvironmentProviders;
+declare function provideGeolocation(): EnvironmentProviders;
+declare function provideNotifications(): EnvironmentProviders;
+declare function provideClipboard(): EnvironmentProviders;
+declare function provideMediaDevices(): EnvironmentProviders;
+declare function provideBattery(): EnvironmentProviders;
+declare function provideWebShare(): EnvironmentProviders;
+declare function provideWebStorage(): EnvironmentProviders;
+declare function provideWebSocket(): EnvironmentProviders;
+declare function provideWebWorker(): EnvironmentProviders;
+declare function providePermissions(): EnvironmentProviders;
+declare function provideMediaApis(): EnvironmentProviders;
+declare function provideLocationApis(): EnvironmentProviders;
+declare function provideStorageApis(): EnvironmentProviders;
+declare function provideCommunicationApis(): EnvironmentProviders;
+
+declare const version = "0.1.0";
+
+export { BatteryService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, GeolocationService, MediaDevicesService, NotificationService, PermissionsService, WebShareService, WebSocketService, WebStorageService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, permissionGuard, provideBattery, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideGeolocation, provideLocationApis, provideMediaApis, provideMediaDevices, provideNotifications, providePermissions, provideStorageApis, provideWebShare, provideWebSocket, provideWebStorage, provideWebWorker, version };
+export type { BatteryInfo, BatteryManager, BrowserCapabilityId, BrowserError, BrowserPermissions, BrowserWebApisConfig, CameraCapabilities, CameraInfo, ErrorCallback, EventHandler, GeolocationCoordinates, GeolocationError, GeolocationOptions, GeolocationPosition$1 as GeolocationPosition, GeolocationWatchOptions, MediaDevice, MediaDeviceKind, MediaDevicesInfo, MediaStreamConstraints$1 as MediaStreamConstraints, MediaTrackConstraints$1 as MediaTrackConstraints, PermissionNameExt, PermissionRequest, StorageEvent, StorageOptions, StorageValue, WebSocketConfig, WebSocketMessage, WebSocketStatus, WorkerMessage, WorkerStatus, WorkerTask };