/**
 * Reporting filter contract — pure TypeScript domain types (F-143).
 * No third-party imports, no module dependencies. Only the shared reporting
 * vocabulary consumed by the application layer and the route layer.
 */

/** Date-comparison modes for the `compare` query param. */
export const REPORTING_COMPARISON = ['none', 'previous_equal', 'previous_calendar'] as const;
export type ComparisonMode = (typeof REPORTING_COMPARISON)[number];

/** Sales channels a report can be scoped to. */
export const REPORTING_CHANNELS = ['all', 'ecommerce', 'pos', 'admin'] as const;
export type ReportingChannel = (typeof REPORTING_CHANNELS)[number];

/** Dimensions a report can be grouped by. */
export const REPORTING_GROUP_BY = [
  'day',
  'week',
  'month',
  'hour',
  'store',
  'channel',
  'terminal',
  'cashier',
  'payment',
] as const;
export type GroupBy = (typeof REPORTING_GROUP_BY)[number];

/** Inclusive-start, exclusive-end date window. `[from, to)` avoids double counting. */
export interface DateRange {
  from: string;
  to: string;
}

/** Previous-period range produced by a comparison mode. `null` for `none`. */
export interface ComparisonRange {
  from: string;
  to: string;
}

/** Availability of a metric under the current data model (F-142 §4 baseline). */
export type Availability = 'available' | 'unavailable';

/** Metadata describing a single filter field, for client-side UI generation. */
export interface FilterFieldMeta {
  name: string;
  type: 'uuid' | 'string' | 'enum' | 'date';
  required: boolean;
  repeatable: boolean;
  options?: readonly string[];
  description: string;
}

/** Normalized reporting filters after parsing + validation. */
export interface ReportingFilters {
  range: DateRange;
  compare: ComparisonMode;
  channel: ReportingChannel;
  storeIds: string[];
  terminalIds: string[];
  cashierIds: string[];
  paymentMethodIds: string[];
  productIds: string[];
  categoryIds: string[];
  brandIds: string[];
  customerId: string | undefined;
  state: string[];
  groupBy: GroupBy | undefined;
  page: number;
  pageSize: number;
  sort: string | undefined;
}

/** Which metrics can be computed from the current model. */
export interface DataAvailability {
  grossSales: Availability;
  netSales: Availability;
  discounts: Availability;
  tax: Availability;
  unitsSold: Availability;
  orders: Availability;
  customers: Availability;
  margin: Availability;
  paymentMethod: Availability;
  refunds: Availability;
  shipping: Availability;
}

/** The shared metadata block returned by `GET /reporting/filters/schema`. */
export interface ReportingFilterMeta {
  filters: FilterFieldMeta[];
  comparison: {
    modes: ComparisonMode[];
    rangeBounds: 'inclusive_start_exclusive_end';
  };
  groupBy: GroupBy[];
  pagination: {
    pageMin: number;
    pageSizeMin: number;
    pageSizeMax: number;
  };
  dataAvailability: DataAvailability;
}
