/**
 * Hostex Incomes & Expenses (Transactions) API types
 */

/** A dictionary entry (income/expense item or method) */
export interface FinanceDictionaryEntry {
  /** The id of the entry */
  id: number;
  /** The name of the entry */
  name: string;
}

/**
 * Income items response data
 */
export interface IncomeItemsData {
  income_items: FinanceDictionaryEntry[];
}

/**
 * Expense items response data
 */
export interface ExpenseItemsData {
  expense_items: FinanceDictionaryEntry[];
}

/**
 * Expense methods response data
 */
export interface ExpenseMethodsData {
  expense_methods: FinanceDictionaryEntry[];
}

/** Transaction direction */
export type TransactionDirection = 'income' | 'expense';

/** Transaction payment status */
export type TransactionStatus = 'paid' | 'outstanding';

/** What a transaction entry is linked to */
export type TransactionLinkType = 'property' | 'reservation' | 'operator';

/**
 * An income / expense entry
 */
export interface Transaction {
  /** Unique identifier of the entry */
  id: number;
  /** income = money received, expense = money spent */
  direction: TransactionDirection;
  /** Absolute amount, always non-negative */
  amount: number;
  /** The currency code of the entry */
  currency: string;
  /** Payment status */
  status?: TransactionStatus;
  /** When the action took place (ISO 8601 UTC) */
  action_at?: string | null;
  /** Item categorization id (income_items or expense_items by direction) */
  item_id?: number | null;
  /** Human-readable item name */
  item_name?: string | null;
  /** Payment method id (income_methods or expense_methods by direction) */
  payment_method_id?: number | null;
  /** Human-readable payment method name */
  payment_method_name?: string | null;
  /** Free-form note */
  note?: string;
  /** Creator display name, or `System` */
  operator_name?: string;
  /** What the entry is linked to */
  link_type?: TransactionLinkType;
  /** Related property id, if any */
  property_id?: number | null;
  /** Related property title */
  property_title?: string | null;
  /** Linked stay_code, null when not reservation-linked */
  stay_code?: string | null;
  /** Creation time (ISO 8601 UTC) */
  created_at?: string;
  /** Last update time (ISO 8601 UTC) */
  updated_at?: string;
}

/**
 * Transactions query parameters
 */
export interface TransactionsQueryParams {
  /** Internal id of a specific entry */
  id?: number;
  /** Start of the action time range, inclusive (YYYY-MM-DD) */
  start_date?: string;
  /** End of the action time range, inclusive (YYYY-MM-DD) */
  end_date?: string;
  /** The starting point from which to begin returning results */
  offset?: number;
  /** The maximum number of results to return, max 100 */
  limit?: number;
  /** Filter entries linked to the given property id */
  property_id?: number;
  /** Filter entries linked to the given stay */
  stay_code?: string;
  /** Filter by direction */
  direction?: TransactionDirection;
  /** Filter by item categorization id */
  item_id?: number;
  /** Filter by payment method id */
  payment_method_id?: number;
  /** Filter by currency code */
  currency?: string;
  /** Substring match on the entry note */
  keyword?: string;
}

/**
 * Transactions response data
 */
export interface TransactionsData {
  transactions: Transaction[];
  /** Total number of entries matching the filters */
  total: number;
}

/**
 * Create transaction parameters
 */
export interface CreateTransactionParams {
  /** Property to record against; mutually exclusive with stay_code */
  property_id?: number;
  /** Stay to record against; mutually exclusive with property_id */
  stay_code?: string;
  /** income = money received, expense = money spent */
  direction: TransactionDirection;
  /** Absolute amount; always positive, sign derived from direction */
  amount: number;
  /** Currency code; required unless stay_code is provided */
  currency?: string;
  /** Item categorization id (from income_items / expense_items by direction) */
  item_id: number;
  /** Payment method id (from income_methods / expense_methods by direction) */
  payment_method_id: number;
  /** When the action took place (ISO 8601); defaults to now */
  action_at?: string;
  /** Free-form note (max 500 characters) */
  note?: string;
}

/**
 * Create transaction response data
 */
export interface CreateTransactionData {
  /** Unique identifier of the newly created entry */
  transaction_id: number;
}

/**
 * Update transaction parameters
 */
export interface UpdateTransactionParams {
  /** The id of the entry to update */
  id: number;
  /** New absolute amount (always positive) */
  amount?: number;
  /** New item categorization id */
  item_id?: number;
  /** New payment method id */
  payment_method_id?: number;
  /** New action time (ISO 8601) */
  action_at?: string;
  /** New free-form note (max 500 characters) */
  note?: string;
}