@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/utils/crypto-compat.d.ts

@@ -0,0 +1,92 @@
+type BufferEncodingName = "utf8" | "utf-8" | "base64" | "hex";
+type HashDigestEncoding = BufferEncodingName;
+interface HashBuilder {
+    update(data: string | Uint8Array): HashBuilder;
+    digest(): Uint8Array;
+    digest(encoding: HashDigestEncoding): string;
+}
+/**
+ * Create a hash object for incremental hashing (cross-platform - synchronous)
+ *
+ * This function works in both Node.js and browser environments using
+ * synchronous noble hash implementations.
+ *
+ * @param algorithm - Hash algorithm ('sha256', 'sha1', 'sha512')
+ * @returns Hash object with update() and digest() methods
+ */
+export declare function createHash(algorithm: string): {
+    update(data: string | Uint8Array): HashBuilder;
+    digest(): Uint8Array;
+    digest(encoding: HashDigestEncoding): string;
+};
+/**
+ * Create a hash asynchronously (works in both Node.js and browser)
+ *
+ * This is the recommended method for cross-platform code.
+ *
+ * @param algorithm - Hash algorithm ('sha256', 'sha1', 'sha512')
+ * @param data - Data to hash
+ * @returns Hash result
+ */
+export declare function createHashAsync(algorithm: string, data: string | Uint8Array): Promise<Uint8Array>;
+/**
+ * Create a cipher for encryption (cross-platform - synchronous)
+ *
+ * @param algorithm - Cipher algorithm (only 'aes-256-cbc' is supported)
+ * @param key - 256-bit (32-byte) encryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @returns Cipher object with update() and final() methods
+ */
+export declare function createCipheriv(algorithm: string, key: Uint8Array, iv: Uint8Array): {
+    update(data: string, inputEncoding: string, outputEncoding: string): string;
+    final(encoding: string): string;
+};
+/**
+ * Create a decipher for decryption (cross-platform - synchronous)
+ *
+ * @param algorithm - Cipher algorithm (only 'aes-256-cbc' is supported)
+ * @param key - 256-bit (32-byte) decryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @returns Decipher object with update() and final() methods
+ */
+export declare function createDecipheriv(algorithm: string, key: Uint8Array, iv: Uint8Array): {
+    update(data: string, inputEncoding: string, outputEncoding: string): string;
+    final(encoding: string): string;
+};
+/**
+ * Encrypt data asynchronously (works in both Node.js and browser)
+ *
+ * This is the recommended method for cross-platform code using AES-256-CBC.
+ *
+ * @param key - 256-bit (32-byte) encryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @param data - Data to encrypt
+ * @returns Encrypted data
+ */
+export declare function encryptAsync(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt data asynchronously (works in both Node.js and browser)
+ *
+ * This is the recommended method for cross-platform code using AES-256-CBC.
+ *
+ * @param key - 256-bit (32-byte) decryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @param data - Data to decrypt
+ * @returns Decrypted data
+ */
+export declare function decryptAsync(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Encrypt using AES-256-GCM (synchronous).
+ *
+ * This is used for cross-language secret encryption with integrity protection.
+ */
+export declare function encryptAes256Gcm(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): {
+    ciphertext: Uint8Array;
+    tag: Uint8Array;
+};
+/**
+ * Decrypt using AES-256-GCM (synchronous).
+ */
+export declare function decryptAes256Gcm(key: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array, tag: Uint8Array, aad?: Uint8Array): Uint8Array;
+export {};
+//# sourceMappingURL=crypto-compat.d.ts.map

package/packages/typescript/src/utils/crypto-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-compat.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/crypto-compat.ts"],"names":[],"mappings":"AAwBA,KAAK,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE9D,KAAK,kBAAkB,GAAG,kBAAkB,CAAC;AAE7C,UAAU,WAAW;IACpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,CAAC;IAC/C,MAAM,IAAI,UAAU,CAAC;IACrB,MAAM,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAAC;CAC7C;AAoQD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC9C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,CAAC;IAC/C,MAAM,IAAI,UAAU,CAAC;IACrB,MAAM,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAAC;CAC7C,CAmBA;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GAAG,UAAU,GACvB,OAAO,CAAC,UAAU,CAAC,CAKrB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC7B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,GACZ;IACF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5E,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC,CA+CA;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,GACZ;IACF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5E,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC,CAyDA;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CACjC,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,UAAU,GACd,OAAO,CAAC,UAAU,CAAC,CAIrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CACjC,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,UAAU,GACd,OAAO,CAAC,UAAU,CAAC,CAIrB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,SAAS,EAAE,UAAU,EACrB,GAAG,CAAC,EAAE,UAAU,GACd;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,CAc7C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,UAAU,EACf,GAAG,CAAC,EAAE,UAAU,GACd,UAAU,CAmBZ"}

package/packages/typescript/src/utils/crypto-compat.js

@@ -0,0 +1,373 @@
+/**
+ * Browser and Node.js compatible crypto abstraction
+ * Provides cross-platform interface for cryptographic operations
+ *
+ * @module crypto-compat
+ *
+ * This module provides both synchronous (Node.js only) and asynchronous (cross-platform)
+ * APIs for cryptographic operations. Use async methods for browser compatibility.
+ *
+ * @example
+ * ```typescript
+ * // Node.js synchronous API
+ * const hash = createHash('sha256').update('data').digest();
+ *
+ * // Cross-platform async API
+ * const hash = await createHashAsync('sha256', 'data');
+ * ```
+ */
+import { cbc, gcm } from "@noble/ciphers/aes.js";
+import { md5, ripemd160, sha1 } from "@noble/hashes/legacy.js";
+import { sha224, sha256, sha384, sha512 } from "@noble/hashes/sha2.js";
+import * as BufferUtils from "./buffer";
+const HASH_ALGORITHMS = {
+    md5,
+    ripemd160,
+    sha1,
+    sha224,
+    sha256,
+    sha384,
+    sha512,
+};
+const AES_BLOCK_SIZE = 16;
+/**
+ * Normalize supported encodings to the names expected by buffer utils.
+ */
+function normalizeEncoding(encoding) {
+    switch (encoding.toLowerCase()) {
+        case "base64":
+            return "base64";
+        case "hex":
+            return "hex";
+        case "utf8":
+        case "utf-8":
+            return "utf8";
+        default:
+            throw new Error(`Unsupported encoding: ${encoding}. Supported: utf8, utf-8, base64, hex.`);
+    }
+}
+/**
+ * Copy arbitrary byte-like input into an owned Uint8Array with an ArrayBuffer backing store.
+ */
+function toOwnedUint8Array(data) {
+    const output = new Uint8Array(data.length);
+    output.set(data);
+    return output;
+}
+/**
+ * Convert string or bytes into a Uint8Array.
+ */
+function toUint8Array(data, encoding = "utf8") {
+    if (typeof data === "string") {
+        const normalized = normalizeEncoding(encoding);
+        return normalized === "hex"
+            ? toOwnedUint8Array(BufferUtils.fromHex(data))
+            : toOwnedUint8Array(BufferUtils.fromString(data, normalized));
+    }
+    return toOwnedUint8Array(data);
+}
+/**
+ * Convert bytes into a string using the requested encoding.
+ */
+function toEncodedString(bytes, encoding = "utf8") {
+    return BufferUtils.bufferToString(bytes, normalizeEncoding(encoding));
+}
+/**
+ * Concatenate two byte arrays into a fresh Uint8Array.
+ */
+function concatBytes(a, b) {
+    return toOwnedUint8Array(BufferUtils.concat([a, b]));
+}
+/**
+ * Slice bytes into a fresh Uint8Array.
+ */
+function sliceBytes(bytes, start, end) {
+    return toOwnedUint8Array(BufferUtils.slice(bytes, start, end));
+}
+/**
+ * Hash algorithm mapping for Web Crypto API
+ */
+const WEB_CRYPTO_ALGO_MAP = {
+    sha256: "SHA-256",
+    sha1: "SHA-1",
+    sha512: "SHA-512",
+};
+/**
+ * Get Web Crypto SubtleCrypto interface, throwing if unavailable
+ */
+function getWebCryptoSubtle() {
+    const globalThisCrypto = globalThis.crypto;
+    const subtle = globalThisCrypto?.subtle;
+    if (!subtle) {
+        throw new Error("Web Crypto API not available. This browser may not support cryptographic operations.");
+    }
+    return subtle;
+}
+/**
+ * Resolve a synchronous hash implementation.
+ */
+function getSyncHashFactory(algorithm) {
+    const normalized = algorithm.toLowerCase();
+    const hashFactory = HASH_ALGORITHMS[normalized];
+    if (!hashFactory) {
+        throw new Error(`Unsupported algorithm: ${algorithm}. Supported: ${Object.keys(HASH_ALGORITHMS).join(", ")}`);
+    }
+    return hashFactory;
+}
+/**
+ * Hash data using Web Crypto API (browser-compatible)
+ */
+async function webCryptoHash(algorithm, data) {
+    const subtle = getWebCryptoSubtle();
+    const webAlgo = WEB_CRYPTO_ALGO_MAP[algorithm.toLowerCase()];
+    if (!webAlgo) {
+        throw new Error(`Unsupported algorithm: ${algorithm}. Supported: ${Object.keys(WEB_CRYPTO_ALGO_MAP).join(", ")}`);
+    }
+    const hashBuffer = await subtle.digest(webAlgo, Uint8Array.from(data));
+    return new Uint8Array(hashBuffer);
+}
+/**
+ * Encrypt data using AES-256-CBC with Web Crypto API (browser-compatible)
+ */
+async function webCryptoEncrypt(key, iv, data) {
+    validateKeyAndIv(key, iv);
+    const subtle = getWebCryptoSubtle();
+    const cryptoKey = await subtle.importKey("raw", Uint8Array.from(key), { name: "AES-CBC", length: 256 }, false, ["encrypt"]);
+    const encrypted = await subtle.encrypt({ name: "AES-CBC", iv: Uint8Array.from(iv) }, cryptoKey, Uint8Array.from(data));
+    return new Uint8Array(encrypted);
+}
+/**
+ * Decrypt data using AES-256-CBC with Web Crypto API (browser-compatible)
+ */
+async function webCryptoDecrypt(key, iv, data) {
+    validateKeyAndIv(key, iv);
+    const subtle = getWebCryptoSubtle();
+    const cryptoKey = await subtle.importKey("raw", Uint8Array.from(key), { name: "AES-CBC", length: 256 }, false, ["decrypt"]);
+    const decrypted = await subtle.decrypt({ name: "AES-CBC", iv: Uint8Array.from(iv) }, cryptoKey, Uint8Array.from(data));
+    return new Uint8Array(decrypted);
+}
+/**
+ * Add PKCS#7 padding to a CBC plaintext tail.
+ */
+function applyPkcs7Padding(data) {
+    const padLength = AES_BLOCK_SIZE - (data.length % AES_BLOCK_SIZE || 0);
+    const padding = new Uint8Array(padLength === 0 ? AES_BLOCK_SIZE : padLength);
+    padding.fill(padding.length);
+    return concatBytes(data, padding);
+}
+/**
+ * Remove PKCS#7 padding from a decrypted CBC plaintext tail.
+ */
+function removePkcs7Padding(data) {
+    if (data.length === 0 || data.length % AES_BLOCK_SIZE !== 0) {
+        throw new Error("Invalid ciphertext length for AES-CBC payload.");
+    }
+    const padLength = data[data.length - 1];
+    if (padLength < 1 || padLength > AES_BLOCK_SIZE) {
+        throw new Error("Invalid PKCS#7 padding.");
+    }
+    for (let i = data.length - padLength; i < data.length; i++) {
+        if (data[i] !== padLength) {
+            throw new Error("Invalid PKCS#7 padding.");
+        }
+    }
+    return sliceBytes(data, 0, data.length - padLength);
+}
+/**
+ * Validate key and IV lengths for AES-256-CBC
+ */
+function validateKeyAndIv(key, iv) {
+    if (key.length !== 32) {
+        throw new Error(`Invalid key length: ${key.length} bytes. Expected 32 bytes for AES-256.`);
+    }
+    if (iv.length !== 16) {
+        throw new Error(`Invalid IV length: ${iv.length} bytes. Expected 16 bytes for AES-CBC.`);
+    }
+}
+/**
+ * Validate key and IV lengths for AES-256-GCM
+ *
+ * GCM requires a 32-byte key. The recommended nonce/IV length is 12 bytes.
+ */
+function validateKeyAndGcmIv(key, iv) {
+    if (key.length !== 32) {
+        throw new Error(`Invalid key length: ${key.length} bytes. Expected 32 bytes for AES-256.`);
+    }
+    if (iv.length !== 12) {
+        throw new Error(`Invalid IV length: ${iv.length} bytes. Expected 12 bytes for AES-GCM.`);
+    }
+}
+/**
+ * Create a hash object for incremental hashing (cross-platform - synchronous)
+ *
+ * This function works in both Node.js and browser environments using
+ * synchronous noble hash implementations.
+ *
+ * @param algorithm - Hash algorithm ('sha256', 'sha1', 'sha512')
+ * @returns Hash object with update() and digest() methods
+ */
+export function createHash(algorithm) {
+    const hash = getSyncHashFactory(algorithm).create();
+    function digest(encoding) {
+        const hashDigest = Uint8Array.from(hash.digest());
+        if (!encoding) {
+            return hashDigest;
+        }
+        return toEncodedString(hashDigest, normalizeEncoding(encoding));
+    }
+    const builder = {
+        update(data) {
+            hash.update(toUint8Array(data));
+            return builder;
+        },
+        digest,
+    };
+    return builder;
+}
+/**
+ * Create a hash asynchronously (works in both Node.js and browser)
+ *
+ * This is the recommended method for cross-platform code.
+ *
+ * @param algorithm - Hash algorithm ('sha256', 'sha1', 'sha512')
+ * @param data - Data to hash
+ * @returns Hash result
+ */
+export async function createHashAsync(algorithm, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    return webCryptoHash(algorithm, bytes);
+}
+/**
+ * Create a cipher for encryption (cross-platform - synchronous)
+ *
+ * @param algorithm - Cipher algorithm (only 'aes-256-cbc' is supported)
+ * @param key - 256-bit (32-byte) encryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @returns Cipher object with update() and final() methods
+ */
+export function createCipheriv(algorithm, key, iv) {
+    if (algorithm !== "aes-256-cbc") {
+        throw new Error(`Unsupported algorithm: ${algorithm}. Only 'aes-256-cbc' is supported.`);
+    }
+    validateKeyAndIv(key, iv);
+    const normalizedKey = Uint8Array.from(key);
+    let currentIv = Uint8Array.from(iv);
+    let pending = new Uint8Array(0);
+    return {
+        update(data, inputEncoding, outputEncoding) {
+            const incoming = toUint8Array(data, normalizeEncoding(inputEncoding));
+            pending = concatBytes(pending, incoming);
+            const fullBlockLength = pending.length - (pending.length % AES_BLOCK_SIZE);
+            if (fullBlockLength === 0) {
+                return "";
+            }
+            const plaintextChunk = sliceBytes(pending, 0, fullBlockLength);
+            pending = sliceBytes(pending, fullBlockLength);
+            const encryptedChunk = Uint8Array.from(cbc(normalizedKey, currentIv, { disablePadding: true }).encrypt(plaintextChunk));
+            currentIv = sliceBytes(encryptedChunk, encryptedChunk.length - AES_BLOCK_SIZE);
+            return toEncodedString(encryptedChunk, normalizeEncoding(outputEncoding));
+        },
+        final(encoding) {
+            const encryptedTail = Uint8Array.from(cbc(normalizedKey, currentIv, { disablePadding: true }).encrypt(applyPkcs7Padding(pending)));
+            pending = new Uint8Array(0);
+            return toEncodedString(encryptedTail, normalizeEncoding(encoding));
+        },
+    };
+}
+/**
+ * Create a decipher for decryption (cross-platform - synchronous)
+ *
+ * @param algorithm - Cipher algorithm (only 'aes-256-cbc' is supported)
+ * @param key - 256-bit (32-byte) decryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @returns Decipher object with update() and final() methods
+ */
+export function createDecipheriv(algorithm, key, iv) {
+    if (algorithm !== "aes-256-cbc") {
+        throw new Error(`Unsupported algorithm: ${algorithm}. Only 'aes-256-cbc' is supported.`);
+    }
+    validateKeyAndIv(key, iv);
+    const normalizedKey = Uint8Array.from(key);
+    let currentIv = Uint8Array.from(iv);
+    let pending = new Uint8Array(0);
+    return {
+        update(data, inputEncoding, outputEncoding) {
+            const incoming = toUint8Array(data, normalizeEncoding(inputEncoding));
+            pending = concatBytes(pending, incoming);
+            const decryptableLength = pending.length > AES_BLOCK_SIZE
+                ? pending.length -
+                    AES_BLOCK_SIZE -
+                    ((pending.length - AES_BLOCK_SIZE) % AES_BLOCK_SIZE)
+                : 0;
+            if (decryptableLength === 0) {
+                return "";
+            }
+            const ciphertextChunk = sliceBytes(pending, 0, decryptableLength);
+            pending = sliceBytes(pending, decryptableLength);
+            const plaintextChunk = Uint8Array.from(cbc(normalizedKey, currentIv, { disablePadding: true }).decrypt(ciphertextChunk));
+            currentIv = sliceBytes(ciphertextChunk, ciphertextChunk.length - AES_BLOCK_SIZE);
+            return toEncodedString(plaintextChunk, normalizeEncoding(outputEncoding));
+        },
+        final(encoding) {
+            if (pending.length === 0 || pending.length % AES_BLOCK_SIZE !== 0) {
+                throw new Error("Invalid ciphertext length for AES-CBC payload.");
+            }
+            const decryptedTail = Uint8Array.from(cbc(normalizedKey, currentIv, { disablePadding: true }).decrypt(pending));
+            pending = new Uint8Array(0);
+            return toEncodedString(removePkcs7Padding(decryptedTail), normalizeEncoding(encoding));
+        },
+    };
+}
+/**
+ * Encrypt data asynchronously (works in both Node.js and browser)
+ *
+ * This is the recommended method for cross-platform code using AES-256-CBC.
+ *
+ * @param key - 256-bit (32-byte) encryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @param data - Data to encrypt
+ * @returns Encrypted data
+ */
+export async function encryptAsync(key, iv, data) {
+    validateKeyAndIv(key, iv);
+    return webCryptoEncrypt(key, iv, data);
+}
+/**
+ * Decrypt data asynchronously (works in both Node.js and browser)
+ *
+ * This is the recommended method for cross-platform code using AES-256-CBC.
+ *
+ * @param key - 256-bit (32-byte) decryption key
+ * @param iv - 128-bit (16-byte) initialization vector
+ * @param data - Data to decrypt
+ * @returns Decrypted data
+ */
+export async function decryptAsync(key, iv, data) {
+    validateKeyAndIv(key, iv);
+    return webCryptoDecrypt(key, iv, data);
+}
+/**
+ * Encrypt using AES-256-GCM (synchronous).
+ *
+ * This is used for cross-language secret encryption with integrity protection.
+ */
+export function encryptAes256Gcm(key, iv, plaintext, aad) {
+    validateKeyAndGcmIv(key, iv);
+    const encrypted = Uint8Array.from(gcm(Uint8Array.from(key), Uint8Array.from(iv), aad ? Uint8Array.from(aad) : undefined).encrypt(Uint8Array.from(plaintext)));
+    const tagStart = encrypted.length - 16;
+    return {
+        ciphertext: sliceBytes(encrypted, 0, tagStart),
+        tag: sliceBytes(encrypted, tagStart),
+    };
+}
+/**
+ * Decrypt using AES-256-GCM (synchronous).
+ */
+export function decryptAes256Gcm(key, iv, ciphertext, tag, aad) {
+    validateKeyAndGcmIv(key, iv);
+    if (tag.length !== 16) {
+        throw new Error(`Invalid tag length: ${tag.length} bytes. Expected 16 bytes for AES-GCM tag.`);
+    }
+    const combined = concatBytes(Uint8Array.from(ciphertext), Uint8Array.from(tag));
+    return Uint8Array.from(gcm(Uint8Array.from(key), Uint8Array.from(iv), aad ? Uint8Array.from(aad) : undefined).decrypt(combined));
+}

package/packages/typescript/src/utils/deterministic.d.ts

@@ -0,0 +1,9 @@
+export declare function buildDeterministicSeed(...parts: Array<string | number | null | undefined>): string;
+export declare function hashStringToUint32(value: string): number;
+export declare function createDeterministicRandom(seed: string | number): () => number;
+export declare function deterministicShuffle<T>(items: readonly T[], seed: string | number): T[];
+export declare function deterministicSample<T>(items: readonly T[], count: number, seed: string | number): T[];
+export declare function deterministicPick<T>(items: readonly T[], seed: string | number): T | undefined;
+export declare function getDeterministicNames(count: number, seed: string | number): string[];
+export declare function stableStringify(value: unknown): string;
+//# sourceMappingURL=deterministic.d.ts.map

package/packages/typescript/src/utils/deterministic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/deterministic.ts"],"names":[],"mappings":"AAIA,wBAAgB,sBAAsB,CACrC,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GACjD,MAAM,CAOR;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,MAAM,CAW7E;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EACrC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,MAAM,GAAG,MAAM,GACnB,CAAC,EAAE,CAQL;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EACpC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,MAAM,GACnB,CAAC,EAAE,CASL;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAClC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,MAAM,GAAG,MAAM,GACnB,CAAC,GAAG,SAAS,CAEf;AAED,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,MAAM,GACnB,MAAM,EAAE,CAeV;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/packages/typescript/src/utils/deterministic.js

@@ -0,0 +1,70 @@
+import { EXAMPLE_NAMES } from "./example-names";
+const UINT32_MAX = 0x100000000;
+export function buildDeterministicSeed(...parts) {
+    const filtered = parts
+        .map((part) => part === undefined || part === null ? "" : String(part).trim())
+        .filter((part) => part.length > 0);
+    return filtered.length > 0 ? filtered.join("::") : "default";
+}
+export function hashStringToUint32(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+export function createDeterministicRandom(seed) {
+    let state = typeof seed === "number" ? seed >>> 0 : hashStringToUint32(String(seed));
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / UINT32_MAX;
+    };
+}
+export function deterministicShuffle(items, seed) {
+    const random = createDeterministicRandom(seed);
+    const shuffled = [...items];
+    for (let i = shuffled.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+}
+export function deterministicSample(items, count, seed) {
+    if (count <= 0 || items.length === 0) {
+        return [];
+    }
+    return deterministicShuffle(items, seed).slice(0, Math.min(count, items.length));
+}
+export function deterministicPick(items, seed) {
+    return deterministicSample(items, 1, seed)[0];
+}
+export function getDeterministicNames(count, seed) {
+    if (count <= 0) {
+        return [];
+    }
+    const ordered = deterministicShuffle(EXAMPLE_NAMES, buildDeterministicSeed(seed, "names"));
+    return Array.from({ length: count }, (_, index) => {
+        const name = ordered[index % ordered.length];
+        return typeof name === "string" && name.length > 0
+            ? name
+            : `user${index + 1}`;
+    });
+}
+export function stableStringify(value) {
+    return JSON.stringify(sortStable(value));
+}
+function sortStable(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => sortStable(entry));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, nestedValue]) => [key, sortStable(nestedValue)]));
+    }
+    return value;
+}

package/packages/typescript/src/utils/environment.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Browser and Node.js compatible environment variable abstraction
+ * This module provides a cross-platform interface for accessing environment variables
+ * that works in both browser and Node.js environments.
+ */
+/**
+ * Type representing the runtime environment
+ */
+export type RuntimeEnvironment = "node" | "browser" | "unknown";
+/**
+ * Interface for environment configuration
+ */
+export interface EnvironmentConfig {
+    [key: string]: string | boolean | number | undefined;
+}
+/**
+ * Detect the current runtime environment
+ */
+export declare function detectEnvironment(): RuntimeEnvironment;
+/**
+ * Environment abstraction class
+ */
+declare class Environment {
+    private readonly runtime;
+    private browserStore;
+    private cache;
+    constructor();
+    /**
+     * Get the current runtime environment
+     */
+    getRuntime(): RuntimeEnvironment;
+    /**
+     * Check if running in Node.js
+     */
+    isNode(): boolean;
+    /**
+     * Check if running in browser
+     */
+    isBrowser(): boolean;
+    /**
+     * Get an environment variable
+     */
+    get(key: string, defaultValue?: string): string | undefined;
+    /**
+     * Set an environment variable (mainly for browser/testing)
+     */
+    set(key: string, value: string | boolean | number): void;
+    /**
+     * Check if an environment variable exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get all environment variables
+     */
+    getAll(): EnvironmentConfig;
+    /**
+     * Get a boolean environment variable
+     */
+    getBoolean(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Get a number environment variable
+     */
+    getNumber(key: string, defaultValue?: number): number | undefined;
+    /**
+     * Clear the cache (useful for testing)
+     */
+    clearCache(): void;
+}
+/**
+ * Get the singleton Environment instance
+ */
+export declare function getEnvironment(): Environment;
+/**
+ * Convenience function to get an environment variable
+ */
+export declare function getEnv(key: string, defaultValue?: string): string | undefined;
+/**
+ * Convenience function to set an environment variable
+ */
+export declare function setEnv(key: string, value: string | boolean | number): void;
+/**
+ * Convenience function to check if an environment variable exists
+ */
+export declare function hasEnv(key: string): boolean;
+/**
+ * Convenience function to get a boolean environment variable
+ */
+export declare function getBooleanEnv(key: string, defaultValue?: boolean): boolean;
+/**
+ * Convenience function to get a number environment variable
+ */
+export declare function getNumberEnv(key: string, defaultValue?: number): number | undefined;
+/**
+ * Initialize browser environment with config
+ * This should be called early in browser apps to set up environment
+ */
+export declare function initBrowserEnvironment(config: EnvironmentConfig): void;
+/**
+ * Export the current runtime for convenience
+ */
+export declare const currentRuntime: RuntimeEnvironment;
+/**
+ * Re-export the Environment class for advanced usage
+ */
+export { Environment };
+/**
+ * Find the .env file by traversing up the directory tree
+ * Searches from startDir upwards until it finds a .env file or reaches the root
+ *
+ * @param startDir - Directory to start searching from (defaults to process.cwd())
+ * @param filenames - Array of filenames to search for (defaults to ['.env', '.env.local'])
+ * @returns Path to the .env file if found, null otherwise
+ */
+export declare function findEnvFile(startDir?: string, filenames?: string[]): string | null;
+/**
+ * Load environment variables from .env file into process.env
+ *
+ * Node.js only - does nothing in browser environments
+ *
+ * @param envPath - Optional explicit path to .env file. If not provided, will search upwards from cwd
+ * @returns true if .env was found and loaded successfully
+ * @throws Error if the .env file exists but cannot be parsed
+ */
+export declare function loadEnvFile(envPath?: string): boolean;
+//# sourceMappingURL=environment.d.ts.map

package/packages/typescript/src/utils/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/environment.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACrD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,CAoBtD;AA0CD;;GAEG;AACH,cAAM,WAAW;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,YAAY,CAAwC;IAC5D,OAAO,CAAC,KAAK,CAA8C;;IAS3D;;OAEG;IACH,UAAU,IAAI,kBAAkB;IAIhC;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAqB3D;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI;IAaxD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;OAEG;IACH,MAAM,IAAI,iBAAiB;IAY3B;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO;IAKtD;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASjE;;OAEG;IACH,UAAU,IAAI,IAAI;CAGlB;AAOD;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAK5C;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAE1E;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO,CAExE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAEpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAStE;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,oBAAsB,CAAC;AAElD;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,CAAC;AAMvB;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,GAAE,MAAM,EAA2B,GAC1C,MAAM,GAAG,IAAI,CAkCf;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CA6BrD"}