@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

bun add @hasna/invoices

CLI

# 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:

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:

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

cd dashboard
bun install
bun run dev

Set API base if needed:

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

bun install
cd dashboard && bun install && cd ..
cd sdk && bun install && cd ..

bun run typecheck
bun run build
bun test

License

Apache-2.0