@umbra-privacy/sdk 1.0.0

package/dist/types-n-sHFcgr.d.ts

@@ -0,0 +1,495 @@
+import { S as SubBrandedType, B as BrandedType } from './cryptography-BTGC72u-.js';
+
+/**
+ * Temporal Types
+ *
+ * This module defines branded types for timestamp components used in
+ * time-scoped viewing key derivation. These types provide compile-time
+ * safety for temporal values with runtime validation.
+ *
+ * ## Overview
+ *
+ * The module provides a hierarchical type system:
+ * - `TimestampComponent` - Base branded type for all timestamp values
+ * - `Year`, `Month`, `Day`, `Hour`, `Minute`, `Second` - Subbranded types
+ *
+ * ## Validation Ranges
+ *
+ * - Year: 0 to 9999 (reasonable range for most applications)
+ * - Month: 1 to 12
+ * - Day: 1 to 31
+ * - Hour: 0 to 23
+ * - Minute: 0 to 59
+ * - Second: 0 to 59
+ *
+ * @remarks
+ * All temporal component types are encoded as `bigint` to integrate directly with the BN254
+ * field arithmetic used in viewing key derivation. The branded type system prevents accidentally
+ * passing a `Month` where a `Year` is expected, catching a class of derivation-key bugs at
+ * compile time.
+ *
+ * @packageDocumentation
+ * @module common/temporal/types
+ */
+
+/**
+ * Minimum valid year value (inclusive).
+ *
+ * @remarks Year 0 corresponds to 1 BCE in the proleptic Gregorian calendar.
+ * @see {@link YEAR_MAX}
+ * @see {@link assertYear}
+ * @public
+ */
+declare const YEAR_MIN = 0n;
+/**
+ * Maximum valid year value (inclusive).
+ *
+ * @remarks Upper bound chosen to comfortably cover all practical use cases.
+ * @see {@link YEAR_MIN}
+ * @see {@link assertYear}
+ * @public
+ */
+declare const YEAR_MAX = 9999n;
+/**
+ * Minimum valid month value (inclusive).
+ *
+ * @remarks January is represented as 1, following the ISO 8601 convention.
+ * @see {@link MONTH_MAX}
+ * @see {@link assertMonth}
+ * @public
+ */
+declare const MONTH_MIN = 1n;
+/**
+ * Maximum valid month value (inclusive).
+ *
+ * @remarks December is represented as 12.
+ * @see {@link MONTH_MIN}
+ * @see {@link assertMonth}
+ * @public
+ */
+declare const MONTH_MAX = 12n;
+/**
+ * Minimum valid day value (inclusive).
+ *
+ * @remarks The first day of any month.
+ * @see {@link DAY_MAX}
+ * @see {@link assertDay}
+ * @public
+ */
+declare const DAY_MIN = 1n;
+/**
+ * Maximum valid day value (inclusive).
+ *
+ * @remarks
+ * Set to 31 to accommodate all months. Month-specific validation (e.g., February having at most
+ * 28 or 29 days) is not enforced here and must be handled at the application level if needed.
+ *
+ * @see {@link DAY_MIN}
+ * @see {@link assertDay}
+ * @public
+ */
+declare const DAY_MAX = 31n;
+/**
+ * Minimum valid hour value (inclusive), in 24-hour format.
+ *
+ * @see {@link HOUR_MAX}
+ * @see {@link assertHour}
+ * @public
+ */
+declare const HOUR_MIN = 0n;
+/**
+ * Maximum valid hour value (inclusive), in 24-hour format.
+ *
+ * @see {@link HOUR_MIN}
+ * @see {@link assertHour}
+ * @public
+ */
+declare const HOUR_MAX = 23n;
+/**
+ * Minimum valid minute value (inclusive).
+ *
+ * @see {@link MINUTE_MAX}
+ * @see {@link assertMinute}
+ * @public
+ */
+declare const MINUTE_MIN = 0n;
+/**
+ * Maximum valid minute value (inclusive).
+ *
+ * @see {@link MINUTE_MIN}
+ * @see {@link assertMinute}
+ * @public
+ */
+declare const MINUTE_MAX = 59n;
+/**
+ * Minimum valid second value (inclusive).
+ *
+ * @see {@link SECOND_MAX}
+ * @see {@link assertSecond}
+ * @public
+ */
+declare const SECOND_MIN = 0n;
+/**
+ * Maximum valid second value (inclusive).
+ *
+ * @remarks Leap seconds (value 60) are not supported.
+ * @see {@link SECOND_MIN}
+ * @see {@link assertSecond}
+ * @public
+ */
+declare const SECOND_MAX = 59n;
+/**
+ * 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
+ * Every `assertXxx` function in this module throws `TemporalAssertionError` on failure.
+ * Catch this specific type to distinguish temporal validation failures from other 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}`);
+ *     }
+ * }
+ * ```
+ *
+ * @sealed
+ * @public
+ */
+declare class TemporalAssertionError extends Error {
+    /**
+     * The actual value that failed the assertion.
+     * @readonly
+     */
+    readonly value: unknown;
+    /**
+     * The type that was expected (e.g., `"Month"`, `"Hour"`).
+     * @readonly
+     */
+    readonly expectedType: string;
+    /**
+     * Description of the constraint that was violated.
+     *
+     * @remarks
+     * `undefined` when the failure was a type mismatch (e.g., received a number instead of a
+     * bigint). Contains a human-readable range string (e.g., `"1 <= value <= 12"`) when the
+     * value was the correct type but out of the valid range.
+     * @readonly
+     */
+    readonly constraint: string | undefined;
+    /**
+     * Creates a new TemporalAssertionError.
+     *
+     * @param message - Human-readable description of what went wrong
+     * @param details - Structured error details for programmatic inspection
+     * @param details.value - The value that failed the assertion
+     * @param details.expectedType - Name of the branded type that was expected
+     * @param details.constraint - Optional human-readable constraint that was violated
+     */
+    constructor(message: string, details: {
+        value: unknown;
+        expectedType: string;
+        constraint?: string;
+    });
+}
+/**
+ * Base branded type for all timestamp components.
+ *
+ * `TimestampComponent` is a branded bigint that serves as the parent type for all
+ * calendar-component types: `Year`, `Month`, `Day`, `Hour`, `Minute`, and `Second`.
+ *
+ * @remarks
+ * All timestamp component types are subbrands of `TimestampComponent`. Code that accepts
+ * any calendar component without caring which one (e.g., a generic key-derivation utility)
+ * can accept `TimestampComponent` as its parameter type.
+ *
+ * @example
+ * ```typescript
+ * import { TimestampComponent, assertTimestampComponent } from "./temporal";
+ *
+ * const value: bigint = 2024n;
+ * assertTimestampComponent(value);
+ * // Now value is typed as TimestampComponent
+ * ```
+ *
+ * @see {@link Year}
+ * @see {@link Month}
+ * @see {@link Day}
+ * @see {@link Hour}
+ * @see {@link Minute}
+ * @see {@link Second}
+ * @public
+ */
+type TimestampComponent = BrandedType<bigint, "TimestampComponent">;
+/**
+ * Asserts that a value is a valid TimestampComponent (non-negative bigint).
+ *
+ * @param value - The bigint to validate (must be `>= 0`)
+ * @throws {TemporalAssertionError} If value is not a bigint or is negative
+ * @returns `void` — narrows the type of `value` to `TimestampComponent` on success
+ *
+ * @example
+ * ```typescript
+ * const value = 100n;
+ * assertTimestampComponent(value);
+ * // value is now typed as TimestampComponent
+ * ```
+ *
+ * @public
+ */
+declare function assertTimestampComponent(value: bigint): asserts value is TimestampComponent;
+/**
+ * Branded type for year values in the Gregorian calendar.
+ *
+ * `Year` is a subbrand of `TimestampComponent` used to represent the year component of a
+ * UTC timestamp in time-scoped viewing key derivation. Valid range: `YEAR_MIN` (0) to
+ * `YEAR_MAX` (9999).
+ *
+ * @remarks
+ * The type distinction between `Year`, `Month`, `Day`, etc. is intentional: passing
+ * a `Month` value where a `Year` is expected is a compile-time error, preventing
+ * subtle key-derivation bugs.
+ *
+ * @example
+ * ```typescript
+ * import { Year, assertYear } from "./temporal";
+ *
+ * const year: bigint = 2024n;
+ * assertYear(year);
+ * // year is now typed as Year
+ *
+ * const generator = getYearlyViewingKeyGenerator({ masterViewingKey });
+ * const key = await generator(mint, year);
+ * ```
+ *
+ * @see {@link assertYear}
+ * @see {@link YEAR_MIN}
+ * @see {@link YEAR_MAX}
+ * @public
+ */
+type Year = SubBrandedType<TimestampComponent, "Year">;
+/**
+ * Asserts that a value is a valid `Year` in the range `[YEAR_MIN, YEAR_MAX]` (0–9999).
+ *
+ * @param value - The bigint to validate
+ * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[YEAR_MIN, YEAR_MAX]`
+ * @returns `void` — narrows the type of `value` to `Year` on success
+ *
+ * @example
+ * ```typescript
+ * const year = 2024n;
+ * assertYear(year);
+ * // year is now typed as Year
+ * ```
+ *
+ * @public
+ */
+declare function assertYear(value: bigint): asserts value is Year;
+/**
+ * Branded type for month values in the Gregorian calendar (1 = January, 12 = December).
+ *
+ * `Month` is a subbrand of `TimestampComponent`. Valid range: `MONTH_MIN` (1) to
+ * `MONTH_MAX` (12).
+ *
+ * @example
+ * ```typescript
+ * import { Month, assertMonth } from "./temporal";
+ *
+ * const month: bigint = 6n; // June
+ * assertMonth(month);
+ * // month is now typed as Month
+ * ```
+ *
+ * @see {@link assertMonth}
+ * @see {@link MONTH_MIN}
+ * @see {@link MONTH_MAX}
+ * @public
+ */
+type Month = SubBrandedType<TimestampComponent, "Month">;
+/**
+ * Asserts that a value is a valid `Month` in the range `[MONTH_MIN, MONTH_MAX]` (1–12).
+ *
+ * @param value - The bigint to validate
+ * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[MONTH_MIN, MONTH_MAX]`
+ * @returns `void` — narrows the type of `value` to `Month` on success
+ *
+ * @example
+ * ```typescript
+ * const month = 6n;
+ * assertMonth(month);
+ * // month is now typed as Month
+ * ```
+ *
+ * @public
+ */
+declare function assertMonth(value: bigint): asserts value is Month;
+/**
+ * Branded type for day-of-month values in the Gregorian calendar.
+ *
+ * `Day` is a subbrand of `TimestampComponent`. Valid range: `DAY_MIN` (1) to `DAY_MAX` (31).
+ *
+ * @remarks
+ * This type does not enforce month-specific day limits (e.g., February has 28 or 29 days).
+ * Additional calendar validation must be performed by the application if required.
+ *
+ * @example
+ * ```typescript
+ * import { Day, assertDay } from "./temporal";
+ *
+ * const day: bigint = 15n;
+ * assertDay(day);
+ * // day is now typed as Day
+ * ```
+ *
+ * @see {@link assertDay}
+ * @see {@link DAY_MIN}
+ * @see {@link DAY_MAX}
+ * @public
+ */
+type Day = SubBrandedType<TimestampComponent, "Day">;
+/**
+ * Asserts that a value is a valid `Day` in the range `[DAY_MIN, DAY_MAX]` (1–31).
+ *
+ * @param value - The bigint to validate
+ * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[DAY_MIN, DAY_MAX]`
+ * @returns `void` — narrows the type of `value` to `Day` on success
+ *
+ * @example
+ * ```typescript
+ * const day = 15n;
+ * assertDay(day);
+ * // day is now typed as Day
+ * ```
+ *
+ * @public
+ */
+declare function assertDay(value: bigint): asserts value is Day;
+/**
+ * Branded type for hour-of-day values in 24-hour format.
+ *
+ * `Hour` is a subbrand of `TimestampComponent`. Valid range: `HOUR_MIN` (0) to `HOUR_MAX` (23).
+ *
+ * @remarks
+ * Uses 24-hour clock convention: midnight is 0, noon is 12, and 11 PM is 23.
+ *
+ * @example
+ * ```typescript
+ * import { Hour, assertHour } from "./temporal";
+ *
+ * const hour: bigint = 14n; // 2 PM
+ * assertHour(hour);
+ * // hour is now typed as Hour
+ * ```
+ *
+ * @see {@link assertHour}
+ * @see {@link HOUR_MIN}
+ * @see {@link HOUR_MAX}
+ * @public
+ */
+type Hour = SubBrandedType<TimestampComponent, "Hour">;
+/**
+ * Asserts that a value is a valid `Hour` in the range `[HOUR_MIN, HOUR_MAX]` (0–23).
+ *
+ * @param value - The bigint to validate
+ * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[HOUR_MIN, HOUR_MAX]`
+ * @returns `void` — narrows the type of `value` to `Hour` on success
+ *
+ * @example
+ * ```typescript
+ * const hour = 14n;
+ * assertHour(hour);
+ * // hour is now typed as Hour
+ * ```
+ *
+ * @public
+ */
+declare function assertHour(value: bigint): asserts value is Hour;
+/**
+ * Branded type for minute-of-hour values.
+ *
+ * `Minute` is a subbrand of `TimestampComponent`. Valid range: `MINUTE_MIN` (0) to
+ * `MINUTE_MAX` (59).
+ *
+ * @example
+ * ```typescript
+ * import { Minute, assertMinute } from "./temporal";
+ *
+ * const minute: bigint = 30n;
+ * assertMinute(minute);
+ * // minute is now typed as Minute
+ * ```
+ *
+ * @see {@link assertMinute}
+ * @see {@link MINUTE_MIN}
+ * @see {@link MINUTE_MAX}
+ * @public
+ */
+type Minute = SubBrandedType<TimestampComponent, "Minute">;
+/**
+ * Asserts that a value is a valid `Minute` in the range `[MINUTE_MIN, MINUTE_MAX]` (0–59).
+ *
+ * @param value - The bigint to validate
+ * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[MINUTE_MIN, MINUTE_MAX]`
+ * @returns `void` — narrows the type of `value` to `Minute` on success
+ *
+ * @example
+ * ```typescript
+ * const minute = 30n;
+ * assertMinute(minute);
+ * // minute is now typed as Minute
+ * ```
+ *
+ * @public
+ */
+declare function assertMinute(value: bigint): asserts value is Minute;
+/**
+ * Branded type for second-of-minute values.
+ *
+ * `Second` is a subbrand of `TimestampComponent`. Valid range: `SECOND_MIN` (0) to
+ * `SECOND_MAX` (59). Leap seconds (value 60) are not supported.
+ *
+ * @example
+ * ```typescript
+ * import { Second, assertSecond } from "./temporal";
+ *
+ * const second: bigint = 45n;
+ * assertSecond(second);
+ * // second is now typed as Second
+ * ```
+ *
+ * @see {@link assertSecond}
+ * @see {@link SECOND_MIN}
+ * @see {@link SECOND_MAX}
+ * @public
+ */
+type Second = SubBrandedType<TimestampComponent, "Second">;
+/**
+ * Asserts that a value is a valid `Second` in the range `[SECOND_MIN, SECOND_MAX]` (0–59).
+ *
+ * @param value - The bigint to validate
+ * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[SECOND_MIN, SECOND_MAX]`
+ * @returns `void` — narrows the type of `value` to `Second` on success
+ *
+ * @example
+ * ```typescript
+ * const second = 45n;
+ * assertSecond(second);
+ * // second is now typed as Second
+ * ```
+ *
+ * @public
+ */
+declare function assertSecond(value: bigint): asserts value is Second;
+
+export { type Day as D, type Hour as H, type Month as M, type Second as S, TemporalAssertionError as T, type Year as Y, type Minute as a, DAY_MAX as b, DAY_MIN as c, HOUR_MAX as d, HOUR_MIN as e, MINUTE_MAX as f, MINUTE_MIN as g, MONTH_MAX as h, MONTH_MIN as i, SECOND_MAX as j, SECOND_MIN as k, type TimestampComponent as l, YEAR_MAX as m, YEAR_MIN as n, assertDay as o, assertHour as p, assertMinute as q, assertMonth as r, assertSecond as s, assertTimestampComponent as t, assertYear as u };