@accounter/server/src/__tests__/factories/charge.ts

Accounter GraphQL server

/**
 * Charge factory for test fixtures
 *
 * Creates minimal charge objects ready for database insertion.
 *
 * Based on charges table schema from migrations and charges.provider.ts:
 * - Required: owner_id
 * - Optional: type, accountant_status, user_description, tax_category_id, optional_vat, documents_optional_flag, is_property
 *
 * @see packages/server/src/modules/charges/providers/charges.provider.ts (generateCharge query)
 * @see packages/migrations/src/actions/*-charges-*.ts (migrations)
 */

import { makeUUID, makeUUIDLegacy } from '../../demo-fixtures/helpers/deterministic-uuid.js';

/**
 * Charge insert parameters shape
 *
 * Matches the fields from generateCharge SQL query in charges.provider.ts:
 * INSERT INTO accounter_schema.charges (owner_id, type, accountant_status, user_description, tax_category_id, optional_vat, documents_optional_flag)
 */
export interface ChargeInsertParams {
  id?: string;
  owner_id: string;
  is_property?: boolean | null;
  type?: string | null;
  accountant_status?: string | null;
  user_description?: string | null;
  tax_category_id?: string | null;
  optional_vat?: boolean | null;
  documents_optional_flag?: boolean | null;
}

/**
 * Create a charge for test fixtures
 *
 * @param params - Required fields (owner_id, tax_category_id) and optional user_description
 * @param overrides - Optional overrides for any charge field
 * @returns Charge object ready for database insertion
 *
 * @remarks
 * - owner_id is required (must be a valid business UUID)
 * - tax_category_id defaults to deterministic UUID if not provided
 * - user_description defaults to null (will be auto-generated by database if needed)
 * - type defaults to null (database will determine based on related records)
 * - accountant_status defaults to 'PENDING' (database requires NOT NULL)
 * - optional_vat defaults to false (database requires NOT NULL)
 * - documents_optional_flag defaults to false (database requires NOT NULL)
 * - is_property defaults to null (property-related charges can override to true)
 * - id defaults to deterministic UUID if not provided
 *
 * @example
 * ```typescript
 * // Minimal charge with required fields
 * const charge = createCharge({
 *   owner_id: makeUUID('business', 'test-owner'),
 *   tax_category_id: makeUUID('tax-category', 'tax-cat-1'),
 * });
 *
 * // Charge with user description
 * const descCharge = createCharge(
 *   {
 *     owner_id: makeUUID('business', 'test-owner'),
 *     tax_category_id: makeUUID('tax-category', 'tax-cat-1'),
 *     user_description: 'Office supplies purchase',
 *   }
 * );
 *
 * // Charge with overrides
 * const customCharge = createCharge(
 *   {
 *     owner_id: makeUUID('business', 'test-owner'),
 *     tax_category_id: makeUUID('tax-category', 'tax-cat-1'),
 *   },
 *   {
 *     type: 'PAYROLL',
 *     accountant_status: 'REVIEWED',
 *     optional_vat: true,
 *   }
 * );
 * ```
 */
export function createCharge(
  params: {
    owner_id: string;
    tax_category_id?: string;
    user_description?: string;
  },
  overrides?: Partial<ChargeInsertParams>,
): ChargeInsertParams {
  return {
    id: makeUUIDLegacy(),
    owner_id: params.owner_id,
    type: null,
    accountant_status: 'PENDING',
    user_description: params.user_description ?? null,
    tax_category_id: params.tax_category_id ?? makeUUID('tax-category', 'default-tax-category'),
    optional_vat: false,
    documents_optional_flag: false,
    ...overrides,
  };
}