@updraft-solutions/mcrit-sdk 0.18.7 → 0.19.1

package/src/schemas/report.ts

@@ -1,306 +1,173 @@
-// Report Status Types
-export type ReportStatus = "pending" | "processing" | "completed" | "failed";
+import type { Media } from "../types/models";
 
-// Report Type Enum
-export type ReportType =
-  | "financial"
-  | "operational"
-  | "instructor_efficiency"
-  | "company_development";
+// ─────────────────────────────────────────────────────────────────────────────
+// Company reports (Berichte) — section-document contract.
+// A report is compiled server-side into an ordered list of typed sections;
+// the same JSON drives the PDF and the in-app viewer. Values are raw numbers
+// with a `format`; `label`-format values and every `*Key`/`label`/`title`
+// string are translation keys resolved through `ReportDetail.labels`.
+// ─────────────────────────────────────────────────────────────────────────────
 
-// Granularity Options
-export type ReportGranularity =
-  | "total"
-  | "yearly"
-  | "quarterly"
-  | "monthly"
-  | "weekly"
-  | "daily";
+export type ReportStatus = "queued" | "processing" | "completed" | "failed";
 
-// Media Type (matching backend MediaResource)
-export interface Media {
-  type: "media";
-  id: number;
-  description?: string;
-  url: string | null;
-  mime_type: string;
-  file_name: string;
-  size: number;
-  collection_name: string;
-  created_at: string;
-  updated_at: string;
-}
-
-// Media Collection (for reports - only PDF)
-export interface ReportMedia {
-  pdf?: Media | null;
-}
+export type ReportType = "financial" | "operations" | "training" | "development";
 
-// Base Report Interface
-export interface Report {
-  id: number;
-  reportable_type: string;
-  reportable_id: number;
-  report_type: ReportType;
-  parameters: ReportParameters;
-  data: ReportData;
-  metadata: ReportMetadata;
-  status: ReportStatus;
-  generated_at: string | null;
-  expires_at: string | null;
-  created_at: string;
-  updated_at: string;
-  media?: ReportMedia;
-}
+export type ReportGranularity = "total" | "weekly" | "monthly" | "quarterly" | "yearly";
 
-// Report Parameters
-export interface ReportParameters {
-  start_date?: string | null;
-  end_date?: string | null;
-  granularity: ReportGranularity;
-}
+export type ReportValueFormat =
+  | "number"
+  | "currency"
+  | "percent"
+  | "hours"
+  | "date"
+  | "text"
+  | "label";
 
-// Report Generation Parameters (for API requests)
-export interface ReportGenerationParams {
-  type: ReportType;
-  start_date?: string | null;
-  end_date?: string | null;
-  granularity?: ReportGranularity;
-}
+export type ReportChartKind = "line" | "bar" | "horizontal_bar" | "stacked_bar" | "donut";
 
-// Report Metadata
-export interface ReportMetadata {
-  requested_by?: number;
-  requested_at?: string;
-  started_at?: string;
-  completed_at?: string;
-  duration_seconds?: number;
-  attempt?: number;
-  error?: string;
-  batch?: boolean;
-}
+export type ReportCellValue = string | number | null;
 
-// Base structure for period-based data
-export interface PeriodData<T> {
-  summary: T;
-  by_period?: Record<string, T>;
+export interface ReportComparison {
+  current: number | null;
+  previous: number | null;
+  previous_year: number | null;
+  /** Percent delta vs the previous period; null without a usable baseline. */
+  delta_previous: number | null;
+  delta_previous_year: number | null;
 }
 
-// Generic Report Data
-export type ReportData =
-  | FinancialReportData
-  | OperationalReportData
-  | InstructorEfficiencyReportData
-  | CompanyDevelopmentReportData;
-
-// =====================
-// Financial Report Types
-// =====================
-
-export interface FinancialReportData {
-  revenue: PeriodData<RevenueData>;
-  expenses: PeriodData<ExpenseData>;
-  invoices: PeriodData<InvoiceData>;
-  prepaid_packages: PeriodData<PrepaidPackageData>;
-  summary: PeriodData<FinancialSummaryData>;
+export interface ReportKpi {
+  /** Translation key (see `ReportDetail.labels`). */
+  label: string;
+  value: number | null;
+  format: ReportValueFormat;
+  comparison: ReportComparison | null;
 }
 
-export interface RevenueData {
-  total_gross: number;
-  total_net: number;
-  by_type: Record<string, number>;
-  count?: number;
+export interface ReportKpiGridSection {
+  kind: "kpi_grid";
+  title: string;
+  items: ReportKpi[];
 }
 
-export interface ExpenseData {
-  total_gross: number;
-  total_net: number;
-  by_category: Record<string, number>;
-  count?: number;
+export interface ReportColumn {
+  key: string;
+  label: string;
+  format: ReportValueFormat;
+  align: "left" | "right";
 }
 
-export interface InvoiceData {
-  total_count: number;
-  total_gross: number;
-  by_status: Record<string, number>;
-  by_paid_status: Record<string, number>;
+export interface ReportDataTableSection {
+  kind: "data_table";
+  title: string;
+  columns: ReportColumn[];
+  rows: Record<string, ReportCellValue>[];
+  totals: Record<string, ReportCellValue> | null;
+  /** Translation key shown when `rows` is empty. */
+  empty: string | null;
 }
 
-export interface PrepaidPackageData {
-  total_packages: number;
-  total_initial_value: number;
-  total_remaining_value: number;
-  total_used_value: number;
-  usage_percentage: number;
+export interface ReportSeries {
+  label: string;
+  data: (number | null)[];
 }
 
-export interface FinancialSummaryData {
-  total_revenue: number;
-  total_expenses: number;
-  profit: number;
-  profit_margin: number;
+export interface ReportChartSection {
+  kind: "chart";
+  title: string;
+  chart: ReportChartKind;
+  /** Axis labels, or slice labels for a donut; may be translation keys. */
+  categories: string[];
+  series: ReportSeries[];
+  format: ReportValueFormat;
 }
 
-// =====================
-// Operational Report Types
-// =====================
-
-export interface OperationalReportData {
-  flight_hours: FlightHoursData;
-  bookings: BookingsData;
-  landings: LandingsData;
-  aircraft_utilization: AircraftUtilization[];
-  member_activity: MemberActivityData;
+export interface ReportCalloutSection {
+  kind: "callout";
+  text: string;
+  params: Record<string, string | number | boolean>;
+  tone: "info" | "warning";
 }
 
-export interface FlightHoursData {
-  total_hours: number;
-  total_flights: number;
-  average_flight_hours: number;
-  by_month?: Record<string, number>;
-  by_period?: Record<
-    string,
-    {
-      hours: number;
-      flights: number;
-      average: number;
-    }
-  >;
-}
+export type ReportSection =
+  | ReportKpiGridSection
+  | ReportDataTableSection
+  | ReportChartSection
+  | ReportCalloutSection;
 
-export interface BookingsData {
-  total_bookings: number;
-  completion_rate: number;
-  average_efficiency: number;
-  by_status: Record<string, number>;
-  by_period?: Record<
-    string,
-    {
-      total: number;
-      completed: number;
-      cancelled: number;
-    }
-  >;
+export interface ReportParameters {
+  /** Local calendar date (Y-m-d) in `timezone`. */
+  start_date: string;
+  end_date: string;
+  granularity: ReportGranularity;
+  timezone: string;
 }
 
-export interface LandingsData {
-  total_landings: number;
-  full_stop_landings: number;
-  touch_and_gos: number;
-  top_airports: Array<{
-    airport_code: string;
-    airport_name: string;
-    count: number;
-  }>;
+export interface ReportDocument {
+  version: number;
+  type: ReportType;
+  company_id: number;
+  period: ReportParameters;
+  locale: string;
+  sections: ReportSection[];
 }
 
-export interface AircraftUtilization {
-  aircraft_id: number;
-  aircraft_registration: string;
-  aircraft_name: string;
-  total_hours: number;
-  total_bookings: number;
-  utilization_rate: number;
+export interface ReportRequester {
+  id: number;
+  name: string;
 }
 
-export interface MemberActivityData {
-  top_pilots: Array<{
-    member_id: number;
-    member_name: string;
-    flight_hours: number;
-    booking_count: number;
-  }>;
-  total_active_members: number;
+/** Identity tier — what the list shows; never carries the section document. */
+export interface Report {
+  type: "report";
+  id: number;
+  report_type: ReportType;
+  status: ReportStatus;
+  parameters: ReportParameters;
+  locale: string;
+  error: string | null;
+  generated_at: string | null;
+  created_at: string | null;
+  requested_by?: ReportRequester | null;
+  background_task_uuid?: string | null;
+  media?: { pdf: Media | null };
+  can?: Record<string, boolean | null>;
 }
 
-// =====================
-// Instructor Efficiency Report Types
-// =====================
-
-export interface InstructorEfficiencyReportData {
-  instructors: InstructorData[];
-  summary: InstructorSummaryData;
-  period: {
-    start_date: string;
-    end_date: string;
-  };
+export interface ReportDetail extends Report {
+  data: ReportDocument | null;
+  /** Translation key → text in the report's locale, for every key the document uses. */
+  labels: Record<string, string>;
 }
 
-export interface InstructorData {
-  instructor_id: number;
-  instructor_name: string;
-  instructor_email: string;
-  total_bookings: number;
-  average_efficiency: number;
-  average_delay_minutes: number;
-  total_flight_hours: number;
-  bookings_with_efficiency: number;
-  by_period?: Record<
-    string,
-    {
-      bookings: number;
-      efficiency: number;
-      delay: number;
-      hours: number;
-    }
-  >;
+export interface ReportTypeMeta {
+  type: ReportType;
+  title: string;
+  description: string;
 }
 
-export interface InstructorSummaryData {
-  total_instructors: number;
-  average_efficiency_overall: number;
-  average_delay_overall: number;
-  total_bookings_overall: number;
-  total_flight_hours_overall: number;
-  best_performer: {
-    name: string;
-    efficiency: number;
-  };
+export interface ReportGranularityMeta {
+  value: ReportGranularity;
+  label: string;
 }
 
-// =====================
-// Company Development Report Types
-// =====================
-
-export interface CompanyDevelopmentReportData {
-  summary?: Record<string, any>;
-  metrics?: Record<string, any>;
-  by_period?: Record<string, any>;
+/** `GET companies/{company}/meta/reports` */
+export interface ReportMeta {
+  types: ReportTypeMeta[];
+  granularities: ReportGranularityMeta[];
+  max_buckets: number;
 }
 
-// =====================
-// Helper Types
-// =====================
-
-// Report list item for display in tables/lists
-export interface ReportListItem {
-  id: number;
+/** `POST companies/{company}/reports` */
+export interface StoreReportInput {
   type: ReportType;
-  status: ReportStatus;
-  created_at: string;
-  generated_at: string | null;
-  parameters: ReportParameters;
+  start_date: string;
+  end_date: string;
+  granularity?: ReportGranularity;
 }
 
-// Report generation response
-export interface ReportGenerationResponse {
+/** 409 body when an identical report is already queued or processing. */
+export interface ReportConflictResponse {
   message: string;
-  data?: Report | Report[];
-  skipped?: Array<{
-    type: ReportType;
-    message: string;
-    report: Report;
-  }>;
-}
-
-// Report status response
-export interface ReportStatusResponse {
-  data: {
-    id: number;
-    status: ReportStatus;
-    report_type: ReportType;
-    created_at: string;
-    generated_at: string | null;
-    metadata: ReportMetadata;
-  };
+  data: Report;
 }