Skip to content

README.md

Latest commit

 

History

History
113 lines (83 loc) · 3.46 KB

README.md

File metadata and controls

113 lines (83 loc) · 3.46 KB

Callora Backend

API gateway, usage metering, and billing services for the Callora API marketplace. Talks to Soroban contracts and Horizon for on-chain settlement.

Tech stack

  • Node.js + TypeScript
  • Express for HTTP API
  • Planned: Horizon listener, PostgreSQL, billing engine

What's included

  • Health check: GET /api/health
  • Placeholder routes: GET /api/apis, GET /api/usage
  • JSON body parsing; ready to add auth, metering, and contract calls
  • In-memory VaultRepository with:
    • create(userId, contractId, network)
    • findByUserId(userId, network)
    • updateBalanceSnapshot(id, balance, lastSyncedAt)

Vault repository behavior

<<<<<<< HEAD Endpoint:

GET /api/developers/analytics

Authentication:

  • Requires x-user-id header (developer identity for now).

Query params:

  • from (required): ISO date/time
  • to (required): ISO date/time
  • groupBy (optional): day | week | month (default: day)
  • apiId (optional): filters to one API (must belong to authenticated developer)
  • includeTop (optional): set to true to include topEndpoints and anonymized topUsers =======
  • Enforces one vault per user per network.
  • balanceSnapshot is stored in smallest units using non-negative integer bigint values.
  • findByUserId is network-aware and returns the vault for a specific user/network pair.

main

Local setup

  1. Prerequisites: Node.js 18+

  2. Install and run (dev):

    cd callora-backend
npm install
npm run dev

<<<<<<< HEAD

  1. API base: http://localhost:3000

Docker Setup

You can run the entire stack (API and PostgreSQL) locally using Docker Compose:

docker compose up --build

The API will be available at http://localhost:3000, and the PostgreSQL database will be mapped to local port 5432.

  1. API base: http://localhost:3000. Example: http://localhost:3000/api/health.

main

Scripts

Command Description
npm run dev Run with tsx watch (no build)
npm run build Compile TypeScript to dist/
npm start Run compiled dist/index.js
npm test Run unit tests
npm run test:coverage Run unit tests with coverage

Observability (Prometheus Metrics)

The application exposes a standard Prometheus text-format metrics endpoint at GET /api/metrics. It automatically tracks http_requests_total, http_request_duration_seconds, and default Node.js system metrics.

Production Security:

In production (NODE_ENV=production), this endpoint is protected. You must configure the METRICS_API_KEY environment variable and scrape the endpoint using an authorization header: Authorization: Bearer <YOUR_METRICS_API_KEY>

Project layout

callora-backend/
|-- src/
|   |-- index.ts                          # Express app and routes
|   |-- repositories/
|       |-- vaultRepository.ts            # Vault repository implementation
|       |-- vaultRepository.test.ts       # Unit tests
|-- package.json
|-- tsconfig.json

Environment

<<<<<<< HEAD

  • PORT — HTTP port (default: 3000). Optional for local dev.

This repo is part of Callora. Frontend: callora-frontend. Contracts: callora-contracts.

  • PORT - HTTP port (default: 3000). Optional for local dev.

This repo is part of Callora. Frontend: callora-frontend. Contracts: callora-contracts.

main