# Digits

Fetch ledger entries from Digits' API, with OAuth2 token refresh and account filtering.

## Setup

### Option 1: Credentials file (recommended)

Create a JSON credentials file with your Digits OAuth2 credentials:

```json
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "access_token": "your_access_token",
  "refresh_token": "your_refresh_token",
  "legal_entity_id": "le_xxx"
}
```

Save it with restricted permissions:

```bash
chmod 600 ~/.config/vgrid/digits.json
```

VisiGrid will automatically refresh the access token using the refresh token and update the file in place.

### Option 2: Direct access token

Pass a valid access token and legal entity ID directly:

```bash
vgrid fetch digits --access-token eyJ... --legal-entity-id le_123 \
  --from 2026-01-01 --to 2026-01-31
```

This mode skips token refresh, so the token must be unexpired.

## Usage

```bash
vgrid fetch digits --credentials ~/.config/vgrid/digits.json \
  --from 2026-01-01 --to 2026-01-31 --out digits.csv
```

Filter to a specific account:

```bash
vgrid fetch digits --credentials ~/.config/vgrid/digits.json \
  --from 2026-01-01 --to 2026-01-31 \
  --account "Operating Account" --out digits.csv
```

Fetch only credits:

```bash
vgrid fetch digits --credentials ~/.config/vgrid/digits.json \
  --from 2026-01-01 --to 2026-01-31 --include credit --out digits.csv
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `--from` | Start date inclusive (YYYY-MM-DD) | required |
| `--to` | End date exclusive (YYYY-MM-DD) | required |
| `--credentials` | Path to OAuth2 credentials JSON file | — |
| `--access-token` | Digits access token (requires `--legal-entity-id`) | — |
| `--legal-entity-id` | Digits legal entity ID | — |
| `--account` | Filter by account name | all accounts |
| `--account-id` | Filter by account ID | all accounts |
| `--include` | Entry types to include, comma-separated | `credit,debit` |
| `--out` | Output CSV path | stdout |
| `-q` / `--quiet` | Suppress progress messages | off |

## Type mapping

Digits entries use `credit` and `debit` types directly as the canonical type. These are the only valid values for the `--include` filter.

| Digits type | Canonical type | Sign |
|---|---|---|
| `credit` | `credit` | positive |
| `debit` | `debit` | negative |

## Date handling

- **`effective_date`** — entry date from the Digits API (YYYY-MM-DD)
- **`posted_date`** — same as effective date

## Notes

**OAuth2 token refresh.** When using a credentials file, VisiGrid automatically refreshes the access token if it's expired and writes the updated token back to the file. The file must be writable.

**File permissions.** On Unix systems, VisiGrid warns if the credentials file has group or world-readable permissions (mode should be `0600`).

**Account filtering.** Use `--account` to filter by account name (exact match) or `--account-id` to filter by account ID. When no filter is specified, entries from all accounts are included.

**Source ID format.** Entry IDs are prefixed with `entry:` (e.g. `entry:ent_001`).