@particle/esim-tooling 1.0.0 → 1.1.0

package/README.md

@@ -130,6 +130,74 @@ const server: ServerAdapter = {
 };
 ```
 
+### Logging
+
+The library provides utilities for logging APDU and ES9+ traffic, useful for debugging adapter implementations.
+
+**LoggingDeviceAdapter** wraps any `DeviceAdapter` to log all APDU traffic:
+
+```typescript
+import { LoggingDeviceAdapter } from '@particle/esim-tooling';
+
+// Wrap your adapter with default console logging
+const loggingAdapter = new LoggingDeviceAdapter(rawAdapter);
+
+// Or provide a custom logger
+const loggingAdapter = new LoggingDeviceAdapter(rawAdapter, (event) => {
+  // event.index: sequential APDU number (1-based)
+  // event.direction: 'request' | 'response'
+  // event.formatted: human-readable string
+  // event.raw: Uint8Array of raw bytes
+  // event.isError: true if response SW1 is not 0x90 or 0x61
+  myLogger.debug(`APDU ${event.direction}: ${event.formatted}`);
+});
+
+const lpa = new EsimLpa({ device: loggingAdapter, server });
+```
+
+**LoggingServerAdapter** wraps any `ServerAdapter` to log all ES9+ traffic:
+
+```typescript
+import { LoggingServerAdapter } from '@particle/esim-tooling';
+
+// Wrap your adapter with default console logging
+const loggingAdapter = new LoggingServerAdapter(rawAdapter);
+
+// Or provide a custom logger
+const loggingAdapter = new LoggingServerAdapter(rawAdapter, (event) => {
+  // event.index: sequential request number (1-based)
+  // event.direction: 'request' | 'response'
+  // event.formatted: human-readable string
+  // event.endpoint: ES9+ endpoint name
+  // event.smdpAddress: SM-DP+ server address
+  // event.statusCode: HTTP status (response only)
+  // event.raw: Uint8Array of raw bytes
+  // event.isError: true if HTTP status >= 400
+  myLogger.debug(`ES9+ ${event.direction}: ${event.formatted}`);
+});
+
+const lpa = new EsimLpa({ device, server: loggingAdapter });
+```
+
+**Standalone formatting functions** for custom logging:
+
+```typescript
+import {
+  formatApduRequest, formatApduResponse, isApduError,
+  formatServerRequest, formatServerResponse, isServerError,
+} from '@particle/esim-tooling';
+
+// APDU formatting
+formatApduRequest(apdu);      // "ch1 STORE_DATA(255) MORE blk=0 (81e21100 ff ...)"
+formatApduResponse(response); // "OK (9000)" or "MORE_DATA(16) (6110)"
+isApduError(response);        // true if SW1 not 0x90 or 0x61
+
+// ES9+ formatting
+formatServerRequest('initiateAuthentication', 'smdp.example.com', data); // "initiateAuthentication smdp.example.com (123 bytes)"
+formatServerResponse(200, data); // "HTTP 200 (456 bytes)"
+isServerError(statusCode);       // true if status >= 400
+```
+
 ## API Reference
 
 ### `EsimLpa`

package/dist/index.d.ts

@@ -3,4 +3,7 @@ export { ProfileState, ProfileClass, NotificationEvent, CancelSessionReason, Ena
 export type { DeviceAdapter, ServerAdapter, ServerResponse, Profile, Notification, NotificationMetadata, NotificationWithResult, SendResult, ProcessNotificationsOptions, ProcessNotificationsResult, ProfileInstallationResult, ActivationCode, DownloadStep, DownloadProgress, DownloadResult, InstallProfileOptions, EsimLpaOptions, } from './types.js';
 export { EsimError, DeviceError, Es10Error, Es9PlusError, TlvError, ActivationCodeError, } from './errors.js';
 export { parseActivationCode, isValidActivationCode, formatActivationCode } from './activation-code.js';
+export { formatApduRequest, formatApduResponse, isApduError, formatServerRequest, formatServerResponse, isServerError, } from './logging-format.js';
+export { LoggingDeviceAdapter, LoggingServerAdapter } from './logging-adapter.js';
+export type { ApduLogEvent, ServerLogEvent } from './logging-adapter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,OAAO,EACP,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,EACtB,UAAU,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,OAAO,EACP,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,EACtB,UAAU,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAExG,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -2,4 +2,6 @@ export { EsimLpa } from './lpa.js';
 export { ProfileState, ProfileClass, NotificationEvent, CancelSessionReason, EnableProfileResult, DisableProfileResult, DeleteProfileResult, BppInstallErrorCode, } from './types.js';
 export { EsimError, DeviceError, Es10Error, Es9PlusError, TlvError, ActivationCodeError, } from './errors.js';
 export { parseActivationCode, isValidActivationCode, formatActivationCode } from './activation-code.js';
+export { formatApduRequest, formatApduResponse, isApduError, formatServerRequest, formatServerResponse, isServerError, } from './logging-format.js';
+export { LoggingDeviceAdapter, LoggingServerAdapter } from './logging-adapter.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAsBpB,OAAO,EACL,SAAS,EACT,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAsBpB,OAAO,EACL,SAAS,EACT,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAExG,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/logging-adapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Optional logging wrappers for DeviceAdapter and ServerAdapter.
+ *
+ * Wraps adapters to log traffic using the decorator pattern.
+ * The underlying adapters are unchanged.
+ */
+import type { DeviceAdapter, ServerAdapter, ServerResponse } from './types.js';
+/**
+ * Event emitted for each APDU request or response.
+ */
+export interface ApduLogEvent {
+    /** Sequential APDU index (1-based) */
+    index: number;
+    /** Whether this is a request or response */
+    direction: 'request' | 'response';
+    /** Human-readable formatted string */
+    formatted: string;
+    /** Raw APDU bytes */
+    raw: Uint8Array;
+    /** True if response SW1 is not 0x90 or 0x61 */
+    isError: boolean;
+}
+/**
+ * A DeviceAdapter wrapper that logs all APDU traffic.
+ *
+ * @example
+ * ```typescript
+ * import { LoggingDeviceAdapter } from '@particle/esim-tooling';
+ *
+ * // Use default console logging
+ * const adapter = new LoggingDeviceAdapter(rawAdapter);
+ *
+ * // Or provide a custom logger
+ * const adapter = new LoggingDeviceAdapter(rawAdapter, (event) => {
+ *   myLogger.debug(`APDU ${event.direction}: ${event.formatted}`);
+ * });
+ * ```
+ */
+export declare class LoggingDeviceAdapter implements DeviceAdapter {
+    private inner;
+    private logger;
+    private apduCount;
+    constructor(inner: DeviceAdapter, logger?: (event: ApduLogEvent) => void);
+    sendApdu(apdu: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * Event emitted for each ES9+ server request or response.
+ */
+export interface ServerLogEvent {
+    /** Sequential request index (1-based) */
+    index: number;
+    /** Whether this is a request or response */
+    direction: 'request' | 'response';
+    /** Human-readable formatted string */
+    formatted: string;
+    /** ES9+ endpoint name */
+    endpoint: string;
+    /** SM-DP+ server address */
+    smdpAddress: string;
+    /** HTTP status code (response only) */
+    statusCode?: number;
+    /** Raw request/response bytes */
+    raw?: Uint8Array;
+    /** True if HTTP status >= 400 */
+    isError: boolean;
+}
+/**
+ * A ServerAdapter wrapper that logs all ES9+ traffic.
+ *
+ * @example
+ * ```typescript
+ * import { LoggingServerAdapter } from '@particle/esim-tooling';
+ *
+ * // Use default console logging
+ * const adapter = new LoggingServerAdapter(rawAdapter);
+ *
+ * // Or provide a custom logger
+ * const adapter = new LoggingServerAdapter(rawAdapter, (event) => {
+ *   myLogger.debug(`ES9+ ${event.direction}: ${event.formatted}`);
+ * });
+ * ```
+ */
+export declare class LoggingServerAdapter implements ServerAdapter {
+    private inner;
+    private logger;
+    private requestCount;
+    constructor(inner: ServerAdapter, logger?: (event: ServerLogEvent) => void);
+    sendRsp(smdpAddress: string, endpoint: string, requestData: Uint8Array): Promise<ServerResponse>;
+}
+//# sourceMappingURL=logging-adapter.d.ts.map

package/dist/logging-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-adapter.d.ts","sourceRoot":"","sources":["../src/logging-adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAc/E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,SAAS,EAAE,SAAS,GAAG,UAAU,CAAC;IAClC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,GAAG,EAAE,UAAU,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AAUD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,SAAS,CAAK;gBAEV,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI;IAKlE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;CA2BtD;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,SAAS,EAAE,SAAS,GAAG,UAAU,CAAC;IAClC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;CAClB;AAUD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,YAAY,CAAK;gBAEb,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI;IAKpE,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;CAgCvG"}

package/dist/logging-adapter.js

@@ -0,0 +1,123 @@
+/**
+ * Optional logging wrappers for DeviceAdapter and ServerAdapter.
+ *
+ * Wraps adapters to log traffic using the decorator pattern.
+ * The underlying adapters are unchanged.
+ */
+import { formatApduRequest, formatApduResponse, isApduError, formatServerRequest, formatServerResponse, isServerError, } from './logging-format.js';
+/**
+ * Default APDU logger that writes to console.
+ */
+function defaultApduLogger(event) {
+    const prefix = event.direction === 'request' ? '>>' : event.isError ? '!!' : '<<';
+    console.log(`    APDU[${event.index}] ${prefix} ${event.formatted}`);
+}
+/**
+ * A DeviceAdapter wrapper that logs all APDU traffic.
+ *
+ * @example
+ * ```typescript
+ * import { LoggingDeviceAdapter } from '@particle/esim-tooling';
+ *
+ * // Use default console logging
+ * const adapter = new LoggingDeviceAdapter(rawAdapter);
+ *
+ * // Or provide a custom logger
+ * const adapter = new LoggingDeviceAdapter(rawAdapter, (event) => {
+ *   myLogger.debug(`APDU ${event.direction}: ${event.formatted}`);
+ * });
+ * ```
+ */
+export class LoggingDeviceAdapter {
+    inner;
+    logger;
+    apduCount = 0;
+    constructor(inner, logger) {
+        this.inner = inner;
+        this.logger = logger ?? defaultApduLogger;
+    }
+    async sendApdu(apdu) {
+        this.apduCount++;
+        const index = this.apduCount;
+        // Log request
+        this.logger({
+            index,
+            direction: 'request',
+            formatted: formatApduRequest(apdu),
+            raw: apdu,
+            isError: false,
+        });
+        // Send to inner adapter
+        const resp = await this.inner.sendApdu(apdu);
+        // Log response
+        this.logger({
+            index,
+            direction: 'response',
+            formatted: formatApduResponse(resp),
+            raw: resp,
+            isError: isApduError(resp),
+        });
+        return resp;
+    }
+}
+/**
+ * Default server logger that writes to console.
+ */
+function defaultServerLogger(event) {
+    const prefix = event.direction === 'request' ? '>>' : event.isError ? '!!' : '<<';
+    console.log(`    ES9+[${event.index}] ${prefix} ${event.formatted}`);
+}
+/**
+ * A ServerAdapter wrapper that logs all ES9+ traffic.
+ *
+ * @example
+ * ```typescript
+ * import { LoggingServerAdapter } from '@particle/esim-tooling';
+ *
+ * // Use default console logging
+ * const adapter = new LoggingServerAdapter(rawAdapter);
+ *
+ * // Or provide a custom logger
+ * const adapter = new LoggingServerAdapter(rawAdapter, (event) => {
+ *   myLogger.debug(`ES9+ ${event.direction}: ${event.formatted}`);
+ * });
+ * ```
+ */
+export class LoggingServerAdapter {
+    inner;
+    logger;
+    requestCount = 0;
+    constructor(inner, logger) {
+        this.inner = inner;
+        this.logger = logger ?? defaultServerLogger;
+    }
+    async sendRsp(smdpAddress, endpoint, requestData) {
+        this.requestCount++;
+        const index = this.requestCount;
+        // Log request
+        this.logger({
+            index,
+            direction: 'request',
+            formatted: formatServerRequest(endpoint, smdpAddress, requestData),
+            endpoint,
+            smdpAddress,
+            raw: requestData,
+            isError: false,
+        });
+        // Send to inner adapter
+        const response = await this.inner.sendRsp(smdpAddress, endpoint, requestData);
+        // Log response
+        this.logger({
+            index,
+            direction: 'response',
+            formatted: formatServerResponse(response.statusCode, response.responseData),
+            endpoint,
+            smdpAddress,
+            statusCode: response.statusCode,
+            raw: response.responseData,
+            isError: isServerError(response.statusCode),
+        });
+        return response;
+    }
+}
+//# sourceMappingURL=logging-adapter.js.map

package/dist/logging-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-adapter.js","sourceRoot":"","sources":["../src/logging-adapter.ts"],"names":[],"mappings":"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"}

package/dist/logging-format.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Formatting utilities for logging and debugging APDU and ES9+ traffic.
+ */
+/**
+ * Format an APDU request for logging.
+ *
+ * Returns a human-readable string with:
+ * - Logical channel number
+ * - INS name (MANAGE_CHANNEL, SELECT, STORE_DATA, GET_RESPONSE)
+ * - P1/P2 details (OPEN/CLOSE for MANAGE_CHANNEL, LAST/MORE for STORE_DATA)
+ * - Hex dump with spaces separating header, Lc, data, and Le
+ *
+ * @example
+ * ```typescript
+ * formatApduRequest(new Uint8Array([0x00, 0x70, 0x00, 0x00, 0x01]))
+ * // => "ch0 MANAGE_CHANNEL OPEN (00700000 01)"
+ *
+ * formatApduRequest(new Uint8Array([0x81, 0xe2, 0x91, 0x00, 0x05, ...data]))
+ * // => "ch1 STORE_DATA(5) LAST blk=0 (81e29100 05 ...)"
+ * ```
+ */
+export declare function formatApduRequest(apdu: Uint8Array): string;
+/**
+ * Format an APDU response for logging.
+ *
+ * Returns a human-readable string with:
+ * - Status word name (OK, FILE_NOT_FOUND, MORE_DATA, etc.)
+ * - Full hex dump including data and SW1 SW2
+ *
+ * @example
+ * ```typescript
+ * formatApduResponse(new Uint8Array([0x90, 0x00]))
+ * // => "OK (9000)"
+ *
+ * formatApduResponse(new Uint8Array([0x01, 0x02, 0x03, 0x61, 0x10]))
+ * // => "MORE_DATA(16) (010203 6110)"
+ * ```
+ */
+export declare function formatApduResponse(resp: Uint8Array): string;
+/**
+ * Check if an APDU response indicates an error (SW1 not 0x90 or 0x61).
+ */
+export declare function isApduError(resp: Uint8Array): boolean;
+/**
+ * Format an ES9+ server request for logging.
+ *
+ * @example
+ * ```typescript
+ * formatServerRequest('initiateAuthentication', 'smdp.example.com', data)
+ * // => "initiateAuthentication smdp.example.com (123 bytes)"
+ * ```
+ */
+export declare function formatServerRequest(endpoint: string, smdpAddress: string, data: Uint8Array): string;
+/**
+ * Format an ES9+ server response for logging.
+ *
+ * @example
+ * ```typescript
+ * formatServerResponse(200, data)
+ * // => "HTTP 200 (456 bytes)"
+ *
+ * formatServerResponse(204)
+ * // => "HTTP 204 (no content)"
+ * ```
+ */
+export declare function formatServerResponse(statusCode: number, data?: Uint8Array): string;
+/**
+ * Check if an HTTP status code indicates an error (>= 400).
+ */
+export declare function isServerError(statusCode: number): boolean;
+//# sourceMappingURL=logging-format.d.ts.map

package/dist/logging-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-format.d.ts","sourceRoot":"","sources":["../src/logging-format.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwDH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAmD1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAM3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAIrD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAEnG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAKlF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/logging-format.js

@@ -0,0 +1,194 @@
+/**
+ * Formatting utilities for logging and debugging APDU and ES9+ traffic.
+ */
+/** Convert bytes to hex string (internal helper) */
+function toHex(data) {
+    return Array.from(data)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+// ---------------------------------------------------------------------------
+// APDU formatting
+// ---------------------------------------------------------------------------
+/** Decode INS byte to human-readable name */
+function insName(ins) {
+    switch (ins) {
+        case 0x70:
+            return 'MANAGE_CHANNEL';
+        case 0xa4:
+            return 'SELECT';
+        case 0xe2:
+            return 'STORE_DATA';
+        case 0xc0:
+            return 'GET_RESPONSE';
+        default:
+            return ins.toString(16).padStart(2, '0');
+    }
+}
+/** Decode common status words */
+function swName(sw1, sw2) {
+    const sw = (sw1 << 8) | sw2;
+    switch (sw) {
+        case 0x9000:
+            return 'OK';
+        case 0x6a82:
+            return 'FILE_NOT_FOUND';
+        case 0x6a88:
+            return 'REFERENCED_DATA_NOT_FOUND';
+        case 0x6985:
+            return 'CONDITIONS_NOT_SATISFIED';
+        case 0x6982:
+            return 'SECURITY_STATUS_NOT_SATISFIED';
+        default:
+            if (sw1 === 0x61)
+                return `MORE_DATA(${sw2})`;
+            if (sw1 === 0x6c)
+                return `WRONG_LE(${sw2})`;
+            return `${sw1.toString(16).padStart(2, '0')}${sw2.toString(16).padStart(2, '0')}`;
+    }
+}
+/** Extract logical channel from CLA byte */
+function claChannel(cla) {
+    if ((cla & 0x40) === 0)
+        return cla & 0x03;
+    return 4 + (cla & 0x0f);
+}
+/**
+ * Format an APDU request for logging.
+ *
+ * Returns a human-readable string with:
+ * - Logical channel number
+ * - INS name (MANAGE_CHANNEL, SELECT, STORE_DATA, GET_RESPONSE)
+ * - P1/P2 details (OPEN/CLOSE for MANAGE_CHANNEL, LAST/MORE for STORE_DATA)
+ * - Hex dump with spaces separating header, Lc, data, and Le
+ *
+ * @example
+ * ```typescript
+ * formatApduRequest(new Uint8Array([0x00, 0x70, 0x00, 0x00, 0x01]))
+ * // => "ch0 MANAGE_CHANNEL OPEN (00700000 01)"
+ *
+ * formatApduRequest(new Uint8Array([0x81, 0xe2, 0x91, 0x00, 0x05, ...data]))
+ * // => "ch1 STORE_DATA(5) LAST blk=0 (81e29100 05 ...)"
+ * ```
+ */
+export function formatApduRequest(apdu) {
+    if (apdu.length < 4)
+        return toHex(apdu);
+    const cla = apdu[0];
+    const ins = apdu[1];
+    const p1 = apdu[2];
+    const p2 = apdu[3];
+    const channel = claChannel(cla);
+    let detail = `ch${channel} ${insName(ins)}`;
+    // Add context based on INS
+    switch (ins) {
+        case 0x70: // MANAGE CHANNEL
+            detail += p2 === 0x00 && p1 === 0x00 ? ' OPEN' : ` CLOSE(${p2})`;
+            break;
+        case 0xe2: // STORE DATA
+            // Lc is byte 4 - how many bytes we're sending
+            if (apdu.length >= 5) {
+                const lc = apdu[4];
+                detail += `(${lc})`;
+            }
+            detail += p1 === 0x91 ? ' LAST' : ' MORE';
+            detail += ` blk=${p2}`;
+            break;
+        case 0xc0: // GET RESPONSE
+            // Le is the last byte - how many bytes we're requesting
+            if (apdu.length >= 5) {
+                const le = apdu[4];
+                detail += `(${le})`;
+            }
+            break;
+        default:
+            break;
+    }
+    // Format hex with spaces separating: header Lc data [Le]
+    const header = toHex(apdu.subarray(0, 4));
+    let hex = header;
+    if (apdu.length > 4) {
+        const lc = apdu[4];
+        hex += ' ' + toHex(apdu.subarray(4, 5)); // Lc
+        if (lc > 0 && apdu.length > 5) {
+            hex += ' ' + toHex(apdu.subarray(5, 5 + lc)); // Data
+        }
+        if (apdu.length > 5 + lc) {
+            hex += ' ' + toHex(apdu.subarray(5 + lc)); // Le
+        }
+    }
+    return `${detail} (${hex})`;
+}
+/**
+ * Format an APDU response for logging.
+ *
+ * Returns a human-readable string with:
+ * - Status word name (OK, FILE_NOT_FOUND, MORE_DATA, etc.)
+ * - Full hex dump including data and SW1 SW2
+ *
+ * @example
+ * ```typescript
+ * formatApduResponse(new Uint8Array([0x90, 0x00]))
+ * // => "OK (9000)"
+ *
+ * formatApduResponse(new Uint8Array([0x01, 0x02, 0x03, 0x61, 0x10]))
+ * // => "MORE_DATA(16) (010203 6110)"
+ * ```
+ */
+export function formatApduResponse(resp) {
+    if (resp.length < 2)
+        return `invalid (${toHex(resp)})`;
+    const sw1 = resp[resp.length - 2];
+    const sw2 = resp[resp.length - 1];
+    const swStr = swName(sw1, sw2);
+    return `${swStr} (${toHex(resp)})`;
+}
+/**
+ * Check if an APDU response indicates an error (SW1 not 0x90 or 0x61).
+ */
+export function isApduError(resp) {
+    if (resp.length < 2)
+        return true;
+    const sw1 = resp[resp.length - 2];
+    return sw1 !== 0x90 && sw1 !== 0x61;
+}
+// ---------------------------------------------------------------------------
+// ES9+ server formatting
+// ---------------------------------------------------------------------------
+/**
+ * Format an ES9+ server request for logging.
+ *
+ * @example
+ * ```typescript
+ * formatServerRequest('initiateAuthentication', 'smdp.example.com', data)
+ * // => "initiateAuthentication smdp.example.com (123 bytes)"
+ * ```
+ */
+export function formatServerRequest(endpoint, smdpAddress, data) {
+    return `${endpoint} ${smdpAddress} (${data.length} bytes)`;
+}
+/**
+ * Format an ES9+ server response for logging.
+ *
+ * @example
+ * ```typescript
+ * formatServerResponse(200, data)
+ * // => "HTTP 200 (456 bytes)"
+ *
+ * formatServerResponse(204)
+ * // => "HTTP 204 (no content)"
+ * ```
+ */
+export function formatServerResponse(statusCode, data) {
+    if (!data || data.length === 0) {
+        return `HTTP ${statusCode} (no content)`;
+    }
+    return `HTTP ${statusCode} (${data.length} bytes)`;
+}
+/**
+ * Check if an HTTP status code indicates an error (>= 400).
+ */
+export function isServerError(statusCode) {
+    return statusCode >= 400;
+}
+//# sourceMappingURL=logging-format.js.map

package/dist/logging-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-format.js","sourceRoot":"","sources":["../src/logging-format.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle/esim-tooling",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "TypeScript library for eSIM profile provisioning (SGP.22)",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -41,3 +41,15 @@ export {
 } from './errors.js';
 
 export { parseActivationCode, isValidActivationCode, formatActivationCode } from './activation-code.js';
+
+export {
+  formatApduRequest,
+  formatApduResponse,
+  isApduError,
+  formatServerRequest,
+  formatServerResponse,
+  isServerError,
+} from './logging-format.js';
+
+export { LoggingDeviceAdapter, LoggingServerAdapter } from './logging-adapter.js';
+export type { ApduLogEvent, ServerLogEvent } from './logging-adapter.js';

package/src/logging-adapter.ts

@@ -0,0 +1,193 @@
+/**
+ * Optional logging wrappers for DeviceAdapter and ServerAdapter.
+ *
+ * Wraps adapters to log traffic using the decorator pattern.
+ * The underlying adapters are unchanged.
+ */
+
+import type { DeviceAdapter, ServerAdapter, ServerResponse } from './types.js';
+import {
+  formatApduRequest,
+  formatApduResponse,
+  isApduError,
+  formatServerRequest,
+  formatServerResponse,
+  isServerError,
+} from './logging-format.js';
+
+// ---------------------------------------------------------------------------
+// Device adapter logging
+// ---------------------------------------------------------------------------
+
+/**
+ * Event emitted for each APDU request or response.
+ */
+export interface ApduLogEvent {
+  /** Sequential APDU index (1-based) */
+  index: number;
+  /** Whether this is a request or response */
+  direction: 'request' | 'response';
+  /** Human-readable formatted string */
+  formatted: string;
+  /** Raw APDU bytes */
+  raw: Uint8Array;
+  /** True if response SW1 is not 0x90 or 0x61 */
+  isError: boolean;
+}
+
+/**
+ * Default APDU logger that writes to console.
+ */
+function defaultApduLogger(event: ApduLogEvent): void {
+  const prefix = event.direction === 'request' ? '>>' : event.isError ? '!!' : '<<';
+  console.log(`    APDU[${event.index}] ${prefix} ${event.formatted}`);
+}
+
+/**
+ * A DeviceAdapter wrapper that logs all APDU traffic.
+ *
+ * @example
+ * ```typescript
+ * import { LoggingDeviceAdapter } from '@particle/esim-tooling';
+ *
+ * // Use default console logging
+ * const adapter = new LoggingDeviceAdapter(rawAdapter);
+ *
+ * // Or provide a custom logger
+ * const adapter = new LoggingDeviceAdapter(rawAdapter, (event) => {
+ *   myLogger.debug(`APDU ${event.direction}: ${event.formatted}`);
+ * });
+ * ```
+ */
+export class LoggingDeviceAdapter implements DeviceAdapter {
+  private inner: DeviceAdapter;
+  private logger: (event: ApduLogEvent) => void;
+  private apduCount = 0;
+
+  constructor(inner: DeviceAdapter, logger?: (event: ApduLogEvent) => void) {
+    this.inner = inner;
+    this.logger = logger ?? defaultApduLogger;
+  }
+
+  async sendApdu(apdu: Uint8Array): Promise<Uint8Array> {
+    this.apduCount++;
+    const index = this.apduCount;
+
+    // Log request
+    this.logger({
+      index,
+      direction: 'request',
+      formatted: formatApduRequest(apdu),
+      raw: apdu,
+      isError: false,
+    });
+
+    // Send to inner adapter
+    const resp = await this.inner.sendApdu(apdu);
+
+    // Log response
+    this.logger({
+      index,
+      direction: 'response',
+      formatted: formatApduResponse(resp),
+      raw: resp,
+      isError: isApduError(resp),
+    });
+
+    return resp;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server adapter logging
+// ---------------------------------------------------------------------------
+
+/**
+ * Event emitted for each ES9+ server request or response.
+ */
+export interface ServerLogEvent {
+  /** Sequential request index (1-based) */
+  index: number;
+  /** Whether this is a request or response */
+  direction: 'request' | 'response';
+  /** Human-readable formatted string */
+  formatted: string;
+  /** ES9+ endpoint name */
+  endpoint: string;
+  /** SM-DP+ server address */
+  smdpAddress: string;
+  /** HTTP status code (response only) */
+  statusCode?: number;
+  /** Raw request/response bytes */
+  raw?: Uint8Array;
+  /** True if HTTP status >= 400 */
+  isError: boolean;
+}
+
+/**
+ * Default server logger that writes to console.
+ */
+function defaultServerLogger(event: ServerLogEvent): void {
+  const prefix = event.direction === 'request' ? '>>' : event.isError ? '!!' : '<<';
+  console.log(`    ES9+[${event.index}] ${prefix} ${event.formatted}`);
+}
+
+/**
+ * A ServerAdapter wrapper that logs all ES9+ traffic.
+ *
+ * @example
+ * ```typescript
+ * import { LoggingServerAdapter } from '@particle/esim-tooling';
+ *
+ * // Use default console logging
+ * const adapter = new LoggingServerAdapter(rawAdapter);
+ *
+ * // Or provide a custom logger
+ * const adapter = new LoggingServerAdapter(rawAdapter, (event) => {
+ *   myLogger.debug(`ES9+ ${event.direction}: ${event.formatted}`);
+ * });
+ * ```
+ */
+export class LoggingServerAdapter implements ServerAdapter {
+  private inner: ServerAdapter;
+  private logger: (event: ServerLogEvent) => void;
+  private requestCount = 0;
+
+  constructor(inner: ServerAdapter, logger?: (event: ServerLogEvent) => void) {
+    this.inner = inner;
+    this.logger = logger ?? defaultServerLogger;
+  }
+
+  async sendRsp(smdpAddress: string, endpoint: string, requestData: Uint8Array): Promise<ServerResponse> {
+    this.requestCount++;
+    const index = this.requestCount;
+
+    // Log request
+    this.logger({
+      index,
+      direction: 'request',
+      formatted: formatServerRequest(endpoint, smdpAddress, requestData),
+      endpoint,
+      smdpAddress,
+      raw: requestData,
+      isError: false,
+    });
+
+    // Send to inner adapter
+    const response = await this.inner.sendRsp(smdpAddress, endpoint, requestData);
+
+    // Log response
+    this.logger({
+      index,
+      direction: 'response',
+      formatted: formatServerResponse(response.statusCode, response.responseData),
+      endpoint,
+      smdpAddress,
+      statusCode: response.statusCode,
+      raw: response.responseData,
+      isError: isServerError(response.statusCode),
+    });
+
+    return response;
+  }
+}

package/src/logging-format.ts

@@ -0,0 +1,204 @@
+/**
+ * Formatting utilities for logging and debugging APDU and ES9+ traffic.
+ */
+
+/** Convert bytes to hex string (internal helper) */
+function toHex(data: Uint8Array): string {
+  return Array.from(data)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+// ---------------------------------------------------------------------------
+// APDU formatting
+// ---------------------------------------------------------------------------
+
+/** Decode INS byte to human-readable name */
+function insName(ins: number): string {
+  switch (ins) {
+    case 0x70:
+      return 'MANAGE_CHANNEL';
+    case 0xa4:
+      return 'SELECT';
+    case 0xe2:
+      return 'STORE_DATA';
+    case 0xc0:
+      return 'GET_RESPONSE';
+    default:
+      return ins.toString(16).padStart(2, '0');
+  }
+}
+
+/** Decode common status words */
+function swName(sw1: number, sw2: number): string {
+  const sw = (sw1 << 8) | sw2;
+  switch (sw) {
+    case 0x9000:
+      return 'OK';
+    case 0x6a82:
+      return 'FILE_NOT_FOUND';
+    case 0x6a88:
+      return 'REFERENCED_DATA_NOT_FOUND';
+    case 0x6985:
+      return 'CONDITIONS_NOT_SATISFIED';
+    case 0x6982:
+      return 'SECURITY_STATUS_NOT_SATISFIED';
+    default:
+      if (sw1 === 0x61) return `MORE_DATA(${sw2})`;
+      if (sw1 === 0x6c) return `WRONG_LE(${sw2})`;
+      return `${sw1.toString(16).padStart(2, '0')}${sw2.toString(16).padStart(2, '0')}`;
+  }
+}
+
+/** Extract logical channel from CLA byte */
+function claChannel(cla: number): number {
+  if ((cla & 0x40) === 0) return cla & 0x03;
+  return 4 + (cla & 0x0f);
+}
+
+/**
+ * Format an APDU request for logging.
+ *
+ * Returns a human-readable string with:
+ * - Logical channel number
+ * - INS name (MANAGE_CHANNEL, SELECT, STORE_DATA, GET_RESPONSE)
+ * - P1/P2 details (OPEN/CLOSE for MANAGE_CHANNEL, LAST/MORE for STORE_DATA)
+ * - Hex dump with spaces separating header, Lc, data, and Le
+ *
+ * @example
+ * ```typescript
+ * formatApduRequest(new Uint8Array([0x00, 0x70, 0x00, 0x00, 0x01]))
+ * // => "ch0 MANAGE_CHANNEL OPEN (00700000 01)"
+ *
+ * formatApduRequest(new Uint8Array([0x81, 0xe2, 0x91, 0x00, 0x05, ...data]))
+ * // => "ch1 STORE_DATA(5) LAST blk=0 (81e29100 05 ...)"
+ * ```
+ */
+export function formatApduRequest(apdu: Uint8Array): string {
+  if (apdu.length < 4) return toHex(apdu);
+
+  const cla = apdu[0];
+  const ins = apdu[1];
+  const p1 = apdu[2];
+  const p2 = apdu[3];
+  const channel = claChannel(cla);
+
+  let detail = `ch${channel} ${insName(ins)}`;
+
+  // Add context based on INS
+  switch (ins) {
+    case 0x70: // MANAGE CHANNEL
+      detail += p2 === 0x00 && p1 === 0x00 ? ' OPEN' : ` CLOSE(${p2})`;
+      break;
+    case 0xe2: // STORE DATA
+      // Lc is byte 4 - how many bytes we're sending
+      if (apdu.length >= 5) {
+        const lc = apdu[4];
+        detail += `(${lc})`;
+      }
+      detail += p1 === 0x91 ? ' LAST' : ' MORE';
+      detail += ` blk=${p2}`;
+      break;
+    case 0xc0: // GET RESPONSE
+      // Le is the last byte - how many bytes we're requesting
+      if (apdu.length >= 5) {
+        const le = apdu[4];
+        detail += `(${le})`;
+      }
+      break;
+    default:
+      break;
+  }
+
+  // Format hex with spaces separating: header Lc data [Le]
+  const header = toHex(apdu.subarray(0, 4));
+  let hex = header;
+  if (apdu.length > 4) {
+    const lc = apdu[4];
+    hex += ' ' + toHex(apdu.subarray(4, 5)); // Lc
+    if (lc > 0 && apdu.length > 5) {
+      hex += ' ' + toHex(apdu.subarray(5, 5 + lc)); // Data
+    }
+    if (apdu.length > 5 + lc) {
+      hex += ' ' + toHex(apdu.subarray(5 + lc)); // Le
+    }
+  }
+
+  return `${detail} (${hex})`;
+}
+
+/**
+ * Format an APDU response for logging.
+ *
+ * Returns a human-readable string with:
+ * - Status word name (OK, FILE_NOT_FOUND, MORE_DATA, etc.)
+ * - Full hex dump including data and SW1 SW2
+ *
+ * @example
+ * ```typescript
+ * formatApduResponse(new Uint8Array([0x90, 0x00]))
+ * // => "OK (9000)"
+ *
+ * formatApduResponse(new Uint8Array([0x01, 0x02, 0x03, 0x61, 0x10]))
+ * // => "MORE_DATA(16) (010203 6110)"
+ * ```
+ */
+export function formatApduResponse(resp: Uint8Array): string {
+  if (resp.length < 2) return `invalid (${toHex(resp)})`;
+  const sw1 = resp[resp.length - 2];
+  const sw2 = resp[resp.length - 1];
+  const swStr = swName(sw1, sw2);
+  return `${swStr} (${toHex(resp)})`;
+}
+
+/**
+ * Check if an APDU response indicates an error (SW1 not 0x90 or 0x61).
+ */
+export function isApduError(resp: Uint8Array): boolean {
+  if (resp.length < 2) return true;
+  const sw1 = resp[resp.length - 2];
+  return sw1 !== 0x90 && sw1 !== 0x61;
+}
+
+// ---------------------------------------------------------------------------
+// ES9+ server formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format an ES9+ server request for logging.
+ *
+ * @example
+ * ```typescript
+ * formatServerRequest('initiateAuthentication', 'smdp.example.com', data)
+ * // => "initiateAuthentication smdp.example.com (123 bytes)"
+ * ```
+ */
+export function formatServerRequest(endpoint: string, smdpAddress: string, data: Uint8Array): string {
+  return `${endpoint} ${smdpAddress} (${data.length} bytes)`;
+}
+
+/**
+ * Format an ES9+ server response for logging.
+ *
+ * @example
+ * ```typescript
+ * formatServerResponse(200, data)
+ * // => "HTTP 200 (456 bytes)"
+ *
+ * formatServerResponse(204)
+ * // => "HTTP 204 (no content)"
+ * ```
+ */
+export function formatServerResponse(statusCode: number, data?: Uint8Array): string {
+  if (!data || data.length === 0) {
+    return `HTTP ${statusCode} (no content)`;
+  }
+  return `HTTP ${statusCode} (${data.length} bytes)`;
+}
+
+/**
+ * Check if an HTTP status code indicates an error (>= 400).
+ */
+export function isServerError(statusCode: number): boolean {
+  return statusCode >= 400;
+}