Component Reference

Types

TypeScript type definitions for the Open Ledger SDK

The SDK exports several TypeScript types and interfaces for use in your application.

1import {
2  Transaction,
3  Account,
4  JournalEntry,
5  AccountBalance,
6  GroupedAccounts,
7  Company,
8  Category,
9  FinancialMetrics,
10  ProfitAndLossData,
11  CashFlowData,
12  ExpiringOAuthResponse,
13} from "@openledger/accounting-react";

Core Entity Types

Company

Represents a company entity in the accounting system.

1interface Company {
2  id: string;
3  external_id: string;
4  legal_name: string;
5  tin?: string;
6  us_state: string;
7  entity_type: string;
8  phone_number: string;
9  date_created: Date;
10  status: "ACTIVE" | "INACTIVE";
11  developer_id?: string;
12  notification_frequency: string;
13  accounting_method: string;
14  fiscal_year_start: Date;
15  default_currency: string;
16  google_auth_token?: string;
17  admin_user_id?: number;
18  address_id?: number;
19  phone?: string;
20  website?: string;
21  logo_url?: string;
22  subscription_plan?: string;
23  billing_information?: string;
24}
25
26interface CreateCompanyRequest {
27  external_id?: string;
28  legal_name: string;
29  tin?: string;
30  us_state: string;
31  entity_type: string;
32  phone_number: string;
33  developer?: string;
34}
35
36interface UpdateCompanyRequest {
37  external_id?: string;
38  legal_name?: string;
39  tin?: string;
40  us_state?: string;
41  entity_type?: string;
42  phone_number?: string;
43  status?: "ACTIVE" | "INACTIVE";
44}

Category and Ledger Account

Represents categories and chart of accounts entries.

1enum CategoryType {
2  REVENUE = "REVENUE",
3  EXPENSE = "EXPENSE",
4  ASSET = "ASSET",
5  LIABILITY = "LIABILITY",
6  EQUITY = "EQUITY",
7  INTEREST_INCOME = "INTEREST_INCOME",
8  COGS_EXPENSE = "COGS_EXPENSE",
9  SGA_EXPENSE = "SGA_EXPENSE",
10  SM_EXPENSE = "SM_EXPENSE",
11  RD_EXPENSE = "RD_EXPENSE",
12  INTEREST_EXPENSE = "INTEREST_EXPENSE",
13  TAX_EXPENSE = "TAX_EXPENSE",
14}
15
16enum FinancialType {
17  // Asset Types
18  CASH = "CASH",
19  ACCOUNTS_RECEIVABLE = "ACCOUNTS_RECEIVABLE",
20  INVENTORY = "INVENTORY",
21  PREPAID_EXPENSES = "PREPAID_EXPENSES",
22  SHORT_TERM_INVESTMENTS = "SHORT_TERM_INVESTMENTS",
23  FIXED_ASSETS = "FIXED_ASSETS",
24  INTANGIBLE_ASSETS = "INTANGIBLE_ASSETS",
25  LONG_TERM_INVESTMENTS = "LONG_TERM_INVESTMENTS",
26  OTHER_ASSETS = "OTHER_ASSETS",
27
28  // Liability Types
29  ACCOUNTS_PAYABLE = "ACCOUNTS_PAYABLE",
30  PAYROLL_LIABILITIES = "PAYROLL_LIABILITIES",
31  TAX_LIABILITIES = "TAX_LIABILITIES",
32  SHORT_TERM_DEBT = "SHORT_TERM_DEBT",
33  ACCRUED_LIABILITIES = "ACCRUED_LIABILITIES",
34  LONG_TERM_DEBT = "LONG_TERM_DEBT",
35  DEFERRED_LIABILITIES = "DEFERRED_LIABILITIES",
36  OTHER_LIABILITIES = "OTHER_LIABILITIES",
37
38  // Equity Types
39  COMMON_STOCK = "COMMON_STOCK",
40  RETAINED_EARNINGS = "RETAINED_EARNINGS",
41  OWNER_EQUITY = "OWNER_EQUITY",
42  OTHER_EQUITY = "OTHER_EQUITY",
43
44  // Revenue Types
45  SALES = "SALES",
46  SERVICE_REVENUES = "SERVICE_REVENUES",
47  OTHER_REVENUE = "OTHER_REVENUE",
48
49  // Expense Types
50  COST_OF_GOODS_SOLD = "COST_OF_GOODS_SOLD",
51  PAYROLL_EXPENSES = "PAYROLL_EXPENSES",
52  GENERAL_ADMINISTRATIVE = "GENERAL_ADMINISTRATIVE",
53  UTILITIES_EXPENSES = "UTILITIES_EXPENSES",
54  RENT_EXPENSES = "RENT_EXPENSES",
55  ADVERTISING_EXPENSES = "ADVERTISING_EXPENSES",
56  PROFESSIONAL_FEES = "PROFESSIONAL_FEES",
57  REPAIR_MAINTENANCE = "REPAIR_MAINTENANCE",
58  INSURANCE_EXPENSES = "INSURANCE_EXPENSES",
59  DEPRECIATION_AMORTIZATION = "DEPRECIATION_AMORTIZATION",
60  TAX_EXPENSES = "TAX_EXPENSES",
61  INTEREST_EXPENSES = "INTEREST_EXPENSES",
62  OTHER_EXPENSES = "OTHER_EXPENSES",
63}
64
65interface LedgerAccount {
66  id: string;
67  instanceId: string;
68  parentAccountId: string | null;
69  name: string;
70  type: AccountType;
71  financialType: FinancialType | null;
72  isCategory: boolean;
73  code: number | null;
74  subTypeCode: number | null;
75  tbAccountId: string | null;
76  templateNodeId: string | null;
77  ledgerId: string;
78  entityId: string | null;
79  createdAt: string | Date;
80  updatedAt: string | Date;
81  topLevel: boolean;
82  metadata: Record<string, any> | null;
83}
84
85// For backward compatibility
86type Category = LedgerAccount;

Account & Account Balance

Represents a financial account and its balance.

1interface Account {
2  id: string;
3  name: string;
4  type: AccountType;
5  subtype?: AccountSubtype;
6  code?: string;
7  description?: string;
8  balance: number;
9  parent_id?: string;
10  children?: Account[];
11  created_at: string;
12  updated_at: string;
13}
14
15type AccountType = "asset" | "liability" | "equity" | "revenue" | "expense";
16
17type AccountSubtype =
18  | "cash"
19  | "accounts_receivable"
20  | "inventory"
21  | "fixed_asset"
22  | "accounts_payable"
23  | "long_term_debt"
24  | "owner_equity"
25  | "retained_earnings"
26  | "sales"
27  | "cost_of_goods_sold"
28  | "operating_expense"
29  | "tax_expense";
30
31interface AccountBalance {
32  name: string;
33  type: string;
34  financialType: string;
35  accountCode: number;
36  subTypeCode: number;
37  tb_primary_account_id?: string;
38  tb_corresponding_account_id?: string;
39  balance: {
40    debits_pending: string;
41    debits_posted: string;
42    credits_pending: string;
43    credits_posted: string;
44    timestamp: string;
45  };
46  metadata?: {
47    reportPeriod: string | null;
48  };
49}
50
51interface GroupedAccounts {
52  [type: string]: AccountBalance[];
53}

Transaction

Represents a financial transaction.

1interface Transaction {
2  id: string;
3  date: Date;
4  amount: number;
5  currency: string;
6  description: string;
7  status: TransactionStatus;
8  bank_transaction_id?: string;
9  transaction_type: string;
10  company_id: string;
11  direction: "CREDIT" | "DEBIT";
12  counterparty_name?: string;
13  categorizationStatus: "PENDING" | "CATEGORIZED";
14  category_id?: string;
15  created_at: Date;
16  updated_at?: Date;
17}
18
19enum TransactionStatus {
20  PENDING = "PENDING",
21  CLEARED = "CLEARED",
22  VOID = "VOID",
23  RECONCILED = "RECONCILED",
24}
25
26interface TransactionsByMonth {
27  year: number;
28  month: number;
29  delta: number;
30  transactions: Transaction[];
31}
32
33interface TransactionForSuggestion {
34  id?: string;
35  entityId: string;
36  bank_transaction_id: string;
37  amount: number;
38  description?: string;
39  merchant_name?: string;
40  counterparty_name?: string;
41  date: string;
42  direction?: "CREDIT" | "DEBIT";
43  category_id?: string;
44  // Additional fields available...
45}

JournalEntry

Represents a double-entry accounting journal entry.

1interface JournalEntry {
2  id: string;
3  date: string;
4  description: string;
5  lines: JournalEntryLine[];
6  reference?: string;
7  status: JournalEntryStatus;
8  created_at: string;
9  updated_at: string;
10}
11
12interface JournalEntryLine {
13  id: string;
14  account_id: string;
15  account?: Account;
16  amount: number;
17  type: "debit" | "credit";
18  description?: string;
19}
20
21type JournalEntryStatus = "draft" | "posted" | "reconciled";

Financial Reports & Metrics

ProfitAndLossData

Profit and loss report data.

1interface ProfitAndLossData {
2  totalRevenue: number;
3  totalExpenses: number;
4  netProfit: number;
5  revenueChange?: number;
6  expenseChange?: number;
7  profitChange?: number;
8}
9
10interface ProfitAndLossDataYearly {
11  year: number;
12  month: number;
13  totalRevenue: number;
14  totalExpenses: number;
15  netProfit: number;
16  months: {
17    month: number;
18    totalRevenue: number;
19    totalExpenses: number;
20    netProfit: number;
21  }[];
22}

CashFlowData

Cash flow report data.

1interface CashFlowData {
2  operatingActivities: CashFlowActivity;
3  investingActivities: CashFlowActivity;
4  financingActivities: CashFlowActivity;
5  netCashFlow: number;
6}
7
8interface CashFlowActivity {
9  total: number;
10  categories: CashFlowCategory[];
11}
12
13interface CashFlowCategory {
14  subcategory_name: string;
15  amount: number;
16  transactions: Transaction[];
17}

RevenueProfitExpenseResponse

Revenue, profit, and expense report data.

1interface RevenueProfitExpenseResponse {
2  revenue: {
3    total: number;
4    categories: {
5      subcategory_name: string;
6      amount: number;
7      transactions: Transaction[];
8    }[];
9  };
10  expenses: {
11    total: number;
12    categories: {
13      subcategory_name: string;
14      amount: number;
15      transactions: Transaction[];
16    }[];
17  };
18  netProfit: number;
19  totalRevenue: number;
20  totalExpenses: number;
21  revenueChange: number;
22  expenseChange: number;
23  profitChange: number;
24}

FinancialMetrics

Key financial metrics for dashboard displays.

1interface FinancialMetrics {
2  cashBalance: number;
3  revenue: number;
4  expenses: number;
5  profit: number;
6  assets: number;
7  liabilities: number;
8  equity: number;
9  trends: {
10    revenue: Trend;
11    expenses: Trend;
12    profit: Trend;
13  };
14}
15
16interface Trend {
17  data: number[];
18  labels: string[];
19  change: number;
20  changePercentage: number;
21}

Hierarchical Account Structure

Account structure for hierarchical reports.

1interface AccountNode {
2  id: string;
3  name: string;
4  balance: number;
5  financialType: string | null;
6  isCategory: boolean;
7  level: number;
8  children: AccountNode[];
9}
10
11interface HierarchicalBalanceSheet {
12  assets: AccountNode[];
13  liabilities: AccountNode[];
14  equity: AccountNode[];
15  totals: {
16    totalAssets: number;
17    totalLiabilities: number;
18    totalEquity: number;
19    liabilitiesAndEquity: number;
20  };
21}
22
23interface HierarchicalIncomeStatement {
24  revenue: AccountNode[];
25  expenses: AccountNode[];
26  totals: {
27    totalRevenue: number;
28    totalExpenses: number;
29    netIncome: number;
30  };
31}

Integration Types

Plaid Integration

Types for Plaid bank connection.

1interface PlaidAccount {
2  id: string;
3  plaid_account_id: string;
4  plaid_access_token: string;
5  account_name: string;
6  account_type: string;
7  account_subtype: string;
8  account_mask: string;
9  entityId: string;
10  balances: {
11    available: number;
12    current: number;
13    iso_currency_code: string;
14    unofficial_currency_code?: string;
15  };
16}
17
18interface CompanyPlaidAccounts {
19  id: number;
20  account_id: string;
21  account_type: string;
22  account_name: string;
23  account_mask: string;
24  balance_available: number;
25  balance_current: number;
26  company_id: number;
27  created_at: string;
28  updated_at: string;
29}

Authentication Types

Types for authentication and API access.

1interface OAuthResponse {
2  access_token: string;
3  token_type: string;
4  expires_in: number;
5}
6
7interface ExpiringOAuthResponse extends OAuthResponse {
8  expires_at: Date;
9}
10
11type AuthenticatedRequestOptions<T> = {
12  params: T;
13};
14
15type APIFunction<T> = (
16  baseUrl: string,
17  accessToken: string | undefined,
18  options?: AuthenticatedRequestOptions<T>
19) => Promise<any>;

UI & Messaging Types

Chat and AI Assistant

Types for chat and messaging functionality.

1interface Chat {
2  id: number;
3  name?: string;
4  entityId: string;
5  messages: Message[];
6  createdAt: Date;
7  updatedAt: Date;
8  messagesJson?: any;
9}
10
11interface Message {
12  id: number;
13  content: string;
14  role: ChatRole;
15  chatId: number;
16  attachments: Attachment[];
17  createdAt: Date;
18}
19
20interface Attachment {
21  id: number;
22  filename: string;
23  url: string;
24  messageId: number;
25  createdAt?: Date;
26}
27
28enum ChatRole {
29  USER = "USER",
30  ASSISTANT = "ASSISTANT",
31}

Theme Configuration

Theme configuration for customizing the appearance of the SDK.

1interface AccelThemeConfigColors {
2  primary?: ColorHexConfig;
3  secondary?: ColorHexConfig;
4  accent?: ColorHexConfig;
5  background?: ColorHexConfig;
6  text?: ColorHexConfig;
7  positive?: ColorHexConfig;
8  negative?: ColorHexConfig;
9  isDarkMode?: boolean;
10  darkMode?: {
11    background?: ColorHexConfig;
12    accent?: ColorHexConfig;
13    text?: ColorHexConfig;
14  };
15}
16
17interface AccelThemeConfig {
18  colors?: AccelThemeConfigColors;
19}
20
21interface ColorHexConfig {
22  hex: string;
23}

Financial Overview Response

Response structure for financial overview data from useFinancialOverview.

1interface FinancialOverviewResponse {
2  monthlyRevenue: [string, number][];
3  monthlyExpenses: [string, number][];
4  monthlyProfit: [string, number][];
5  monthlyCashBalance: [string, number][];
6  totalRevenue: number;
7  totalExpenses: number;
8  totalProfit: number;
9  currentCashBalance: number;
10  chartData: {
11    date: string;
12    Revenue: number;
13    Expenses: number;
14    Profit: number;
15    value: number;
16  }[];
17  latestMonthStats: {
18    revenue: number;
19    expenses: number;
20    profit: number;
21    revenueChange: number;
22    expensesChange: number;
23    profitChange: number;
24  };
25  plaidAccounts: {
26    account_id: string;
27    balances: {
28      available: number;
29      current: number;
30      iso_currency_code: string;
31      limit: null | number;
32      unofficial_currency_code: null | string;
33    };
34    holder_category: string;
35    mask: string;
36    name: string;
37    official_name: string;
38    persistent_account_id: string;
39    subtype: string;
40    type: string;
41  }[];
42  filterInfo: {
43    statusFilter: string;
44    dateRange: {
45      startDate: string | null;
46      endDate: string;
47    };
48    interval: string;
49  };
50}

Financial Reports Response

Response structure for financial reports data from useFinancialReports.

1interface FinancialReports {
2  reportPeriod: {
3    month: string | null;
4    year: string | null;
5    startDate: string | null;
6    endDate: string | null;
7  };
8  balanceSheet: {
9    hierarchical: HierarchicalBalanceSheet;
10    totalCurrentAssets: number;
11    totalNonCurrentAssets: number;
12    totalAssets: number;
13    totalCurrentLiabilities: number;
14    totalNonCurrentLiabilities: number;
15    totalLiabilities: number;
16    totalEquity: number;
17    liabilitiesAndEquity: number;
18  };
19  incomeStatement: {
20    hierarchical: HierarchicalIncomeStatement;
21    revenue: number;
22    expenses: number;
23    grossProfit: number;
24    operatingIncome: number;
25    incomeBeforeTax: number;
26    netIncome: number;
27  };
28  cashFlowStatement: {
29    hierarchical: {
30      operatingActivities: {
31        netIncome: number;
32        adjustments: {
33          depreciation: number;
34          changeInAccountsReceivable: number;
35          changeInInventory: number;
36          changeInAccountsPayable: number;
37          changeInAccruedLiabilities: number;
38        };
39      };
40      investingActivities: {
41        purchaseOfFixedAssets: number;
42        purchaseOfInvestments: number;
43        saleOfInvestments: number;
44      };
45      financingActivities: {
46        proceedsFromDebt: number;
47        repaymentOfDebt: number;
48        issuanceOfStock: number;
49        dividendsPaid: number;
50      };
51      totals: {
52        totalOperatingActivities: number;
53        totalInvestingActivities: number;
54        totalFinancingActivities: number;
55        netChangeInCash: number;
56      };
57    };
58    netCashFromOperatingActivities: number;
59    netCashFromInvestingActivities: number;
60    netCashFromFinancingActivities: number;
61    netChangeInCash: number;
62  };
63  reconciliation: {
64    plaidAccountsTotal: number;
65    ledgerCashBalance: number;
66    difference: number;
67    plaidAccounts: any[];
68  };
69  accountHierarchy: AccountNode[];
70  pdf_urls: {
71    profit_loss: string | null;
72    balance_sheet: string | null;
73    cash_flow: string | null;
74  };
75}