avo-inspector 3.0.1 → 3.1.0-alpha.2

package/README.md

@@ -25,6 +25,38 @@ or
     yarn add avo-inspector
 ```
 
+# Lite Build (Production-Optimized)
+
+For size-sensitive deployments (GTM, script tags, etc.), use the lite entry point which excludes encryption and event spec validation — reducing the gzipped bundle from ~37 KB to ~7.5 KB:
+
+```javascript
+import { AvoInspector, AvoInspectorEnv } from "avo-inspector/lite";
+
+let inspector = new AvoInspector({
+  apiKey: "your api key",
+  env: AvoInspectorEnv.Prod,
+  version: "1.0.0",
+});
+```
+
+The lite build has the same tracking API as the full version — `trackSchemaFromEvent`, `trackSchema`, and `extractSchema` all work identically. The differences:
+
+- No `publicEncryptionKey` constructor option (TypeScript will error if passed)
+- No event spec validation (dev/staging feature)
+- No property value encryption (dev/staging feature)
+- No stream ID generation/persistence (dev/staging debugger feature)
+- No event deduplication — **if you use both Avo Codegen and manual `trackSchemaFromEvent` calls for the same events, use the full build instead** to avoid sending duplicate schemas
+- Works universally with any bundler or minifier — no flags or configuration needed
+
+**Size comparison:**
+
+| | Minified | Gzipped |
+|---|---|---|
+| Full (`avo-inspector`) | 129 KB | 37 KB |
+| Lite (`avo-inspector/lite`) | 20 KB | 5.2 KB |
+
+See `examples/lite-size-demos/` for working examples with terser, webpack, and rollup.
+
 # Initialization
 
 Obtain the API key at [Avo.app](https://www.avo.app/welcome)

package/dist/AvoBatcher.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AvoBatcher = void 0;
+const AvoInspector_1 = require("./AvoInspector");
+class AvoBatcher {
+    constructor(networkCallsHandler) {
+        this.events = [];
+        this.networkCallsHandler = networkCallsHandler;
+        this.batchFlushAttemptTimestamp = Date.now();
+        AvoInspector_1.AvoInspector.avoStorage
+            .getItemAsync(AvoBatcher.cacheKey)
+            .then((savedEvents) => {
+            if (savedEvents !== null) {
+                const nonNullSavedEvents = savedEvents.filter((event) => event !== null);
+                this.events = this.events.concat(nonNullSavedEvents);
+                this.checkIfBatchNeedsToBeSent();
+            }
+        })
+            .catch((error) => {
+            console.error("Avo Inspector: error getting events from cache", error);
+        });
+    }
+    handleSessionStarted() {
+        this.events.push(this.networkCallsHandler.bodyForSessionStartedCall());
+        this.saveEvents();
+        this.checkIfBatchNeedsToBeSent();
+    }
+    handleTrackSchema(eventName, schema, eventId, eventHash, eventSpecMetadata) {
+        this.events.push(this.networkCallsHandler.bodyForEventSchemaCall(eventName, schema, eventId, eventHash, eventSpecMetadata));
+        this.saveEvents();
+        if (AvoInspector_1.AvoInspector.shouldLog) {
+            console.log("Avo Inspector: saved event " +
+                eventName +
+                " with schema " +
+                JSON.stringify(schema));
+        }
+        this.checkIfBatchNeedsToBeSent();
+    }
+    checkIfBatchNeedsToBeSent() {
+        const batchSize = this.events.length;
+        const now = Date.now();
+        const timeSinceLastFlushAttempt = now - this.batchFlushAttemptTimestamp;
+        const sendBySize = batchSize % AvoInspector_1.AvoInspector.batchSize == 0;
+        const sendByTime = timeSinceLastFlushAttempt >= AvoInspector_1.AvoInspector.batchFlushSeconds * 1000;
+        const avoBatcher = this;
+        if (sendBySize || sendByTime) {
+            this.batchFlushAttemptTimestamp = now;
+            const sendingEvents = avoBatcher.events;
+            avoBatcher.events = [];
+            this.networkCallsHandler.callInspectorWithBatchBody(sendingEvents, function (error) {
+                if (error != null) {
+                    avoBatcher.events = avoBatcher.events.concat(sendingEvents);
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.log("Avo Inspector: batch sending failed: " +
+                            error.message +
+                            ". We will attempt to send your schemas with next batch");
+                    }
+                }
+                else {
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.log("Avo Inspector: batch sent successfully.");
+                    }
+                }
+                avoBatcher.saveEvents();
+            });
+        }
+    }
+    saveEvents() {
+        if (this.events.length > 1000) {
+            const extraElements = this.events.length - 1000;
+            this.events.splice(0, extraElements);
+        }
+        AvoInspector_1.AvoInspector.avoStorage.setItem(AvoBatcher.cacheKey, this.events);
+    }
+    static get cacheKey() {
+        return "AvoInspectorEvents";
+    }
+}
+exports.AvoBatcher = AvoBatcher;

package/dist/AvoDeduplicator.d.ts

@@ -1,10 +1,18 @@
 export declare class AvoDeduplicator {
-    avoFunctionsEvents: Record<number, string>;
-    manualEvents: Record<number, string>;
-    avoFunctionsEventsParams: Record<string, Record<string, any>>;
-    manualEventsParams: Record<string, Record<string, any>>;
+    private _nextId;
+    avoFunctionsEvents: Record<string, string>;
+    manualEvents: Record<string, string>;
+    avoFunctionsEventsParams: Record<string, {
+        eventName: string;
+        params: Record<string, any>;
+    }>;
+    manualEventsParams: Record<string, {
+        eventName: string;
+        params: Record<string, any>;
+    }>;
     shouldRegisterEvent(eventName: string, params: Record<string, any>, fromAvoFunction: boolean): boolean;
     private hasSameEventAs;
+    private removeEntriesByName;
     private lookForEventIn;
     hasSeenEventParams(params: Record<string, any>, checkInAvoFunctions: boolean): boolean;
     private lookForEventParamsIn;

package/{dist-native → dist}/AvoDeduplicator.js

@@ -1,16 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AvoDeduplicator = void 0;
-var AvoSchemaParser_1 = require("./AvoSchemaParser");
-var utils_1 = require("./utils");
-var AvoDeduplicator = /** @class */ (function () {
-    function AvoDeduplicator() {
+const AvoSchemaParser_1 = require("./AvoSchemaParser");
+const utils_1 = require("./utils");
+class AvoDeduplicator {
+    constructor() {
         this.avoFunctionsEvents = {};
         this.manualEvents = {};
         this.avoFunctionsEventsParams = {};
         this.manualEventsParams = {};
     }
-    AvoDeduplicator.prototype.shouldRegisterEvent = function (eventName, params, fromAvoFunction) {
+    shouldRegisterEvent(eventName, params, fromAvoFunction) {
         this.clearOldEvents();
         if (fromAvoFunction) {
             this.avoFunctionsEvents[Date.now()] = eventName;
@@ -20,11 +20,11 @@ var AvoDeduplicator = /** @class */ (function () {
             this.manualEvents[Date.now()] = eventName;
             this.manualEventsParams[eventName] = params;
         }
-        var checkInAvoFunctions = !fromAvoFunction;
+        const checkInAvoFunctions = !fromAvoFunction;
         return !this.hasSameEventAs(eventName, params, checkInAvoFunctions);
-    };
-    AvoDeduplicator.prototype.hasSameEventAs = function (eventName, params, checkInAvoFunctions) {
-        var result = false;
+    }
+    hasSameEventAs(eventName, params, checkInAvoFunctions) {
+        let result = false;
         if (checkInAvoFunctions) {
             if (this.lookForEventIn(eventName, params, this.avoFunctionsEventsParams)) {
                 result = true;
@@ -40,12 +40,12 @@ var AvoDeduplicator = /** @class */ (function () {
             delete this.manualEventsParams[eventName];
         }
         return result;
-    };
-    AvoDeduplicator.prototype.lookForEventIn = function (eventName, params, eventsStorage) {
-        for (var otherEventName in eventsStorage) {
+    }
+    lookForEventIn(eventName, params, eventsStorage) {
+        for (const otherEventName in eventsStorage) {
             if (eventsStorage.hasOwnProperty(otherEventName)) {
                 if (otherEventName === eventName) {
-                    var otherParams = eventsStorage[eventName];
+                    const otherParams = eventsStorage[eventName];
                     if (otherParams && (0, utils_1.deepEquals)(params, otherParams)) {
                         return true;
                     }
@@ -53,9 +53,9 @@ var AvoDeduplicator = /** @class */ (function () {
             }
         }
         return false;
-    };
-    AvoDeduplicator.prototype.hasSeenEventParams = function (params, checkInAvoFunctions) {
-        var result = false;
+    }
+    hasSeenEventParams(params, checkInAvoFunctions) {
+        let result = false;
         if (checkInAvoFunctions) {
             if (this.lookForEventParamsIn(params, this.avoFunctionsEventsParams)) {
                 result = true;
@@ -67,37 +67,37 @@ var AvoDeduplicator = /** @class */ (function () {
             }
         }
         return result;
-    };
-    AvoDeduplicator.prototype.lookForEventParamsIn = function (params, eventsStorage) {
-        for (var otherEventName in eventsStorage) {
+    }
+    lookForEventParamsIn(params, eventsStorage) {
+        for (const otherEventName in eventsStorage) {
             if (eventsStorage.hasOwnProperty(otherEventName)) {
-                var otherParams = eventsStorage[otherEventName];
+                const otherParams = eventsStorage[otherEventName];
                 if (otherParams && (0, utils_1.deepEquals)(params, otherParams)) {
                     return true;
                 }
             }
         }
         return false;
-    };
-    AvoDeduplicator.prototype.shouldRegisterSchemaFromManually = function (eventName, eventSchema) {
+    }
+    async shouldRegisterSchemaFromManually(eventName, eventSchema) {
         this.clearOldEvents();
-        return !this.hasSameShapeInAvoFunctionsAs(eventName, eventSchema);
-    };
-    AvoDeduplicator.prototype.hasSameShapeInAvoFunctionsAs = function (eventName, eventSchema) {
-        var result = false;
-        if (this.lookForEventSchemaIn(eventName, eventSchema, this.avoFunctionsEventsParams)) {
+        return !(await this.hasSameShapeInAvoFunctionsAs(eventName, eventSchema));
+    }
+    async hasSameShapeInAvoFunctionsAs(eventName, eventSchema) {
+        let result = false;
+        if (await this.lookForEventSchemaIn(eventName, eventSchema, this.avoFunctionsEventsParams)) {
             result = true;
         }
         if (result) {
             delete this.avoFunctionsEventsParams[eventName];
         }
         return result;
-    };
-    AvoDeduplicator.prototype.lookForEventSchemaIn = function (eventName, eventSchema, eventsStorage) {
-        for (var otherEventName in eventsStorage) {
+    }
+    async lookForEventSchemaIn(eventName, eventSchema, eventsStorage) {
+        for (const otherEventName in eventsStorage) {
             if (eventsStorage.hasOwnProperty(otherEventName)) {
                 if (otherEventName === eventName) {
-                    var otherSchema = AvoSchemaParser_1.AvoSchemaParser.extractSchema(eventsStorage[eventName]);
+                    const otherSchema = await AvoSchemaParser_1.AvoSchemaParser.extractSchema(eventsStorage[eventName]);
                     if (otherSchema && (0, utils_1.deepEquals)(eventSchema, otherSchema)) {
                         return true;
                     }
@@ -105,38 +105,37 @@ var AvoDeduplicator = /** @class */ (function () {
             }
         }
         return false;
-    };
-    AvoDeduplicator.prototype.clearOldEvents = function () {
-        var now = Date.now();
-        var msToConsiderOld = 300;
-        for (var time in this.avoFunctionsEvents) {
+    }
+    clearOldEvents() {
+        const now = Date.now();
+        const msToConsiderOld = 300;
+        for (const time in this.avoFunctionsEvents) {
             if (this.avoFunctionsEvents.hasOwnProperty(time)) {
-                var timestamp = Number(time) || 0;
+                const timestamp = Number(time) || 0;
                 if (now - timestamp > msToConsiderOld) {
-                    var eventName = this.avoFunctionsEvents[time];
+                    const eventName = this.avoFunctionsEvents[time];
                     delete this.avoFunctionsEvents[time];
                     delete this.avoFunctionsEventsParams[eventName];
                 }
             }
         }
-        for (var time in this.manualEvents) {
+        for (const time in this.manualEvents) {
             if (this.manualEvents.hasOwnProperty(time)) {
-                var timestamp = Number(time) || 0;
+                const timestamp = Number(time) || 0;
                 if (now - timestamp > msToConsiderOld) {
-                    var eventName = this.manualEvents[time];
+                    const eventName = this.manualEvents[time];
                     delete this.manualEvents[time];
                     delete this.manualEventsParams[eventName];
                 }
             }
         }
-    };
+    }
     // used in tests
-    AvoDeduplicator.prototype._clearEvents = function () {
+    _clearEvents() {
         this.avoFunctionsEvents = {};
         this.manualEvents = {};
         this.avoFunctionsEventsParams = {};
         this.manualEventsParams = {};
-    };
-    return AvoDeduplicator;
-}());
+    }
+}
 exports.AvoDeduplicator = AvoDeduplicator;

package/dist/AvoEncryption.js

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateKeyPair = generateKeyPair;
+exports.encryptValue = encryptValue;
+exports.decryptValue = decryptValue;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const p256_1 = require("@noble/curves/p256");
+/**
+ * Converts bytes (Uint8Array) to hex string
+ */
+function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Converts hex string to bytes (Uint8Array)
+ */
+function hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    }
+    return bytes;
+}
+// Get crypto API - works in both browser and Node.js environments
+// In browser: window.crypto or globalThis.crypto
+// In Node.js: global.crypto or globalThis.crypto (polyfilled in tests)
+const getCrypto = () => {
+    // Try globalThis first (works in both Node.js and browsers)
+    if (typeof globalThis !== 'undefined' && globalThis.crypto) {
+        const crypto = globalThis.crypto;
+        if (crypto && crypto.subtle) {
+            return crypto;
+        }
+    }
+    // Try window (browser)
+    if (typeof window !== 'undefined' && window.crypto) {
+        const crypto = window.crypto;
+        if (crypto && crypto.subtle) {
+            return crypto;
+        }
+    }
+    // Try global (Node.js)
+    if (typeof global !== 'undefined' && global.crypto) {
+        const crypto = global.crypto;
+        if (crypto && crypto.subtle) {
+            return crypto;
+        }
+    }
+    // Fallback - should not happen in proper environments
+    const debugInfo = {
+        hasGlobalThis: typeof globalThis !== 'undefined',
+        hasGlobalThisCrypto: typeof globalThis !== 'undefined' && !!globalThis.crypto,
+        hasGlobalThisCryptoSubtle: typeof globalThis !== 'undefined' && !!globalThis.crypto && !!globalThis.crypto.subtle,
+        hasWindow: typeof window !== 'undefined',
+        hasWindowCrypto: typeof window !== 'undefined' && !!window.crypto,
+        hasGlobal: typeof global !== 'undefined',
+        hasGlobalCrypto: typeof global !== 'undefined' && !!global.crypto,
+        hasGlobalCryptoSubtle: typeof global !== 'undefined' && !!global.crypto && !!global.crypto.subtle
+    };
+    throw new Error('crypto.subtle not available. Debug: ' + JSON.stringify(debugInfo));
+};
+/**
+ * Generates a new ECC key pair for encryption/decryption.
+ * Uses P-256 (prime256v1 / NIST P-256) curve which is standard for Web Crypto API.
+ *
+ * @returns An object containing the private and public keys as hex strings
+ */
+function generateKeyPair() {
+    // Generate a new random private key (32 bytes)
+    const privateKeyBytes = p256_1.p256.utils.randomPrivateKey();
+    // Get public key (uncompressed format: 65 bytes = 0x04 + 32-byte x + 32-byte y)
+    const publicKeyBytes = p256_1.p256.getPublicKey(privateKeyBytes, false);
+    // Convert to hex strings
+    const privateKey = bytesToHex(privateKeyBytes).padStart(64, '0');
+    const publicKey = bytesToHex(publicKeyBytes);
+    return {
+        privateKey,
+        publicKey
+    };
+}
+/**
+ * Derives a key from shared secret using SHA-256
+ */
+async function deriveKey(sharedSecret) {
+    const cryptoAPI = getCrypto();
+    return await cryptoAPI.subtle.digest('SHA-256', sharedSecret);
+}
+/**
+ * Safely converts Uint8Array to base64 string.
+ * Uses Buffer in Node.js for efficiency, or chunked conversion in browsers
+ * to avoid call stack overflow with large arrays.
+ */
+function uint8ArrayToBase64(bytes) {
+    // Check if we're in Node.js and Buffer is available
+    if (typeof Buffer !== 'undefined' && Buffer.from) {
+        return Buffer.from(bytes).toString('base64');
+    }
+    // Browser fallback: use chunked conversion to avoid call stack overflow
+    // Chunk size of 8192 (8k) is safe for String.fromCharCode.apply
+    const CHUNK_SIZE = 8192;
+    let binaryString = '';
+    for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+        const chunk = bytes.slice(i, i + CHUNK_SIZE);
+        // Convert chunk to array and use apply for this small chunk
+        binaryString += String.fromCharCode.apply(null, Array.from(chunk));
+    }
+    return btoa(binaryString);
+}
+/**
+ * Encrypts a value using ECC public key encryption (ECIES).
+ * The encrypted output can only be decrypted by the client using their private key.
+ * This ensures that Avo cannot decrypt the values on the backend.
+ *
+ * ECIES uses hybrid encryption (ECDH + AES-256-GCM) which provides:
+ * - No message size limitations
+ * - Fast encryption even for large values
+ * - Strong authentication via GCM
+ *
+ * SPECIFICATION (Standard Web Crypto Profile):
+ * 1. Curve: P-256 (prime256v1 / NIST P-256)
+ * 2. Key Derivation (KDF): SHA-256(SharedSecret)
+ * 3. Cipher: AES-256-GCM
+ * 4. Serialization: [Version(1b)] + [EphemeralPubKey(33 or 65b)] + [IV(16b)] + [AuthTag(16b)] + [Ciphertext]
+ *    Version 0x00 = Standard Web Profile
+ *    EphemeralPubKey: 0x04 (uncompressed) + 64 bytes = 65 bytes total, or compressed format (33 bytes)
+ *
+ * @param value - The value to encrypt (any type - will be JSON stringified)
+ * @param publicKey - The ECC public key in hex format provided by the client
+ * @returns Promise resolving to base64-encoded encrypted string that can only be decrypted with the private key
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function encryptValue(value, publicKey) {
+    try {
+        // Convert the value to a JSON string to support all types
+        // Note: JSON.stringify(undefined) returns undefined (not a string), so handle it explicitly
+        const stringValue = value === undefined ? 'null' : JSON.stringify(value);
+        if (stringValue === undefined) {
+            throw new Error('Cannot encrypt undefined value');
+        }
+        // 1. Prepare Public Key
+        // Ensure publicKey is a string
+        const publicKeyStr = typeof publicKey === 'string' ? publicKey : String(publicKey);
+        // Convert recipient's public key from hex to bytes
+        const recipientPublicKeyBytes = hexToBytes(publicKeyStr);
+        // 2. Generate Ephemeral Key Pair on P-256
+        const ephemeralPrivateKeyBytes = p256_1.p256.utils.randomPrivateKey();
+        const ephemeralPublicKeyBytes = p256_1.p256.getPublicKey(ephemeralPrivateKeyBytes, false); // Uncompressed format (65 bytes)
+        // 3. Derive Shared Secret (ECDH)
+        // getSharedSecret returns compressed point (33 bytes: 0x02/0x03 + X-coordinate)
+        // Extract X-coordinate (last 32 bytes) to match elliptic's derive().toArray("be", 32)
+        const sharedSecretPoint = p256_1.p256.getSharedSecret(ephemeralPrivateKeyBytes, recipientPublicKeyBytes);
+        const sharedSecret = sharedSecretPoint.slice(-32); // Extract X-coordinate (last 32 bytes)
+        // 4. Key Derivation (Hash with SHA-256)
+        const derivedKeyBuffer = await deriveKey(sharedSecret);
+        // 5. Import Key for Web Crypto AES-GCM
+        const cryptoAPI = getCrypto();
+        const keyMaterial = await cryptoAPI.subtle.importKey('raw', derivedKeyBuffer, { name: 'AES-GCM' }, false, ['encrypt']);
+        // 6. Generate random IV (16 bytes)
+        const iv = cryptoAPI.getRandomValues(new Uint8Array(16));
+        // 7. Encrypt using AES-256-GCM
+        // Convert string to Uint8Array
+        const plaintext = new TextEncoder().encode(stringValue);
+        const encryptedData = await cryptoAPI.subtle.encrypt({
+            name: 'AES-GCM',
+            iv,
+            tagLength: 128 // 16 bytes = 128 bits
+        }, keyMaterial, plaintext);
+        // Web Crypto API appends the auth tag to the ciphertext
+        // We need to extract it separately for our format
+        const encryptedArray = new Uint8Array(encryptedData);
+        const authTagLength = 16; // 128 bits = 16 bytes
+        const ciphertextLength = encryptedArray.length - authTagLength;
+        const ciphertext = encryptedArray.slice(0, ciphertextLength);
+        const authTag = encryptedArray.slice(ciphertextLength);
+        // 8. Serialize Output
+        // Format: [Version(1)] + [Ephemeral Public Key(65)] + [IV(16)] + [AuthTag(16)] + [Ciphertext]
+        const version = new Uint8Array([0x00]); // Version 0: Standard Web Profile
+        // Combine all parts
+        const resultLength = 1 + ephemeralPublicKeyBytes.length + 16 + 16 + ciphertext.length;
+        const result = new Uint8Array(resultLength);
+        let offset = 0;
+        result.set(version, offset);
+        offset += 1;
+        result.set(ephemeralPublicKeyBytes, offset);
+        offset += ephemeralPublicKeyBytes.length;
+        result.set(iv, offset);
+        offset += 16;
+        result.set(authTag, offset);
+        offset += 16;
+        result.set(ciphertext, offset);
+        // Convert to base64 using safe conversion that handles large arrays
+        return uint8ArrayToBase64(result);
+    }
+    catch (error) {
+        throw new Error(`Failed to encrypt value. Please check that the public key is valid. Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Decrypts a value that was encrypted with encryptValue.
+ *
+ * SPECIFICATION (Standard Web Crypto Profile):
+ * 1. Curve: P-256 (prime256v1 / NIST P-256)
+ * 2. Key Derivation (KDF): SHA-256(SharedSecret)
+ * 3. Cipher: AES-256-GCM
+ * 4. Deserialization: [Version(1b)] + [EphemeralPubKey(33 or 65b)] + [IV(16b)] + [AuthTag(16b)] + [Ciphertext]
+ *
+ * @param encryptedValue - The base64-encoded encrypted string
+ * @param privateKey - The ECC private key in hex format
+ * @returns Promise resolving to the original decrypted value (parsed from JSON)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function decryptValue(encryptedValue, privateKey) {
+    try {
+        // Convert encrypted value from base64 to Uint8Array
+        const binaryString = atob(encryptedValue);
+        const encryptedBuffer = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            encryptedBuffer[i] = binaryString.charCodeAt(i);
+        }
+        // Minimum size: version(1) + pubkey(33 min) + iv(16) + authTag(16) + ciphertext(1 min) = 67 bytes
+        if (encryptedBuffer.length < 67) {
+            throw new Error('Invalid encrypted data: payload too short');
+        }
+        // Ensure privateKey is a string
+        const privateKeyStr = typeof privateKey === 'string' ? privateKey : String(privateKey);
+        // 1. Deserialize Input
+        // Format: [Version(1)] + [Ephemeral Public Key(33 or 65)] + [IV(16)] + [AuthTag(16)] + [Ciphertext]
+        let offset = 0;
+        const version = encryptedBuffer[offset];
+        offset += 1;
+        if (version !== 0x00) {
+            throw new Error(`Unsupported encryption version: ${version}`);
+        }
+        // Check header to determine public key size (0x02/0x03 = 33 bytes compressed, 0x04 = 65 bytes uncompressed)
+        const keyHeader = encryptedBuffer[offset];
+        const pubKeySize = keyHeader === 0x02 || keyHeader === 0x03 ? 33 : 65;
+        // Validate buffer has enough bytes for this key format
+        const minRequired = 1 + pubKeySize + 16 + 16 + 1;
+        if (encryptedBuffer.length < minRequired) {
+            throw new Error(`Invalid encrypted data: expected at least ${minRequired} bytes, got ${encryptedBuffer.length}`);
+        }
+        const ephemeralPublicKey = encryptedBuffer.slice(offset, offset + pubKeySize);
+        offset += pubKeySize;
+        const iv = encryptedBuffer.slice(offset, offset + 16); // IV (16 bytes)
+        offset += 16;
+        const authTag = encryptedBuffer.slice(offset, offset + 16); // Auth tag (16 bytes)
+        offset += 16;
+        const ciphertext = encryptedBuffer.slice(offset); // Remaining bytes are ciphertext
+        // 2. Prepare Private Key
+        const recipientPrivateKeyBytes = hexToBytes(privateKeyStr);
+        // 3. Derive Shared Secret (ECDH)
+        // getSharedSecret returns compressed point (33 bytes: 0x02/0x03 + X-coordinate)
+        // Extract X-coordinate (last 32 bytes) to match elliptic's derive().toArray("be", 32)
+        const sharedSecretPoint = p256_1.p256.getSharedSecret(recipientPrivateKeyBytes, ephemeralPublicKey);
+        const sharedSecret = sharedSecretPoint.slice(-32); // Extract X-coordinate (last 32 bytes)
+        // 4. Key Derivation (Hash with SHA-256)
+        const derivedKeyBuffer = await deriveKey(sharedSecret);
+        // 5. Import Key for Web Crypto AES-GCM
+        const cryptoAPI = getCrypto();
+        const keyMaterial = await cryptoAPI.subtle.importKey('raw', derivedKeyBuffer, { name: 'AES-GCM' }, false, ['decrypt']);
+        // 6. Decrypt using AES-256-GCM
+        // Web Crypto API expects the auth tag appended to ciphertext
+        const combinedLength = ciphertext.length + authTag.length;
+        const data = new Uint8Array(combinedLength);
+        data.set(ciphertext, 0);
+        data.set(authTag, ciphertext.length);
+        const decryptedBuffer = await cryptoAPI.subtle.decrypt({
+            name: 'AES-GCM',
+            iv,
+            tagLength: 128 // 16 bytes = 128 bits
+        }, keyMaterial, data);
+        // 7. Convert to string and parse JSON
+        const decoder = new TextDecoder();
+        const stringValue = decoder.decode(decryptedBuffer);
+        return JSON.parse(stringValue);
+    }
+    catch (error) {
+        throw new Error(`Failed to decrypt value. Please check that the private key is valid and matches the public key used for encryption. Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/{dist-native → dist}/AvoGuid.js

@@ -5,7 +5,8 @@ var AvoGuid = /** @class */ (function () {
     }
     AvoGuid.newGuid = function () {
         return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
-            var r = (Math.random() * 16) | 0, v = c == "x" ? r : (r & 0x3) | 0x8;
+            var r = (Math.random() * 16) | 0;
+            var v = c === "x" ? r : (r & 0x3) | 0x8;
             return v.toString(16);
         });
     };