API daemon: HTTP API mode for product and AI Agent billing integrations

[wauputr4]

Goal

Add an optional HTTP API daemon mode so products, backend services, automations, and AI / AI Agent orchestration can call Rute Bayar without shelling out per payment operation.

Example target command:

rute-bayar api serve --addr :8081 --environment sandbox --db ./rute-bayar.sqlite3

Why

• Enables dynamic billing by product, tenant, provider, AI Agent run, usage, or workflow.
• Keeps provider integration modular behind one internal API.
• Lets product systems switch between providers without embedding gateway-specific logic.
• Gives the future Web UI a stable backend surface.
• Allows external systems to create payments, check payment status, request refunds, and inspect webhook/forwarding state.

MVP Scope

• Add api serve command.
• Add API daemon package or reuse the existing daemon HTTP routing pattern where appropriate.
• Add GET /healthz.
• Add JSON API auth with a simple static bearer token to start, for example RUTE_BAYAR_API_TOKEN.
• Document that the API must not be exposed publicly without TLS and auth.
• Return consistent JSON error shapes.
• Reuse existing services instead of duplicating provider logic.

Initial Endpoints

• POST /api/v1/payments: create payment through existing provider adapters.
• GET /api/v1/payments/{reference}: read provider-neutral payment status.
• POST /api/v1/refunds: request refund.
• GET /api/v1/providers: list supported providers and configured accounts.
• GET /api/v1/webhooks/events: inspect received webhook events.
• GET /api/v1/forwarding/attempts: inspect forwarding delivery attempts.

AI / AI Agent Billing Use Cases

• Agent runner creates a payment after calculating usage.
• Product backend chooses provider dynamically based on product, tenant, or availability.
• AI workflow stores payment reference using agent_run_id, tenant_id, or product_id.
• Webhook forwarding notifies AI orchestration when payment succeeds or refund status changes.

Non-Goals

• No hosted SaaS auth model yet.
• No multi-user dashboard in this issue.
• No Web UI implementation here.
• No provider-specific business UI here.

Acceptance Criteria

• rute-bayar api serve starts successfully and returns GET /healthz.
• API requests require auth when token is configured.
• Payment create/status/refund endpoints call existing service paths.
• Raw provider inbound/outbound JSON storage remains unchanged.
• Unit tests cover auth, validation, service wiring, and error response shape.
• README/docs include local API daemon usage and production security notes.