import { Temporal } from 'temporal-polyfill';

/** DST-aware: same wall-clock time, `n` calendar days later in `timeZone`. */
export declare const addDays: (value: InstantInput, n: number, timeZone: string) => Temporal.Instant;

/** DST-UNAWARE: exactly `n × 3600` seconds later. No zone — an instant offset. */
export declare const addHours: (value: InstantInput, n: number) => Temporal.Instant;

/** DST-aware: same wall-clock time, `n` calendar months later in `timeZone`
 *  (clamps to the last day of a shorter month per Temporal's default). */
export declare const addMonths: (value: InstantInput, n: number, timeZone: string) => Temporal.Instant;

/** Throw unless `timeZone` is a valid IANA name. Storage rule: validate on
 *  input, never store an unverified zone string. */
export declare const assertTimeZone: (timeZone: string) => string;

/** The last-resort fallback. UTC is always valid and never surprising. */
export declare const DEFAULT_TIME_ZONE = "UTC";

/** Last instant (23:59:59.999999999) of the local day in `timeZone`. */
export declare const endOfDay: (value: InstantInput, timeZone: string) => Temporal.Instant;

/** Date only, in `timeZone`. Default `dateStyle: 'medium'`. */
export declare const formatDate: (value: InstantInput, timeZone: string, options?: FormatOptions) => string;

/** Date + time, in `timeZone`. Default `dateStyle`/`timeStyle: 'medium'`. */
export declare const formatDateTime: (value: InstantInput, timeZone: string, options?: FormatOptions) => string;

/** Options common to the absolute formatters: an explicit `locale` plus any
 *  `Intl.DateTimeFormatOptions` override (a `timeZone` in here wins over the
 *  positional `timeZone` argument). */
export declare type FormatOptions = {
    readonly locale?: string;
} & Intl.DateTimeFormatOptions;

/**
 * "3 hours ago", "in 2 days". Picks the largest unit that fits the signed
 * distance between `value` and `now` (default: the current instant). This
 * is zone-independent: it measures elapsed real time, not wall-clock days.
 */
export declare const formatRelativeTime: (value: InstantInput, options?: RelativeTimeOptions) => string;

/** Time only, in `timeZone`. Default `timeStyle: 'medium'`. */
export declare const formatTime: (value: InstantInput, timeZone: string, options?: FormatOptions) => string;

/** Bridge a JS `Date` (DB read) to a `Temporal.Instant`. */
export declare const fromDate: (date: Date) => Temporal.Instant;

/** Parse an ISO-8601 instant (offset / `Z` required). Alias: `parseISO`. */
export declare const instant: (iso: string) => Temporal.Instant;

/** Anything that unambiguously denotes a UTC instant: a Temporal.Instant,
 *  a JS `Date` (what the DB layer produces), or an ISO-8601 string with an
 *  explicit offset / `Z`. */
export declare type InstantInput = Temporal.Instant | Date | string;

/** Is `a` strictly after `b`? Zone-independent (compares absolute instants). */
export declare const isAfter: (a: InstantInput, b: InstantInput) => boolean;

/** Is `a` strictly before `b`? Zone-independent (compares absolute instants). */
export declare const isBefore: (a: InstantInput, b: InstantInput) => boolean;

/** Do `a` and `b` fall on the same calendar day in `timeZone`? */
export declare const isSameDay: (a: InstantInput, b: InstantInput, timeZone: string) => boolean;

/** Is `timeZone` a valid IANA name this runtime knows? Uses `Intl`, which
 *  is the authority both Temporal and formatting defer to. */
export declare const isValidTimeZone: (timeZone: string) => boolean;

/** The current UTC instant. */
export declare const now: () => Temporal.Instant;

/** Parse a `YYYY-MM-DD` calendar date. */
export declare const parseDate: (iso: string) => Temporal.PlainDate;

/** Parse an ISO-8601 instant. Same as `instant`, named for parse sites. */
export declare const parseISO: (iso: string) => Temporal.Instant;

/** A calendar date with no time and no zone (birthdays, holidays, due dates). */
export declare const plainDate: (year: number, month: number, day: number) => Temporal.PlainDate;

/** Options for `formatRelativeTime`. */
export declare interface RelativeTimeOptions {
    readonly locale?: string;
    /** The instant to measure against. Defaults to "now". */
    readonly now?: InstantInput;
    readonly numeric?: Intl.RelativeTimeFormatNumeric;
    readonly style?: Intl.RelativeTimeFormatStyle;
}

/**
 * Resolve the effective IANA timezone for a request, in priority order.
 * Returns a validated IANA name, never an unchecked string; falls back to
 * `UTC` when no signal yields a known zone.
 */
export declare const resolveTimezone: (args: ResolveTimezoneArgs) => string;

export declare interface ResolveTimezoneArgs {
    /** The viewing user's stored profile timezone, if any. */
    readonly userTimeZone?: string | null;
    /** The tenant / org default timezone, if any. */
    readonly tenantTimeZone?: string | null;
    /** The browser-reported timezone (from the client), if any. */
    readonly browserTimeZone?: string | null;
}

/** First instant of the local day containing `value` in `timeZone`. */
export declare const startOfDay: (value: InstantInput, timeZone: string) => Temporal.Instant;

/** First instant of the local month containing `value` in `timeZone`. */
export declare const startOfMonth: (value: InstantInput, timeZone: string) => Temporal.Instant;

export { Temporal }

/** Bridge a `Temporal.Instant` back to a JS `Date` for storage / interop. */
export declare const toDate: (instant: Temporal.Instant) => Date;

/** Today's calendar date in `timeZone` (no clock, no zone on the result). */
export declare const today: (timeZone: string) => Temporal.PlainDate;

/**
 * Coerce a permissive instant input to a `Temporal.Instant`. This is the
 * single funnel every helper runs its input through, so callers can pass
 * the `Date` a query returned without a manual conversion.
 *
 * A string MUST carry an explicit offset or `Z` — a naive `2026-01-01T12:00`
 * has no instant and throws, by design (the whole point is no silent
 * zone-guessing).
 */
export declare const toInstant: (value: InstantInput) => Temporal.Instant;

/** Project a UTC instant into a wall-clock `ZonedDateTime` in `timeZone`. */
export declare const toTimezone: (value: InstantInput, timeZone: string) => Temporal.ZonedDateTime;

/** The canonical wire / storage form: ISO-8601 in UTC (`…Z`). */
export declare const toUTCString: (value: InstantInput) => string;

export { }