import { type Maybe, type Milliseconds, type Minutes, type TimezoneString } from '@dereekb/util';
import { type ICalendar, type ICalendarDateTimeValue, type ICalendarTimezone, type ICalendarTimezoneTransition } from './icalendar.model';
/**
 * Configuration for deriving a {@link ICalendarTimezone} over a bounded window.
 */
export interface ICalendarTimezoneForRangeConfig {
    /**
     * The IANA zone to derive. I.E. "America/Denver".
     */
    readonly timezone: TimezoneString;
    /**
     * First instant covered by the derived VTIMEZONE.
     */
    readonly start: Date;
    /**
     * Last instant covered by the derived VTIMEZONE.
     */
    readonly end: Date;
}
/**
 * Interval between offset probes when scanning a window for transitions.
 *
 * A zone never changes its offset twice within a single day, so a daily probe cannot miss a transition; the
 * exact instant is then recovered by bisecting the bracketing day.
 */
export declare const ICALENDAR_TIMEZONE_PROBE_INTERVAL: Milliseconds;
/**
 * Derives every UTC-offset transition a zone undergoes within the given window.
 *
 * IANA transition rules are not available from any dependency in this package, so they are discovered
 * empirically: the window is probed daily for an offset change, and each detected change is bisected down to
 * the millisecond. The result is a bare list of observances, which is what RFC 5545 3.6.5 requires (only
 * DTSTART, TZOFFSETFROM and TZOFFSETTO are mandatory) and what Apple and Exchange actually emit — no IANA
 * rule has to be reverse-engineered into RRULE form.
 *
 * The first entry is always the observance already in effect at the start of the window.
 *
 * @param config - The zone and window to scan.
 * @returns The transitions, in chronological order. Always at least one.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function iCalendarTimezoneTransitionsForRange(config: ICalendarTimezoneForRangeConfig): readonly ICalendarTimezoneTransition[];
/**
 * Derives a {@link ICalendarTimezone} for the given zone and window.
 *
 * @param config - The zone and window to scan.
 * @returns The VTIMEZONE model.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function iCalendarTimezoneForRange(config: ICalendarTimezoneForRangeConfig): ICalendarTimezone;
/**
 * Returns every date-time value the calendar's events carry.
 *
 * @param calendar - The calendar to inspect.
 * @returns The values, in event order.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function iCalendarDateTimeValues(calendar: ICalendar): readonly ICalendarDateTimeValue[];
/**
 * Returns the distinct TZIDs referenced by the calendar's events.
 *
 * @param calendar - The calendar to inspect.
 * @returns The referenced zones, in first-seen order.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function iCalendarReferencedTimezones(calendar: ICalendar): readonly TimezoneString[];
/**
 * Configuration for {@link iCalendarWithDerivedTimezones}.
 */
export interface ICalendarWithDerivedTimezonesConfig {
    /**
     * Number of minutes to extend the derived window on each side of the events' own range.
     *
     * Defaults to {@link ICALENDAR_DERIVED_TIMEZONE_PADDING}, so a feed whose events sit inside one observance
     * still carries the neighbouring transitions.
     */
    readonly padding?: Maybe<Minutes>;
}
/**
 * Default padding applied on each side of the derived VTIMEZONE window: one year.
 */
export declare const ICALENDAR_DERIVED_TIMEZONE_PADDING: Minutes;
/**
 * Returns a copy of the calendar carrying a derived VTIMEZONE for every zone its events reference.
 *
 * A zoned event is only interpretable by a client when the calendar also carries the matching VTIMEZONE, and
 * hand-writing one is error-prone, so this derives them from the events themselves. A calendar whose events
 * are all UTC or all-day is returned unchanged, since it needs no VTIMEZONE at all.
 *
 * @param calendar - The calendar to complete.
 * @param config - Optional window padding.
 * @returns The calendar, with derived timezones when any are referenced.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function iCalendarWithDerivedTimezones(calendar: ICalendar, config?: Maybe<ICalendarWithDerivedTimezonesConfig>): ICalendar;