npm package: @hasna/invoices
Description: Invoice generation and management for AI agents - CLI + MCP server + REST API + dashboard + SDK
Author: Andrei Hasna
Latest version: 0.1.1

# @hasna/invoices

Invoice generation and management for AI agents.

`@hasna/invoices` ships four surfaces in one repo:
- CLI (`invoices`)
- MCP server (`invoices-mcp`)
- REST API server (`invoices-serve`)
- Web dashboard (`dashboard/`)
- Typed Web/Node SDK (`sdk/` as `@hasna/invoices-sdk`)

## Features

- Local SQLite storage with WAL mode + migrations
- PostgreSQL migration support via `@hasna/cloud`
- Cloud sync push/pull between local SQLite and PostgreSQL
- Feedback delivery with remote send + local fallback persistence
- Invoice + line item CRUD with computed totals
- FTS5 search over invoice number, parties, and notes
- Agent registry (`register_agent`, `heartbeat`, `set_focus`, `list_agents`)
- MCP tools for invoice workflows
- Shadcn-based dashboard structure aligned with open-todos

## Install

```bash
bun add @hasna/invoices
```

## CLI

```bash
# initialize local SQLite schema
invoices db:migrate

# initialize PostgreSQL schema translated from local migrations
invoices db:migrate:pg

# cloud sync (all tables by default)
invoices cloud:push
invoices cloud:pull

# optional subset
invoices cloud:push --tables parties,invoices,invoice_lines

# feedback
invoices feedback:send --message "SDK auth flow failed on staging"

# create parties
invoices party:create --kind issuer --name "Hasna SRL"
invoices party:create --kind customer --name "ACME GmbH"

# create invoice
invoices invoice:create \
  --number INV-1001 \
  --issuer-id <ISSUER_ID> \
  --customer-id <CUSTOMER_ID> \
  --currency EUR \
  --line "Implementation:10:5000:1900"

# list/search/update
invoices invoice:list
invoices invoice:search "INV-1001"
invoices invoice:status <INVOICE_ID> sent

# agent lifecycle
invoices agent:register --name octavian
invoices agent:list
```

## REST API

Run server:

```bash
invoices-serve
```

Key endpoints:

- `GET /health`
- `POST /api/migrate`
- `POST /api/migrate/pg`
- `POST /api/cloud/push`
- `POST /api/cloud/pull`
- `POST /api/feedback`
- `GET|POST /api/parties`
- `GET|POST /api/invoices`
- `GET /api/invoices/search?q=...`
- `POST /api/invoices/:id/status`
- `GET /api/stats`
- `GET|POST /api/agents`
- `POST /api/agents/:id/heartbeat`
- `POST /api/agents/:id/focus`

## MCP

Run MCP stdio server:

```bash
invoices-mcp
```

Core tools:

- `migrate_database`, `migrate_postgres`
- `cloud_push`, `cloud_pull`, `send_feedback`
- `create_party`, `list_parties`
- `create_invoice`, `get_invoice`, `list_invoices`, `search_invoices`, `update_invoice_status`, `delete_invoice`
- `register_agent`, `heartbeat`, `set_focus`, `list_agents`

## Dashboard

```bash
cd dashboard
bun install
bun run dev
```

Set API base if needed:

```bash
export VITE_API_BASE_URL=http://localhost:3487
```

## Security

- Optional API auth via `INVOICES_API_KEY`
- Optional CORS allowlist via `INVOICES_ALLOWED_ORIGIN`
- Security reports are stored under `reports/`

## Development

```bash
bun install
cd dashboard && bun install && cd ..
cd sdk && bun install && cd ..

bun run typecheck
bun run build
bun test
```

## License

Apache-2.0