@angular-helpers/browser-web-apis 21.3.0 → 21.4.0

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@angular-helpers/browser-web-apis",
-  "version": "21.3.0",
+  "version": "21.4.0",
   "description": "Sistema de servicios Angular para acceso formalizado a Browser Web APIs (cámara, permisos, geolocalización, etc.)",
+  "homepage": "https://gaspar1992.github.io/angular-helpers/docs/browser-web-apis",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Gaspar1992/angular-helpers"
+  },
+  "bugs": {
+    "url": "https://github.com/Gaspar1992/angular-helpers/issues"
+  },
   "keywords": [
     "angular",
     "typescript",

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

@@ -21,44 +21,74 @@ declare class PermissionsService implements BrowserPermissions {
 }
 
 /**
- * Base class for all Browser Web API services
+ * Base class for all Browser Web API services.
  * Provides common functionality for:
- * - Support checking
- * - Permission management
- * - Error handling
+ * - Platform detection (browser vs server)
+ * - Support assertion via Template Method
+ * - Error creation with cause chaining
+ * - Structured logging
  * - Lifecycle management with destroyRef
- * - Logging
+ *
+ * Services that also need permission querying should extend
+ * `PermissionAwareBrowserApiBaseService` instead.
  */
 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
+     * Abstract method that must be implemented by child services.
+     * Returns the API name used in log messages and error strings.
      */
     protected abstract getApiName(): string;
     /**
-     * Check if running in browser environment using Angular's platform detection
+     * 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
+     * Check if running in server environment using Angular's platform detection.
      */
     protected isServerEnvironment(): boolean;
     /**
-     * Request a permission
+     * Template Method: throws a standard error when the API is not available.
+     * Uses getApiName() to produce consistent error messages.
      */
-    protected requestPermission(permission: PermissionNameExt): Promise<boolean>;
+    protected ensureSupported(): void;
     /**
-     * Create an error with proper cause chaining
+     * Create an error with proper cause chaining.
      */
     protected createError(message: string, cause?: unknown): Error;
+    /**
+     * Log an error with the service name as prefix.
+     */
+    protected logError(message: string, error?: unknown): void;
+    /**
+     * Log an informational message with the service name as prefix.
+     */
+    protected logInfo(message: string): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<BrowserApiBaseService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<BrowserApiBaseService>;
 }
 
-declare class CameraService extends BrowserApiBaseService {
+/**
+ * Extension of `BrowserApiBaseService` for services that need to query
+ * browser permissions via the Permissions API.
+ *
+ * Only services that actively call `requestPermission()` should extend this
+ * class. All other services should extend `BrowserApiBaseService` directly
+ * to avoid carrying an unnecessary PermissionsService dependency.
+ */
+declare abstract class PermissionAwareBrowserApiBaseService extends BrowserApiBaseService {
+    protected permissionsService: PermissionsService;
+    /**
+     * Query the Permissions API for the given permission name.
+     * Returns `true` if the permission state is `'granted'`.
+     */
+    protected requestPermission(permission: PermissionNameExt): Promise<boolean>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PermissionAwareBrowserApiBaseService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PermissionAwareBrowserApiBaseService>;
+}
+
+declare class CameraService extends PermissionAwareBrowserApiBaseService {
     private currentStream;
     protected getApiName(): string;
     private ensureCameraSupport;
@@ -116,12 +146,11 @@ declare class NotificationService extends BrowserApiBaseService {
     static ɵprov: i0.ɵɵInjectableDeclaration<NotificationService>;
 }
 
-declare class ClipboardService extends BrowserApiBaseService {
+declare class ClipboardService extends PermissionAwareBrowserApiBaseService {
     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>;
 }
@@ -324,7 +353,6 @@ declare class BatteryService extends BrowserApiBaseService {
     initialize(): Promise<BatteryInfo>;
     getBatteryInfo(): BatteryInfo;
     watchBatteryInfo(): Observable<BatteryInfo>;
-    private setupEventListeners;
     getNativeBatteryManager(): BatteryManager;
     isCharging(): boolean;
     getLevel(): number;
@@ -497,8 +525,8 @@ interface IntersectionObserverOptions {
     rootMargin?: string;
     threshold?: number | number[];
 }
-declare class IntersectionObserverService {
-    private readonly platformId;
+declare class IntersectionObserverService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     observe(element: Element, options?: IntersectionObserverOptions): Observable<IntersectionObserverEntry[]>;
     observeVisibility(element: Element, options?: IntersectionObserverOptions): Observable<boolean>;
@@ -515,8 +543,8 @@ interface ElementSize {
     inlineSize: number;
     blockSize: number;
 }
-declare class ResizeObserverService {
-    private readonly platformId;
+declare class ResizeObserverService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     observe(element: Element, options?: ResizeObserverOptions): Observable<ResizeObserverEntry[]>;
     observeSize(element: Element, options?: ResizeObserverOptions): Observable<ElementSize>;
@@ -525,8 +553,8 @@ declare class ResizeObserverService {
 }
 
 type VisibilityState = 'visible' | 'hidden' | 'prerender';
-declare class PageVisibilityService {
-    private readonly platformId;
+declare class PageVisibilityService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     get isHidden(): boolean;
     get visibilityState(): VisibilityState;
@@ -536,12 +564,46 @@ declare class PageVisibilityService {
     static ɵprov: i0.ɵɵInjectableDeclaration<PageVisibilityService>;
 }
 
-declare class BroadcastChannelService {
-    private readonly destroyRef;
-    private readonly platformId;
-    private channels;
+/**
+ * Base class for services that manage a named registry of persistent
+ * connections (e.g. BroadcastChannel, EventSource, WebSocket pools).
+ *
+ * Implements the Template Method pattern: subclasses define how a single
+ * native connection is closed via `closeNativeConnection()`, while this
+ * class handles the Map lifecycle (remove, closeAll, getActiveKeys).
+ *
+ * Public-facing method names (`close`, `disconnect`, `getOpenChannels`, etc.)
+ * remain the responsibility of the concrete service to preserve the public API.
+ */
+declare abstract class ConnectionRegistryBaseService<T> extends BrowserApiBaseService {
+    protected readonly connections: Map<string, T>;
+    /**
+     * Template Method: close a single native connection.
+     * Implemented by each concrete service.
+     */
+    protected abstract closeNativeConnection(connection: T): void;
+    /**
+     * Remove and close the connection registered under `key`.
+     * Safe to call even if the key does not exist.
+     */
+    protected removeConnection(key: string): void;
+    /**
+     * Close all registered connections and clear the registry.
+     */
+    protected closeAllConnections(): void;
+    /**
+     * Return the keys of all currently open connections.
+     */
+    protected getConnectionKeys(): string[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<ConnectionRegistryBaseService<any>, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ConnectionRegistryBaseService<any>>;
+}
+
+declare class BroadcastChannelService extends ConnectionRegistryBaseService<BroadcastChannel> {
+    protected getApiName(): string;
+    protected closeNativeConnection(channel: BroadcastChannel): void;
     isSupported(): boolean;
-    private ensureSupport;
+    private ensureBroadcastChannelSupported;
     open<T = unknown>(name: string): Observable<T>;
     post<T = unknown>(name: string, data: T): void;
     close(name: string): void;
@@ -562,8 +624,8 @@ interface NetworkInformation {
     saveData?: boolean;
     online: boolean;
 }
-declare class NetworkInformationService {
-    private readonly platformId;
+declare class NetworkInformationService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     getSnapshot(): NetworkInformation;
     watch(): Observable<NetworkInformation>;
@@ -596,8 +658,8 @@ interface OrientationInfo {
     type: OrientationType;
     angle: number;
 }
-declare class ScreenOrientationService {
-    private readonly platformId;
+declare class ScreenOrientationService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     getSnapshot(): OrientationInfo;
     get isPortrait(): boolean;
@@ -609,9 +671,8 @@ declare class ScreenOrientationService {
     static ɵprov: i0.ɵɵInjectableDeclaration<ScreenOrientationService>;
 }
 
-declare class FullscreenService {
-    private readonly destroyRef;
-    private readonly platformId;
+declare class FullscreenService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     get isFullscreen(): boolean;
     get fullscreenElement(): Element | null;
@@ -703,12 +764,11 @@ interface SSEConfig {
     withCredentials?: boolean;
     eventTypes?: string[];
 }
-declare class ServerSentEventsService {
-    private readonly destroyRef;
-    private readonly platformId;
-    private sources;
+declare class ServerSentEventsService extends ConnectionRegistryBaseService<EventSource> {
+    protected getApiName(): string;
+    protected closeNativeConnection(source: EventSource): void;
     isSupported(): boolean;
-    private ensureSupport;
+    private ensureSSESupported;
     connect<T = unknown>(url: string, config?: SSEConfig): Observable<SSEMessage<T>>;
     disconnect(url: string): void;
     disconnectAll(): void;
@@ -725,8 +785,8 @@ interface VibrationPreset {
     notification: VibrationPattern;
     doubleTap: VibrationPattern;
 }
-declare class VibrationService {
-    private readonly platformId;
+declare class VibrationService extends BrowserApiBaseService {
+    protected getApiName(): string;
     readonly presets: VibrationPreset;
     isSupported(): boolean;
     vibrate(pattern?: VibrationPattern): boolean;
@@ -747,11 +807,10 @@ interface SpeechOptions {
     rate?: number;
     pitch?: number;
 }
-declare class SpeechSynthesisService {
-    private readonly destroyRef;
-    private readonly platformId;
+declare class SpeechSynthesisService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
-    private ensureSupport;
+    private ensureSpeechSynthesisSupported;
     get state(): SpeechState;
     get isPending(): boolean;
     getVoices(): SpeechSynthesisVoice[];
@@ -774,8 +833,8 @@ interface MutationObserverOptions {
     attributeFilter?: string[];
 }
 
-declare class MutationObserverService {
-    private readonly platformId;
+declare class MutationObserverService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     observe(target: Node, options?: MutationObserverOptions): Observable<MutationRecord[]>;
     static ɵfac: i0.ɵɵFactoryDeclaration<MutationObserverService, never>;
@@ -789,8 +848,8 @@ interface PerformanceObserverConfig {
     buffered?: boolean;
 }
 
-declare class PerformanceObserverService {
-    private readonly platformId;
+declare class PerformanceObserverService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     observe(config: PerformanceObserverConfig): Observable<PerformanceEntryList>;
     observeByType(type: PerformanceEntryType, buffered?: boolean): Observable<PerformanceEntryList>;
@@ -808,8 +867,8 @@ interface IdleState {
 interface IdleDetectorOptions {
     threshold?: number;
 }
-declare class IdleDetectorService {
-    private readonly platformId;
+declare class IdleDetectorService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     requestPermission(): Promise<PermissionState>;
     watch(options?: IdleDetectorOptions): Observable<IdleState>;
@@ -820,8 +879,8 @@ declare class IdleDetectorService {
 interface ColorSelectionResult {
     sRGBHex: string;
 }
-declare class EyeDropperService {
-    private readonly platformId;
+declare class EyeDropperService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     open(signal?: AbortSignal): Promise<ColorSelectionResult>;
     static ɵfac: i0.ɵɵFactoryDeclaration<EyeDropperService, never>;
@@ -838,8 +897,8 @@ interface DetectedBarcode {
     format: BarcodeFormat;
     rawValue: string;
 }
-declare class BarcodeDetectorService {
-    private readonly platformId;
+declare class BarcodeDetectorService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     getSupportedFormats(): Promise<BarcodeFormat[]>;
     detect(image: ImageBitmapSource, formats?: BarcodeFormat[]): Promise<DetectedBarcode[]>;
@@ -852,9 +911,8 @@ interface AudioAnalyserData {
     frequencyData: Uint8Array;
     timeDomainData: Uint8Array;
 }
-declare class WebAudioService {
-    private readonly platformId;
-    private readonly destroyRef;
+declare class WebAudioService extends BrowserApiBaseService {
+    protected getApiName(): string;
     private context;
     isSupported(): boolean;
     getContext(): AudioContext;
@@ -883,8 +941,8 @@ interface GamepadState {
     timestamp: number;
 }
 
-declare class GamepadService {
-    private readonly platformId;
+declare class GamepadService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     getSnapshot(index: number): GamepadState | null;
     getConnectedGamepads(): GamepadState[];
@@ -980,8 +1038,8 @@ interface BluetoothDeviceInfo {
     name: string | undefined;
     connected: boolean;
 }
-declare class WebBluetoothService {
-    private readonly platformId;
+declare class WebBluetoothService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     requestDevice(options?: BluetoothRequestDeviceOptions): Promise<BluetoothDeviceRef>;
     connect(device: BluetoothDeviceRef): Promise<BluetoothRemoteGATTServer>;
@@ -1002,8 +1060,8 @@ interface UsbDeviceInfo {
     serialNumber: string | undefined;
     opened: boolean;
 }
-declare class WebUsbService {
-    private readonly platformId;
+declare class WebUsbService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     requestDevice(filters?: UsbDeviceFilterDef[]): Promise<UsbDeviceRef>;
     getDevices(): Promise<UsbDeviceRef[]>;
@@ -1023,8 +1081,8 @@ declare class WebUsbService {
     static ɵprov: i0.ɵɵInjectableDeclaration<WebUsbService>;
 }
 
-declare class WebNfcService {
-    private readonly platformId;
+declare class WebNfcService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     scan(): Observable<NdefReadingEvent>;
     write(message: NdefMessage | string, options?: NdefWriteOptions): Promise<void>;
@@ -1065,8 +1123,8 @@ interface PaymentResult {
     payerEmail: string | null;
     payerPhone: string | null;
 }
-declare class PaymentRequestService {
-    private readonly platformId;
+declare class PaymentRequestService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     canMakePayment(methods: PaymentMethodConfig[], details: PaymentDetailsInit): Promise<boolean>;
     show(methods: PaymentMethodConfig[], details: PaymentDetailsInit, options?: PaymentOptionsConfig): Promise<PaymentResult>;
@@ -1104,8 +1162,8 @@ interface CredentialResult {
     id: string;
     type: string;
 }
-declare class CredentialManagementService {
-    private readonly platformId;
+declare class CredentialManagementService extends BrowserApiBaseService {
+    protected getApiName(): string;
     isSupported(): boolean;
     isPublicKeySupported(): boolean;
     get(options?: CredentialRequestOptions): Promise<Credential | null>;
@@ -1391,5 +1449,5 @@ declare function provideCredentialManagement(): EnvironmentProviders;
 
 declare const version = "0.1.0";
 
-export { BarcodeDetectorService, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, CredentialManagementService, EyeDropperService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IdleDetectorService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PaymentRequestService, PerformanceObserverService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, VibrationService, WebAudioService, WebBluetoothService, WebNfcService, WebShareService, WebSocketService, WebStorageService, WebUsbService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectGamepad, injectIdleDetector, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, permissionGuard, provideBarcodeDetector, provideBattery, provideBroadcastChannel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideCredentialManagement, provideEyeDropper, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIdleDetector, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePaymentRequest, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideVibration, provideWebAudio, provideWebBluetooth, provideWebNfc, provideWebShare, provideWebSocket, provideWebStorage, provideWebUsb, provideWebWorker, version };
+export { BarcodeDetectorService, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, ConnectionRegistryBaseService, CredentialManagementService, EyeDropperService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IdleDetectorService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PaymentRequestService, PerformanceObserverService, PermissionAwareBrowserApiBaseService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, VibrationService, WebAudioService, WebBluetoothService, WebNfcService, WebShareService, WebSocketService, WebStorageService, WebUsbService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectGamepad, injectIdleDetector, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, permissionGuard, provideBarcodeDetector, provideBattery, provideBroadcastChannel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideCredentialManagement, provideEyeDropper, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIdleDetector, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePaymentRequest, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideVibration, provideWebAudio, provideWebBluetooth, provideWebNfc, provideWebShare, provideWebSocket, provideWebStorage, provideWebUsb, provideWebWorker, version };
 export type { AudioAnalyserData, AudioContextState, BarcodeFormat, BatteryInfo, BatteryManager, BluetoothDeviceInfo, BluetoothDeviceRef, BluetoothRequestDeviceOptions, BrowserCapabilityId, BrowserError, BrowserPermissions, BrowserWebApisConfig, CameraCapabilities, CameraInfo, ColorSelectionResult, ConnectionType, CredentialResult, DetectedBarcode, EffectiveConnectionType, ElementInput, ElementSize, ErrorCallback, EventHandler, FileOpenOptions, FileSaveOptions, GamepadRef, GamepadState, GeolocationCoordinates, GeolocationError, GeolocationOptions, GeolocationPosition$1 as GeolocationPosition, GeolocationWatchOptions, IdleDetectorOptions, IdleDetectorRef, IdleState, IntersectionObserverOptions, IntersectionRef, MediaDevice, MediaDeviceKind, MediaDevicesInfo, MediaStreamConstraints$1 as MediaStreamConstraints, MediaTrackConstraints$1 as MediaTrackConstraints, MutationObserverOptions, MutationRef, NdefMessage, NdefReadingEvent, NdefWriteOptions, NetworkInformation, NetworkInformationRef, OrientationInfo, OrientationLockType, OrientationType, PageVisibilityRef, PasswordCredentialData, PaymentDetailsInit, PaymentMethodConfig, PaymentOptionsConfig, PaymentResult, PerformanceEntryType, PerformanceObserverConfig, PerformanceObserverRef, PermissionNameExt, PermissionRequest, PublicKeyCredentialOptions, RecordingOptions, RecordingResult, RecordingState, ResizeObserverOptions, ResizeRef, SSEConfig, SSEConnectionState, SSEMessage, ScreenIdleState, ScreenOrientationRef, SpeechOptions, SpeechState, StorageEvent, StorageOptions, StorageValue, UsbDeviceFilterDef, UsbDeviceInfo, UsbDeviceRef, UserIdleState, VibrationPattern, VibrationPreset, VisibilityState, WakeLockStatus, WakeLockType, WebSocketConfig, WebSocketMessage, WebSocketStatus, WorkerMessage, WorkerStatus, WorkerTask };