@umbra-privacy/sdk 1.0.0

package/dist/index-CLj_zWSD.d.ts

@@ -0,0 +1,235 @@
+import { Y as Year, M as Month, D as Day, H as Hour, a as Minute, S as Second } from './types-n-sHFcgr.js';
+
+/**
+ * Temporal Utilities
+ *
+ * This module provides utility functions for working with UTC timestamps
+ * and extracting calendar components. These utilities are used for
+ * time-scoped viewing key derivation and other temporal operations.
+ *
+ * @remarks
+ * All functions in this module work exclusively with UTC timestamps to ensure consistent
+ * key derivation regardless of the local timezone of the machine running the SDK.
+ *
+ * The dependency-injection pattern (`getUtcNowFunction`, `getExtractUtcComponentsFunction`)
+ * allows tests to inject a fixed `dateProvider` so that time-based key derivation is
+ * deterministic in test environments.
+ *
+ * @packageDocumentation
+ * @module common/temporal
+ */
+
+/**
+ * UTC timestamp components decomposed into individually branded fields.
+ *
+ * Contains all six calendar components extracted from a UTC timestamp. Each field is
+ * a branded type that enforces the correct range at compile time and runtime.
+ *
+ * @remarks
+ * This interface is produced by `extractUtcComponents` and `getUtcNow`. It is consumed
+ * by time-scoped viewing key derivation functions to select the correct time granularity
+ * (yearly, monthly, daily, etc.).
+ *
+ * @example
+ * ```typescript
+ * const now: UtcTimestampComponents = getUtcNow();
+ * // now.year is a Year, now.month is a Month, etc.
+ * const yearKey = deriveYearlyViewingKey(masterViewingKey, now.year);
+ * ```
+ *
+ * @see {@link extractUtcComponents}
+ * @see {@link getUtcNow}
+ * @public
+ */
+interface UtcTimestampComponents {
+    /**
+     * The year component in the range [0, 9999].
+     * @see {@link Year}
+     */
+    year: Year;
+    /**
+     * The month component in the range [1, 12] (1 = January, 12 = December).
+     * @see {@link Month}
+     */
+    month: Month;
+    /**
+     * The day-of-month component in the range [1, 31].
+     * @see {@link Day}
+     */
+    day: Day;
+    /**
+     * The hour component in 24-hour format, in the range [0, 23].
+     * @see {@link Hour}
+     */
+    hour: Hour;
+    /**
+     * The minute component in the range [0, 59].
+     * @see {@link Minute}
+     */
+    minute: Minute;
+    /**
+     * The second component in the range [0, 59].
+     * @see {@link Second}
+     */
+    second: Second;
+}
+/**
+ * Function type for getting the current UTC timestamp components.
+ *
+ * @remarks
+ * Implementations should return the current moment in UTC. The default implementation calls
+ * `new Date()`, but tests can substitute a fixed-time provider via `getUtcNowFunction`.
+ *
+ * @returns The current UTC timestamp decomposed into branded calendar components
+ *
+ * @see {@link getUtcNowFunction}
+ * @see {@link defaultGetUtcNow}
+ * @public
+ */
+type GetUtcNowFunction = () => UtcTimestampComponents;
+/**
+ * Function type for extracting UTC components from a `Date` object.
+ *
+ * @remarks
+ * Useful when working with a specific historical timestamp rather than the current time.
+ *
+ * @param date - A JavaScript `Date` object (any timezone; UTC getters are always used)
+ * @returns The timestamp decomposed into branded UTC calendar components
+ *
+ * @see {@link getExtractUtcComponentsFunction}
+ * @see {@link defaultExtractUtcComponents}
+ * @public
+ */
+type ExtractUtcComponentsFunction = (date: Date) => UtcTimestampComponents;
+/**
+ * Extracts UTC timestamp components from a `Date` object.
+ *
+ * @remarks
+ * All calendar components are extracted using the `getUTC*` family of methods, so the
+ * result is independent of the local timezone setting of the host machine.
+ *
+ * Month is adjusted from the 0-indexed `Date.getUTCMonth()` (0–11) to the 1-indexed
+ * `Month` branded type (1–12).
+ *
+ * @param date - The `Date` object to extract components from
+ * @returns The six UTC calendar components as branded `UtcTimestampComponents`
+ * @throws {TemporalAssertionError} If any extracted component is out of range (should not
+ *   occur with valid `Date` objects produced by the JavaScript runtime)
+ *
+ * @example
+ * ```typescript
+ * const date = new Date('2024-06-15T14:30:45Z');
+ * const components = extractUtcComponents(date);
+ * // { year: 2024n, month: 6n, day: 15n, hour: 14n, minute: 30n, second: 45n }
+ * ```
+ *
+ * @see {@link UtcTimestampComponents}
+ * @see {@link getUtcNow}
+ * @public
+ */
+declare function extractUtcComponents(date: Date): UtcTimestampComponents;
+/**
+ * Gets the current UTC timestamp components.
+ *
+ * @remarks
+ * Equivalent to calling `extractUtcComponents(new Date())`. Provided as a convenience
+ * function for the common case of deriving keys for the current moment.
+ *
+ * @returns The current UTC timestamp decomposed into branded calendar components
+ *
+ * @example
+ * ```typescript
+ * const now = getUtcNow();
+ * console.log(`Current UTC: ${now.year}-${now.month}-${now.day} ${now.hour}:${now.minute}:${now.second}`);
+ * ```
+ *
+ * @see {@link extractUtcComponents}
+ * @see {@link defaultGetUtcNow}
+ * @public
+ */
+declare function getUtcNow(): UtcTimestampComponents;
+/**
+ * Creates a UTC timestamp components getter with optional dependency injection.
+ *
+ * @remarks
+ * Use this factory when you need to inject a custom date source for testing or for
+ * deterministic key derivation in non-interactive scripts. The returned function captures
+ * `dateProvider` in its closure.
+ *
+ * @param deps - Optional dependency overrides
+ * @param deps.dateProvider - A zero-argument function returning the current `Date`. Defaults
+ *   to `() => new Date()`.
+ * @defaultValue `deps` — `undefined` (uses real system clock)
+ * @returns A `GetUtcNowFunction` that calls `dateProvider` on each invocation
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const getUtc = getUtcNowFunction();
+ * const now = getUtc();
+ *
+ * // With custom date provider (for testing)
+ * const getUtc = getUtcNowFunction({
+ *   dateProvider: () => new Date('2024-06-15T14:30:45Z')
+ * });
+ * const fixedTime = getUtc();
+ * ```
+ *
+ * @see {@link GetUtcNowFunction}
+ * @see {@link defaultGetUtcNow}
+ * @public
+ */
+declare function getUtcNowFunction(deps?: {
+    dateProvider?: () => Date;
+}): GetUtcNowFunction;
+/**
+ * Creates an extractor function for UTC components with optional dependency injection.
+ *
+ * @remarks
+ * Currently a pass-through to `extractUtcComponents`. The `deps` parameter is reserved
+ * for future use (e.g., injecting a custom calendar implementation). Prefer
+ * `defaultExtractUtcComponents` unless you need the factory pattern for consistency with
+ * other injectable utilities in the SDK.
+ *
+ * @param deps - Reserved for future dependency overrides; currently unused
+ * @returns An `ExtractUtcComponentsFunction` backed by the built-in `extractUtcComponents`
+ *
+ * @example
+ * ```typescript
+ * const extract = getExtractUtcComponentsFunction();
+ * const components = extract(new Date());
+ * ```
+ *
+ * @see {@link ExtractUtcComponentsFunction}
+ * @see {@link defaultExtractUtcComponents}
+ * @public
+ */
+declare function getExtractUtcComponentsFunction(deps?: Record<string, never>): ExtractUtcComponentsFunction;
+/**
+ * Default `GetUtcNowFunction` using the real system clock.
+ *
+ * @remarks
+ * This is the pre-built instance of `getUtcNowFunction()` for use throughout the SDK.
+ * Pass `defaultGetUtcNow` as the `getUtcNow` dependency when constructing SDK services
+ * in production. Substitute a custom function in tests.
+ *
+ * @see {@link GetUtcNowFunction}
+ * @see {@link getUtcNowFunction}
+ * @public
+ */
+declare const defaultGetUtcNow: GetUtcNowFunction;
+/**
+ * Default `ExtractUtcComponentsFunction` backed by `extractUtcComponents`.
+ *
+ * @remarks
+ * This is the pre-built instance for use throughout the SDK when an
+ * `ExtractUtcComponentsFunction` is required. Equivalent to calling
+ * `getExtractUtcComponentsFunction()` with no arguments.
+ *
+ * @see {@link ExtractUtcComponentsFunction}
+ * @see {@link getExtractUtcComponentsFunction}
+ * @public
+ */
+declare const defaultExtractUtcComponents: ExtractUtcComponentsFunction;
+
+export { type ExtractUtcComponentsFunction as E, type GetUtcNowFunction as G, type UtcTimestampComponents as U, defaultGetUtcNow as a, getUtcNow as b, getUtcNowFunction as c, defaultExtractUtcComponents as d, extractUtcComponents as e, getExtractUtcComponentsFunction as g };

package/dist/index-CX6_pIRS.d.cts

@@ -0,0 +1,235 @@
+import { Y as Year, M as Month, D as Day, H as Hour, a as Minute, S as Second } from './types-BBuELtY8.cjs';
+
+/**
+ * Temporal Utilities
+ *
+ * This module provides utility functions for working with UTC timestamps
+ * and extracting calendar components. These utilities are used for
+ * time-scoped viewing key derivation and other temporal operations.
+ *
+ * @remarks
+ * All functions in this module work exclusively with UTC timestamps to ensure consistent
+ * key derivation regardless of the local timezone of the machine running the SDK.
+ *
+ * The dependency-injection pattern (`getUtcNowFunction`, `getExtractUtcComponentsFunction`)
+ * allows tests to inject a fixed `dateProvider` so that time-based key derivation is
+ * deterministic in test environments.
+ *
+ * @packageDocumentation
+ * @module common/temporal
+ */
+
+/**
+ * UTC timestamp components decomposed into individually branded fields.
+ *
+ * Contains all six calendar components extracted from a UTC timestamp. Each field is
+ * a branded type that enforces the correct range at compile time and runtime.
+ *
+ * @remarks
+ * This interface is produced by `extractUtcComponents` and `getUtcNow`. It is consumed
+ * by time-scoped viewing key derivation functions to select the correct time granularity
+ * (yearly, monthly, daily, etc.).
+ *
+ * @example
+ * ```typescript
+ * const now: UtcTimestampComponents = getUtcNow();
+ * // now.year is a Year, now.month is a Month, etc.
+ * const yearKey = deriveYearlyViewingKey(masterViewingKey, now.year);
+ * ```
+ *
+ * @see {@link extractUtcComponents}
+ * @see {@link getUtcNow}
+ * @public
+ */
+interface UtcTimestampComponents {
+    /**
+     * The year component in the range [0, 9999].
+     * @see {@link Year}
+     */
+    year: Year;
+    /**
+     * The month component in the range [1, 12] (1 = January, 12 = December).
+     * @see {@link Month}
+     */
+    month: Month;
+    /**
+     * The day-of-month component in the range [1, 31].
+     * @see {@link Day}
+     */
+    day: Day;
+    /**
+     * The hour component in 24-hour format, in the range [0, 23].
+     * @see {@link Hour}
+     */
+    hour: Hour;
+    /**
+     * The minute component in the range [0, 59].
+     * @see {@link Minute}
+     */
+    minute: Minute;
+    /**
+     * The second component in the range [0, 59].
+     * @see {@link Second}
+     */
+    second: Second;
+}
+/**
+ * Function type for getting the current UTC timestamp components.
+ *
+ * @remarks
+ * Implementations should return the current moment in UTC. The default implementation calls
+ * `new Date()`, but tests can substitute a fixed-time provider via `getUtcNowFunction`.
+ *
+ * @returns The current UTC timestamp decomposed into branded calendar components
+ *
+ * @see {@link getUtcNowFunction}
+ * @see {@link defaultGetUtcNow}
+ * @public
+ */
+type GetUtcNowFunction = () => UtcTimestampComponents;
+/**
+ * Function type for extracting UTC components from a `Date` object.
+ *
+ * @remarks
+ * Useful when working with a specific historical timestamp rather than the current time.
+ *
+ * @param date - A JavaScript `Date` object (any timezone; UTC getters are always used)
+ * @returns The timestamp decomposed into branded UTC calendar components
+ *
+ * @see {@link getExtractUtcComponentsFunction}
+ * @see {@link defaultExtractUtcComponents}
+ * @public
+ */
+type ExtractUtcComponentsFunction = (date: Date) => UtcTimestampComponents;
+/**
+ * Extracts UTC timestamp components from a `Date` object.
+ *
+ * @remarks
+ * All calendar components are extracted using the `getUTC*` family of methods, so the
+ * result is independent of the local timezone setting of the host machine.
+ *
+ * Month is adjusted from the 0-indexed `Date.getUTCMonth()` (0–11) to the 1-indexed
+ * `Month` branded type (1–12).
+ *
+ * @param date - The `Date` object to extract components from
+ * @returns The six UTC calendar components as branded `UtcTimestampComponents`
+ * @throws {TemporalAssertionError} If any extracted component is out of range (should not
+ *   occur with valid `Date` objects produced by the JavaScript runtime)
+ *
+ * @example
+ * ```typescript
+ * const date = new Date('2024-06-15T14:30:45Z');
+ * const components = extractUtcComponents(date);
+ * // { year: 2024n, month: 6n, day: 15n, hour: 14n, minute: 30n, second: 45n }
+ * ```
+ *
+ * @see {@link UtcTimestampComponents}
+ * @see {@link getUtcNow}
+ * @public
+ */
+declare function extractUtcComponents(date: Date): UtcTimestampComponents;
+/**
+ * Gets the current UTC timestamp components.
+ *
+ * @remarks
+ * Equivalent to calling `extractUtcComponents(new Date())`. Provided as a convenience
+ * function for the common case of deriving keys for the current moment.
+ *
+ * @returns The current UTC timestamp decomposed into branded calendar components
+ *
+ * @example
+ * ```typescript
+ * const now = getUtcNow();
+ * console.log(`Current UTC: ${now.year}-${now.month}-${now.day} ${now.hour}:${now.minute}:${now.second}`);
+ * ```
+ *
+ * @see {@link extractUtcComponents}
+ * @see {@link defaultGetUtcNow}
+ * @public
+ */
+declare function getUtcNow(): UtcTimestampComponents;
+/**
+ * Creates a UTC timestamp components getter with optional dependency injection.
+ *
+ * @remarks
+ * Use this factory when you need to inject a custom date source for testing or for
+ * deterministic key derivation in non-interactive scripts. The returned function captures
+ * `dateProvider` in its closure.
+ *
+ * @param deps - Optional dependency overrides
+ * @param deps.dateProvider - A zero-argument function returning the current `Date`. Defaults
+ *   to `() => new Date()`.
+ * @defaultValue `deps` — `undefined` (uses real system clock)
+ * @returns A `GetUtcNowFunction` that calls `dateProvider` on each invocation
+ *
+ * @example
+ * ```typescript
+ * // Default usage
+ * const getUtc = getUtcNowFunction();
+ * const now = getUtc();
+ *
+ * // With custom date provider (for testing)
+ * const getUtc = getUtcNowFunction({
+ *   dateProvider: () => new Date('2024-06-15T14:30:45Z')
+ * });
+ * const fixedTime = getUtc();
+ * ```
+ *
+ * @see {@link GetUtcNowFunction}
+ * @see {@link defaultGetUtcNow}
+ * @public
+ */
+declare function getUtcNowFunction(deps?: {
+    dateProvider?: () => Date;
+}): GetUtcNowFunction;
+/**
+ * Creates an extractor function for UTC components with optional dependency injection.
+ *
+ * @remarks
+ * Currently a pass-through to `extractUtcComponents`. The `deps` parameter is reserved
+ * for future use (e.g., injecting a custom calendar implementation). Prefer
+ * `defaultExtractUtcComponents` unless you need the factory pattern for consistency with
+ * other injectable utilities in the SDK.
+ *
+ * @param deps - Reserved for future dependency overrides; currently unused
+ * @returns An `ExtractUtcComponentsFunction` backed by the built-in `extractUtcComponents`
+ *
+ * @example
+ * ```typescript
+ * const extract = getExtractUtcComponentsFunction();
+ * const components = extract(new Date());
+ * ```
+ *
+ * @see {@link ExtractUtcComponentsFunction}
+ * @see {@link defaultExtractUtcComponents}
+ * @public
+ */
+declare function getExtractUtcComponentsFunction(deps?: Record<string, never>): ExtractUtcComponentsFunction;
+/**
+ * Default `GetUtcNowFunction` using the real system clock.
+ *
+ * @remarks
+ * This is the pre-built instance of `getUtcNowFunction()` for use throughout the SDK.
+ * Pass `defaultGetUtcNow` as the `getUtcNow` dependency when constructing SDK services
+ * in production. Substitute a custom function in tests.
+ *
+ * @see {@link GetUtcNowFunction}
+ * @see {@link getUtcNowFunction}
+ * @public
+ */
+declare const defaultGetUtcNow: GetUtcNowFunction;
+/**
+ * Default `ExtractUtcComponentsFunction` backed by `extractUtcComponents`.
+ *
+ * @remarks
+ * This is the pre-built instance for use throughout the SDK when an
+ * `ExtractUtcComponentsFunction` is required. Equivalent to calling
+ * `getExtractUtcComponentsFunction()` with no arguments.
+ *
+ * @see {@link ExtractUtcComponentsFunction}
+ * @see {@link getExtractUtcComponentsFunction}
+ * @public
+ */
+declare const defaultExtractUtcComponents: ExtractUtcComponentsFunction;
+
+export { type ExtractUtcComponentsFunction as E, type GetUtcNowFunction as G, type UtcTimestampComponents as U, defaultGetUtcNow as a, getUtcNow as b, getUtcNowFunction as c, defaultExtractUtcComponents as d, extractUtcComponents as e, getExtractUtcComponentsFunction as g };