report.ts defines REPORT_RESOURCES, a const allowlist mirroring the backend registry (per the code comment — the backend is the source of truth and rejects anything not listed there). ReportResourceName = keyof typeof REPORT_RESOURCES:

ReportResourceConfig splits each resource's fields into three roles: dimensionFields (safe to filter/group-by as-is), dateFields (a subset of dimension fields that are also safe to bucket via ReportGroupBy.bucket), and metricFields (safe to aggregate via ReportMetric). invoices and payments correspond to the Payment domain class — "the class is named Paymentfor backward compatibility, it represents what the API calls an invoice"; payments here is the Stripe payment/charge record, distinct from the invoices resource. checkouts corresponds to Checkout; payroll_run_lines to PayrollRunLine; account_credit_transactions to AccountCreditTransaction.

Four types in report.ts compose the filter/groupBy/metric/sort request, generic over a field-name union Field extends string = string (narrowed by ReportResourceConfig's three arrays when a caller wants autocomplete, same pattern as QueryRequest<T>):

const ReportAggFnList = ["count", "sum", "avg", "min", "max"] as const;
type ReportAggFn = (typeof ReportAggFnList)[number];

const ReportBucketList = ["day", "week", "month"] as const;
type ReportBucket = (typeof ReportBucketList)[number];

interface ReportGroupBy<Field extends string = string> {
  field: Field;
  bucket?: ReportBucket; // buckets a date field by day/week/month; omit to group as-is on a dimension field
}

interface ReportMetric<Field extends string = string> {
  field: Field | "*";  // "*" is only meaningful with agg: "count"
  agg: ReportAggFn;
}

interface ReportSort {
  on: "group" | "metric";
  index: number;        // index into groupBy (on: "group") or metrics (on: "metric") — referenced by position, not name
  order?: "asc" | "desc";
}

interface RunReportRequest<Field extends string = string> {
  resource: ReportResourceName;
  filter?: QueryRequest<Field>["filter"];
  logic?: "and" | "or";
  groupBy?: ReportGroupBy<Field>[];
  metrics: ReportMetric<Field>[];
  sort?: ReportSort;
  limit?: number;
  offset?: number;
  includeDeleted?: boolean;
}

interface RunSavedReportRequest {
  reportDefinitionID: string;
  limit?: number;
  offset?: number;
  includeDeleted?: boolean;
}

RunSavedReportRequest runs a previously saved ReportDefinition instead of sending the full ad-hoc shape; its limit/offset/includeDeletedoverride the saved definition's values when provided (the definition itself carries no limit/offset/includeDeleted — those three are per-run-only, never persisted).

type ReportRow = Record<string, string | number | null>;

Each row is dynamically keyed, not a fixed interface — column names are constructed positionally from the request's own groupBy/metrics arrays (per the doc comment on ReportRow):

E.g. { groupBy: [{ field: "status" }], metrics: [{ field: "amount", agg: "sum" }, { field: "*", agg: "count" }] } produces rows shaped like { g0_status: "resolved", m0_sum_amount: 4820, m1_count_all: 12 }.

async function RunReport<Field extends string = string>(
  company: Company,
  request: RunReportRequest<Field> | RunSavedReportRequest,
): Promise<SimpleResult<ReportRow[]>>

POST /company/{companyID}/report — server-side filter/groupBy/metric aggregation over an allowlisted resource (see REPORT_RESOURCES above for what each resource supports). Accepts either shape in the union: a RunReportRequest (ad-hoc — specifies resource plus the full filter/groupBy/metrics/sort shape) or a RunSavedReportRequest ({ reportDefinitionID, limit?, offset?, includeDeleted? } — re-runs a saved ReportDefinition by id). The backend distinguishes the two by the presence of reportDefinitionID vs. resource/metrics.

definition.ts. A saved query config — the filter/groupBy/metrics/sort shape plus name/resource, persisted so it can be re-run via Run() without resending the full shape each time. DataStructure<ReportDefinitionData>, endpoint /company/{companyID}/report/definitions.

interface ReportDefinitionShape {
  filter?: QueryRequest["filter"];
  logic?: "and" | "or";
  groupBy?: ReportGroupBy[];
  metrics: ReportMetric[];
  sort?: ReportSort;
}

interface LazyReportDefinitionData {
  id: string;
  companyID: string;
  name: string;
  resource: ReportResourceName;
  definition: ReportDefinitionShape;
  createdByUserID?: string | null;
}

interface ReportDefinitionData extends LazyReportDefinitionData {
  createdAt: Date;
  updatedAt: Date;
}

new ReportDefinition(id: string, company: Company);
new ReportDefinition(data: LazyReportDefinitionData | ReportDefinitionData, company: Company, lazy?: boolean);

ReportDefinition.create(company: Company, definitions: CreateReportDefinitionData[]): Promise<EventData<string[]>>

ReportDefinition.query(company: Company, data: QueryRequest): Promise<SimpleResult<ReportDefinition[]>>

definition.save(): Promise<SimpleResult<EventData>>

definition.delete(): Promise<SimpleResult<EventData>>

definition.Run(opts?: { limit?: number; offset?: number; includeDeleted?: boolean }): Promise<SimpleResult<ReportRow[]>>