Open Ledger React Library

Open Ledger React is a comprehensive library for building financial dashboards and managing accounting data. It provides a set of React components and hooks for easy integration into your application.

Installation

npm install @openledger/accounting-react

Usage

To use the Open Ledger React library, you need to wrap your application with the OpenLedgerProvider and then use the exported components and hooks.

Setting up the Provider

import { OpenLedgerProvider } from '@openledger/accounting-react';

function App() {
  return (
    <OpenLedgerProvider
      entityId="your-entity-id"
      accessToken={{
        access_token: '',
        token_type: 'Bearer',
        expires_in: 3600,
        expires_at: new Date(2026, 1, 1),
      }}
      environment="development"
      theme={yourThemeObject}
      apiUrl={'your-api-url'}
    >
      {/* Your app components */}
    </OpenLedgerProvider>
  );
}

Warning: Without valid keys (entityId, enterpriseId, and enterpriseSecret), the package will throw errors. If you need to obtain these keys or have any issues, please reach out to the Open Ledger team at [email protected] for assistance.

Main Exports

1. OpenLedgerProvider: The main provider component that wraps your application.
2. useOpenLedgerContext: A hook to access the OpenLedger context within your components.
3. useTransactionContext: A hook to access transaction-related data and functions.
4. useAccountContext: A hook to access account-related data and functions.
5. TransactionTable: A component to display transaction data in a table format.
6. Dashboard: A pre-built dashboard view component.
7. OpenLedgerView: A comprehensive view component that includes various financial views.
8. TransactionsView: A component for displaying and managing transactions.
9. SettingsView: A component for managing application settings.
10. ReportView: A component for generating and displaying financial reports.

Using Components

import {
  OpenLedgerView,
  TransactionTable,
  DashboardBox,
} from '@openledger/accounting-react';

function MyComponent() {
  return (
    <div>
      <OpenLedgerView />
      <DashboardBox>{/* Custom widget content */}</DashboardBox>
    </div>
  );
}

Using Hooks

import {
  useOpenLedgerContext,
  useTransactionContext,
  useAccountContext,
} from '@openledger/accounting-react';

function MyCustomComponent() {
  const { auth, entityId, theme } = useOpenLedgerContext();
  const { transactions } = useTransactionContext();
  const { accounts } = useAccountContext();

  // Use the data in your component
}

Features

• Comprehensive financial dashboard
• Transaction management
• Account management
• Profit and Loss reporting
• Balance Sheet reporting
• Cash Flow Statement
• AI-powered financial reports
• Plaid integration for bank account connections
• Customizable theming

Configuration

The OpenLedgerProvider accepts the following props:

• entityId: Your company's unique identifier
• enterpriseId: Your enterprise ID for authentication
• enterpriseSecret: Your enterprise secret for authentication
• accessToken: (Optional) An access token if you're not using enterpriseId/secret
• environment: The environment to use ('development' or 'production')
• theme: A theme object to customize the appearance
• apiUrl: The URL of your API (required)

Contributing

Please read our contributing guidelines before submitting pull requests.

License

This project is licensed under the MIT License.

OpenLedger Accounting System

Accounting Principles

OpenLedger follows standard double-entry bookkeeping principles for all financial transactions:

Core Accounting Rules

1. Double-Entry System: Every transaction affects at least two accounts.
2. Balancing Principle: For every transaction, total debits must equal total credits.
3. Account Behaviors:
   • Assets and Expenses INCREASE with DEBITS and DECREASE with CREDITS
   • Liabilities, Equity, and Revenue INCREASE with CREDITS and DECREASE with DEBITS

Handling of Negative Amounts

The system handles negative amounts by treating them as reversals of the normal accounting effect:

1. Negative DEBIT: Effectively treated as a CREDIT
2. Negative CREDIT: Effectively treated as a DEBIT

This ensures proper accounting treatment for scenarios like:

• Revenue reversals (refunds)
• Asset returns
• Expense refunds
• Liability reductions

Example Scenarios

| Transaction | Amount | Direction | Effective Direction | Effect on Account | | ----------- | ------ | --------- | ------------------- | ---------------------- | | Sale | +$100 | CREDIT | CREDIT | INCREASE Revenue | | Refund | -$100 | CREDIT | DEBIT | DECREASE Revenue | | Purchase | +$500 | DEBIT | DEBIT | INCREASE Asset/Expense | | Return | -$500 | DEBIT | CREDIT | DECREASE Asset/Expense |

Financial Statements

All financial statements follow standard accounting conventions:

1. Profit & Loss: Shows revenue increase (credits) and expense increase (debits) over a period
2. Balance Sheet: Shows assets = liabilities + equity at a point in time
3. Cash Flow: Shows operating, investing, and financing activities affecting cash

Negative values in financial statements are displayed in parentheses following accounting convention.