@ale-rainbow/web-sdk 5.1.0

package/lib/services/deviceManagement/webHidManager.service.d.ts

@@ -0,0 +1,616 @@
+/**
+ * @module DeviceManagement
+ */
+import type { Subscription } from "rxjs";
+import { RBEvent } from "../../models/event.model";
+import { Service } from "../../services/service";
+/** @internal */
+export declare const WEB_HID_MANAGER_SVC = "WebHidManagerService";
+/**
+ * Events emitted by {@link WebHidManagerService} in response to hardware button presses
+ * or device lifecycle changes. Subscribe via {@link WebHidManagerService.subscribe}.
+ *
+ * @eventProperty
+ */
+export declare enum WebHidEvents {
+    /**
+     * The user pressed the mute button on the headset while a call was unmuted.
+     * The application should mute the active call's microphone.
+     */
+    MUTED_CALL_BY_DEVICE = "MUTED_CALL_BY_DEVICE",
+    /**
+     * The user pressed the mute button on the headset while a call was muted.
+     * The application should unmute the active call's microphone.
+     */
+    UNMUTED_CALL_BY_DEVICE = "UNMUTED_CALL_BY_DEVICE",
+    /**
+     * The user lifted the headset or pressed the answer button.
+     * The application should answer the current incoming or ringing call.
+     */
+    ANSWERED_CALL_BY_DEVICE = "ANSWERED_CALL_BY_DEVICE",
+    /**
+     * The user pressed the hang-up button or placed the headset back on the cradle.
+     * The application should release (hang up) the active call.
+     */
+    RELEASED_CALL_BY_DEVICE = "RELEASED_CALL_BY_DEVICE",
+    /**
+     * The user performed a long-press or double-click on the reject button.
+     * The application should decline the current incoming call without answering.
+     */
+    REJECTED_CALL_BY_DEVICE = "REJECTED_CALL_BY_DEVICE",
+    /**
+     * The physical HID device was unplugged or became unavailable.
+     * The application may notify the user and attempt to reconnect when a new device is selected.
+     */
+    DEVICE_DISCONNECTED = "DEVICE_DISCONNECTED",
+    /**
+     * No pre-granted HID device matching the current microphone could be found.
+     * The application should prompt the user to grant browser permission for their headset
+     * (typically by calling {@link WebHidManagerService.requestDevicePermission} from a button click).
+     */
+    ON_PERMISSION_ASKED = "ON_PERMISSION_ASKED",
+    /**
+     * A HID device has been successfully opened and configured.
+     * The application can call {@link IWebHidManager.getDeviceName} to retrieve the device name
+     * and update the UI accordingly.
+     */
+    DEVICE_CONNECTED = "DEVICE_CONNECTED",
+    /**
+     * The selected device was opened but its HID descriptor contains no telephony collections
+     * (no call-control input or output usages). The device cannot manage calls.
+     * The application should warn the user that their headset is not compatible.
+     * The event data contains `deviceName: string` with the product name of the incompatible device.
+     */
+    DEVICE_NO_TELEPHONY_SUPPORT = "DEVICE_NO_TELEPHONY_SUPPORT"
+}
+/**
+ * Public contract of the WebHID headset manager.
+ *
+ * Consumers should depend on this interface rather than the concrete class to ease
+ * testing and future substitution.
+ */
+export interface WebHidManagerService {
+    /** Starts the service. Must be called before any other method. */
+    start: () => void;
+    /** Stops the service, releases the HID device, and completes the event stream. */
+    stop: () => Promise<void>;
+    /** Returns `true` when a HID device is currently open and ready. */
+    isConnected: () => boolean;
+    /**
+     * Opens the browser HID device picker so the user can grant permission to their headset.
+     *
+     * **Must be called from a user-gesture context** (e.g. a button click handler).
+     * Calling it programmatically is rejected by Chrome/Edge with a `SecurityError`.
+     */
+    requestDevicePermission: () => Promise<void>;
+    /**
+     * Notifies the service that the selected microphone has changed.
+     * Called by {@link DeviceManagementServiceRB} — do not call directly.
+     * @param mic - The newly selected audio input device, or `null` if none is selected.
+     */
+    onMicrophoneChanged: (mic: MediaDeviceInfo | null) => Promise<void>;
+    /** Returns the product name of the currently connected HID device, or an empty string. */
+    getDeviceName: () => string;
+    /**
+     * Signals a new call to the headset.
+     * For incoming calls the headset will start ringing; for outgoing calls it goes off-hook.
+     * @param id - Opaque call identifier used for logging.
+     * @param incoming - `true` for an incoming call (ring), `false` for an outgoing call (off-hook).
+     */
+    addCallToDevice: (id: string, incoming: boolean) => Promise<void>;
+    /**
+     * Signals that the call has been answered (the audio path is now active).
+     * Stops ringing, sets off-hook, and initialises the mute LED.
+     * @param id - Opaque call identifier used for logging.
+     * @param incoming - Whether the call was originally incoming.
+     */
+    answeredCallToDevice: (id: string, incoming: boolean) => Promise<void>;
+    /**
+     * Signals that a call has ended and the headset should return to idle.
+     * Stops any active ringing, clears off-hook and mute states.
+     * @param id - Opaque call identifier used for logging.
+     * @param incoming - Whether the call was incoming (used to decide whether to silence the ringer).
+     * @param ringing - Whether the headset was still ringing when the call ended (i.e. rejected before answer).
+     */
+    releaseCallToDevice: (id: string, incoming?: boolean, ringing?: boolean) => Promise<void>;
+    /**
+     * Synchronises the headset's mute LED with the application's mute state.
+     * No-op if the headset is already in the requested state.
+     * @param id - Opaque call identifier used for logging.
+     * @param mutedOn - `true` to show the mute indicator on the headset, `false` to clear it.
+     */
+    muteCallToDevice: (id: string, mutedOn: boolean) => Promise<void>;
+    /**
+     * Releases the HID device without stopping the service.
+     * Used when the microphone selection changes — the service stays alive to handle the next device.
+     */
+    releaseDevice: () => Promise<void>;
+    /**
+     * Subscribes to events emitted by the headset.
+     * @param handler - Callback invoked for every matching event.
+     * @param eventNames - Optional filter: one or several {@link WebHidEvents} values.
+     *   When omitted, all events are delivered.
+     * @returns An RxJS {@link Subscription} — call `.unsubscribe()` to stop receiving events.
+     */
+    subscribe: (handler: (event: RBEvent<WebHidEvents>) => void, eventNames?: WebHidEvents | WebHidEvents[]) => Subscription;
+}
+/**
+ * Singleton service that bridges the browser WebHID API with the Rainbow call stack.
+ *
+ * ### Responsibilities
+ * - **Device discovery**: when the user selects a microphone, the service attempts to match a
+ *   pre-granted HID device by vendor/product ID (parsed from the Chrome/Edge media label) or by
+ *   product name substring. If no match is found it emits {@link WebHidEvents.ON_PERMISSION_ASKED}
+ *   so the UI can invite the user to grant permission.
+ * - **Output reports** (application → headset): translates call-state changes into HID output
+ *   reports that control the ring tone, off-hook indicator, and mute LED on the physical device.
+ * - **Input reports** (headset → application): translates raw HID bit-field reports into
+ *   strongly-typed {@link WebHidEvents} events consumed by {@link HeadsetManagementService}.
+ *
+ * ### Lifecycle
+ * 1. {@link DeviceManagementServiceRB} calls `start()` after it has started.
+ * 2. Each time the selected microphone changes, `DeviceManagementServiceRB` calls
+ *    {@link onMicrophoneChanged} — the service releases the current HID device and attempts to
+ *    open the one matching the new microphone.
+ * 3. `stop()` releases the device and completes the RxJS subject, terminating all subscribers.
+ *
+ * ### Output-report pipeline
+ * When a call-state change method is called (e.g. `addCallToDevice`), the service:
+ * 1. Looks up the target usage ID in the {@link ControlMap}.
+ * 2. Updates the cached {@link lastOutputBuffers} buffer for that report ID, setting or clearing
+ *    the individual bit at the pre-computed `bitOffset`.
+ * 3. Calls `HIDDevice.sendReport(reportId, buffer)`.
+ *
+ * Reusing the same buffer across calls preserves all previously set bits, which is required
+ * because a single output report byte may carry multiple independent control bits.
+ *
+ * ### Input-report pipeline
+ * On every `inputreport` event the service:
+ * 1. Looks up the report ID in the {@link ControlMap} input map.
+ * 2. Iterates the usages registered for that report, extracting each bit value.
+ * 3. Applies absolute/relative state-machine logic (see `isAbsoluteHookSwitch` /
+ *    `isAbsolutePhoneMute`) to decide whether a transition has occurred.
+ * 4. Emits the appropriate {@link WebHidEvents} event.
+ *
+ * @internal
+ */
+export declare class WebHidManagerServiceRB extends Service implements WebHidManagerService {
+    private readonly logger;
+    /**
+     * RxJS subject that fans out {@link WebHidEvents} to all active subscribers.
+     *
+     * Not `readonly`: {@link stop} completes it, and a completed Subject is terminal — `next()`
+     * becomes a no-op and every later `subscribe()` completes immediately. Because this service is
+     * a singleton reused across a logout/login in the same tab, {@link start} recreates it so
+     * headset events survive a re-login (CRRAINB-54489).
+     */
+    private rxSubject;
+    /**
+     * Serialises every device-facing operation so two callers can never interleave output reports
+     * on the shared {@link lastOutputBuffers}. The upper `HeadsetManagementService` queue already
+     * orders them, but its `DEVICE_CALL_TIMEOUT_MS` watchdog can advance that queue while a slow
+     * vendor workaround is still writing — a mute sent into the middle of the Konftel re-arm left
+     * the device deaf for the rest of the call and emitted a phantom unmute event. This lock keeps
+     * the device consistent regardless of what the caller does (CRRAINB-54986).
+     */
+    private deviceLock;
+    /**
+     * `true` when the Hook Switch usage reports its persistent state (the value reflects whether
+     * the device is currently off-hook).  `false` (relative) when the device reports only
+     * momentary button-press events and the application must toggle state itself.
+     */
+    private isAbsoluteHookSwitch;
+    /**
+     * `true` when the Phone Mute usage reports its persistent state (the value reflects whether
+     * the microphone is currently muted). `false` (relative) when only button-press events are sent.
+     */
+    private isAbsolutePhoneMute;
+    /** Currently open HID device. `undefined` when no device is connected. */
+    private device;
+    /**
+     * Pre-built lookup table mapping report IDs to their usage bit offsets.
+     * Populated once in {@link openAndConfigureDevice} and reset in {@link clearVariables}.
+     */
+    private controlMap;
+    /**
+     * Last byte buffers sent for each output report ID.
+     * Reused on every `sendOutputUsage` call so that setting one bit does not clear others
+     * in the same report byte.
+     */
+    private lastOutputBuffers;
+    /**
+     * Last hook-switch value received from the hardware.
+     * Used to suppress duplicate absolute reports (CRRAINB-51267).
+     *
+     * Driven by what we command ({@link offHook} mirrors every write, {@link addCallToDevice} resets
+     * it for a ringing call) and by genuine gestures — never by acknowledgements, which on a Konftel
+     * can carry a transient value that would then make the next real press read as a repeat
+     * (CRRAINB-54986, CRRAINB-54424).
+     */
+    private lastHardwareHookState;
+    /**
+     * Last mute value received from the hardware.
+     * Used to synchronise the software mute state when a call is answered with the headset
+     * already in a muted position.
+     *
+     * Deliberately **not** reset by {@link addCallToDevice} (unlike {@link isMuted}): a mute
+     * pressed while idle or while the call was still ringing has already been acknowledged to the
+     * device, so the LED is on and the user expects to stay muted. The asymmetry is what makes the
+     * resync in {@link answeredCallToDevice} fire and emit the mute event the application ignored
+     * at press time (there was no managed call yet). Only {@link releaseCallToDevice} and
+     * {@link clearVariables} clear it.
+     */
+    private lastHardwareMuteState;
+    /**
+     * Current mute state: as last communicated to the headset via {@link mute}, or as last
+     * reported by the hardware in `onInputReport` — a device press updates it immediately so the
+     * application echo that follows is recognised as already-synced.
+     */
+    private isMuted;
+    /**
+     * Tells the device's acknowledgements of our own output reports apart from real button presses.
+     * Fed by {@link sendOutputUsage} and {@link offHook}, consulted by {@link onInputReport}.
+     */
+    private readonly echoFilter;
+    /** Software off-hook state as last communicated to the headset via {@link offHook}. */
+    private isOffHook;
+    /**
+     * When {@link releaseCallToDevice} last sent the device `OFF_HOOK=false`, or `null` once the
+     * resulting transition has been waited out (or when no release is pending). Read by
+     * {@link addCallToDevice} to hold a call taking over until an absolute-hook device has actually
+     * settled — see `ABSOLUTE_HOOK_RELEASE_SETTLE_MS` (CRRAINB-54489).
+     */
+    private lastOffHookClearedAt;
+    /**
+     * `true` once {@link answeredCallToDevice} has been called for the current call — i.e. the
+     * call/conference is genuinely connected, as opposed to still ringing (incoming) or dialling
+     * (outgoing). Needed because `isOffHook` alone can't make that distinction: `addCallToDevice`
+     * already sets it `true` for an outgoing call the moment it starts dialling. Reset in
+     * {@link addCallToDevice} and {@link releaseCallToDevice}. See CRRAINB-54420.
+     */
+    private isAnswered;
+    /**
+     * `true` once the Konftel Ego delayed mute re-send (CRRAINB-51238) has run for the current
+     * call. It is paid exactly once: paying it twice pushed the incoming answer sequence past the
+     * caller's 3 s ceiling and let the next queued command interleave with it (CRRAINB-54986). On an
+     * incoming call it is deliberately paid by the *nested* answer of the re-arm, not the outer one,
+     * so that it doubles as the settle the device needs after the synthetic release (CRRAINB-54424).
+     *
+     * Deliberately reset only by the **public** {@link addCallToDevice} / {@link releaseCallToDevice}
+     * entry points and {@link clearVariables}, never by the internal ones the re-arm drives, so the
+     * synthetic release→add→answer sequence does not re-arm the flag it is meant to respect.
+     */
+    private konftelMuteResyncDone;
+    /** If the HID is enabled by user. User can disable the HID in the app */
+    serviceEnabled: boolean;
+    /**
+     * `true` when the connected device is an Alcatel Temporis IP AT10.
+     * Enables a workaround that sends a double off-hook report so the device can be hung up
+     * during the outgoing dialling phase.
+     */
+    private isAT10;
+    /** `true` after {@link start} has been called and before {@link stop} completes. */
+    private started;
+    /** The `MediaDeviceInfo` for the currently selected microphone. Set by {@link onMicrophoneChanged}. */
+    private currentDevice;
+    /**
+     * Vendor ID parsed from the current microphone label, cached so that
+     * {@link requestDevicePermission} can pre-filter the browser device picker.
+     * `null` when the label does not carry ID information.
+     */
+    private parsedVendorId;
+    /**
+     * Product ID parsed from the current microphone label, cached so that
+     * {@link requestDevicePermission} can pre-filter the browser device picker.
+     * `null` when the label does not carry ID information.
+     */
+    private parsedProductId;
+    /**
+     * Stable bound reference for the `inputreport` event listener.
+     * Stored as a field because `removeEventListener` requires the exact same function reference
+     * that was passed to `addEventListener`; anonymous arrow functions cannot be unregistered.
+     */
+    private readonly boundInputReportHandler;
+    /**
+     * Stable bound reference for the HID `disconnect` event listener.
+     * Same rationale as {@link boundInputReportHandler}.
+     */
+    private readonly boundDisconnectHandler;
+    static getInstance(): WebHidManagerServiceRB;
+    static build(): WebHidManagerServiceRB;
+    private constructor();
+    /**
+     * If TRUE, all connected devices will be allowed to be connected.
+     * Otherwise we use on only the brandList
+     */
+    allowAllHeadsets: boolean;
+    /**
+     * Starts the service. Called by {@link DeviceManagementServiceRB} after it starts.
+     * Microphone changes are subsequently pushed via {@link onMicrophoneChanged}.
+     */
+    start(): void;
+    /**
+     * Runs `task` with exclusive access to the device, queued behind any operation already in
+     * flight. See {@link deviceLock}.
+     *
+     * A rejection is contained: the chain the next caller waits on is reset to a resolved promise,
+     * so one failing operation never wedges the lock, while the original rejection still reaches
+     * the caller that issued it.
+     */
+    private runExclusive;
+    /**
+     * Called by {@link DeviceManagementServiceRB} whenever the selected audio input device changes.
+     * Releases the current HID connection and reconnects to the device matching the new microphone.
+     */
+    onMicrophoneChanged(mic: MediaDeviceInfo | null, forceAllow?: boolean): Promise<void>;
+    /**
+     * List of brands that are allowed to be connected to WebHID. In that case we avoid asking for permissions
+     * on devices that have no HID capabilities
+     */
+    brandList: string[];
+    checkIfDeviceCouldBeManaged(mic: MediaDeviceInfo, forceAllow?: boolean): boolean;
+    /**
+     * Stops the service: releases the HID device and completes the event stream.
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns `true` when a HID device is currently open and ready to receive output reports.
+     */
+    isConnected(): boolean;
+    isHidSupported(): boolean;
+    /**
+     * Opens the browser HID device picker, filtered to the vendor/product of the currently
+     * selected microphone when available, or to all telephony devices as a fallback.
+     *
+     * **Must be called from a user-gesture context** (e.g. a button click handler).
+     * Calling it programmatically will be rejected by Chrome/Edge with a `SecurityError`.
+     */
+    requestDevicePermission(): Promise<void>;
+    /**
+     * Returns the product name reported by the currently connected HID device.
+     * Returns an empty string when no device is connected.
+     */
+    getDeviceName(): string;
+    /**
+     * Signals a new call to the headset and sets the appropriate LED state.
+     *
+     * - **Incoming call** (`incoming = true`): starts the ring tone via {@link ring}.
+     *   An extra ring command is sent on Konftel Ego devices to work around a firmware quirk
+     *   where the first report is occasionally silently discarded.
+     * - **Outgoing call** (`incoming = false`): sets the headset off-hook immediately since the
+     *   user has already initiated the call from the application.
+     *   A duplicate off-hook is sent for AT10 devices so that the hang-up action is reliably
+     *   recognised during the dialling phase.
+     *
+     * @param id - Opaque call identifier, used for logging only.
+     * @param incoming - `true` for an incoming call, `false` for an outgoing call.
+     */
+    addCallToDevice(id: string, incoming: boolean): Promise<void>;
+    /**
+     * {@link addCallToDevice} without the device lock — for callers that already hold it.
+     *
+     * `skipReleaseSettle` is set by the Konftel incoming re-arm: its preceding release is synthetic
+     * (the call is not going anywhere, the device is being re-driven in place), so waiting out the
+     * absolute-hook teardown there would add 800 ms inside a sequence that already has to fit the
+     * caller's device-call timeout. The settle the device does need is supplied instead by the
+     * delayed resend that closes the re-arm — see {@link konftelMuteResyncDone}.
+     */
+    private addCallToDeviceInternal;
+    /**
+     * Signals that the call has been answered and the audio path is now active.
+     *
+     * Sequence of output reports:
+     * 1. For incoming calls: stops the ring tone.
+     * 2. Sets the headset off-hook.
+     * 3. Initialises the mute LED to "unmuted" (important for devices that retain LED state).
+     *    An extra mute command is sent after a 1 s delay on Konftel Ego devices to work around
+     *    a firmware issue where mute events are silently dropped for outgoing calls (CRRAINB-51238).
+     * 4. Synchronises the software mute state with the hardware: if the user had already
+     *    pressed the mute button before the call was answered, the corresponding
+     *    {@link WebHidEvents.MUTED_CALL_BY_DEVICE} or {@link WebHidEvents.UNMUTED_CALL_BY_DEVICE}
+     *    event is emitted to bring the call stack in sync.
+     *
+     * @param id - Opaque call identifier, used for logging only.
+     * @param incoming - Whether the call was originally incoming (determines ring-stop behaviour).
+     */
+    answeredCallToDevice(id: string, incoming: boolean): Promise<void>;
+    /** {@link answeredCallToDevice} without the device lock — for callers that already hold it. */
+    private answeredCallToDeviceInternal;
+    /**
+     * Synchronises the headset's mute LED with the application-side mute state.
+     * Skips the HID report when the headset is already in the requested state to avoid
+     * redundant USB traffic and potential firmware glitches.
+     *
+     * @param id - Opaque call identifier, used for logging only.
+     * @param mutedOn - `true` to illuminate the mute LED, `false` to extinguish it.
+     */
+    muteCallToDevice(id: string, mutedOn: boolean): Promise<void>;
+    /** {@link muteCallToDevice} without the device lock — for callers that already hold it. */
+    private muteCallToDeviceInternal;
+    /**
+     * Returns the headset to its idle state after a call ends.
+     *
+     * Sequence of output reports:
+     * 1. If the call was incoming or still ringing: stops the ring tone.
+     * 2. Konftel Ego workaround: sends an off-hook `true` before clearing it so the device
+     *    correctly transitions out of the active state when the call was not a pure ring.
+     * 3. Clears the mute LED.
+     * 4. Clears off-hook.
+     *
+     * All software state flags (`isOffHook`, `isMuted`, hardware hook/mute snapshots) are reset.
+     *
+     * @param id - Opaque call identifier, used for logging only.
+     * @param incoming - Whether the call was incoming (used to decide whether to stop ringing).
+     * @param ringing - Whether the headset was ringing at release time (i.e. call was rejected before answer).
+     */
+    releaseCallToDevice(id: string, incoming?: boolean, ringing?: boolean): Promise<void>;
+    /** {@link releaseCallToDevice} without the device lock — for callers that already hold it. */
+    private releaseCallToDeviceInternal;
+    /**
+     * if set to FALSE, the service will no longer use the HID nor connect automatically
+     */
+    enableHidManagement(enable: boolean): void;
+    /**
+     * Releases the currently connected HID device without stopping the service.
+     *
+     * Called internally when the microphone selection changes so the service can reconnect
+     * to a different physical device. Unlike {@link stop}, this method does **not** complete
+     * the RxJS subject — existing subscribers survive across device switches.
+     *
+     * Steps:
+     * 1. Sends a final {@link releaseCallToDevice} to clear any active LED state on the device.
+     * 2. Removes the `inputreport` and `disconnect` event listeners.
+     * 3. Resets all internal state via {@link clearVariables}.
+     */
+    releaseDevice(): Promise<void>;
+    /**
+     * Subscribes to events emitted by the headset.
+     *
+     * The subscription survives device reconnections — the underlying RxJS subject is only
+     * completed by {@link stop}, so callers do not need to re-subscribe when the microphone
+     * changes.
+     *
+     * Subscriber errors are swallowed so that a faulty handler cannot break other subscribers
+     * or interrupt the input-report processing loop.
+     *
+     * @param handler - Callback invoked for every matching event.
+     * @param eventNames - Optional filter. When omitted, all {@link WebHidEvents} are delivered.
+     *   Pass a single value or an array to receive only specific events.
+     * @returns An RxJS {@link Subscription} — call `.unsubscribe()` when the caller is destroyed.
+     */
+    subscribe(handler: (event: RBEvent<WebHidEvents>) => void, eventNames?: WebHidEvents | WebHidEvents[]): Subscription;
+    /**
+     * Tries to connect to a pre-granted HID device matching the given microphone.
+     * First attempts an exact match by vendor/product IDs parsed from the media label
+     * (Chrome/Edge embed `(vendorId:productId)` in the label), then falls back to a
+     * product name substring match.
+     *
+     * Does NOT call `requestDevice()` — use {@link requestDevicePermission} for that.
+     */
+    private tryConnectFromMediaDevice;
+    /**
+     * Alternative permission-request path that always opens the browser device picker
+     * restricted to the Telephony usage page, regardless of any parsed vendor/product IDs.
+     *
+     * Unlike {@link requestDevicePermission}, this method requires a currently selected
+     * microphone (`currentDevice` must be set). It is intended as a fallback when the
+     * label-based ID parsing fails and the caller still wants to offer a picker.
+     *
+     * **Must be called from a user-gesture context.**
+     */
+    requestAccessToDevice(): Promise<void>;
+    /**
+     * Opens the HID device, builds the control map, initializes output buffers,
+     * and attaches event listeners.
+     */
+    private openAndConfigureDevice;
+    /**
+     * Parses the `(vendorId:productId)` hex suffix embedded in Chrome/Edge media device labels.
+     * Example: `"Jabra Speak 710 (0b0e:2475)"` → `{ vendorId: 0x0b0e, productId: 0x2475 }`.
+     *
+     * Uses `lastIndexOf` so that device names containing parentheses (e.g. `"Jabra (USB)"`)
+     * do not confuse the parser — only the trailing segment is inspected.
+     */
+    private parseVendorProductFromLabel;
+    /**
+     * Strips the `(vendorId:productId)` suffix from a media label to get the plain device name
+     * for fallback name-based matching.
+     */
+    extractFriendlyName(label: string): string;
+    /**
+     * Starts or stops the headset ring tone by writing to the `RING` and `RINGER` output usages.
+     *
+     * Both usages are written when the device exposes them because some headsets require both
+     * to start ringing. The `RINGER` usage is skipped for Konftel Ego devices due to a firmware
+     * incompatibility (CRRAINB-51521).
+     *
+     * @param ringOn - `true` to start ringing, `false` to stop.
+     */
+    private ring;
+    /**
+     * Sets or clears the off-hook indicator on the headset.
+     * Controls the "active call" LED and audio path of the device.
+     * @param value - `true` to go off-hook (call active), `false` to return to idle.
+     */
+    private offHook;
+    /**
+     * Sets or clears the mute LED on the headset by writing to both `MUTE` and `MICROPHONE`
+     * output usages when available.
+     *
+     * The `MICROPHONE` usage is skipped for Konftel Ego devices due to a firmware
+     * incompatibility (CRRAINB-51521).
+     *
+     * @param muteOn - `true` to illuminate the mute LED, `false` to extinguish it.
+     */
+    private mute;
+    /**
+     * Publishes a {@link WebHidEvents} event to all active subscribers.
+     * @param name - The event to emit.
+     */
+    private sendEvent;
+    /**
+     * Case-insensitive substring check. Returns `false` (rather than throwing) when either
+     * argument is not a valid string, making it safe to use against untrusted device labels.
+     * @param str - The string to search within.
+     * @param includedStr - The substring to look for.
+     */
+    private includesCaseInsensitive;
+    /**
+     * Returns the key name for a numeric value in a constant object, or a hex string fallback.
+     * Used exclusively for human-readable log messages — not on the hot input-report path.
+     * @param obj - Constant map (e.g. `INPUT_USAGE`, `OUTPUT_USAGE`).
+     * @param value - The numeric value to look up.
+     */
+    private getKeyByValue;
+    /**
+     * Returns `true` when the connected device exposes the specified output usage in its
+     * HID descriptor, meaning a report can be sent for it.
+     * @param usage - Packed usage ID (`(page << 16) | id`).
+     */
+    private isAvailableUsage;
+    /**
+     * Resets all device-scoped state to its initial value.
+     * Called by {@link releaseDevice} and implicitly by {@link stop} so that the service is
+     * ready to accept a fresh connection without residual state from a previous device.
+     */
+    private clearVariables;
+    /**
+     * Determines the exact bit offset for every reported usage within a report descriptor item list.
+     */
+    private extractUsages;
+    /**
+     * Extracts the `isAbsolute` flag for Hook Switch and Phone Mute usages.
+     *
+     * - **Absolute (true)**: the report reflects the current persistent state of the control.
+     * - **Relative (false)**: the report signals a momentary event; the application must toggle.
+     */
+    private extractIsAbsoluteValues;
+    /**
+     * Handles a physical HID device disconnection.
+     *
+     * Filters out events from unrelated devices, then cleans up event listeners, nulls the
+     * device reference, and emits {@link WebHidEvents.DEVICE_DISCONNECTED} so the UI layer
+     * can inform the user and optionally attempt reconnection.
+     *
+     * @param event - The native `HIDConnectionEvent` fired by the browser.
+     */
+    private handleDeviceDisconnect;
+    /**
+     * Calculates the byte length of an output report by summing all item bit-widths.
+     */
+    private calculateReportByteLength;
+    /**
+     * Builds the control map by scanning Telephony-page collections of the device.
+     */
+    private buildControlMap;
+    /**
+     * Sends a command to the HID device by setting the specified usage bit in the correct output report.
+     */
+    private sendOutputUsage;
+    /**
+     * Handles an incoming input report from the HID device, translating raw bit values
+     * into call-control events (answer, release, mute, reject).
+     */
+    private onInputReport;
+}
+//# sourceMappingURL=webHidManager.service.d.ts.map

package/lib/services/deviceManagement/webHidManager.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webHidManager.service.d.ts","sourceRoot":"","sources":["../../../src/services/deviceManagement/webHidManager.service.ts"],"names":[],"mappings":"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"}