npm package: @openledger/accounting-react
Description: 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.
Latest version: 1.1.64

# 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

```bash
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

```jsx
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 <info@openledger.com>
> 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

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

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

### Using Hooks

```jsx
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.