@basmilius/apple-encoding 0.9.19 → 0.10.1

package/dist/index.d.mts

@@ -1,6 +1,10 @@
 declare namespace daap_d_exports {
-  export { ContentCode, ContentCodeKey, DecodedTag, PlaybackStatus, TagType, TrackMetadata, decode$3 as decode, decodeTag, decodeToObject, decodeTrackMetadata, encodeContainer, encodePlaybackStatus, encodeTag, encodeTagWithSize, encodeTrackMetadata };
+  export { ContentCode, ContentCodeKey, DecodedTag, PlaybackStatus, TagType, TrackMetadata, decode$4 as decode, decodeTag, decodeToObject, decodeTrackMetadata, encodeContainer, encodePlaybackStatus, encodeTag, encodeTagWithSize, encodeTrackMetadata };
 }
+/**
+* Maps four-character DAAP tag codes to their human-readable DMAP/DAAP content code names.
+* Used to identify the semantic meaning of tags in DAAP protocol messages.
+*/
 declare const ContentCode: {
   readonly mlit: "dmap.listingitem";
   readonly mlcl: "dmap.listing";
@@ -30,6 +34,15 @@ declare const ContentCode: {
   readonly cavs: "daap.songvisiblestate";
   readonly aePP: "com.apple.itunes.photo-properties";
 };
+/**
+* Maps four-character DAAP tag codes to their data type identifiers.
+*
+* Type values: 1=byte, 2=unsigned byte, 3=short, 4=unsigned short,
+* 5=int, 6=unsigned int, 7=long, 8=unsigned long,
+* 9=string, 10=date, 11=version, 12=container.
+*
+* Used by the decoder to determine how to interpret the raw bytes of each tag.
+*/
 declare const TagType: {
   readonly mlit: 12;
   readonly mlcl: 12;
@@ -59,87 +72,288 @@ declare const TagType: {
   readonly cavs: 1;
   readonly aePP: 9;
 };
+/**
+* Encodes a single DAAP tag with an automatically sized value.
+* Numbers are encoded in the smallest big-endian representation that fits.
+*
+* @param tag - Four-character ASCII tag code (e.g. 'minm', 'asar').
+* @param value - The value to encode: string (UTF-8), number (auto-sized BE), bigint (8-byte BE), or raw Buffer.
+* @returns A buffer containing the tag, length, and value.
+* @throws Error if the tag is not exactly 4 characters.
+*/
 declare function encodeTag(tag: string, value: Buffer | string | number | bigint): Buffer;
+/**
+* Encodes a DAAP container tag that wraps other encoded tags.
+*
+* @param tag - Four-character ASCII container tag code (e.g. 'mlit', 'mlcl').
+* @param content - Pre-encoded buffer containing the container's child tags.
+* @returns A buffer containing the container tag, length, and nested content.
+* @throws Error if the tag is not exactly 4 characters.
+*/
 declare function encodeContainer(tag: string, content: Buffer): Buffer;
+/**
+* Encodes playback status fields (playing, shuffle, repeat) into DAAP tags.
+* Only includes tags for fields that are defined in the status object.
+*
+* @param status - The playback status to encode.
+* @returns A buffer containing the encoded DAAP status tags.
+*/
 declare function encodePlaybackStatus(status: PlaybackStatus): Buffer;
+/**
+* Encodes a DAAP tag with an explicitly specified byte size for the numeric value.
+* Useful when the protocol requires a specific size regardless of the value magnitude.
+*
+* @param tag - Four-character ASCII tag code.
+* @param value - The numeric value to encode.
+* @param byteSize - The exact number of bytes to use for the value (1, 2, 4, or 8).
+* @returns A buffer containing the tag, length, and fixed-size value.
+* @throws Error if the tag is not exactly 4 characters.
+*/
 declare function encodeTagWithSize(tag: string, value: number, byteSize: 1 | 2 | 4 | 8): Buffer;
+/**
+* Encodes track metadata into a DAAP listing item (`mlit`) container.
+* Only includes tags for fields that are defined in the metadata object.
+* Duration is converted from seconds to milliseconds for the `astm` tag.
+*
+* @param metadata - The track metadata to encode.
+* @returns A buffer containing an `mlit` container with all defined metadata tags.
+*/
 declare function encodeTrackMetadata(metadata: TrackMetadata): Buffer;
-declare function decode$3(buffer: Buffer): DecodedTag[];
+/**
+* Decodes all DAAP tags from a buffer sequentially.
+* Stops when the buffer is exhausted or a tag cannot be fully decoded.
+*
+* @param buffer - The raw DAAP-encoded buffer.
+* @returns An array of decoded tags with their raw value buffers.
+*/
+declare function decode$4(buffer: Buffer): DecodedTag[];
+/**
+* Decodes a single DAAP tag from the start of a buffer.
+* Returns the decoded tag and the remaining unconsumed buffer.
+*
+* @param buffer - The buffer to decode from. Must contain at least 8 bytes (4 tag + 4 length).
+* @returns A tuple of the decoded tag and remaining buffer, or null if the buffer is too short.
+*/
 declare function decodeTag(buffer: Buffer): [DecodedTag, Buffer] | null;
+/**
+* Decodes a DAAP buffer into a plain object, interpreting values based on {@link TagType}.
+* Container tags (type 12) are recursively decoded. Unknown tags are kept as raw buffers.
+*
+* @param buffer - The raw DAAP-encoded buffer.
+* @returns An object mapping tag codes to their decoded values.
+*/
 declare function decodeToObject(buffer: Buffer): Record<string, unknown>;
+/**
+* Decodes a DAAP buffer into a structured {@link TrackMetadata} object.
+* Handles both bare tag lists and `mlit`-wrapped containers.
+* Duration is converted from the DAAP millisecond `astm` value back to seconds.
+*
+* @param buffer - The raw DAAP-encoded buffer containing track metadata.
+* @returns The decoded track metadata.
+*/
 declare function decodeTrackMetadata(buffer: Buffer): TrackMetadata;
+/** Union type of all valid four-character DAAP content code keys. */
 type ContentCodeKey = keyof typeof ContentCode;
+/** Represents a single decoded DAAP tag with its raw value buffer. */
 type DecodedTag = {
-  readonly tag: string;
-  readonly length: number;
+  /** The four-character ASCII tag code. */readonly tag: string; /** The byte length of the value. */
+  readonly length: number; /** The raw undecoded value bytes. */
   readonly value: Buffer;
 };
+/** Represents the playback state of a DAAP media player. */
 type PlaybackStatus = {
-  readonly playing?: boolean;
-  readonly shuffle?: boolean;
+  /** Whether the player is currently playing. */readonly playing?: boolean; /** Whether shuffle mode is enabled. */
+  readonly shuffle?: boolean; /** The repeat mode: off, repeat one track, or repeat all. */
   readonly repeat?: "off" | "one" | "all";
 };
+/** Metadata for a single media track in the DAAP protocol. */
 type TrackMetadata = {
-  readonly title?: string;
-  readonly artist?: string;
-  readonly albumArtist?: string;
-  readonly album?: string;
-  readonly composer?: string;
-  readonly genre?: string;
-  readonly duration?: number;
-  readonly trackNumber?: number;
-  readonly trackCount?: number;
-  readonly discNumber?: number;
-  readonly discCount?: number;
-  readonly year?: number;
-  readonly bitrate?: number;
-  readonly sampleRate?: number;
+  /** Track title (DAAP tag `minm`). */readonly title?: string; /** Track artist (DAAP tag `asar`). */
+  readonly artist?: string; /** Album artist (DAAP tag `asaa`). */
+  readonly albumArtist?: string; /** Album name (DAAP tag `asal`). */
+  readonly album?: string; /** Composer name (DAAP tag `ascp`). */
+  readonly composer?: string; /** Genre name (DAAP tag `asgn`). */
+  readonly genre?: string; /** Track duration in seconds. Converted to/from milliseconds during encoding/decoding. */
+  readonly duration?: number; /** Track number within the album (DAAP tag `astn`). */
+  readonly trackNumber?: number; /** Total number of tracks on the album (DAAP tag `astc`). */
+  readonly trackCount?: number; /** Disc number within the set (DAAP tag `asdn`). */
+  readonly discNumber?: number; /** Total number of discs in the set (DAAP tag `asdc`). */
+  readonly discCount?: number; /** Release year (DAAP tag `asyr`). */
+  readonly year?: number; /** Bitrate in kbps (DAAP tag `asbr`). */
+  readonly bitrate?: number; /** Sample rate in Hz (DAAP tag `assr`). */
+  readonly sampleRate?: number; /** File size in bytes (DAAP tag `assz`). */
   readonly size?: number;
 };
+declare namespace nskeyedarchiver_d_exports {
+  export { decode$3 as decode, decodeAsArray };
+}
+/**
+* Decodes an NSKeyedArchiver binary plist into plain JavaScript objects.
+* Resolves CF$UID references, decodes NS.objects/NS.keys into arrays/dicts,
+* and strips $class metadata.
+*
+* @param archive - The parsed plist archive containing `$objects` and `$top` keys.
+* @returns The resolved root object, or null if the archive is invalid.
+*/
+declare function decode$3(archive: any): unknown;
+/**
+* Decodes an NSKeyedArchiver plist and returns the root as an array.
+* If the root is not an array, wraps it in one.
+*
+* @param archive - The parsed plist archive containing `$objects` and `$top` keys.
+* @returns The resolved root as an array. Non-array roots are wrapped in a single-element array.
+*/
+declare function decodeAsArray(archive: any): unknown[];
 declare namespace ntp_d_exports {
-  export { PacketFields, decode$2 as decode, encode$2 as encode, now, ns, parts };
+  export { PacketFields, decode$2 as decode, encode$2 as encode, now, parts };
 }
+/**
+* Returns the current wall-clock time as a 64-bit NTP timestamp.
+* The upper 32 bits are whole seconds since the NTP epoch (1900-01-01),
+* and the lower 32 bits are the fractional second.
+*
+* Uses `Date.now()` (wall-clock) rather than a monotone clock because Apple
+* devices expect NTP timestamps anchored to real time.
+*
+* @returns The current time as a 64-bit NTP timestamp.
+*/
 declare function now(): bigint;
-declare function ns(): bigint;
+/**
+* Splits a 64-bit NTP timestamp into its seconds and fractional parts.
+*
+* @param ntp - A 64-bit NTP timestamp (upper 32 bits = seconds, lower 32 bits = fraction).
+* @returns A tuple of [seconds, fraction] as 32-bit unsigned integers.
+*/
 declare function parts(ntp: bigint): [number, number];
+/**
+* Decodes an NTP timing packet from a buffer into its constituent fields.
+* Expects at least 24 bytes; the send timestamp fields (bytes 24-31) default
+* to 0 if the buffer is shorter than 32 bytes.
+*
+* @param buffer - The raw NTP packet buffer (minimum 24 bytes).
+* @returns The decoded packet fields.
+* @throws RangeError if the buffer is shorter than 24 bytes.
+*/
 declare function decode$2(buffer: Buffer): PacketFields;
+/**
+* Encodes NTP timing packet fields into a 32-byte buffer.
+*
+* @param fields - The packet fields to encode.
+* @returns A 32-byte buffer containing the encoded NTP packet.
+*/
 declare function encode$2(fields: PacketFields): Buffer;
+/** Fields of an NTP timing packet used for clock synchronization with Apple devices. */
 type PacketFields = {
-  readonly proto: number;
-  readonly type: number;
-  readonly seqno: number;
-  readonly padding: number;
-  readonly reftime_sec: number;
-  readonly reftime_frac: number;
-  readonly recvtime_sec: number;
-  readonly recvtime_frac: number;
-  readonly sendtime_sec: number;
+  /** Protocol identifier byte. */readonly proto: number; /** Packet type (e.g. request or response). */
+  readonly type: number; /** Sequence number for correlating requests and responses. */
+  readonly seqno: number; /** Padding field (typically zero). */
+  readonly padding: number; /** Reference timestamp, seconds part. */
+  readonly reftime_sec: number; /** Reference timestamp, fractional part. */
+  readonly reftime_frac: number; /** Receive timestamp, seconds part. */
+  readonly recvtime_sec: number; /** Receive timestamp, fractional part. */
+  readonly recvtime_frac: number; /** Send timestamp, seconds part. */
+  readonly sendtime_sec: number; /** Send timestamp, fractional part. */
   readonly sendtime_frac: number;
 };
 declare namespace opack_d_exports {
   export { decode$1 as decode, encode$1 as encode, float, int, sizedInteger };
 }
+/**
+* Wrapper that forces a number to be encoded as an OPack float (FLOAT64).
+* Without this wrapper, JavaScript numbers that happen to be integers
+* would be encoded as OPack integers instead.
+*/
 declare class Float {
   #private;
+  /** The wrapped floating-point value. */
   get value(): number;
+  /**
+  * @param value - The floating-point number to wrap.
+  */
   constructor(value: number);
 }
+/**
+* Wrapper that forces a number to be encoded as an OPack integer.
+* Useful when a value must be encoded as an integer even if it could
+* be represented as an inline value.
+*/
 declare class Integer {
   #private;
+  /** The wrapped integer value. */
   get value(): number;
+  /**
+  * @param value - The integer number to wrap.
+  */
   constructor(value: number);
 }
+/**
+* An integer with an explicit byte size. Produced during OPack decoding when
+* the wire format specifies the exact byte width (1, 2, 4, or 8). During
+* encoding, the specified size is preserved to maintain wire compatibility.
+*/
 declare class SizedInteger {
   #private;
+  /** The byte width of this integer on the wire (1, 2, 4, or 8). */
   get size(): number;
+  /** The numeric value. */
   get value(): number;
+  /**
+  * @param value - The integer value.
+  * @param size - The byte width for wire encoding (1, 2, 4, or 8).
+  */
   constructor(value: number, size: number);
+  /**
+  * Returns the numeric value, enabling implicit numeric coercion.
+  *
+  * @returns The integer value.
+  */
   valueOf(): number;
 }
+/**
+* Creates an OPack float wrapper, ensuring the value is encoded as FLOAT64
+* on the wire regardless of whether it is a whole number.
+*
+* @param value - The floating-point number.
+* @returns A Float wrapper for OPack encoding.
+*/
 declare function float(value: number): Float;
+/**
+* Creates an OPack integer wrapper, ensuring the value is encoded as an
+* explicit integer type on the wire.
+*
+* @param value - The integer number.
+* @returns An Integer wrapper for OPack encoding.
+*/
 declare function int(value: number): Integer;
+/**
+* Creates an OPack sized integer with an explicit byte width.
+* Used during decoding to preserve the original wire size, and during
+* encoding to force a specific byte width.
+*
+* @param value - The integer value.
+* @param size - The byte width (1, 2, 4, or 8).
+* @returns A SizedInteger wrapper for OPack encoding.
+*/
 declare function sizedInteger(value: number, size: number): SizedInteger;
+/**
+* Decodes an OPack-encoded byte array into a JavaScript value.
+* OPack is Apple's compact binary serialization format used in
+* Companion Link and other protocols.
+*
+* @param data - The raw OPack-encoded bytes.
+* @returns The decoded JavaScript value (object, array, string, number, boolean, null, or Uint8Array).
+*/
 declare function decode$1(data: Uint8Array): any;
+/**
+* Encodes a JavaScript value into OPack binary format.
+* Supports null, booleans, numbers, strings, Uint8Array/Buffer, arrays,
+* plain objects, and the explicit type wrappers ({@link float}, {@link int}, {@link sizedInteger}).
+* Automatically deduplicates repeated values using back-references.
+*
+* @param data - The value to encode.
+* @returns The OPack-encoded bytes.
+* @throws TypeError if the value type is unsupported.
+*/
 declare function encode$1(data: any): Uint8Array;
 //#endregion
 //#region ../../node_modules/.bun/@plist+common@1.1.0/node_modules/@plist/common/lib/cjs/types.d.ts
@@ -159,9 +373,17 @@ declare namespace plist_d_exports {
 declare namespace tlv8_d_exports {
   export { ErrorCode, Flags, Method, State, TLV8PairingError, Value, bail, decode, encode };
 }
+/**
+* TLV8 pairing flags used during HAP pair-setup and pair-verify.
+* Sent as part of the TLV8 Flags (0x13) value.
+*/
 declare const Flags: {
   readonly TransientPairing: 0x10;
 };
+/**
+* TLV8 error codes returned by the accessory during pairing.
+* Included in the Error (0x07) TLV value.
+*/
 declare const ErrorCode: {
   readonly Unknown: 0x01;
   readonly Authentication: 0x02;
@@ -171,6 +393,10 @@ declare const ErrorCode: {
   readonly Unavailable: 0x06;
   readonly Busy: 0x07;
 };
+/**
+* HAP pairing method identifiers. Sent in the Method (0x00) TLV value
+* to indicate which pairing operation is being performed.
+*/
 declare const Method: {
   readonly PairSetup: 0x00;
   readonly PairSetupWithAuth: 0x01;
@@ -179,6 +405,10 @@ declare const Method: {
   readonly RemovePairing: 0x04;
   readonly ListPairing: 0x05;
 };
+/**
+* HAP pairing state machine steps (M1 through M6).
+* Each state corresponds to a message in the SRP pair-setup or pair-verify flow.
+*/
 declare const State: {
   readonly M1: 0x01;
   readonly M2: 0x02;
@@ -187,6 +417,10 @@ declare const State: {
   readonly M5: 0x05;
   readonly M6: 0x06;
 };
+/**
+* TLV8 type identifiers for the fields exchanged during HAP pairing.
+* Each value is the type byte that precedes the length and data in a TLV8 entry.
+*/
 declare const Value: {
   readonly Method: 0x00;
   readonly Identifier: 0x01;
@@ -205,12 +439,46 @@ declare const Value: {
   readonly Name: 0x11;
   readonly Flags: 0x13;
 };
+/**
+* Error thrown when a TLV8 pairing exchange fails.
+* Carries the numeric error code from the accessory when available.
+*/
 declare class TLV8PairingError extends Error {
+  /** The TLV8 error code from the accessory, if present. */
   readonly code: number | undefined;
+  /**
+  * @param message - Human-readable error description.
+  * @param code - The TLV8 error code from the accessory response.
+  */
   constructor(message: string, code?: number);
 }
+/**
+* Inspects a decoded TLV8 response for error or back-off conditions and throws
+* an appropriate {@link TLV8PairingError}. Always throws; the return type `never`
+* signals to the compiler that execution does not continue past this call.
+*
+* @param data - The decoded TLV8 map from a pairing response.
+* @throws TLV8PairingError with the specific error code, back-off time, or a generic message.
+*/
 declare function bail(data: Map<number, Buffer>): never;
+/**
+* Encodes an array of TLV8 entries into a single buffer.
+* Values longer than 255 bytes are automatically split into multiple
+* consecutive TLV fragments of the same type, as required by the TLV8 spec.
+*
+* @param entries - An array of [type, value] tuples. Values can be a single byte (number),
+*                  a Buffer, or a Uint8Array.
+* @returns A buffer containing all TLV8 entries concatenated.
+*/
 declare function encode(entries: [number, number | Buffer | Uint8Array][]): Buffer;
+/**
+* Decodes a TLV8 buffer into a map of type to value.
+* Consecutive entries with the same type are automatically concatenated,
+* reassembling fragmented values as required by the TLV8 spec.
+*
+* @param buf - The raw TLV8-encoded buffer.
+* @returns A map from TLV8 type byte to the reassembled value buffer.
+*/
 declare function decode(buf: Buffer): Map<number, Buffer>;
 //#endregion
-export { daap_d_exports as DAAP, ntp_d_exports as NTP, opack_d_exports as OPack, plist_d_exports as Plist, tlv8_d_exports as TLV8 };
+export { daap_d_exports as DAAP, nskeyedarchiver_d_exports as NSKeyedArchiver, ntp_d_exports as NTP, opack_d_exports as OPack, plist_d_exports as Plist, tlv8_d_exports as TLV8 };

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { t as __exportAll } from "./chunk-DQk6qfdC.mjs";
 var daap_exports = /* @__PURE__ */ __exportAll({
 	ContentCode: () => ContentCode,
 	TagType: () => TagType,
-	decode: () => decode$3,
+	decode: () => decode$4,
 	decodeTag: () => decodeTag,
 	decodeToObject: () => decodeToObject,
 	decodeTrackMetadata: () => decodeTrackMetadata,
@@ -14,6 +14,10 @@ var daap_exports = /* @__PURE__ */ __exportAll({
 	encodeTagWithSize: () => encodeTagWithSize,
 	encodeTrackMetadata: () => encodeTrackMetadata
 });
+/**
+* Maps four-character DAAP tag codes to their human-readable DMAP/DAAP content code names.
+* Used to identify the semantic meaning of tags in DAAP protocol messages.
+*/
 const ContentCode = {
 	mlit: "dmap.listingitem",
 	mlcl: "dmap.listing",
@@ -43,6 +47,15 @@ const ContentCode = {
 	cavs: "daap.songvisiblestate",
 	aePP: "com.apple.itunes.photo-properties"
 };
+/**
+* Maps four-character DAAP tag codes to their data type identifiers.
+*
+* Type values: 1=byte, 2=unsigned byte, 3=short, 4=unsigned short,
+* 5=int, 6=unsigned int, 7=long, 8=unsigned long,
+* 9=string, 10=date, 11=version, 12=container.
+*
+* Used by the decoder to determine how to interpret the raw bytes of each tag.
+*/
 const TagType = {
 	mlit: 12,
 	mlcl: 12,
@@ -72,6 +85,15 @@ const TagType = {
 	cavs: 1,
 	aePP: 9
 };
+/**
+* Encodes a single DAAP tag with an automatically sized value.
+* Numbers are encoded in the smallest big-endian representation that fits.
+*
+* @param tag - Four-character ASCII tag code (e.g. 'minm', 'asar').
+* @param value - The value to encode: string (UTF-8), number (auto-sized BE), bigint (8-byte BE), or raw Buffer.
+* @returns A buffer containing the tag, length, and value.
+* @throws Error if the tag is not exactly 4 characters.
+*/
 function encodeTag(tag, value) {
 	if (tag.length !== 4) throw new Error(`Invalid DAAP tag: ${tag}. Tags must be exactly 4 characters.`);
 	const tagBuffer = Buffer.from(tag, "ascii");
@@ -102,6 +124,14 @@ function encodeTag(tag, value) {
 		valueBuffer
 	]);
 }
+/**
+* Encodes a DAAP container tag that wraps other encoded tags.
+*
+* @param tag - Four-character ASCII container tag code (e.g. 'mlit', 'mlcl').
+* @param content - Pre-encoded buffer containing the container's child tags.
+* @returns A buffer containing the container tag, length, and nested content.
+* @throws Error if the tag is not exactly 4 characters.
+*/
 function encodeContainer(tag, content) {
 	if (tag.length !== 4) throw new Error(`Invalid DAAP tag: ${tag}. Tags must be exactly 4 characters.`);
 	const tagBuffer = Buffer.from(tag, "ascii");
@@ -113,6 +143,13 @@ function encodeContainer(tag, content) {
 		content
 	]);
 }
+/**
+* Encodes playback status fields (playing, shuffle, repeat) into DAAP tags.
+* Only includes tags for fields that are defined in the status object.
+*
+* @param status - The playback status to encode.
+* @returns A buffer containing the encoded DAAP status tags.
+*/
 function encodePlaybackStatus(status) {
 	const tags = [];
 	if (status.playing !== void 0) tags.push(encodeTagWithSize("caps", status.playing ? 4 : 3, 1));
@@ -125,6 +162,16 @@ function encodePlaybackStatus(status) {
 	}
 	return Buffer.concat(tags);
 }
+/**
+* Encodes a DAAP tag with an explicitly specified byte size for the numeric value.
+* Useful when the protocol requires a specific size regardless of the value magnitude.
+*
+* @param tag - Four-character ASCII tag code.
+* @param value - The numeric value to encode.
+* @param byteSize - The exact number of bytes to use for the value (1, 2, 4, or 8).
+* @returns A buffer containing the tag, length, and fixed-size value.
+* @throws Error if the tag is not exactly 4 characters.
+*/
 function encodeTagWithSize(tag, value, byteSize) {
 	if (tag.length !== 4) throw new Error(`Invalid DAAP tag: ${tag}. Tags must be exactly 4 characters.`);
 	const tagBuffer = Buffer.from(tag, "ascii");
@@ -151,6 +198,14 @@ function encodeTagWithSize(tag, value, byteSize) {
 		valueBuffer
 	]);
 }
+/**
+* Encodes track metadata into a DAAP listing item (`mlit`) container.
+* Only includes tags for fields that are defined in the metadata object.
+* Duration is converted from seconds to milliseconds for the `astm` tag.
+*
+* @param metadata - The track metadata to encode.
+* @returns A buffer containing an `mlit` container with all defined metadata tags.
+*/
 function encodeTrackMetadata(metadata) {
 	const tags = [];
 	if (metadata.title !== void 0) tags.push(encodeTag("minm", metadata.title));
@@ -170,7 +225,14 @@ function encodeTrackMetadata(metadata) {
 	if (metadata.size !== void 0) tags.push(encodeTagWithSize("assz", metadata.size, 4));
 	return encodeContainer("mlit", Buffer.concat(tags));
 }
-function decode$3(buffer) {
+/**
+* Decodes all DAAP tags from a buffer sequentially.
+* Stops when the buffer is exhausted or a tag cannot be fully decoded.
+*
+* @param buffer - The raw DAAP-encoded buffer.
+* @returns An array of decoded tags with their raw value buffers.
+*/
+function decode$4(buffer) {
 	const tags = [];
 	let remaining = buffer;
 	while (remaining.length > 0) {
@@ -182,6 +244,13 @@ function decode$3(buffer) {
 	}
 	return tags;
 }
+/**
+* Decodes a single DAAP tag from the start of a buffer.
+* Returns the decoded tag and the remaining unconsumed buffer.
+*
+* @param buffer - The buffer to decode from. Must contain at least 8 bytes (4 tag + 4 length).
+* @returns A tuple of the decoded tag and remaining buffer, or null if the buffer is too short.
+*/
 function decodeTag(buffer) {
 	if (buffer.length < 8) return null;
 	const tag = buffer.subarray(0, 4).toString("ascii");
@@ -195,9 +264,16 @@ function decodeTag(buffer) {
 		value
 	}, remaining];
 }
+/**
+* Decodes a DAAP buffer into a plain object, interpreting values based on {@link TagType}.
+* Container tags (type 12) are recursively decoded. Unknown tags are kept as raw buffers.
+*
+* @param buffer - The raw DAAP-encoded buffer.
+* @returns An object mapping tag codes to their decoded values.
+*/
 function decodeToObject(buffer) {
 	const result = {};
-	const tags = decode$3(buffer);
+	const tags = decode$4(buffer);
 	for (const { tag, value } of tags) {
 		const tagType = TagType[tag];
 		if (tagType === void 0) result[tag] = value;
@@ -211,6 +287,14 @@ function decodeToObject(buffer) {
 	}
 	return result;
 }
+/**
+* Decodes a DAAP buffer into a structured {@link TrackMetadata} object.
+* Handles both bare tag lists and `mlit`-wrapped containers.
+* Duration is converted from the DAAP millisecond `astm` value back to seconds.
+*
+* @param buffer - The raw DAAP-encoded buffer containing track metadata.
+* @returns The decoded track metadata.
+*/
 function decodeTrackMetadata(buffer) {
 	const obj = decodeToObject(buffer);
 	const mlit = obj.mlit ?? obj;
@@ -233,28 +317,107 @@ function decodeTrackMetadata(buffer) {
 	};
 }
 
+//#endregion
+//#region src/nskeyedarchiver.ts
+var nskeyedarchiver_exports = /* @__PURE__ */ __exportAll({
+	decode: () => decode$3,
+	decodeAsArray: () => decodeAsArray
+});
+/**
+* Decodes an NSKeyedArchiver binary plist into plain JavaScript objects.
+* Resolves CF$UID references, decodes NS.objects/NS.keys into arrays/dicts,
+* and strips $class metadata.
+*
+* @param archive - The parsed plist archive containing `$objects` and `$top` keys.
+* @returns The resolved root object, or null if the archive is invalid.
+*/
+function decode$3(archive) {
+	const objects = archive?.["$objects"];
+	const top = archive?.["$top"];
+	if (!objects || !top) return null;
+	const resolve = (ref) => {
+		if (ref && typeof ref === "object" && "CF$UID" in ref) return resolve(objects[ref["CF$UID"]]);
+		if (ref === "$null") return null;
+		if (ref && typeof ref === "object") {
+			const obj = ref;
+			if (obj["NS.objects"] && Array.isArray(obj["NS.objects"])) return obj["NS.objects"].map(resolve);
+			if (obj["NS.keys"] && Array.isArray(obj["NS.keys"])) {
+				const keys = obj["NS.keys"].map(resolve);
+				const values = obj["NS.objects"].map(resolve);
+				const result = {};
+				for (let i = 0; i < keys.length; i++) result[keys[i]] = values[i];
+				return result;
+			}
+			const result = {};
+			for (const [key, value] of Object.entries(obj)) {
+				if (key === "$class" || key === "$classname" || key === "$classes") continue;
+				result[key] = resolve(value);
+			}
+			return result;
+		}
+		return ref;
+	};
+	return resolve(top.root ?? top);
+}
+/**
+* Decodes an NSKeyedArchiver plist and returns the root as an array.
+* If the root is not an array, wraps it in one.
+*
+* @param archive - The parsed plist archive containing `$objects` and `$top` keys.
+* @returns The resolved root as an array. Non-array roots are wrapped in a single-element array.
+*/
+function decodeAsArray(archive) {
+	const root = decode$3(archive);
+	return Array.isArray(root) ? root : [root];
+}
+
 //#endregion
 //#region src/ntp.ts
 var ntp_exports = /* @__PURE__ */ __exportAll({
 	decode: () => decode$2,
 	encode: () => encode$2,
 	now: () => now,
-	ns: () => ns,
 	parts: () => parts
 });
+/**
+* NTP epoch offset: the number of seconds between the NTP epoch (1900-01-01)
+* and the Unix epoch (1970-01-01).
+*/
 const EPOCH$1 = 2208988800n;
+/**
+* Returns the current wall-clock time as a 64-bit NTP timestamp.
+* The upper 32 bits are whole seconds since the NTP epoch (1900-01-01),
+* and the lower 32 bits are the fractional second.
+*
+* Uses `Date.now()` (wall-clock) rather than a monotone clock because Apple
+* devices expect NTP timestamps anchored to real time.
+*
+* @returns The current time as a 64-bit NTP timestamp.
+*/
 function now() {
-	const now = ns() / 1000n;
-	const seconds = now / 1000000n;
-	const frac = now - seconds * 1000000n;
-	return seconds + EPOCH$1 << 32n | (frac << 32n) / 1000000n;
-}
-function ns() {
-	return process.hrtime.bigint();
+	const nowMs = BigInt(Date.now());
+	const seconds = nowMs / 1000n;
+	const frac = nowMs - seconds * 1000n;
+	return seconds + EPOCH$1 << 32n | (frac << 32n) / 1000n;
 }
+/**
+* Splits a 64-bit NTP timestamp into its seconds and fractional parts.
+*
+* @param ntp - A 64-bit NTP timestamp (upper 32 bits = seconds, lower 32 bits = fraction).
+* @returns A tuple of [seconds, fraction] as 32-bit unsigned integers.
+*/
 function parts(ntp) {
 	return [Number(ntp >> 32n), Number(ntp & 4294967295n)];
 }
+/**
+* Decodes an NTP timing packet from a buffer into its constituent fields.
+* Expects at least 24 bytes; the send timestamp fields (bytes 24-31) default
+* to 0 if the buffer is shorter than 32 bytes.
+*
+* @param buffer - The raw NTP packet buffer (minimum 24 bytes).
+* @returns The decoded packet fields.
+* @throws RangeError if the buffer is shorter than 24 bytes.
+*/
 function decode$2(buffer) {
 	if (buffer.length < 24) throw new RangeError(`NTP packet too small: expected at least 24 bytes, got ${buffer.length}`);
 	return {
@@ -270,6 +433,12 @@ function decode$2(buffer) {
 		sendtime_frac: buffer.length >= 32 ? buffer.readUInt32BE(28) : 0
 	};
 }
+/**
+* Encodes NTP timing packet fields into a 32-byte buffer.
+*
+* @param fields - The packet fields to encode.
+* @returns A 32-byte buffer containing the encoded NTP packet.
+*/
 function encode$2(fields) {
 	const buffer = Buffer.allocUnsafe(32);
 	buffer.writeUInt8(fields.proto, 0);
@@ -294,6 +463,11 @@ var opack_exports = /* @__PURE__ */ __exportAll({
 	int: () => int,
 	sizedInteger: () => sizedInteger
 });
+/**
+* OPack wire-format tag bytes. Each tag identifies the type and sometimes
+* the inline length of the value that follows. Apple uses OPack for
+* Companion Link and other device-to-device communication.
+*/
 const TAG = {
 	TRUE: 1,
 	FALSE: 2,
@@ -335,59 +509,147 @@ const TAG = {
 };
 const textDecoder = new TextDecoder();
 const textEncoder = new TextEncoder();
+/**
+* Wrapper that forces a number to be encoded as an OPack float (FLOAT64).
+* Without this wrapper, JavaScript numbers that happen to be integers
+* would be encoded as OPack integers instead.
+*/
 var Float = class {
+	/** The wrapped floating-point value. */
 	get value() {
 		return this.#value;
 	}
 	#value;
+	/**
+	* @param value - The floating-point number to wrap.
+	*/
 	constructor(value) {
 		this.#value = value;
 	}
 };
+/**
+* Wrapper that forces a number to be encoded as an OPack integer.
+* Useful when a value must be encoded as an integer even if it could
+* be represented as an inline value.
+*/
 var Integer = class {
+	/** The wrapped integer value. */
 	get value() {
 		return this.#value;
 	}
 	#value;
+	/**
+	* @param value - The integer number to wrap.
+	*/
 	constructor(value) {
 		this.#value = value;
 	}
 };
+/**
+* An integer with an explicit byte size. Produced during OPack decoding when
+* the wire format specifies the exact byte width (1, 2, 4, or 8). During
+* encoding, the specified size is preserved to maintain wire compatibility.
+*/
 var SizedInteger = class {
+	/** The byte width of this integer on the wire (1, 2, 4, or 8). */
 	get size() {
 		return this.#size;
 	}
+	/** The numeric value. */
 	get value() {
 		return this.#value;
 	}
 	#size;
 	#value;
+	/**
+	* @param value - The integer value.
+	* @param size - The byte width for wire encoding (1, 2, 4, or 8).
+	*/
 	constructor(value, size) {
 		this.#size = size;
 		this.#value = value;
 	}
+	/**
+	* Returns the numeric value, enabling implicit numeric coercion.
+	*
+	* @returns The integer value.
+	*/
 	valueOf() {
 		return this.#value;
 	}
 };
+/**
+* Creates an OPack float wrapper, ensuring the value is encoded as FLOAT64
+* on the wire regardless of whether it is a whole number.
+*
+* @param value - The floating-point number.
+* @returns A Float wrapper for OPack encoding.
+*/
 function float(value) {
 	return new Float(value);
 }
+/**
+* Creates an OPack integer wrapper, ensuring the value is encoded as an
+* explicit integer type on the wire.
+*
+* @param value - The integer number.
+* @returns An Integer wrapper for OPack encoding.
+*/
 function int(value) {
 	return new Integer(value);
 }
+/**
+* Creates an OPack sized integer with an explicit byte width.
+* Used during decoding to preserve the original wire size, and during
+* encoding to force a specific byte width.
+*
+* @param value - The integer value.
+* @param size - The byte width (1, 2, 4, or 8).
+* @returns A SizedInteger wrapper for OPack encoding.
+*/
 function sizedInteger(value, size) {
 	return new SizedInteger(value, size);
 }
+/**
+* Decodes an OPack-encoded byte array into a JavaScript value.
+* OPack is Apple's compact binary serialization format used in
+* Companion Link and other protocols.
+*
+* @param data - The raw OPack-encoded bytes.
+* @returns The decoded JavaScript value (object, array, string, number, boolean, null, or Uint8Array).
+*/
 function decode$1(data) {
 	return _unpackAt(data, 0, []).value;
 }
+/**
+* Encodes a JavaScript value into OPack binary format.
+* Supports null, booleans, numbers, strings, Uint8Array/Buffer, arrays,
+* plain objects, and the explicit type wrappers ({@link float}, {@link int}, {@link sizedInteger}).
+* Automatically deduplicates repeated values using back-references.
+*
+* @param data - The value to encode.
+* @returns The OPack-encoded bytes.
+* @throws TypeError if the value type is unsupported.
+*/
 function encode$1(data) {
 	return _pack(data, []);
 }
+/**
+* Creates a single-byte Uint8Array.
+*
+* @param b - The byte value (0-255).
+* @returns A Uint8Array containing the single byte.
+*/
 function u8(b) {
 	return Uint8Array.of(b);
 }
+/**
+* Converts an unsigned integer to a little-endian byte array.
+*
+* @param value - The integer value to convert.
+* @param byteLen - The number of bytes to produce.
+* @returns A Uint8Array of length `byteLen` in little-endian order.
+*/
 function uintToLEBytes(value, byteLen) {
 	const out = new Uint8Array(byteLen);
 	let v = BigInt(value);
@@ -397,6 +659,15 @@ function uintToLEBytes(value, byteLen) {
 	}
 	return out;
 }
+/**
+* Reads a little-endian unsigned integer of arbitrary byte length from a buffer.
+* Returns 0 if the read would exceed the buffer bounds.
+*
+* @param buf - The source buffer.
+* @param offset - The byte offset to start reading from.
+* @param len - The number of bytes to read (1, 2, 4, or any).
+* @returns The decoded unsigned integer value.
+*/
 function readLittleEndian(buf, offset, len) {
 	if (offset + len > buf.length) return 0;
 	if (len === 1) return buf[offset];
@@ -408,6 +679,16 @@ function readLittleEndian(buf, offset, len) {
 		return Number(v);
 	}
 }
+/**
+* Recursively packs a JavaScript value into OPack binary format.
+* Maintains an object list for back-reference deduplication: if a packed
+* value already exists in the list, a compact reference tag is emitted instead.
+*
+* @param data - The value to pack.
+* @param objectList - Accumulator of previously packed objects for deduplication.
+* @returns The OPack-encoded bytes for this value.
+* @throws TypeError if the value type is unsupported.
+*/
 function _pack(data, objectList) {
 	let packed = null;
 	if (data === null || data === void 0) packed = u8(TAG.NULL);
@@ -444,6 +725,10 @@ function _pack(data, objectList) {
 		packed = new Uint8Array(9);
 		packed[0] = TAG.FLOAT64;
 		new DataView(packed.buffer, packed.byteOffset + 1, 8).setFloat64(0, data, true);
+	} else if (data < 0) {
+		packed = new Uint8Array(9);
+		packed[0] = TAG.INT_8BYTE;
+		new DataView(packed.buffer, packed.byteOffset + 1, 8).setBigInt64(0, BigInt(data), true);
 	} else if (data <= TAG.INT_INLINE_MAX_VALUE) packed = u8(TAG.INT_BASE + data);
 	else if (data <= 255) {
 		packed = new Uint8Array(2);
@@ -612,6 +897,18 @@ function _pack(data, objectList) {
 	else if (packed.length > 1) objectList.push(packed);
 	return packed;
 }
+/**
+* Unpacks a single OPack value starting at the given offset.
+* Handles all OPack types: booleans, null, UUID, timestamp, integers, floats,
+* strings, byte arrays, arrays, dictionaries, and back-references.
+* Decoded non-reference values are added to the object list for future reference resolution.
+*
+* @param data - The full OPack-encoded buffer.
+* @param offset - The byte offset to start unpacking from.
+* @param objectList - Accumulator of previously unpacked objects for reference resolution.
+* @returns The unpacked value and the new byte offset.
+* @throws TypeError if the buffer is exhausted or an unknown tag is encountered.
+*/
 function _unpackAt(data, offset, objectList) {
 	if (offset >= data.length) throw new TypeError("No data to unpack");
 	const tag = data[offset];
@@ -1261,7 +1558,15 @@ var tlv8_exports = /* @__PURE__ */ __exportAll({
 	decode: () => decode,
 	encode: () => encode
 });
+/**
+* TLV8 pairing flags used during HAP pair-setup and pair-verify.
+* Sent as part of the TLV8 Flags (0x13) value.
+*/
 const Flags = { TransientPairing: 16 };
+/**
+* TLV8 error codes returned by the accessory during pairing.
+* Included in the Error (0x07) TLV value.
+*/
 const ErrorCode = {
 	Unknown: 1,
 	Authentication: 2,
@@ -1271,6 +1576,10 @@ const ErrorCode = {
 	Unavailable: 6,
 	Busy: 7
 };
+/**
+* HAP pairing method identifiers. Sent in the Method (0x00) TLV value
+* to indicate which pairing operation is being performed.
+*/
 const Method = {
 	PairSetup: 0,
 	PairSetupWithAuth: 1,
@@ -1279,6 +1588,10 @@ const Method = {
 	RemovePairing: 4,
 	ListPairing: 5
 };
+/**
+* HAP pairing state machine steps (M1 through M6).
+* Each state corresponds to a message in the SRP pair-setup or pair-verify flow.
+*/
 const State = {
 	M1: 1,
 	M2: 2,
@@ -1287,6 +1600,10 @@ const State = {
 	M5: 5,
 	M6: 6
 };
+/**
+* TLV8 type identifiers for the fields exchanged during HAP pairing.
+* Each value is the type byte that precedes the length and data in a TLV8 entry.
+*/
 const Value = {
 	Method: 0,
 	Identifier: 1,
@@ -1305,14 +1622,31 @@ const Value = {
 	Name: 17,
 	Flags: 19
 };
+/**
+* Error thrown when a TLV8 pairing exchange fails.
+* Carries the numeric error code from the accessory when available.
+*/
 var TLV8PairingError = class extends Error {
+	/** The TLV8 error code from the accessory, if present. */
 	code;
+	/**
+	* @param message - Human-readable error description.
+	* @param code - The TLV8 error code from the accessory response.
+	*/
 	constructor(message, code) {
 		super(message);
 		this.name = "TLV8PairingError";
 		this.code = code;
 	}
 };
+/**
+* Inspects a decoded TLV8 response for error or back-off conditions and throws
+* an appropriate {@link TLV8PairingError}. Always throws; the return type `never`
+* signals to the compiler that execution does not continue past this call.
+*
+* @param data - The decoded TLV8 map from a pairing response.
+* @throws TLV8PairingError with the specific error code, back-off time, or a generic message.
+*/
 function bail(data) {
 	if (data.has(Value.BackOff)) {
 		const buffer = data.get(Value.BackOff);
@@ -1326,6 +1660,15 @@ function bail(data) {
 	}
 	throw new TLV8PairingError("Invalid response");
 }
+/**
+* Encodes an array of TLV8 entries into a single buffer.
+* Values longer than 255 bytes are automatically split into multiple
+* consecutive TLV fragments of the same type, as required by the TLV8 spec.
+*
+* @param entries - An array of [type, value] tuples. Values can be a single byte (number),
+*                  a Buffer, or a Uint8Array.
+* @returns A buffer containing all TLV8 entries concatenated.
+*/
 function encode(entries) {
 	let totalSize = 0;
 	for (const [, valueRaw] of entries) {
@@ -1361,6 +1704,14 @@ function encode(entries) {
 	}
 	return result;
 }
+/**
+* Decodes a TLV8 buffer into a map of type to value.
+* Consecutive entries with the same type are automatically concatenated,
+* reassembling fragmented values as required by the TLV8 spec.
+*
+* @param buf - The raw TLV8-encoded buffer.
+* @returns A map from TLV8 type byte to the reassembled value buffer.
+*/
 function decode(buf) {
 	const map = /* @__PURE__ */ new Map();
 	let i = 0;
@@ -1380,4 +1731,4 @@ function decode(buf) {
 }
 
 //#endregion
-export { daap_exports as DAAP, ntp_exports as NTP, opack_exports as OPack, plist_exports as Plist, tlv8_exports as TLV8 };
+export { daap_exports as DAAP, nskeyedarchiver_exports as NSKeyedArchiver, ntp_exports as NTP, opack_exports as OPack, plist_exports as Plist, tlv8_exports as TLV8 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@basmilius/apple-encoding",
     "description": "Common encoding utilities for Apple Protocols.",
-    "version": "0.9.19",
+    "version": "0.10.1",
     "type": "module",
     "license": "MIT",
     "author": {