Oscilar Schema

account.ts

// Type definitions
type CountryCode = string; // Two character ISO 3166 country code, e.g., "US", "GB"

// Account-related Enums
enum AccountType {
  Checking = "checking",
  Saving = "saving",
  CreditCard = "credit_card",
  DebitCard = "debit_card",
  Wallet = "wallet",
  Crypto = "crypto",
  Iban = "iban",
  Pix = "pix",
  Eft = "eft",
}

enum AccountStatus {
  Active = "active",
  Deleted = "deleted",
  Unknown = "unknown",
}

// Address Interface (same as in previous schema)
interface Address {
  type: string;
  street_line1: string;
  street_line2?: string;
  city: string;
  state: string;
  zip: string;
  country: CountryCode;
}

// Related Account Interface
interface RelatedAccount {
  account_id: string;
  relationship: string;
  start_date: string; // ISO 8601 format
  end_date?: string; // ISO 8601 format, optional
}

// Related Party Interface
interface RelatedParty {
  party_id: string;
  relationship: string;
  start_date: string; // ISO 8601 format
  end_date?: string; // ISO 8601 format, optional
}

// Main Account Interface
interface Account {
  account_id: string; // Primary key
  account_nickname?: string; // Alias
  account_number?: string; // Last 4
  account_since: string; // createdAt
  account_type: AccountType;
  card_expiry_date?: string; // Format: MMYY
  card_issuer?: string;
  card_issuing_bank?: string;
  card_network?: string; //Card type
  name_on_card?: string;
  partner_id?: string;
  related_accounts?: RelatedAccount[];
  related_parties?: RelatedParty[];
  routing_number?: string;
  status: AccountStatus;
  tags?: Record<string, string>; // Map with string keys and string values
  updated_at: string; // ISO 8601 format, required for Oscilar ingestion
}

action.ts

enum ActionType {
  UrlWhitelist = "url_whitelist",
  SettlementChange = "settlement_change",
  SettingChange = "setting_change",
  OverrideInsurance = "override_insurance", // Override chargeback protection insurance
  MerchantSuspended = "merchant_suspended",
  UserBlocked = "user_blocked",
  WebhookUrlAdded = "webhook_url_added",
  
}

enum Actor {
  Party = "party",
  System = "system",
}

interface Action {
  action_id: string; // Primary key
  action_time: string; // ISO 8601 format
  action_type: ActionType;
  actor_type: Actor; // Actor enum 
  actor_internal_id: string; // coinflow system ID
  description?: string;
  email?: string;
  ip_address?: string;
  labels?: string[];
  partner_id?: string;
  party_id?: string; // Party
  tags?: Record<string, string>; // Map with string keys and values
}

party.ts

type CountryCode = string; // Two character ISO 3166 country code, e.g., "US", "GB"

enum PartyType {
  User = "user",
  Business = "business",
  FinancialInstitution = "financial_institution"
}

interface PartyAccount {
  account_id: string;
  relationship: string;
  start_date: string; // ISO 8601 format
  end_date?: string; // ISO 8601 format, optional
}

interface Address {
  type: string;
  street_line1: string;
  street_line2?: string;
  city: string;
  state: string;
  zip: string;
  country: CountryCode;
}

// Party
interface Merchant {
  party_id: string; // Primary key
  accounts: PartyAccount[]; // Always empty
  addresses: Address[]; // Verification
  annual_revenue?: number; // Prisma DB
  business_name?: string; // Verification
  customer_since: string; // CreatedAt
  dba?: string; // Merchant ID
  emails?: string[]; // User emails
  mcc?: string; // MCC code from Shift4/EMP
  partner_id?: string; // Parent merchant ID 
  party_type: PartyType; // Business
  registration_country?: CountryCode; // Verification
  registration_state?: string; // Verification
  tax_id?: string; // Verification
  UBOs?: string[]; // Array of party_ids
}

// Party
interface User {
  party_id: string; // Primary key
  accounts: PartyAccount[]; // Bank_Accounts
  addresses: Address[]; // Verification
  birth_country?: CountryCode; // Verification
  birth_date?: string; // Verification
  customer_since: string; // createdAt
  emails?: string[];
  first_name?: string; // Verification
  gender?: string; // Verification
  ip_addresses?: string[]; // Verification
  last_name?: string; // Verification
  partner_id?: string; // Merchant Primary Key
  party_type: PartyType; // User
}

// Party
interface Business {
  party_id: string; // Primary key
  accounts: PartyAccount[]; // Pull from bank_accounts
  addresses: Address[];
  business_name?: string; // Pull from Verification
  customer_since: string; // Coinflow CreatedAt Timestampe
  emails?: string[]; 
  party_type: PartyType; // Business
  registration_country?: CountryCode; // Pull from Verification
  registration_state?: string; // Pull from Verification 
  partner_id?: string; // Merchant Primary Key
  tax_id?: string; // Pull from Verification
}

// Party
interface Customer {
  party_id: string; // Primary key
  accounts: PartyAccount[]; // Bank_Accounts
  addresses: Address[]; // Verification
  birth_country?: CountryCode; // Verification
  birth_date?: string; // Verification
  customer_since: string; // createdAt
  emails?: string[];
  first_name?: string; // Verification
  gender?: string; // Verification
  ip_addresses?: string[]; // Verification
  last_name?: string; // Verification
  partner_id?: string; // Merchant Primary Key
  party_type: PartyType; // User
}

transaction.ts

enum TransactionType {
  Ach = "ach",
  Wire = "wire",
  Card = "card",
  Rtp = "rtp",
  Sepa = "sepa",
  Eft = "eft",
  Pix = "pix",
  Ukfp = "ukfp",
  Crypto = "crypto"
}

enum TransactionSubtype {
  Withdrawal = "withdrawal",
  Return = "return",
  Refund = "refund",
  Purchase = "purchase",
}

enum Direction {
  Outgoing = "outgoing",
  Incoming = "incoming"
}

enum TransactionStatus {
  Pending = "pending",
  Settled = "settled",
  Cancelled = "cancelled",
  Chargeback = "chargeback",
  Refunded = "refunded",
  Failed = "failed"
}

interface Transaction {
  transaction_id: string; // Primary key
  party_id: string; // customer/user/business
  account_id: string; // payment/withdrawal method account
  partner_id?: string; // merchant ID
  transaction_type?: TransactionType;
  transaction_subtype?: TransactionSubtype;
  transaction_code?: string; // Decline code, or 01 for success
  direction: Direction;
  transaction_amount: number;
  transaction_currency_code: CurrencyCode;
  transaction_exchange_rate?: number;
  description?: string;
  status?: TransactionStatus;
  error?: string;
  posted_time?: string; // createdAt UTC
  estimated_settlement_time?: string; // estimated delivery date
  updated_at?: string; // ISO 8601 format
  reference_id?: string; // Coinflow payment ID
  card_transaction_network?: string; // card type
  card_processor?: string; //shift4, payarc, etc
  card_last_4?: string;
  fees?: number;
  ip_address?: string;
  email?: string;
  device_details?: string; // Mobile, web, etc
  tags?: Record<string, string>; // Map with string keys and values
  labels?: string[];
}