@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/errors/index.js

@@ -1,4 +1,6 @@
-export { ClaimUtxoError, ConversionError, CreateUtxoError, CryptographyAssertionError, CryptographyError, EncryptedDepositError, EncryptedWithdrawalError, FetchUtxosError, InstructionError, MasterSeedSigningRejectedError, MathematicsAssertionError, QueryError, RegistrationError, RpcError, SolanaAssertionError, TemporalAssertionError, TransactionError, TransactionSigningError, UmbraError, isClaimUtxoError, isConversionError, isCreateUtxoError, isCryptographyError, isEncryptedDepositError, isEncryptedWithdrawalError, isFetchUtxosError, isInstructionError, isQueryError, isRegistrationError, isRpcError, isTransactionError, isTransactionSigningError, isUmbraError } from '../chunk-WVHQ46DD.js';
+export { ClaimUtxoError, ComputationMonitorError, ConversionError, CreateUtxoError, EncryptedDepositError, EncryptedWithdrawalError, FetchUtxosError, InstructionError, MasterSeedSigningRejectedError, QueryError, RegistrationError, RpcError, TransactionError, TransactionSigningError, isClaimUtxoError, isComputationMonitorError, isConversionError, isCreateUtxoError, isEncryptedDepositError, isEncryptedWithdrawalError, isFetchUtxosError, isInstructionError, isQueryError, isRegistrationError, isRpcError, isTransactionError, isTransactionSigningError } from '../chunk-GP26R377.js';
+export { CryptographyError, isCryptographyError } from '../chunk-5KPQXPQM.js';
+export { CryptographyAssertionError, MathematicsAssertionError, SolanaAssertionError, TemporalAssertionError, UmbraError, isUmbraError } from '../chunk-4TZVXB5G.js';
 import '../chunk-7QVYU63E.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/errors-B9EoPeWV.d.cts

@@ -0,0 +1,593 @@
+/**
+ * Error Classes
+ *
+ * Centralized error hierarchy for the Umbra SDK.
+ * Contains the base `UmbraError` and all domain-specific assertion error classes.
+ *
+ * @remarks
+ * The SDK uses a two-level error hierarchy:
+ *
+ * 1. `UmbraError` — top-level base class for all SDK errors. Consumers can use
+ *    `instanceof UmbraError` (or the `isUmbraError` type guard) to distinguish SDK errors
+ *    from third-party or built-in errors in a catch block.
+ *
+ * 2. Domain assertion errors — thrown by type-assertion functions when a value fails
+ *    validation. Each domain has its own class to make it easy to catch errors from a
+ *    specific subsystem:
+ *    - `MathematicsAssertionError` — thrown by `assertU8`, `assertU256`, etc.
+ *    - `CryptographyAssertionError` — thrown by `assertBn254FieldElement`, `assertAesKey`, etc.
+ *    - `SolanaAssertionError` — thrown by Solana-type assertion functions.
+ *    - `TemporalAssertionError` — thrown by `assertYear`, `assertMonth`, etc.
+ *
+ * All four assertion error classes share the same three properties:
+ * - `value` — the actual value that failed
+ * - `expectedType` — the name of the expected branded type
+ * - `constraint` — optional human-readable constraint description
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module common/errors
+ */
+/**
+ * Base error class for all Umbra SDK errors.
+ *
+ * All errors thrown by the SDK extend this class, allowing consumers
+ * to distinguish SDK errors from other errors using `instanceof`.
+ *
+ * @remarks
+ * Prefer using the `isUmbraError` type guard over `instanceof UmbraError` when writing
+ * defensive catch handlers — the type guard also works across module boundaries and
+ * iframe/realm boundaries where `instanceof` may fail due to different class references.
+ *
+ * Sub-classes (domain assertion errors) extend this class so callers can catch either
+ * all SDK errors at once (`instanceof UmbraError`) or only a specific domain's failures
+ * (e.g., `instanceof MathematicsAssertionError`).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await umbraClient.register();
+ * } catch (error) {
+ *   if (error instanceof UmbraError) {
+ *     console.log('SDK error:', error.message);
+ *     console.log('Error code:', error.code);
+ *   } else {
+ *     throw error; // Re-throw non-SDK errors
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link isUmbraError}
+ * @public
+ */
+declare class UmbraError extends Error {
+    /**
+     * A machine-readable error code for programmatic error handling.
+     *
+     * @remarks
+     * Defaults to `"UMBRA_ERROR"` when no code is supplied in the constructor options.
+     * Sub-classes or specific throw sites should supply a more specific code to allow
+     * callers to branch on error identity without string-matching `message`.
+     *
+     * @readonly
+     */
+    readonly code: string;
+    /**
+     * Additional context about the error.
+     *
+     * @remarks
+     * A free-form key-value map of diagnostic data attached to the error at the throw site.
+     * Useful for logging and debugging — consumers should not rely on specific keys for
+     * control flow; use `code` for programmatic branching instead.
+     *
+     * Will be `undefined` when no context was provided to the constructor.
+     *
+     * @readonly
+     */
+    readonly context?: Record<string, unknown>;
+    /**
+     * The original error that caused this error, if any.
+     *
+     * @remarks
+     * When an SDK function wraps a lower-level error (e.g., a failed RPC call or a
+     * cryptographic library error), it sets `cause` to the original thrown value so
+     * callers can inspect the full error chain.
+     *
+     * Will be `undefined` when there is no underlying cause.
+     *
+     * @readonly
+     */
+    readonly cause?: unknown;
+    /**
+     * Creates a new UmbraError.
+     *
+     * @param message - Human-readable description of what went wrong. Should be
+     *   actionable and specific enough for a developer to understand the failure
+     *   without reading source code.
+     * @param options - Optional structured metadata attached to the error.
+     * @param options.code - Machine-readable error code for programmatic branching.
+     *   Defaults to `"UMBRA_ERROR"` if omitted.
+     * @param options.context - Free-form diagnostic key-value pairs. Omit or set to
+     *   `undefined` to leave the `context` property unset.
+     * @param options.cause - The original error that triggered this one. Enables
+     *   full error-chain inspection. Omit or set to `undefined` when there is no
+     *   underlying cause.
+     *
+     * @defaultValue `options` — `undefined` (all options optional)
+     * @defaultValue `options.code` — `"UMBRA_ERROR"`
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        context?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+/**
+ * Type guard to check if an error is an UmbraError.
+ *
+ * @remarks
+ * Prefer this guard over `error instanceof UmbraError` in generic catch handlers because
+ * it is safe to call with any value (including `null`, primitives, and non-Error objects)
+ * and narrows the type to `UmbraError` for TypeScript's type system in the true branch.
+ *
+ * @param error - The value to test. Typically the caught value in a `catch (error)` block,
+ *   typed as `unknown`.
+ * @returns `true` and narrows `error` to `UmbraError` when the value is an instance of
+ *   `UmbraError` (or any sub-class such as `MathematicsAssertionError`). Returns `false`
+ *   for all other values.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await operation();
+ * } catch (error) {
+ *   if (isUmbraError(error)) {
+ *     // error is narrowed to UmbraError here
+ *     console.log('SDK error code:', error.code);
+ *     console.log('SDK error context:', error.context);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link UmbraError}
+ * @public
+ */
+declare function isUmbraError(error: unknown): error is UmbraError;
+/**
+ * Error thrown when a value fails a mathematical type assertion.
+ *
+ * This error provides detailed information about why an assertion failed,
+ * including the actual value, the expected type, and the constraint that
+ * was violated.
+ *
+ * @remarks
+ * All assertion functions in the mathematics module (e.g., `assertU8`, `assertU256`,
+ * `assertU32LeBytes`) throw this error type on failure. Catch it specifically to handle
+ * mathematical type validation failures differently from cryptographic or Solana errors.
+ *
+ * The three diagnostic properties together allow automated logging pipelines to produce
+ * structured records without parsing the `message` string:
+ * - `value` — the actual value that was supplied
+ * - `expectedType` — the branded type name (e.g., `"U8"`, `"U256LeBytes"`)
+ * - `constraint` — the violated range or length rule, or `undefined` for type mismatches
+ *
+ * Note that this class does NOT extend `UmbraError`. It extends `Error` directly to keep
+ * the assertion error classes lightweight and independent of the UmbraError hierarchy.
+ * Use `isUmbraError` only to detect top-level SDK operational errors; use
+ * `instanceof MathematicsAssertionError` for assertion failures.
+ *
+ * @example
+ * ```typescript
+ * import { assertU8, MathematicsAssertionError } from "./mathematics";
+ *
+ * try {
+ *     const value = assertU8(256n); // Will throw
+ * } catch (error) {
+ *     if (error instanceof MathematicsAssertionError) {
+ *         console.error(`Assertion failed for ${error.expectedType}`);
+ *         console.error(`Value: ${error.value}`);
+ *         console.error(`Constraint: ${error.constraint}`);
+ *         // Output:
+ *         // Assertion failed for U8
+ *         // Value: 256
+ *         // Constraint: 0 <= value <= 255
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe parse pattern — returns null instead of throwing
+ * function safeParseU8(value: bigint): U8 | null {
+ *     try {
+ *         return assertU8(value);
+ *     } catch (error) {
+ *         if (error instanceof MathematicsAssertionError) {
+ *             console.warn(`Invalid U8 value: ${value}`);
+ *             return null;
+ *         }
+ *         throw error; // Re-throw unexpected errors
+ *     }
+ * }
+ * ```
+ *
+ * @sealed
+ * @public
+ */
+declare class MathematicsAssertionError extends Error {
+    /**
+     * The actual value that failed the assertion.
+     *
+     * @remarks
+     * The runtime type reflects what was actually passed to the assertion function:
+     * - `bigint` for integer assertions (`assertU8`, `assertU256`, etc.)
+     * - `Uint8Array` for byte-array assertions (`assertU256LeBytes`, `assertU32LeBytes`, etc.)
+     * - Any other type when a non-numeric value was passed unexpectedly
+     *
+     * @readonly
+     */
+    readonly value: unknown;
+    /**
+     * The type that was expected.
+     *
+     * @remarks
+     * Contains the branded type name exactly as it appears in the SDK type system,
+     * e.g., `"U8"`, `"U256"`, `"U32LeBytes"`. Use this for structured logging or
+     * to build user-facing error messages without parsing the `message` string.
+     *
+     * @readonly
+     */
+    readonly expectedType: string;
+    /**
+     * Description of the constraint that was violated.
+     *
+     * @remarks
+     * Is `undefined` when only a type check failed (e.g., a `string` was passed where a
+     * `bigint` was expected). Contains a human-readable inequality or length rule when a
+     * value of the correct type was out of the allowed range.
+     *
+     * @example
+     * - `"0 <= value <= 255"` — U8 range violation
+     * - `"length === 32"` — U256LeBytes length violation
+     * - `"value >= 0"` — negative value passed to an unsigned integer assertion
+     *
+     * @readonly
+     */
+    readonly constraint: string | undefined;
+    /**
+     * Creates a new MathematicsAssertionError.
+     *
+     * @param message - Human-readable description of the assertion failure. Should name
+     *   the assertion function, the expected type, and the constraint that was violated.
+     * @param options - Structured diagnostic details attached to the error.
+     * @param options.value - The actual value that was supplied and failed the assertion.
+     * @param options.expectedType - The name of the branded type that was expected
+     *   (e.g., `"U8"`, `"U256LeBytes"`).
+     * @param options.constraint - Optional human-readable constraint description
+     *   (e.g., `"0 <= value <= 255"`). Omit when the failure is a type mismatch rather
+     *   than a range violation.
+     */
+    constructor(message: string, options: {
+        value: unknown;
+        expectedType: string;
+        constraint?: string;
+    });
+}
+/**
+ * Error thrown when a value fails a cryptographic type assertion.
+ *
+ * This error provides detailed information about why an assertion failed,
+ * including the actual value, the expected type, and the constraint that
+ * was violated.
+ *
+ * @remarks
+ * Thrown by assertion functions in the cryptography module, such as
+ * `assertBn254FieldElement`, `assertAesKey`, `assertX25519PrivateKey`, and similar.
+ * Each function validates that a value conforms to a branded cryptographic type,
+ * throwing this error with a precise `expectedType` and `constraint` when it does not.
+ *
+ * Common reasons for failure:
+ * - A `bigint` field element exceeds the BN254 or Curve25519 field prime
+ * - A byte array has the wrong length (e.g., a 31-byte array passed as an AES-256 key)
+ * - A wrong JavaScript type was supplied (e.g., a `number` instead of a `bigint`)
+ *
+ * @example
+ * ```typescript
+ * import { assertBn254FieldElement, CryptographyAssertionError } from "./cryptography";
+ *
+ * try {
+ *     assertBn254FieldElement(invalidValue); // Will throw
+ * } catch (error) {
+ *     if (error instanceof CryptographyAssertionError) {
+ *         console.error(`Assertion failed for ${error.expectedType}`);
+ *         console.error(`Value: ${error.value}`);
+ *         console.error(`Constraint: ${error.constraint}`);
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Distinguish cryptographic assertion failures from mathematical ones
+ * try {
+ *     const key = assertAesKey(rawBytes);
+ * } catch (error) {
+ *     if (error instanceof CryptographyAssertionError) {
+ *         console.warn("Crypto assertion failed:", error.expectedType, error.constraint);
+ *     } else if (error instanceof MathematicsAssertionError) {
+ *         console.warn("Math assertion failed:", error.expectedType, error.constraint);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link MathematicsAssertionError}
+ * @see {@link SolanaAssertionError}
+ * @see {@link TemporalAssertionError}
+ * @sealed
+ * @public
+ */
+declare class CryptographyAssertionError extends Error {
+    /**
+     * The actual value that failed the assertion.
+     *
+     * @remarks
+     * The runtime type reflects what was actually passed to the assertion function:
+     * - `bigint` for field element assertions (`assertBn254FieldElement`, etc.)
+     * - `Uint8Array` for byte-array assertions (`assertAesKey`, `assertX25519PrivateKey`, etc.)
+     * - Any other type when an entirely wrong value type was supplied
+     *
+     * @readonly
+     */
+    readonly value: unknown;
+    /**
+     * The type that was expected (e.g., `"Bn254FieldElement"`, `"PoseidonKey"`, `"AesKey"`).
+     *
+     * @remarks
+     * Contains the branded type name exactly as it appears in the SDK type system.
+     * Use this property for structured logging without parsing the `message` string.
+     *
+     * @readonly
+     */
+    readonly expectedType: string;
+    /**
+     * Description of the constraint that was violated.
+     *
+     * @remarks
+     * Is `undefined` for pure type-mismatch failures (e.g., `string` instead of `bigint`).
+     * Contains a human-readable constraint description for range and length violations
+     * (e.g., `"value < BN254_FIELD_PRIME"`, `"length === 32"`).
+     *
+     * @readonly
+     */
+    readonly constraint: string | undefined;
+    /**
+     * Creates a new CryptographyAssertionError.
+     *
+     * @param message - Human-readable description of the assertion failure. Should name
+     *   the assertion function, the expected type, and the constraint that was violated.
+     * @param options - Structured diagnostic details attached to the error.
+     * @param options.value - The actual value that was supplied and failed the assertion.
+     * @param options.expectedType - The name of the branded cryptographic type that was
+     *   expected (e.g., `"Bn254FieldElement"`, `"AesKey"`).
+     * @param options.constraint - Optional human-readable constraint description.
+     *   Omit when the failure is a type mismatch rather than a range or length violation.
+     */
+    constructor(message: string, options: {
+        value: unknown;
+        expectedType: string;
+        constraint?: string;
+    });
+}
+/**
+ * Error thrown when a Solana type assertion fails.
+ *
+ * This error provides detailed information about why the assertion failed,
+ * including the actual value, expected type, and constraint that was violated.
+ *
+ * @remarks
+ * Thrown by assertion functions for Solana-specific branded types, such as
+ * `assertTransactionSignature`, `assertSignatureBytes`, and similar validators.
+ * These assertions verify that string or byte-array values conform to Solana's
+ * encoding and length conventions (e.g., Base58-encoded 64-byte Ed25519 signatures).
+ *
+ * Common reasons for failure:
+ * - A string that fails Base58 decoding or has the wrong decoded length
+ * - A `Uint8Array` with the wrong byte length for a signature or public key
+ * - A wrong JavaScript type (e.g., `number` instead of `string`)
+ *
+ * @example
+ * ```typescript
+ * import { assertTransactionSignature, SolanaAssertionError } from "./solana";
+ *
+ * try {
+ *     assertTransactionSignature("invalid!signature"); // Will throw
+ * } catch (error) {
+ *     if (error instanceof SolanaAssertionError) {
+ *         console.error(`Assertion failed for ${error.expectedType}`);
+ *         console.error(`Value: ${error.value}`);
+ *         console.error(`Constraint: ${error.constraint}`);
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe parse pattern — returns null on failure
+ * function tryParseSignature(raw: unknown): TransactionSignature | null {
+ *     try {
+ *         return assertTransactionSignature(raw);
+ *     } catch (error) {
+ *         if (error instanceof SolanaAssertionError) return null;
+ *         throw error;
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link MathematicsAssertionError}
+ * @see {@link CryptographyAssertionError}
+ * @see {@link TemporalAssertionError}
+ * @sealed
+ * @public
+ */
+declare class SolanaAssertionError extends Error {
+    /**
+     * The actual value that failed the assertion.
+     *
+     * @remarks
+     * The runtime type reflects what was actually passed to the assertion function:
+     * - `string` for Base58-encoded assertions (`assertTransactionSignature`, etc.)
+     * - `Uint8Array` for byte-array assertions (`assertSignatureBytes`, etc.)
+     * - Any other type when a completely wrong value type was supplied
+     *
+     * @readonly
+     */
+    readonly value: unknown;
+    /**
+     * The type that was expected (e.g., `"TransactionSignature"`, `"SignatureBytes"`).
+     *
+     * @remarks
+     * Contains the branded type name exactly as it appears in the SDK type system.
+     * Use this for structured logging without parsing the `message` string.
+     *
+     * @readonly
+     */
+    readonly expectedType: string;
+    /**
+     * Description of the constraint that was violated.
+     *
+     * @remarks
+     * Is `undefined` for pure type-mismatch failures. Contains a human-readable rule
+     * for encoding or length violations (e.g., `"valid Base58"`, `"length === 64"`).
+     *
+     * @readonly
+     */
+    readonly constraint: string | undefined;
+    /**
+     * Creates a new SolanaAssertionError.
+     *
+     * @param message - Human-readable description of the assertion failure. Should name
+     *   the assertion function, the expected type, and the constraint that was violated.
+     * @param options - Structured diagnostic details attached to the error.
+     * @param options.value - The actual value that was supplied and failed the assertion.
+     * @param options.expectedType - The name of the branded Solana type that was expected
+     *   (e.g., `"TransactionSignature"`, `"SignatureBytes"`).
+     * @param options.constraint - Optional human-readable constraint description.
+     *   Omit when the failure is a type mismatch rather than an encoding or length violation.
+     */
+    constructor(message: string, options: {
+        value: unknown;
+        expectedType: string;
+        constraint?: string;
+    });
+}
+/**
+ * Error thrown when a temporal type assertion fails.
+ *
+ * This error provides detailed information about why an assertion failed,
+ * including the actual value, the expected type, and the constraint that
+ * was violated.
+ *
+ * @remarks
+ * Thrown by assertion functions for branded temporal types: `assertYear`, `assertMonth`,
+ * `assertDay`, `assertHour`, `assertMinute`, and `assertSecond`. These functions validate
+ * that a `bigint` value falls within the calendar range appropriate for each component
+ * (e.g., months must be in `[1, 12]`, hours in `[0, 23]`).
+ *
+ * Temporal assertions are used to validate the output of UTC timestamp extraction before
+ * the components are used in time-scoped viewing key derivation. In normal operation they
+ * should never throw (JavaScript's `Date` always produces in-range values), but callers
+ * that construct components manually can encounter these errors.
+ *
+ * @example
+ * ```typescript
+ * import { assertMonth, TemporalAssertionError } from "./temporal";
+ *
+ * try {
+ *     assertMonth(13n); // Will throw — month must be 1–12
+ * } catch (error) {
+ *     if (error instanceof TemporalAssertionError) {
+ *         console.error(`Assertion failed for ${error.expectedType}`);
+ *         console.error(`Value: ${error.value}`);
+ *         console.error(`Constraint: ${error.constraint}`);
+ *         // Output:
+ *         // Assertion failed for Month
+ *         // Value: 13
+ *         // Constraint: 1 <= value <= 12
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe parse of a user-supplied year value
+ * function tryParseYear(raw: bigint): Year | null {
+ *     try {
+ *         return assertYear(raw);
+ *     } catch (error) {
+ *         if (error instanceof TemporalAssertionError) return null;
+ *         throw error;
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link MathematicsAssertionError}
+ * @see {@link CryptographyAssertionError}
+ * @see {@link SolanaAssertionError}
+ * @sealed
+ * @public
+ */
+declare class TemporalAssertionError extends Error {
+    /**
+     * The actual value that failed the assertion.
+     *
+     * @remarks
+     * Will be a `bigint` for all temporal assertions since the temporal types are
+     * BigInt-backed branded types (e.g., `Year`, `Month`, `Day`). May also be any
+     * other type when a non-bigint value was supplied unexpectedly.
+     *
+     * @readonly
+     */
+    readonly value: unknown;
+    /**
+     * The type that was expected (e.g., `"Year"`, `"Month"`, `"Hour"`).
+     *
+     * @remarks
+     * Contains the branded temporal type name exactly as it appears in the SDK type system.
+     * Use this for structured logging without parsing the `message` string.
+     *
+     * @readonly
+     */
+    readonly expectedType: string;
+    /**
+     * Description of the constraint that was violated.
+     *
+     * @remarks
+     * Contains a human-readable range rule for out-of-range values
+     * (e.g., `"1 <= value <= 12"` for a month violation). Is `undefined` only for
+     * pure type-mismatch failures (e.g., a `string` passed where a `bigint` was expected),
+     * which should not occur in normal usage.
+     *
+     * @readonly
+     */
+    readonly constraint: string | undefined;
+    /**
+     * Creates a new TemporalAssertionError.
+     *
+     * @param message - Human-readable description of the assertion failure. Should name
+     *   the assertion function, the expected type, and the violated range constraint.
+     * @param details - Structured diagnostic details attached to the error.
+     * @param details.value - The actual `bigint` value (or other type) that was supplied
+     *   and failed the temporal assertion.
+     * @param details.expectedType - The name of the branded temporal type that was expected
+     *   (e.g., `"Year"`, `"Month"`, `"Hour"`).
+     * @param details.constraint - Optional human-readable range description
+     *   (e.g., `"1 <= value <= 12"`). Omit when the failure is a type mismatch.
+     */
+    constructor(message: string, details: {
+        value: unknown;
+        expectedType: string;
+        constraint?: string;
+    });
+}
+
+export { CryptographyAssertionError as C, MathematicsAssertionError as M, SolanaAssertionError as S, TemporalAssertionError as T, UmbraError as U, isUmbraError as i };