payments/src/lib/types.ts

/** @module payments */

/**
 * Supported currencies by the PS
 *
 * @const
 * @access public
 */
export const SUPPORTED_CURRENCIES = ['USD', 'EUR', 'GBP'];

/**
 * Payment directions enum
 *
 * @enum {string}
 * @access public
 */
export enum PaymentDirection {
  CREDIT = 'CREDIT',
  DEBIT = 'DEBIT',
}

/**
 * Payment statuses enum
 *
 * @enum {string}
 * @access public
 */
export enum PaymentStatus {
  DELETED = 'DELETED',
  NEEDS_APPROVAL = 'NEEDS_APPROVAL',
  APPROVED = 'APPROVED',
  REQUESTED = 'REQUESTED',
  REQUEST_FAILED = 'REQUEST_FAILED',
  SUBMITTED = 'SUBMITTED',
  COMPLETED = 'COMPLETED',
  FAILED = 'FAILED',
  DENIED = 'DENIED',
  CANCELLED = 'CANCELLED',
  PROCESSING = 'PROCESSING',
  REJECTED = 'REJECTED',
  REDRAFTED = 'REDRAFTED',
  CHARGED_BACK = 'CHARGED_BACK',
}

/**
 * Payment processing states enum
 *
 * @enum {string}
 * @access public
 */
export enum PaymentProcessingState {
  UNPROCESSED = 'UNPROCESSED',
  PROCESSED = 'PROCESSED',
}

/**
 * External payment event
 *
 * @access public
 */
export type ExternalPaymentEvent = {
  event_id: string;
  id: string;
  payment_id?: string;
  status: string;
  service: string;
  external_url: string;
  created_at: Date;

  // We disable the linting due to Prisma casting into Json fields issues
  // if we use a `unknown` type, same for the other cases below.
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  metadata?: any;
};

/**
 * External event data
 *
 * @access public
 */
export type ExternalEventData = {
  id: string;
  url: string;
  createdAt: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  metadata: any;
};

/**
 * The payment type
 *
 * @access public
 */
export type Payment = {
  id?: number;
  createdAt?: Date;
  key: string;
  amount: number;
  currency: string;
  direction: PaymentDirection;
  description?: string;
  companyId: string;
  actionBy: string;
  status: PaymentStatus;
  reason?: string;
  effectiveDate: Date;
  processingKey: string;
  processingState: PaymentProcessingState;
  contractName: string;
  externalKey?: string;
  externalService?: string;
  externalStatus?: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  metadata?: any;
  eventData?: ExternalEventData;
  originatingAccount?: string;
  receivingAccount?: string;
};

/**
 * Payment error used for batch approvals responses
 *
 * @access public
 */
export type PaymentError = {
  key: string;
  error: string;
};

/**
 * Batch approval response type
 *
 * @access public
 */
export type PaymentBatchApprove = {
  approved: Payment[];
  errors: PaymentError[];
};

/**
 * Params for payment creation
 *
 * @access public
 */
export type PaymentParams = {
  key?: string;
  amount: number;
  currency: string;
  direction: PaymentDirection;
  description?: string;
  effectiveDate?: Date;
  contractName: string;
  originatingAccount?: string;
  // Counterparty information
  companyId?: string;
  receivingAccount?: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  metadata?: any;
};

/**
 * Filtering params for payment getters and filtering
 *
 * @access private
 */
export type PaymentCallLog = {
  id: number;
  key: string;
  createdAt: Date;
  callName: string;
  actionBy: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  args: any[];
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  metadata: any;
};

/**
 * Filtering params for amounts
 *
 * @access public
 */
type PaymentFiltersAmount = {
  gt: number;
  gte: number;
  lt: number;
  lte: number;
};

/**
 * Filtering params for the effective date
 *
 * @access public
 */
type PaymentFiltersEffectiveDate = { gt: Date; gte: Date; lt: Date; lte: Date };

/**
 * Filtering params for payment getters and filtering
 *
 * @access public
 */
export type PaymentFilters = {
  contractName?: string;
  direction?: PaymentDirection;
  status?: PaymentStatus[];
  currency?: string;
  amount?: PaymentFiltersAmount;
  effectiveDate?: PaymentFiltersEffectiveDate;
  actionBy?: string;
  offset?: number;
  limit?: number;
};