# New API Analytics

Internal analytics dashboard for New API usage logs. The app reads PostgreSQL log data and visualizes calls, token consumption, model usage, channel usage, per-user aggregation, and raw request logs.

## Requirements

- Bun for local development and tests.
- Node.js 20 for the production Docker image.
- PostgreSQL database with New API tables described in `docs/database.md`.
- `PG_CONNECTION_STRING` set to a PostgreSQL connection string.

## Local Development

```bash
bun install
bun run dev
```

Open `http://localhost:3000`.

## Verification

```bash
bun test
bun run lint
bun run build
```

`bun test` covers parser helpers, metric conversion, query behavior, cache behavior, theme helpers, and selected API route guardrails.

Smoke test: AO/Codex can update this README, pass lint, and open a GitLab MR.

## Configuration

Create an environment file or export:

```bash
PG_CONNECTION_STRING=postgres://user:password@host:5432/database
```

The app uses this variable in `lib/db.ts` to create a `pg` connection pool.

OIDC authentication is optional. If no OIDC variables are set, the dashboard and API remain open.
To require login through a standard OIDC provider such as Sinodoor, add:

```bash
OIDC_ISSUER=https://casdoor.example.com
OIDC_CLIENT_ID=analytics
OIDC_CLIENT_SECRET=replace-me
AUTH_SECRET=replace-with-random-secret
NEXTAUTH_URL=https://your-analytics-domain
# Optional login button label:
OIDC_PROVIDER_NAME=Sinodoor
```

Generate `AUTH_SECRET` with a stable random value, for example:

```bash
openssl rand -base64 32
```

When OIDC is enabled, configure the provider redirect URI as:

```text
https://your-analytics-domain/api/auth/callback/oidc
```

`NEXTAUTH_URL` must be the same public `https://` origin that users open through the reverse proxy. This keeps login redirects and callback URLs from using the container listener such as `http://0.0.0.0:8019`.

Partial OIDC configuration is treated as an error instead of falling back to open access.

## Deployment

The included Dockerfile builds a standalone Next.js output and starts `server.js` on port `8019`.

```bash
docker compose up -d --build
```

The default `docker-compose.yml` expects `.env.production` and an external Docker network named `sinobridge`.

For Coolify deployments, use `docker-compose.coolify.yml`. It expects runtime environment variables from Coolify and an external Docker network named `coolify`.

## GitLab Manual Publish

Run the GitLab pipeline manually and set `DOCKER_LOGIN_COMMAND` to the full Huawei Cloud SWR login command.

Optional variables:

- `IMAGE_REPO`: defaults to `swr.cn-north-1.myhuaweicloud.com/sino-bridge/sinocode-analytics`
- `IMAGE_TAG`: defaults to the Git commit short SHA
- `PUSH_LATEST`: defaults to `true`

## Operational Notes

- API query parameters are validated at the route layer. Invalid integers or reversed date ranges return HTTP 400.
- Ranking limits are capped at 100 rows per request.
- Log page size is capped at 200 rows per request.
- Query results are cached in-process for 120 seconds with a 500-entry cap.
- Metric definitions and quota conversion are documented in `docs/metrics.md`.