/**
 * Time utilities.
 *
 * Instants are persisted and compared as UTC. Calendar input and human-facing
 * output use one display timezone: config.yaml `timezone`, else NIUBOT_TZ, else Asia/Shanghai.
 */
export declare const DEFAULT_TIMEZONE = "Asia/Shanghai";
/** Current display timezone (IANA name). */
export declare let TZ: string;
export declare function isValidTimeZone(timezone: string): boolean;
/** Resolve IANA names, aliases, or a short natural-language phrase. */
export declare function normalizeTimeZoneInput(raw: string): string | undefined;
/** True for utterances like「帮我改成北京时区」「改成北京时间」— not `/tz` itself. */
export declare function isTimezoneChangeUtterance(text: string): boolean;
/** Host IANA timezone: process TZ, else the OS zone from Intl. */
export declare function resolveSystemTimeZone(): string;
/** `/tz` args the builtin can handle locally. Unknown names should fall through to the agent. */
export declare function timezoneCommandIsResolved(args: string[]): boolean;
export declare function setDisplayTimezone(timezone: string): void;
/** Startup: config.yaml (from /tz) wins, then NIUBOT_TZ, then Beijing. */
export declare function applyDisplayTimezone(options?: {
    env?: string;
    config?: string;
}): string;
export interface ZonedDateTimeParts {
    year: number;
    month: number;
    day: number;
    hour: number;
    minute: number;
    second: number;
}
export interface UtcTimeRange {
    since?: string;
    before?: string;
}
/** Get a Date's calendar fields in an IANA timezone. */
export declare function getZonedDateTimeParts(date: Date, timeZone?: string): ZonedDateTimeParts;
/** Format a Date as YYYY-MM-DD in an IANA timezone. */
export declare function dateInTimeZone(date?: Date, timeZone?: string): string;
/** Format a Date as YYYY-MM-DD HH:MM:SS in an IANA timezone. */
export declare function dateTimeInTimeZone(date?: Date, timeZone?: string): string;
/** Get today's date (YYYY-MM-DD) in the configured timezone. */
export declare function localToday(): string;
/** Get yesterday's date (YYYY-MM-DD) in the configured timezone. */
export declare function localYesterday(): string;
/** Convert a UTC datetime from DB to HH:MM in an IANA timezone. */
export declare function utcToLocalHHMM(utcDatetime: string, timeZone?: string): string;
/** Convert a UTC datetime from DB to YYYY-MM-DD HH:MM in an IANA timezone. */
export declare function utcToLocalDateTime(utcDatetime: string, timeZone?: string): string;
/** Convert a UTC datetime from DB to local display text with timezone label. */
export declare function formatLocalDateTimeWithTZ(utcDatetime: string, timeZone?: string): string;
/** Label an already-local datetime string with an IANA timezone. */
export declare function labelLocalDateTime(localDatetime: string, timeZone?: string): string;
/** Label a cron expression or schedule as using local calendar time. */
export declare function labelLocalTime(text: string, timeZone?: string): string;
/** Format a Date as canonical UTC YYYY-MM-DD HH:MM:SS for SQLite. */
export declare function utcDateTimeForSql(date: Date): string;
/** Parse user date/datetime input and return canonical UTC SQLite text. */
export declare function userDateTimeToUtcSql(value: string, timeZone?: string): string;
/** Normalize optional user range boundaries to canonical UTC SQLite text. */
export declare function userTimeRangeToUtc(range: UtcTimeRange, timeZone?: string): UtcTimeRange;
/** Convert local calendar fields in an IANA timezone to an instant. */
export declare function zonedDateTimeToDate(parts: ZonedDateTimeParts, timeZone?: string): Date;
/** Get the UTC datetime string for the start of a local date. */
export declare function localDateStartUTC(localDateStr: string, timeZone?: string): string;
/** Get next day's date string (YYYY-MM-DD). */
export declare function nextDay(dateStr: string): string;
/** Return whether an ISO/UTC event timestamp is inside a half-open UTC range. */
export declare function instantIsInUtcRange(timestamp: string | undefined, range: UtcTimeRange): boolean;
/** Check a half-open local-hour window in an IANA timezone. */
export declare function isInLocalHourWindow(date: Date, startHour: number, endHour: number, timeZone?: string): boolean;
/** Get milliseconds until the next occurrence of a local hour. */
export declare function millisecondsUntilLocalHour(date: Date, hour: number, timeZone?: string): number;
/** Get the current SQLite offset modifier. Prefer application-side conversion for historical dates. */
export declare function sqlTZModifier(): string;
/** Parse a canonical UTC DB timestamp or an ISO timestamp with explicit zone. */
export declare function parseInstant(value: string): Date;