/**
 * Date literal support for profiling definition creation.
 *
 * Replaces the year-range model with ISV-compatible date literal segmentation.
 * Definitions become rolling windows that stay relevant without recreation.
 *
 * The 14 supported literals match the ISV DateLiteral.cls constants exactly.
 * See docs/knowledge/salesforce/date-literals.md for full reference.
 */
/**
 * The 14 date literals supported by the ISV DateLiteral.cls.
 * These are the ONLY literals the CLI should generate — they correspond 1:1
 * to the constants in the ISV product's DateLiteral class.
 */
export declare const SUPPORTED_DATE_LITERALS: readonly ["TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_QUARTER", "LAST_QUARTER", "THIS_YEAR", "LAST_YEAR", "N_YEARS_AGO:2", "N_YEARS_AGO:3", "LAST_N_YEARS:2", "LAST_N_YEARS:3"];
/** Type representing any supported date literal value */
export type SupportedDateLiteral = (typeof SUPPORTED_DATE_LITERALS)[number];
/**
 * Customer-facing labels for each date literal.
 * Used in definition names, descriptions, and time category display.
 */
export declare const DATE_LITERAL_LABELS: Record<SupportedDateLiteral, string>;
/**
 * Date literal tier classification.
 *
 * Each tier determines the maximum allowed depth for cascading:
 * - year: depth 0-3 (THIS_YEAR → LAST_YEAR → N_YEARS_AGO:2 → N_YEARS_AGO:3)
 * - quarter: depth 0-1 (THIS_QUARTER → LAST_QUARTER)
 * - month: depth 0-1 (THIS_MONTH → LAST_MONTH)
 * - week: depth 0-1 (THIS_WEEK → LAST_WEEK)
 * - day: depth 0-1 (TODAY → YESTERDAY)
 * - span: depth 0 only (LAST_N_YEARS:2, LAST_N_YEARS:3 combine multiple years)
 */
export type DateLiteralTier = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'span';
/** Maps each literal to its tier */
export declare const LITERAL_TIERS: Record<SupportedDateLiteral, DateLiteralTier>;
/**
 * Maximum cascade depth per tier.
 *
 * Only year-tier literals support depth > 1. Quarter, month, week, and day tiers
 * each represent a single atomic period with no comparable prior available via
 * ISV-supported literals, so depth is capped at 1 for those tiers.
 */
export declare const TIER_MAX_DEPTH: Record<DateLiteralTier, number>;
/**
 * Depth cascade arrays per literal.
 *
 * Starting from a given literal at depth 0, each subsequent depth level
 * adds the next literal in the cascade. Cascades always move backward in time.
 *
 * Example: THIS_YEAR with depth 3 → [THIS_YEAR, LAST_YEAR, N_YEARS_AGO:2]
 */
export declare const LITERAL_CASCADES: Record<SupportedDateLiteral, readonly SupportedDateLiteral[]>;
/**
 * A single entry in a resolved date literal range.
 * Analogous to ComparativeYearEntry in the year-range model.
 */
export type DateLiteralEntry = {
    /** The date literal value (e.g., 'THIS_YEAR', 'LAST_QUARTER') */
    readonly literal: SupportedDateLiteral;
    /** Customer-facing label (e.g., 'This Year', 'Last Quarter') */
    readonly label: string;
};
/**
 * A resolved date literal range for profiling definitions.
 * Analogous to YearRange in the year-range model.
 *
 * Contains the ordered list of date literal entries derived from user input
 * (--date-literal flag + --depth flag).
 */
export type DateLiteralRange = {
    /** Ordered list of date literal entries (most recent first) */
    readonly entries: readonly DateLiteralEntry[];
    /** The date field to filter on (default: CreatedDate) */
    readonly dateField: string;
};
/**
 * Raw flag inputs for date literal range resolution.
 */
export type DateLiteralInput = {
    /** The base date literal (e.g., 'THIS_YEAR') */
    dateLiteral: string;
    /** Number of periods to cascade (counting back from base) */
    depth?: number;
    /** The date field to filter on (default: CreatedDate) */
    dateField?: string;
};
/**
 * Validates a date literal value against the ISV-supported set.
 *
 * @param value - The date literal string to validate
 * @returns undefined if valid, error message string if invalid
 */
export declare function validateDateLiteral(value: string): string | undefined;
/**
 * Resolves CLI flag inputs into a validated DateLiteralRange.
 *
 * @param input - Raw flag inputs
 * @returns Resolved DateLiteralRange
 * @throws Error if inputs are invalid
 */
export declare function resolveDateLiteralRange(input: DateLiteralInput): DateLiteralRange;
/**
 * Returns the customer-facing label for a date literal.
 *
 * @param literal - A supported date literal value
 * @returns The label string, or the raw literal if not found
 */
export declare function getDateLiteralLabel(literal: string): string;
/**
 * Maps each date literal to its `$Constant.*` display value for the expression builder.
 * These are the values that `fsc_expressionBuilder3` renders in the Value field.
 */
export declare const DATE_LITERAL_CONSTANTS: Record<SupportedDateLiteral, string>;
/**
 * Builds an ISV-compatible filterJson string for date literal filtering.
 *
 * Produces the full expression builder JSON schema that `fsc_expressionBuilder3` expects,
 * including all 12 required fields per expression line. The `parameter` field uses `$Constant.*`
 * display values and `parameterValue` / `dateLiteral` use the SOQL literal.
 *
 * The outer envelope (hasFilters, setA) is required by ProfilingDefinitionApiService.resolveFilterClause()
 * to enable WHERE clause filtering. setA.json must be an object (not a string) — the API
 * does JSON.serialize() on it.
 *
 * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
 * @param dateLiteral - The date literal value (e.g., 'THIS_YEAR', 'N_YEARS_AGO:2')
 * @param objectName - The Salesforce object API name (e.g., 'Account', 'Lead'). Defaults to empty string for backward compatibility.
 * @param objectLabel - The Salesforce object label (e.g., 'Account', 'Lead'). Defaults to objectName.
 * @returns JSON string compatible with GlobalProfilingService.createProfilingDefinition()
 */
export declare function buildDateLiteralFilterJson(dateField: string, dateLiteral: string, objectName?: string, objectLabel?: string): string;
/**
 * Builds an ISV-compatible filterJson string for date-literal comparative definitions.
 * Creates SetA (primary period) and SetB (prior period), both using SOQL date literals.
 *
 * Used when method='comparative' with a date literal that has a prior period in its cascade.
 * The prior literal is derived from LITERAL_CASCADES[setALiteral][1] by the caller.
 *
 * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
 * @param setALiteral - The primary (current) date literal for SetA
 * @param setBLiteral - The prior period date literal for SetB
 * @param objectName - The Salesforce object API name
 * @param objectLabel - The Salesforce object label
 * @returns JSON string with hasFilters, setA, and setB
 */
export declare function buildComparativeDateLiteralFilterJson(dateField: string, setALiteral: SupportedDateLiteral, setBLiteral: SupportedDateLiteral, objectName?: string, objectLabel?: string): string;
/**
 * Maps a calendar year to the appropriate SOQL date literal based on distance from current year.
 *
 * @param year - The target calendar year
 * @returns The date literal key (THIS_YEAR, LAST_YEAR, N_YEARS_AGO:2, N_YEARS_AGO:3) or undefined if out of range
 */
export declare function yearToDateLiteral(year: number): SupportedDateLiteral | undefined;
/**
 * Formats a year boundary as an ISO 8601 UTC midnight string.
 * Used for explicit date range expressions in year-based comparisons.
 */
export declare function yearBoundaryISO(year: number): string;
/**
 * Formats a year boundary as a human-readable display string (M/d/yyyy, h:mm a).
 * Used for the `parameter` display value in expression builder JSON.
 */
export declare function yearBoundaryDisplay(year: number): string;
/**
 * Builds an ISV-compatible filterJson string for a single year (SetA only, no SetB).
 * Used for historical definitions scoped to a specific year via --year flag.
 *
 * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
 * @param year - The target year
 * @param objectName - The Salesforce object API name
 * @param objectLabel - The Salesforce object label
 * @returns JSON string with hasFilters and setA (no setB)
 */
export declare function buildHistoricalYearFilterJson(dateField: string, year: number, objectName?: string, objectLabel?: string): string;
/**
 * Builds an ISV-compatible filterJson string for year-based comparative definitions.
 * Creates SetA (target year) and SetB (prior year or all prior years) using explicit
 * date range expressions (>= start AND < end), not date literals.
 *
 * This approach supports arbitrary years with no lookback limitation.
 *
 * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
 * @param year - The target year for SetA
 * @param usePrior - When true, SetB is all records before the target year. When false, SetB is the prior year.
 * @param objectName - The Salesforce object API name
 * @param objectLabel - The Salesforce object label
 * @returns JSON string with hasFilters, setA, and setB
 */
export declare function buildComparativeYearFilterJson(dateField: string, year: number, usePrior: boolean, objectName?: string, objectLabel?: string): string;
/**
 * Builds an ISV-compatible filterJson string for the lifetime-vs-X comparative variant.
 *
 * SetA is unfiltered (empty expressions array — represents "all records / lifetime"); SetB carries the supplied
 * secondary filter. This is the inverse of `buildComparativeYearFilterJson`, where SetA is the year-scoped set and
 * SetB is the prior-year (or unbounded) set.
 *
 * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
 * @param secondary - The secondary filter spec applied to SetB. Accepts `{ kind: 'year', year }` for a year-bounded SetB,
 * or `{ kind: 'dateLiteral', literal }` for a SOQL date-literal SetB.
 * @param objectName - The Salesforce object API name
 * @param objectLabel - The Salesforce object label (defaults to objectName)
 * @returns JSON string with hasFilters, setA (empty), and setB (filtered)
 */
export declare function buildLifetimeComparativeFilterJson(dateField: string, secondary: {
    kind: 'year';
    year: number;
} | {
    kind: 'dateLiteral';
    literal: SupportedDateLiteral;
}, objectName?: string, objectLabel?: string): string;