@basmilius/apple-common 0.9.18 → 0.10.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+import { RemoteInfo } from "node:dgram";
 import { EventEmitter } from "node:events";
 
 //#region ../../node_modules/.bun/uuid@13.0.0/node_modules/uuid/dist/types.d.ts
@@ -12,6 +13,7 @@ declare function v4(options?: Version4Options, buf?: undefined, offset?: number)
 declare function v4<TBuf extends Uint8Array = Uint8Array>(options: Version4Options | undefined, buf: TBuf, offset?: number): TBuf;
 //#endregion
 //#region src/airplayFeatures.d.ts
+/** Type definition for the AirPlay feature flags bitmask object. */
 type AirPlayFeatureFlagsType = {
   readonly SupportsAirPlayVideoV1: bigint;
   readonly SupportsAirPlayPhoto: bigint;
@@ -58,54 +60,225 @@ type AirPlayFeatureFlagsType = {
   readonly SupportsAudioMetadataControl: bigint;
   readonly SupportsRFC2198Redundancy: bigint;
 };
+/**
+ * AirPlay feature flags as a bitmask of bigint values. Each flag corresponds to a specific
+ * capability advertised by an AirPlay device in its mDNS TXT record "features" field.
+ * The bit positions match Apple's internal AirPlayFeatureFlags enum.
+ */
 declare const AirPlayFeatureFlags: AirPlayFeatureFlagsType;
+/** String union of all known AirPlay feature flag names. */
 type AirPlayFeatureFlagName = keyof typeof AirPlayFeatureFlags;
+/** The type of pairing required to connect to an AirPlay device. */
 type PairingRequirement = 'none' | 'pin' | 'transient' | 'homekit';
+/**
+ * Parses an AirPlay features string into a single bigint bitmask.
+ * Features are advertised as either a single hex value or two comma-separated
+ * 32-bit hex values (low,high) which are combined into a 64-bit bitmask.
+ *
+ * @param features - The features string from the mDNS TXT record.
+ * @returns The combined feature flags as a bigint.
+ * @throws If the features string has an unexpected format.
+ */
 declare function parseFeatures(features: string): bigint;
+/**
+ * Checks whether a specific feature flag is set in a features bitmask.
+ *
+ * @param features - The combined feature flags bitmask.
+ * @param flag - The specific flag to check for.
+ * @returns True if the flag is set.
+ */
 declare function hasFeatureFlag(features: bigint, flag: bigint): boolean;
+/**
+ * Returns the names of all feature flags that are set in the given bitmask.
+ * Useful for debugging and diagnostics output.
+ *
+ * @param features - The combined feature flags bitmask.
+ * @returns An array of feature flag names that are active.
+ */
 declare function describeFlags(features: bigint): AirPlayFeatureFlagName[];
+/**
+ * Determines the AirPlay protocol version supported by a device based on its
+ * mDNS TXT record properties. AirPlay 2 is indicated by the presence of
+ * SupportsUnifiedMediaControl or SupportsCoreUtilsPairingAndEncryption flags.
+ *
+ * @param txt - The key-value properties from the device's mDNS TXT record.
+ * @returns 1 for legacy AirPlay, 2 for AirPlay 2.
+ */
 declare function getProtocolVersion(txt: Record<string, string>): 1 | 2;
+/**
+ * Determines the pairing requirement for an AirPlay device based on its
+ * feature flags and status flags. The hierarchy is:
+ * HomeKit pairing > PIN required > Transient (system) pairing > Legacy PIN > None.
+ *
+ * @param txt - The key-value properties from the device's mDNS TXT record.
+ * @returns The pairing requirement type.
+ */
 declare function getPairingRequirement(txt: Record<string, string>): PairingRequirement;
+/**
+ * Checks whether the AirPlay device requires a password to connect.
+ * Determined by the "pw" TXT field or the password bit in the "sf" status flags.
+ *
+ * @param txt - The key-value properties from the device's mDNS TXT record.
+ * @returns True if a password is required.
+ */
 declare function isPasswordRequired(txt: Record<string, string>): boolean;
+/**
+ * Checks whether the AirPlay device supports remote control (Hangdog protocol).
+ * Only devices with the SupportsHangdogRemoteControl flag can receive HID events.
+ *
+ * @param txt - The key-value properties from the device's mDNS TXT record.
+ * @returns True if remote control is supported (typically Apple TV only).
+ */
 declare function isRemoteControlSupported(txt: Record<string, string>): boolean;
 //#endregion
 //#region src/reporter.d.ts
+/**
+ * Available debug output groups. Each group can be independently enabled
+ * or disabled via the global {@link Reporter} singleton.
+ */
 type DebugGroup = 'debug' | 'error' | 'info' | 'net' | 'raw' | 'warn';
+/**
+ * Scoped logger instance tagged with a device or component identifier.
+ * All log output is gated by the global {@link reporter} singleton — messages
+ * are only printed when the corresponding debug group is enabled.
+ */
 declare class Logger {
   #private;
+  /** The identifier this logger is scoped to. */
   get id(): string;
+  /** ANSI-colored label prefix used in log output. */
   get label(): string;
+  /**
+   * @param id - Identifier used as a prefix in log output (typically a device ID or component name).
+   */
   constructor(id: string);
+  /**
+   * Logs a debug-level message (cyan). Only printed when the 'debug' group is enabled.
+   *
+   * @param data - Values to log.
+   */
   debug(...data: any[]): void;
+  /**
+   * Logs an error-level message (red). Only printed when the 'error' group is enabled.
+   *
+   * @param data - Values to log.
+   */
   error(...data: any[]): void;
+  /**
+   * Logs an info-level message (green). Only printed when the 'info' group is enabled.
+   *
+   * @param data - Values to log.
+   */
   info(...data: any[]): void;
+  /**
+   * Logs a network-level message (yellow). Only printed when the 'net' group is enabled.
+   *
+   * @param data - Values to log.
+   */
   net(...data: any[]): void;
+  /**
+   * Logs a raw data message (blue). Only printed when the 'raw' group is enabled.
+   * Typically used for hex dumps and binary protocol data.
+   *
+   * @param data - Values to log.
+   */
   raw(...data: any[]): void;
+  /**
+   * Logs a warning-level message (yellow). Only printed when the 'warn' group is enabled.
+   *
+   * @param data - Values to log.
+   */
   warn(...data: any[]): void;
 }
+/**
+ * Global log output controller that manages which debug groups are active.
+ * All {@link Logger} instances check the singleton {@link reporter} before printing.
+ */
 declare class Reporter {
   #private;
+  /** Enables all debug groups (except 'raw' which is very verbose). */
   all(): void;
+  /** Disables all debug groups, silencing all log output. */
   none(): void;
+  /**
+   * Disables a specific debug group.
+   *
+   * @param group - The debug group to disable.
+   */
   disable(group: DebugGroup): void;
+  /**
+   * Enables a specific debug group.
+   *
+   * @param group - The debug group to enable.
+   */
   enable(group: DebugGroup): void;
+  /**
+   * Checks whether a specific debug group is currently enabled.
+   *
+   * @param group - The debug group to check.
+   * @returns True if the group is enabled.
+   */
   isEnabled(group: DebugGroup): boolean;
 }
+/** Global reporter singleton controlling which debug groups produce output. */
 declare const reporter: Reporter;
 //#endregion
 //#region src/context.d.ts
+/**
+ * Describes the identity that this client presents to Apple devices during pairing
+ * and protocol negotiation. Mimics a real Apple device to ensure compatibility.
+ */
+type DeviceIdentity = {
+  name: string;
+  model: string;
+  osName: string;
+  osVersion: string;
+  osBuildVersion: string;
+  sourceVersion: string;
+  applicationBundleIdentifier: string;
+  applicationBundleVersion: string;
+};
+/**
+ * Shared context for a device connection, carrying the device identifier,
+ * the client identity presented to the accessory, and a scoped logger.
+ * Passed through the entire protocol stack for consistent identification and logging.
+ */
 declare class Context {
   #private;
+  /** Unique identifier of the target device (typically its mDNS hostname). */
   get deviceId(): string;
+  /** The identity this client presents to the Apple device. */
+  get identity(): DeviceIdentity;
+  /** Scoped logger instance tagged with the device identifier. */
   get logger(): Logger;
-  constructor(deviceId: string);
+  /**
+   * @param deviceId - Unique identifier of the target device.
+   * @param identity - Optional partial override of the default device identity.
+   */
+  constructor(deviceId: string, identity?: Partial<DeviceIdentity>);
 }
 //#endregion
 //#region src/pairing.d.ts
+/**
+ * Abstract base class for HAP pairing operations. Provides shared TLV8
+ * decoding with automatic error checking.
+ */
 declare abstract class BasePairing {
   #private;
+  /** The shared context carrying device identity and logger. */
   get context(): Context;
+  /**
+   * @param context - Shared context for logging and device identity.
+   */
   constructor(context: Context);
+  /**
+   * Decodes a TLV8 buffer and checks for error codes. If the TLV contains
+   * an error value, it throws via TLV8.bail.
+   *
+   * @param buffer - The raw TLV8-encoded response.
+   * @returns A map of TLV type numbers to their buffer values.
+   * @throws If the TLV contains an error value.
+   */
   tlv(buffer: Buffer): Map<number, Buffer>;
 }
 /**
@@ -121,9 +294,32 @@ declare abstract class BasePairing {
  */
 declare class AccessoryPair extends BasePairing {
   #private;
+  /**
+   * @param context - Shared context for logging and device identity.
+   * @param requestHandler - Callback that sends TLV8-encoded data and returns the response.
+   */
   constructor(context: Context, requestHandler: RequestHandler);
+  /** Generates a new Ed25519 key pair for long-term identity. Must be called before pin() or transient(). */
   start(): Promise<void>;
+  /**
+   * Performs the full PIN-based pair-setup flow (M1 through M6).
+   * Prompts for a PIN via the provided callback, then completes SRP authentication
+   * and Ed25519 credential exchange with the accessory.
+   *
+   * @param askPin - Async callback that returns the user-entered PIN.
+   * @returns Long-term credentials for future pair-verify sessions.
+   * @throws {PairingError} If any step fails.
+   */
   pin(askPin: () => Promise<string>): Promise<AccessoryCredentials>;
+  /**
+   * Performs the transient (non-persistent) pair-setup flow (M1 through M4 only).
+   * Uses the default transient PIN ('3939'). No long-term credentials are stored;
+   * session keys are derived directly from the SRP shared secret.
+   *
+   * Primarily used for HomePod connections where persistent pairing is not required.
+   *
+   * @returns Session keys for the current connection (not reusable across sessions).
+   */
   transient(): Promise<AccessoryKeys>;
   /**
    * SRP Step 1: Initiates pair-setup by requesting the accessory's SRP public key and salt.
@@ -186,54 +382,93 @@ declare class AccessoryPair extends BasePairing {
  */
 declare class AccessoryVerify extends BasePairing {
   #private;
+  /**
+   * @param context - Shared context for logging and device identity.
+   * @param requestHandler - Callback that sends TLV8-encoded data and returns the response.
+   */
   constructor(context: Context, requestHandler: RequestHandler);
+  /**
+   * Performs the full pair-verify flow (M1 through M4) using stored credentials
+   * from a previous pair-setup. Establishes a new session with forward secrecy
+   * via ephemeral Curve25519 key exchange.
+   *
+   * @param credentials - Long-term credentials from a previous pair-setup.
+   * @returns Session keys derived from the ECDH shared secret.
+   * @throws {AuthenticationError} If the accessory's identity cannot be verified.
+   */
   start(credentials: AccessoryCredentials): Promise<AccessoryKeys>;
 }
+/**
+ * Callback for sending TLV8-encoded pair-setup/pair-verify requests.
+ * Implementations typically wrap HTTP POST or OPack frame sends.
+ *
+ * @param step - The pairing step identifier ('m1', 'm3', or 'm5').
+ * @param data - The TLV8-encoded request payload.
+ * @returns The TLV8-encoded response from the accessory.
+ */
 type RequestHandler = (step: 'm1' | 'm3' | 'm5', data: Buffer) => Promise<Buffer>;
+/** Pair-Setup M1 result: the accessory's SRP public key and salt. */
 type PairM1 = {
   readonly publicKey: Buffer;
   readonly salt: Buffer;
 };
+/** Pair-Setup M2 result: the client's SRP public key and proof. */
 type PairM2 = {
   readonly publicKey: Buffer;
   readonly proof: Buffer;
 };
+/** Pair-Setup M3 result: the server's SRP proof. */
 type PairM3 = {
   readonly serverProof: Buffer;
 };
+/** Pair-Setup M4 result: the derived SRP shared secret. */
 type PairM4 = {
   readonly sharedSecret: Buffer;
 };
+/** Pair-Setup M5 result: the encrypted accessory response data and session key. */
 type PairM5 = {
   readonly authTag: Buffer;
   readonly data: Buffer;
   readonly sessionKey: Buffer;
 };
+/**
+ * Long-term pairing credentials obtained from a successful PIN-based pair-setup.
+ * Stored persistently and used for subsequent pair-verify sessions without
+ * requiring the PIN again.
+ */
 type AccessoryCredentials = {
-  readonly accessoryIdentifier: string;
-  readonly accessoryLongTermPublicKey: Buffer;
-  readonly pairingId: Buffer;
-  readonly publicKey: Buffer;
+  /** The accessory's unique identifier string. */readonly accessoryIdentifier: string; /** The accessory's Ed25519 long-term public key for signature verification. */
+  readonly accessoryLongTermPublicKey: Buffer; /** This controller's unique pairing identifier (UUID). */
+  readonly pairingId: Buffer; /** This controller's Ed25519 public key. */
+  readonly publicKey: Buffer; /** This controller's Ed25519 secret key for signing proofs. */
   readonly secretKey: Buffer;
 };
+/**
+ * Session keys derived from a pairing flow (either transient pair-setup or pair-verify).
+ * Used to derive encryption keys for the subsequent encrypted connection.
+ */
 type AccessoryKeys = {
-  readonly pairingId: Buffer;
-  readonly sharedSecret: Buffer;
-  readonly accessoryToControllerKey: Buffer;
+  /** This controller's pairing identifier. */readonly pairingId: Buffer; /** The ECDH or SRP shared secret, root key for HKDF derivation. */
+  readonly sharedSecret: Buffer; /** Derived key for decrypting data sent by the accessory (may be empty after pair-verify). */
+  readonly accessoryToControllerKey: Buffer; /** Derived key for encrypting data sent to the accessory (may be empty after pair-verify). */
   readonly controllerToAccessoryKey: Buffer;
 };
 //#endregion
 //#region src/storage.d.ts
+/** Protocol types that can have stored pairing credentials. */
 type ProtocolType = 'airplay' | 'companionLink' | 'raop';
+/** A device record stored in persistent storage. */
 type StoredDevice = {
   readonly identifier: string;
   readonly name: string;
 };
+/** Top-level structure of the storage file, versioned for future migration. */
 type StorageData = {
   version: 1;
   devices: Record<string, StoredDevice>;
   credentials: Record<string, SerializedCredentials>;
 };
+/** Base64-serialized form of {@link AccessoryCredentials} for JSON persistence. */
 type SerializedCredentials = {
   readonly accessoryIdentifier: string;
   readonly accessoryLongTermPublicKey: string;
@@ -241,36 +476,114 @@ type SerializedCredentials = {
   readonly publicKey: string;
   readonly secretKey: string;
 };
+/**
+ * Abstract base class for persistent storage of device registrations and
+ * pairing credentials. Subclasses implement the actual load/save mechanism.
+ *
+ * Credentials are stored keyed by "deviceId:protocol" to support per-protocol
+ * pairing (a device can have separate AirPlay and Companion Link credentials).
+ */
 declare abstract class Storage {
   #private;
+  /** The current storage data. */
   get data(): StorageData;
+  /** Loads storage data from the underlying persistence mechanism. */
   abstract load(): Promise<void>;
+  /** Saves the current storage data to the underlying persistence mechanism. */
   abstract save(): Promise<void>;
+  /**
+   * Replaces the internal data with the given storage data.
+   * Used by subclasses during load.
+   *
+   * @param data - The loaded storage data to set.
+   */
   protected setData(data: StorageData): void;
+  /**
+   * Retrieves a stored device by its identifier.
+   *
+   * @param identifier - The device identifier.
+   * @returns The stored device, or undefined if not found.
+   */
   getDevice(identifier: string): StoredDevice | undefined;
+  /**
+   * Stores or updates a device registration.
+   *
+   * @param identifier - The device identifier.
+   * @param device - The device data to store.
+   */
   setDevice(identifier: string, device: StoredDevice): void;
+  /**
+   * Removes a device and all its associated credentials from storage.
+   *
+   * @param identifier - The device identifier to remove.
+   */
   removeDevice(identifier: string): void;
+  /**
+   * Returns all stored devices.
+   *
+   * @returns An array of all stored device records.
+   */
   listDevices(): StoredDevice[];
+  /**
+   * Retrieves pairing credentials for a device and protocol combination.
+   *
+   * @param deviceId - The device identifier.
+   * @param protocol - The protocol type.
+   * @returns The deserialized credentials, or undefined if not found.
+   */
   getCredentials(deviceId: string, protocol: ProtocolType): AccessoryCredentials | undefined;
+  /**
+   * Stores pairing credentials for a device and protocol combination.
+   *
+   * @param deviceId - The device identifier.
+   * @param protocol - The protocol type.
+   * @param credentials - The credentials to store.
+   */
   setCredentials(deviceId: string, protocol: ProtocolType, credentials: AccessoryCredentials): void;
+  /**
+   * Removes pairing credentials for a device and protocol combination.
+   *
+   * @param deviceId - The device identifier.
+   * @param protocol - The protocol type.
+   */
   removeCredentials(deviceId: string, protocol: ProtocolType): void;
 }
+/**
+ * JSON file-based storage implementation. Persists data to a JSON file on disk,
+ * defaulting to `~/.config/apple-protocols/storage.json`.
+ */
 declare class JsonStorage extends Storage {
   #private;
+  /**
+   * @param path - Optional custom file path. Defaults to `~/.config/apple-protocols/storage.json`.
+   */
   constructor(path?: string);
+  /** Loads storage data from the JSON file, if it exists. */
   load(): Promise<void>;
+  /** Saves the current storage data to the JSON file, creating directories as needed. */
   save(): Promise<void>;
 }
+/**
+ * In-memory storage implementation. Data is not persisted between sessions.
+ * Useful for testing or environments without filesystem access.
+ */
 declare class MemoryStorage extends Storage {
+  /** No-op: memory storage has nothing to load. */
   load(): Promise<void>;
+  /** No-op: memory storage has nothing to persist. */
   save(): Promise<void>;
 }
 //#endregion
 //#region src/types.d.ts
+/** Possible states of a TCP connection managed by {@link Connection}. */
 type ConnectionState = 'closing' | 'connected' | 'connecting' | 'disconnected' | 'failed';
+/** Generic event map type used as a constraint for typed EventEmitter subclasses. */
 type EventMap = Record<string, any>;
+/** DNS record class identifiers as defined in RFC 1035. */
 type DnsRecordClass = 'IN' | 'CS' | 'CH' | 'HS' | 'ANY';
+/** DNS record types relevant to mDNS service discovery. */
 type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'MX' | 'NS' | 'NSEC' | 'PTR' | 'SOA' | 'SRV' | 'TXT';
+/** Base fields shared by all DNS resource records. */
 type DnsRecordBase = {
   readonly name: string;
   readonly type: DnsRecordType;
@@ -278,23 +591,28 @@ type DnsRecordBase = {
   readonly flash: boolean;
   readonly ttl: number;
 };
+/** DNS A record containing an IPv4 address. */
 type DnsRecordA = DnsRecordBase & {
   readonly type: 'A';
   readonly rdata: string;
 };
+/** DNS AAAA record containing an IPv6 address. */
 type DnsRecordAAAA = DnsRecordBase & {
   readonly type: 'AAAA';
   readonly rdata: string;
 };
+/** DNS PTR record containing a domain name pointer. */
 type DnsRecordPTR = DnsRecordBase & {
   readonly type: 'PTR';
   readonly rdata: string;
 };
+/** DNS TXT record containing key-value properties (used for mDNS service metadata). */
 type DnsRecordTXT = DnsRecordBase & {
   readonly type: 'TXT';
   readonly rdata: Record<string, string>;
   readonly rdata_buffer: Record<string, Buffer>;
 };
+/** DNS SRV record containing a service location (host, port, priority, weight). */
 type DnsRecordSRV = DnsRecordBase & {
   readonly type: 'SRV';
   readonly rdata: {
@@ -304,11 +622,14 @@ type DnsRecordSRV = DnsRecordBase & {
     readonly target: string;
   };
 };
+/** DNS NSEC record containing next secure domain name. */
 type DnsRecordNSEC = DnsRecordBase & {
   readonly type: 'NSEC';
   readonly rdata: string;
 };
+/** Union of all supported DNS record types. */
 type DnsRecord = DnsRecordA | DnsRecordAAAA | DnsRecordPTR | DnsRecordTXT | DnsRecordSRV | DnsRecordNSEC;
+/** Parsed DNS packet header fields. */
 type DnsPacketHeader = {
   readonly id: number;
   readonly qr: number;
@@ -326,6 +647,7 @@ type DnsPacketHeader = {
   readonly authorities: number;
   readonly additionals: number;
 };
+/** A complete parsed DNS packet with header and all record sections. */
 type DnsPacket = {
   readonly address: string;
   readonly header: DnsPacketHeader;
@@ -334,6 +656,7 @@ type DnsPacket = {
   readonly authorities: DnsRecord[];
   readonly additionals: DnsRecord[];
 };
+/** Base discovery result from an mDNS service query. */
 type Result = {
   readonly fqdn: string;
   readonly address: string;
@@ -347,11 +670,16 @@ type Result = {
   readonly packet: DnsPacket;
   readonly [key: string]: unknown;
 };
+/** Extended discovery result with device identifier, TXT record properties, and parsed feature flags. */
 type DiscoveryResult = {
   readonly id: string;
   readonly txt: Record<string, string>;
   readonly features?: bigint;
 } & Result;
+/**
+ * Aggregated discovery result combining AirPlay, Companion Link, and RAOP
+ * service information for a single physical device.
+ */
 type CombinedDiscoveryResult = {
   readonly id: string;
   readonly name: string;
@@ -362,20 +690,78 @@ type CombinedDiscoveryResult = {
 };
 //#endregion
 //#region src/discovery.d.ts
+/**
+ * mDNS service discovery for Apple devices on the local network.
+ *
+ * Supports discovering AirPlay, Companion Link, and RAOP services via multicast DNS.
+ * Results are cached for 30 seconds to avoid excessive network traffic.
+ * Use the static factory methods {@link Discovery.airplay}, {@link Discovery.companionLink},
+ * and {@link Discovery.raop} for convenience.
+ */
 declare class Discovery {
   #private;
+  /**
+   * @param service - The mDNS service type to discover (e.g. '_airplay._tcp.local').
+   */
   constructor(service: string);
+  /**
+   * Discovers devices advertising this service type via mDNS multicast.
+   * Returns cached results if available and not expired.
+   *
+   * @param useCache - Whether to use cached results. Defaults to true.
+   * @returns An array of discovered devices.
+   */
   find(useCache?: boolean): Promise<DiscoveryResult[]>;
+  /**
+   * Repeatedly searches for a specific device by ID until found or retries are exhausted.
+   * Does not use the cache to ensure fresh results on each attempt.
+   *
+   * @param id - The device ID to search for.
+   * @param tries - Maximum number of discovery attempts. Defaults to 10.
+   * @param timeout - Delay in milliseconds between attempts. Defaults to 1000.
+   * @returns The discovered device.
+   * @throws {DiscoveryError} If the device is not found after all attempts.
+   */
   findUntil(id: string, tries?: number, timeout?: number): Promise<DiscoveryResult>;
+  /** Clears all cached discovery results across all service types. */
   static clearCache(): void;
+  /**
+   * Attempts to wake a sleeping Apple device by knocking on well-known ports.
+   * Sends TCP connection attempts to ports 7000, 3689, 49152, and 32498.
+   *
+   * @param address - The IP address of the device to wake.
+   */
   static wake(address: string): Promise<void>;
+  /**
+   * Discovers all Apple devices on the network across all supported service types
+   * (AirPlay, Companion Link, RAOP) and merges them by device ID.
+   *
+   * @returns An array of combined results, each representing a single physical device
+   *          with its available service endpoints.
+   */
   static discoverAll(): Promise<CombinedDiscoveryResult[]>;
+  /**
+   * Creates a Discovery instance for AirPlay services.
+   *
+   * @returns A new Discovery instance targeting `_airplay._tcp.local`.
+   */
   static airplay(): Discovery;
+  /**
+   * Creates a Discovery instance for Companion Link services.
+   *
+   * @returns A new Discovery instance targeting `_companion-link._tcp.local`.
+   */
   static companionLink(): Discovery;
+  /**
+   * Creates a Discovery instance for RAOP services.
+   *
+   * @returns A new Discovery instance targeting `_raop._tcp.local`.
+   */
   static raop(): Discovery;
 }
 //#endregion
 //#region src/mdns.d.ts
+/** A resolved mDNS service with its name, type, address, port, and TXT properties. */
 type MdnsService = {
   readonly name: string;
   readonly type: string;
@@ -383,14 +769,50 @@ type MdnsService = {
   readonly port: number;
   readonly properties: Record<string, string>;
 };
+/**
+ * Performs unicast DNS-SD queries to specific hosts. First wakes the devices
+ * via TCP knocking, then repeatedly sends DNS queries via UDP to port 5353 on
+ * each host, collecting responses for the specified duration.
+ *
+ * @param hosts - IP addresses of the specific devices to query.
+ * @param services - mDNS service types to discover.
+ * @param timeout - Discovery duration in seconds. Defaults to 4.
+ * @returns An array of resolved mDNS services.
+ */
 declare function unicast(hosts: string[], services: string[], timeout?: number): Promise<MdnsService[]>;
+/**
+ * Performs multicast DNS-SD discovery on the local network. Creates UDP sockets
+ * on all network interfaces, joins the mDNS multicast group (224.0.0.251),
+ * and sends periodic queries for the specified duration.
+ *
+ * Creates two types of sockets:
+ * - One on 0.0.0.0:5353 to receive multicast responses (may fail on some platforms)
+ * - One per local network interface on a random port with multicast membership
+ *
+ * @param services - mDNS service types to discover.
+ * @param timeout - Discovery duration in seconds. Defaults to 4.
+ * @returns An array of resolved mDNS services found on the network.
+ */
 declare function multicast(services: string[], timeout?: number): Promise<MdnsService[]>;
 //#endregion
 //#region src/cli.d.ts
+/**
+ * Prompts the user for input via stdin and returns their response.
+ *
+ * @param message - The message to display before the input cursor.
+ * @returns The user's input string.
+ */
 declare function prompt(message: string): Promise<string>;
+/**
+ * Returns a promise that resolves after the specified delay.
+ * Commonly used for timing gaps in HID press/release sequences.
+ *
+ * @param ms - The delay in milliseconds.
+ */
 declare function waitFor(ms: number): Promise<void>;
 //#endregion
 //#region src/connection.d.ts
+/** Event map for the base Connection class socket events. */
 type ConnectionEventMap = {
   close: [hadError: boolean];
   connect: [];
@@ -399,71 +821,498 @@ type ConnectionEventMap = {
   error: [err: Error];
   timeout: [];
 };
+/**
+ * TCP socket connection wrapper with built-in retry logic and typed events.
+ *
+ * Manages a single TCP socket to an Apple device, providing automatic reconnection
+ * on failure (configurable attempts and interval), keep-alive, and no-delay settings.
+ * Subclasses can extend the event map with protocol-specific events.
+ *
+ * Default retry behavior: 3 attempts with 3-second intervals between retries.
+ */
 declare class Connection<TEventMap extends EventMap = {}> extends EventEmitter<ConnectionEventMap & TEventMap> {
   #private;
+  /** The remote IP address this connection targets. */
   get address(): string;
+  /** The shared context carrying device identity and logger. */
   get context(): Context;
+  /** The remote port this connection targets. */
   get port(): number;
+  /** Whether the connection is currently established and open. */
   get isConnected(): boolean;
+  /** The local IP address of the socket, or '0.0.0.0' if not connected. */
+  get localAddress(): string;
+  /** The current connection state, derived from both internal state and socket readyState. */
   get state(): ConnectionState;
+  /**
+   * @param context - Shared context with device identity and logger.
+   * @param address - The remote IP address to connect to.
+   * @param port - The remote port to connect to.
+   */
   constructor(context: Context, address: string, port: number);
+  /**
+   * Establishes a TCP connection to the remote address. If already connected,
+   * returns immediately. Enables retry logic for the duration of this connection.
+   *
+   * @throws {ConnectionError} If already connecting or all retry attempts are exhausted.
+   */
   connect(): Promise<void>;
+  /** Immediately destroys the underlying socket without graceful shutdown. */
   destroy(): void;
+  /**
+   * Gracefully disconnects by ending the socket and waiting for the 'close' event.
+   * Disables retry logic so the connection does not automatically reconnect.
+   */
   disconnect(): Promise<void>;
+  /**
+   * Enables or disables debug logging for incoming data (hex + ASCII dumps).
+   *
+   * @param enabled - Whether to enable debug output.
+   * @returns This connection instance for chaining.
+   */
   debug(enabled: boolean): this;
+  /**
+   * Configures the retry behavior for connection attempts.
+   *
+   * @param attempts - Maximum number of retry attempts.
+   * @param interval - Delay in milliseconds between retry attempts.
+   * @returns This connection instance for chaining.
+   */
   retry(attempts: number, interval?: number): this;
+  /**
+   * Writes data to the underlying TCP socket.
+   * Emits an error event if the socket is not writable.
+   *
+   * @param data - The data to send.
+   */
   write(data: Buffer | Uint8Array): void;
+  /**
+   * Handles the socket 'close' event. If the connection was active and closed
+   * unexpectedly with an error, triggers a retry.
+   *
+   * @param hadError - Whether the close was caused by an error.
+   */
+  onClose(hadError: boolean): void;
+  /**
+   * Handles successful TCP connection. Enables keep-alive (10s interval),
+   * disables the connection timeout, resets retry counter, and resolves the connect promise.
+   */
+  onConnect(): void;
+  /**
+   * Handles incoming data from the socket. When debug mode is enabled,
+   * logs a hex and ASCII dump of the first 64 bytes.
+   *
+   * @param data - The received data buffer.
+   */
+  onData(data: Buffer): void;
+  /** Handles the socket 'end' event (remote end sent FIN). */
+  onEnd(): void;
+  /**
+   * Handles socket errors. If connecting, schedules a retry; otherwise marks
+   * the connection as failed. Warns if no error listener is registered.
+   *
+   * @param err - The socket error.
+   */
+  onError(err: Error): void;
+  /**
+   * Handles socket timeout. If connecting, schedules a retry;
+   * otherwise destroys the socket and marks the connection as failed.
+   */
+  onTimeout(): void;
 }
+/**
+ * Connection subclass that adds optional ChaCha20-Poly1305 encryption.
+ * Once encryption is enabled, subclasses use the {@link EncryptionState}
+ * to encrypt outgoing data and decrypt incoming data with per-message nonce counters.
+ */
 declare class EncryptionAwareConnection<TEventMap extends EventMap> extends Connection<TEventMap> {
+  /** Whether encryption has been enabled on this connection. */
   get isEncrypted(): boolean;
+  /** The current encryption state, or undefined if encryption is not enabled. */
   _encryption?: EncryptionState;
+  /**
+   * Enables ChaCha20-Poly1305 encryption for this connection.
+   * After calling this, all subsequent data must be encrypted/decrypted
+   * using the provided keys.
+   *
+   * @param readKey - The 32-byte key for decrypting incoming data.
+   * @param writeKey - The 32-byte key for encrypting outgoing data.
+   */
   enableEncryption(readKey: Buffer, writeKey: Buffer): void;
 }
+/**
+ * Holds the symmetric encryption keys and nonce counters for a single
+ * encrypted connection. Each message increments the corresponding counter
+ * to ensure unique nonces for ChaCha20-Poly1305.
+ */
 declare class EncryptionState {
+  /** The 32-byte key used to decrypt incoming data. */
   readKey: Buffer;
+  /** Monotonically increasing counter used as part of the read nonce. */
   readCount: number;
+  /** The 32-byte key used to encrypt outgoing data. */
   writeKey: Buffer;
+  /** Monotonically increasing counter used as part of the write nonce. */
   writeCount: number;
+  /**
+   * @param readKey - The 32-byte decryption key.
+   * @param writeKey - The 32-byte encryption key.
+   */
   constructor(readKey: Buffer, writeKey: Buffer);
 }
 //#endregion
 //#region src/const.d.ts
+/** Default PIN used for transient (non-persistent) AirPlay pairing sessions. */
 declare const AIRPLAY_TRANSIENT_PIN = "3939";
+/** Timeout in milliseconds for HTTP requests during setup and control. */
 declare const HTTP_TIMEOUT = 6000;
+/** mDNS service type for AirPlay device discovery. */
 declare const AIRPLAY_SERVICE = "_airplay._tcp.local";
+/** mDNS service type for Companion Link (remote control protocol) device discovery. */
 declare const COMPANION_LINK_SERVICE = "_companion-link._tcp.local";
+/** mDNS service type for RAOP (Remote Audio Output Protocol) device discovery. */
 declare const RAOP_SERVICE = "_raop._tcp.local";
 //#endregion
 //#region src/symbols.d.ts
+/**
+ * Unique symbol used as a key for accessing encryption state on connection instances.
+ * Provides type-safe access to internal encryption fields without exposing them publicly.
+ */
 declare const ENCRYPTION: unique symbol;
 //#endregion
+//#region src/recovery.d.ts
+/** Events emitted by {@link ConnectionRecovery}. */
+type EventMap$1 = {
+  recovering: [attempt: number];
+  recovered: [];
+  failed: [errors: Error[]];
+};
+/** Configuration options for {@link ConnectionRecovery}. */
+type ConnectionRecoveryOptions = {
+  /** Maximum number of recovery attempts before giving up. Defaults to 3. */maxAttempts?: number; /** Base delay in milliseconds for the first retry. Defaults to 1000. */
+  baseDelay?: number; /** Maximum delay in milliseconds when using exponential backoff. Defaults to 30000. */
+  maxDelay?: number; /** Whether to use exponential backoff (delay doubles each attempt). Defaults to true. */
+  useExponentialBackoff?: boolean; /** If set to a positive value, periodically calls onReconnect at this interval (ms). Defaults to 0 (disabled). */
+  reconnectInterval?: number; /** Callback that performs the actual reconnection. Called during recovery and scheduled reconnects. */
+  onReconnect: () => Promise<void>;
+};
+/**
+ * Manages automatic connection recovery with exponential backoff.
+ *
+ * When an unexpected disconnect occurs, this class schedules retry attempts
+ * with configurable delay (exponential backoff by default: base=1s, max=30s).
+ * Emits 'recovering', 'recovered', and 'failed' events for monitoring.
+ *
+ * Optionally supports a periodic reconnect interval for proactive
+ * connection health checks (failures are silent; unexpected disconnects
+ * trigger the full recovery flow).
+ */
+declare class ConnectionRecovery extends EventEmitter<EventMap$1> {
+  #private;
+  /**
+   * @param options - Recovery configuration including the reconnect callback.
+   */
+  constructor(options: ConnectionRecoveryOptions);
+  /** Whether a recovery attempt is currently in progress. */
+  get isRecovering(): boolean;
+  /** The current retry attempt number (0 when not recovering). */
+  get attempt(): number;
+  /**
+   * Called when a disconnect is detected. Only triggers recovery for
+   * unexpected disconnects; intentional disconnects are ignored.
+   *
+   * @param unexpected - Whether the disconnect was unexpected (e.g. socket error).
+   */
+  handleDisconnect(unexpected: boolean): void;
+  /** Resets the recovery state and restarts the periodic reconnect interval if configured. */
+  reset(): void;
+  /** Permanently disposes this recovery instance, cancelling all timers and removing listeners. */
+  dispose(): void;
+}
+//#endregion
 //#region src/timing.d.ts
+/**
+ * NTP timing server for AirPlay audio synchronization.
+ *
+ * Apple devices send NTP timing requests to synchronize their clocks with the
+ * controller during audio streaming. This server responds with the current
+ * wall-clock time using NTP packet format, enabling the device to calculate
+ * the correct playback offset for synchronized multi-room audio.
+ *
+ * Must use wall-clock time (Date.now), not monotonic time (process.hrtime),
+ * because NTP timestamps are anchored to the Unix epoch.
+ */
 declare class TimingServer {
   #private;
+  /** The UDP port the timing server is listening on, or 0 if not yet bound. */
   get port(): number;
   constructor();
+  /** Closes the UDP socket and resets the port. */
   close(): void;
+  /**
+   * Binds the UDP socket to a random available port and starts listening
+   * for NTP timing requests.
+   *
+   * @throws If the socket fails to bind.
+   */
   listen(): Promise<void>;
+  /**
+   * Handles the socket 'connect' event by configuring buffer sizes.
+   */
+  onConnect(): void;
+  /**
+   * Handles socket errors by logging them.
+   *
+   * @param err - The error that occurred.
+   */
+  onError(err: Error): void;
+  /**
+   * Handles incoming NTP timing requests from Apple devices.
+   * Decodes the request, captures the current NTP timestamp, and sends back
+   * a response with reference, receive, and send timestamps populated.
+   *
+   * @param data - The raw UDP packet data.
+   * @param info - Remote address information of the sender.
+   */
+  onMessage(data: Buffer, info: RemoteInfo): void;
 }
 //#endregion
 //#region src/utils.d.ts
+/**
+ * Generates a random Active-Remote identifier for DACP (Digital Audio Control Protocol).
+ * Used in RTSP headers to identify the remote controller.
+ *
+ * @returns A random 32-bit unsigned integer as a decimal string.
+ */
 declare function generateActiveRemoteId(): string;
+/**
+ * Generates a random DACP-ID for identifying this controller in DACP sessions.
+ *
+ * @returns A random 64-bit integer as an uppercase hexadecimal string.
+ */
 declare function generateDacpId(): string;
+/**
+ * Generates a random session identifier for RTSP and AirPlay sessions.
+ *
+ * @returns A random 32-bit unsigned integer as a decimal string.
+ */
 declare function generateSessionId(): string;
+/**
+ * Finds the first non-internal IPv4 address on this machine.
+ *
+ * @returns The local IPv4 address, or null if none is found.
+ */
 declare function getLocalIP(): string | null;
+/**
+ * Finds the first non-internal MAC address on this machine.
+ *
+ * @returns The MAC address in uppercase colon-separated format, or '00:00:00:00:00:00' if none is found.
+ */
 declare function getMacAddress(): string;
+/**
+ * Generates a cryptographically random 32-bit unsigned integer.
+ *
+ * @returns A random unsigned 32-bit integer.
+ */
 declare function randomInt32(): number;
+/**
+ * Generates a cryptographically random 64-bit unsigned integer.
+ *
+ * @returns A random unsigned 64-bit bigint.
+ */
 declare function randomInt64(): bigint;
+/**
+ * Encodes a 16-bit unsigned integer into a big-endian buffer.
+ *
+ * @param value - The 16-bit unsigned integer to encode.
+ * @returns A 2-byte buffer containing the value in big-endian byte order.
+ */
 declare function uint16ToBE(value: number): Buffer;
+/**
+ * Encodes a 53-bit unsigned integer into an 8-byte little-endian buffer.
+ * Useful for encoding JavaScript-safe integers into 64-bit wire formats.
+ *
+ * @param value - The unsigned integer to encode (must be in range [0, 2^53-1]).
+ * @returns An 8-byte buffer containing the value in little-endian byte order.
+ * @throws If the value is out of range or not an integer.
+ */
 declare function uint53ToLE(value: number): Buffer;
 //#endregion
+//#region src/deviceModel.d.ts
+/** Known Apple device models that can be discovered and controlled via AirPlay/Companion Link. */
+declare enum DeviceModel {
+  Unknown = 0,
+  AppleTVGen2 = 1,
+  AppleTVGen3 = 2,
+  AppleTVHD = 3,
+  AppleTV4K = 4,
+  AppleTV4KGen2 = 5,
+  AppleTV4KGen3 = 6,
+  HomePod = 10,
+  HomePodMini = 11,
+  HomePodGen2 = 12,
+  AirPortExpress = 20,
+  AirPortExpressGen2 = 21
+}
+/** High-level device categories derived from the specific device model. */
+declare enum DeviceType {
+  Unknown = 0,
+  AppleTV = 1,
+  HomePod = 2,
+  AirPort = 3
+}
+/**
+ * Resolves an Apple model identifier or internal code name to a known device model.
+ *
+ * @param identifier - Model identifier (e.g. "AppleTV6,2") or internal name (e.g. "J305AP").
+ * @returns The matching device model, or {@link DeviceModel.Unknown} if unrecognized.
+ */
+declare const lookupDeviceModel: (identifier: string) => DeviceModel;
+/**
+ * Returns the human-readable display name for a device model.
+ *
+ * @param model - The device model to look up.
+ * @returns A display name like "Apple TV 4K (2nd generation)", or "Unknown".
+ */
+declare const getDeviceModelName: (model: DeviceModel) => string;
+/**
+ * Returns the high-level device type category for a device model.
+ *
+ * @param model - The device model to categorize.
+ * @returns The device type (AppleTV, HomePod, AirPort, or Unknown).
+ */
+declare const getDeviceType: (model: DeviceModel) => DeviceType;
+/**
+ * Checks whether the given model is an Apple TV.
+ *
+ * @param model - The device model to check.
+ * @returns True if the model is any Apple TV generation.
+ */
+declare const isAppleTV: (model: DeviceModel) => boolean;
+/**
+ * Checks whether the given model is a HomePod.
+ *
+ * @param model - The device model to check.
+ * @returns True if the model is any HomePod variant.
+ */
+declare const isHomePod: (model: DeviceModel) => boolean;
+/**
+ * Checks whether the given model is an AirPort Express.
+ *
+ * @param model - The device model to check.
+ * @returns True if the model is any AirPort Express generation.
+ */
+declare const isAirPort: (model: DeviceModel) => boolean;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Base error class for all Apple protocol errors.
+ * All domain-specific errors in this library extend from this class,
+ * enabling consumers to catch any protocol error with a single handler.
+ */
+declare class AppleProtocolError extends Error {
+  /** @param message - Human-readable description of the error. */
+  constructor(message: string);
+}
+/**
+ * Thrown when a TCP connection cannot be established or encounters a fatal error.
+ * Parent class for more specific connection errors.
+ */
+declare class ConnectionError extends AppleProtocolError {
+  /** @param message - Human-readable description of the connection failure. */
+  constructor(message: string);
+}
+/** Thrown when a TCP connection attempt exceeds the configured socket timeout. */
+declare class ConnectionTimeoutError extends ConnectionError {
+  /** @param message - Optional custom message; defaults to a standard timeout message. */
+  constructor(message?: string);
+}
+/** Thrown when a TCP connection is closed unexpectedly by the remote end or the OS. */
+declare class ConnectionClosedError extends ConnectionError {
+  /** @param message - Optional custom message; defaults to a standard closed message. */
+  constructor(message?: string);
+}
+/**
+ * Thrown when a pairing operation fails during the HAP pair-setup or pair-verify flow.
+ * Parent class for authentication and credentials errors.
+ */
+declare class PairingError extends AppleProtocolError {
+  /** @param message - Human-readable description of the pairing failure. */
+  constructor(message: string);
+}
+/**
+ * Thrown when the accessory's identity verification fails, such as an invalid
+ * Ed25519 signature or mismatched accessory identifier during pair-verify.
+ */
+declare class AuthenticationError extends PairingError {
+  /** @param message - Human-readable description of the authentication failure. */
+  constructor(message: string);
+}
+/**
+ * Thrown when stored credentials are invalid, missing, or incompatible
+ * with the accessory (e.g. after a factory reset).
+ */
+declare class CredentialsError extends PairingError {
+  /** @param message - Human-readable description of the credentials issue. */
+  constructor(message: string);
+}
+/** Thrown when a protocol command fails to execute on the target device. */
+declare class CommandError extends AppleProtocolError {
+  /** @param message - Human-readable description of the command failure. */
+  constructor(message: string);
+}
+/** Thrown when a protocol setup step fails (e.g. RTSP SETUP, AirPlay stream setup). */
+declare class SetupError extends AppleProtocolError {
+  /** @param message - Human-readable description of the setup failure. */
+  constructor(message: string);
+}
+/** Thrown when mDNS device discovery fails or a device cannot be found after retries. */
+declare class DiscoveryError extends AppleProtocolError {
+  /** @param message - Human-readable description of the discovery failure. */
+  constructor(message: string);
+}
+/** Thrown when an encryption or decryption operation fails (e.g. ChaCha20 auth tag mismatch). */
+declare class EncryptionError extends AppleProtocolError {
+  /** @param message - Human-readable description of the encryption failure. */
+  constructor(message: string);
+}
+/** Thrown when a response from the accessory is malformed or has an unexpected format. */
+declare class InvalidResponseError extends AppleProtocolError {
+  /** @param message - Human-readable description of the invalid response. */
+  constructor(message: string);
+}
+/** Thrown when a protocol operation exceeds its expected time limit. */
+declare class TimeoutError extends AppleProtocolError {
+  /** @param message - Human-readable description of the timeout. */
+  constructor(message: string);
+}
+/** Thrown when a media playback operation fails on the target device. */
+declare class PlaybackError extends AppleProtocolError {
+  /** @param message - Human-readable description of the playback failure. */
+  constructor(message: string);
+}
+//#endregion
 //#region src/audioSource.d.ts
+/**
+ * Represents a source of audio data that can be read in frames.
+ * Implementations include MP3, OGG, WAV, PCM, FFmpeg, URL, SineWave, and Live sources.
+ */
 interface AudioSource {
+  /** Total duration of the audio source in seconds. */
   get duration(): number;
+  /**
+   * Reads the specified number of audio frames from the source.
+   *
+   * @param count - The number of frames to read.
+   * @returns A buffer containing the audio data, or null if the source is exhausted.
+   */
   readFrames(count: number): Promise<Buffer | null>;
+  /** Resets the source to the beginning, allowing it to be read again. */
   reset(): Promise<void>;
+  /** Starts the audio source, initializing any underlying decoders or streams. */
   start(): Promise<void>;
+  /** Stops the audio source and releases any underlying resources. */
   stop(): Promise<void>;
 }
 //#endregion
-export { AIRPLAY_SERVICE, AIRPLAY_TRANSIENT_PIN, type AccessoryCredentials, type AccessoryKeys, AccessoryPair, AccessoryVerify, type AirPlayFeatureFlagName, AirPlayFeatureFlags, type AudioSource, COMPANION_LINK_SERVICE, type CombinedDiscoveryResult, Connection, type ConnectionState, Context, Discovery, type DiscoveryResult, ENCRYPTION, EncryptionAwareConnection, EncryptionState, type EventMap, HTTP_TIMEOUT, JsonStorage, type Logger, type MdnsService, MemoryStorage, type PairingRequirement, type ProtocolType, RAOP_SERVICE, type Reporter, Storage, type StorageData, type StoredDevice, TimingServer, describeFlags, generateActiveRemoteId, generateDacpId, generateSessionId, getLocalIP, getMacAddress, getPairingRequirement, getProtocolVersion, hasFeatureFlag, isPasswordRequired, isRemoteControlSupported, multicast as mdnsMulticast, unicast as mdnsUnicast, parseFeatures, prompt, randomInt32, randomInt64, reporter, uint16ToBE, uint53ToLE, v4 as uuid, waitFor };
+export { AIRPLAY_SERVICE, AIRPLAY_TRANSIENT_PIN, type AccessoryCredentials, type AccessoryKeys, AccessoryPair, AccessoryVerify, type AirPlayFeatureFlagName, AirPlayFeatureFlags, AppleProtocolError, type AudioSource, AuthenticationError, COMPANION_LINK_SERVICE, type CombinedDiscoveryResult, CommandError, Connection, ConnectionClosedError, ConnectionError, ConnectionRecovery, type ConnectionRecoveryOptions, type ConnectionState, ConnectionTimeoutError, Context, CredentialsError, type DeviceIdentity, DeviceModel, DeviceType, Discovery, DiscoveryError, type DiscoveryResult, ENCRYPTION, EncryptionAwareConnection, EncryptionError, EncryptionState, type EventMap, HTTP_TIMEOUT, InvalidResponseError, JsonStorage, type Logger, type MdnsService, MemoryStorage, PairingError, type PairingRequirement, PlaybackError, type ProtocolType, RAOP_SERVICE, type Reporter, SetupError, Storage, type StorageData, type StoredDevice, TimeoutError, TimingServer, describeFlags, generateActiveRemoteId, generateDacpId, generateSessionId, getDeviceModelName, getDeviceType, getLocalIP, getMacAddress, getPairingRequirement, getProtocolVersion, hasFeatureFlag, isAirPort, isAppleTV, isHomePod, isPasswordRequired, isRemoteControlSupported, lookupDeviceModel, multicast as mdnsMulticast, unicast as mdnsUnicast, parseFeatures, prompt, randomInt32, randomInt64, reporter, uint16ToBE, uint53ToLE, v4 as uuid, waitFor };