Operations, Local Development, and Test Automation

Overview

This part of the repository provides the local operator path for bringing the API stack up, verifying that the service is healthy, and exercising the regional US and JP endpoint sets end to end. The scripts are designed to work together: scripts/run-api.sh bootstraps the runtime, scripts/check-api.sh and scripts/check-local-api.sh gate readiness, scripts/check-all-api-paths.sh performs a broad smoke sweep, and scripts/test-use-cases.sh runs scenario-based checks.

The flow is API-first and database-aware. Local startup initializes Docker-backed dependencies, pushes the Prisma schema into the database, creates the default dev API client when needed, and then validates public probes before moving into authenticated consent, token, data, evidence, and decision lifecycle calls.

Architecture Overview

flowchart TB
    subgraph Bootstrap [Local Bootstrap and Smoke Orchestration]
        RunApi[run-api.sh]
        CheckApi[check-api.sh]
        CheckLocal[check-local-api.sh]
        CheckAll[check-all-api-paths.sh]
        TestCases[test-use-cases.sh]
        SeedAuth[seed-dev-auth.sh]
    end

    subgraph Runtime [Local Runtime]
        Compose[Docker Compose runtime]
        Postgres[(PostgreSQL)]
        Redis[(Redis)]
        Prisma[Prisma db push]
        Api[Fastify API]
    end

    subgraph ProbeLayer [Health and Smoke Probes]
        Health[healthz readyz openapi]
        USFlow[US lifecycle flow]
        JPFlow[JP lifecycle flow]
    end

    RunApi --> Compose
    Compose --> Postgres
    Compose --> Redis
    RunApi --> Prisma
    RunApi --> Api

    CheckLocal --> RunApi
    CheckLocal --> CheckApi
    CheckLocal --> SeedAuth
    CheckLocal --> CheckAll

    CheckApi --> Health
    CheckAll --> Health
    CheckAll --> USFlow
    CheckAll --> JPFlow

    TestCases --> Health
    TestCases --> USFlow
    TestCases --> JPFlow

Local Bootstrap and Runtime Wiring

scripts/run-api.sh

[!IMPORTANT] The smoke scripts are wired to the regional API surfaces under /api/v1/us and /api/v1/jp. They exercise both partner-authenticated calls with the API key and user/access-token calls produced during the consent token exchange.

scripts/run-api.sh

This is the bootstrap entrypoint for a local API session. It loads .env when present, checks for pnpm and Docker, chooses available ports for PostgreSQL, Redis, and the API itself, starts the Docker Compose stack, ensures the target database exists, pushes the Prisma schema, generates ephemeral JWT keys if needed, and finally launches the dev server with pnpm dev.

Shell functions

Function Description
extract_port Reads a port number from a URL string.
port_in_use Detects whether a TCP port is already listening.
find_available_port Searches upward from a starting port until a free port is found.
set_url_port Rewrites a URL to point at a new port.
docker_compose Wraps docker-compose and docker compose.
extract_database_name Extracts the database name from DATABASE_URL.
ensure_database_exists Waits for PostgreSQL and creates the target database if it does not exist.
stop_port_listener Kills an existing listener on the requested API port when possible.
ensure_dev_jwt_keys Generates local RSA signing keys and exports them for US and JP token flows.

Execution flow

  1. Loads environment values from .env if the file exists.
  2. Resolves ports for PostgreSQL and Redis, then rewrites DATABASE_URL and REDIS_URL to match the chosen ports.
  3. Frees the requested API port if it is already bound.
  4. Starts the compose stack with docker_compose up -d.
  5. Ensures the target database exists in PostgreSQL.
  6. Runs pnpm install.
  7. Pushes Prisma schema changes with pnpm -C packages/db prisma db push.
  8. Creates ephemeral JWT key pairs when the regional token keys are not already present.
  9. Starts the API in dev mode with pnpm dev.

Bootstrap sequence

sequenceDiagram
    participant Operator as Operator
    participant RunApi as run-api.sh
    participant Compose as Docker Compose
    participant Postgres as PostgreSQL
    participant Redis as Redis
    participant Prisma as Prisma db push
    participant Dev as pnpm dev

    Operator->>RunApi: start local API
    RunApi->>Compose: up -d
    Compose->>Postgres: start service
    Compose->>Redis: start service
    RunApi->>Postgres: ensure database exists
    RunApi->>Prisma: prisma db push
    RunApi->>Dev: pnpm dev
    Dev-->>Operator: API listening on local port

Docker Compose runtime manifests

docker-compose.yml and docker-compose.api.yml

These compose files are the runtime layer consumed by scripts/run-api.sh. The scripts rely on the postgres and redis services being available through published ports, and they query those ports with docker-compose port or docker compose port before building local database and Redis URLs.

Health Checks

scripts/check-api.sh

scripts/check-api.sh

This is the simplest readiness probe. It checks the three public endpoints used by the rest of the local tooling: /healthz, /readyz, and /openapi.json.

Shell functions

Function Description
check_endpoint Performs a fail-fast curl request and exits if the endpoint is unreachable.

Behavior

  • Uses set -euo pipefail for strict failure handling.
  • Validates each endpoint independently.
  • Prints OK <url> after each successful check.

scripts/check-local-api.sh

scripts/check-local-api.sh

This is the full local bootstrap-and-verify script. It starts the API in the background with scripts/run-api.sh, waits for /healthz to respond, resolves the runtime PostgreSQL and Redis ports, pushes the Prisma schema again against the runtime database, runs the public health checks, seeds the dev auth client, and then executes the complete regional smoke sweep.

Shell functions

Function Description
cleanup Stops the background API process on exit, interrupt, or termination.
dc Wraps docker-compose and docker compose.
published_port Reads the published port for a Docker Compose service.

Execution flow

  1. Starts scripts/run-api.sh in the background.
  2. Polls GET /healthz until it succeeds or the timeout is reached.
  3. Reads the published PostgreSQL and Redis ports from Docker Compose.
  4. Runs pnpm -C packages/db prisma db push against the runtime database.
  5. Runs scripts/check-api.sh for the public probes.
  6. Runs scripts/seed-dev-auth.sh with the runtime database and Redis URLs.
  7. Runs scripts/check-all-api-paths.sh against the local base URL.
  8. Prints ✅ Local API full check completed successfully. when the full pass succeeds.

Health validation sequence

sequenceDiagram
    participant Runner as check-local-api.sh
    participant RunApi as run-api.sh
    participant CheckApi as check-api.sh
    participant SeedAuth as seed-dev-auth.sh
    participant CheckAll as check-all-api-paths.sh
    participant API as Fastify API
    participant DB as PostgreSQL
    participant Redis as Redis

    Runner->>RunApi: start API in background
    Runner->>API: poll healthz
    Runner->>DB: prisma db push
    Runner->>CheckApi: validate public probes
    Runner->>SeedAuth: create dev tenant and api client
    Runner->>CheckAll: run regional smoke tests
    CheckAll->>API: authenticated US and JP calls
    CheckAll-->>Runner: success marker

Smoke Test Automation

scripts/check-all-api-paths.sh

scripts/check-all-api-paths.sh

This script performs the broadest endpoint sweep in the repository. It loads .env if present, resolves runtime database connectivity through Docker Compose, optionally seeds the dev auth client, validates the public health endpoints, and then runs the full US and JP lifecycle flow with real token exchange and downstream data calls.

Shell functions

Function Description
need Verifies that a required command such as curl or jq exists.
dc Wraps docker-compose and docker compose.
published_port Reads the published Docker Compose port for a service.

Behavior

  • Uses API_KEY=dev-key by default.
  • Uses AUTO_SEED_AUTH=1 by default.
  • If auto-seeding is enabled, it:
    • derives the runtime database URL from the published PostgreSQL port,
    • runs pnpm -C packages/db prisma db push,
    • calls ./scripts/seed-dev-auth.sh.
  • Validates:
    • /healthz
    • /readyz
    • /openapi.json
  • Exercises both US and JP consent lifecycles.
  • Ends with ✅ API smoke checks completed successfully.

Smoke flow sequence

sequenceDiagram
    participant Smoke as check-all-api-paths.sh
    participant API as Fastify API
    participant DB as PostgreSQL
    participant Seed as seed-dev-auth.sh

    Smoke->>DB: prisma db push
    Smoke->>Seed: seed dev auth
    Smoke->>API: healthz readyz openapi.json
    Smoke->>API: US consent lifecycle
    Smoke->>API: JP consent lifecycle
    Smoke-->>Smoke: completed successfully

scripts/test-use-cases.sh

scripts/test-use-cases.sh

This script is the scenario runner. It accepts a REGION of us or jp and a case selector that chooses a narrower flow: health, consent, data, features, decision, full, or all. It builds per-request IDs from the current timestamp, injects the right authorization header for each class of request, and automatically sets content-type: application/json when a body is present.

Shell functions

Function Description
need Verifies that a required command exists.
request_id Builds a unique x-request-id value for each call.
partner_header Builds the partner API-key authorization header.
access_header Builds the lower-case access-token authorization header used by user-token calls.
xrid_header Builds the request-id header.
api Executes a curl request with optional JSON body.
health Checks the public health endpoints.
create_consent_and_tokens Creates a consent and exchanges the authorization code for tokens.
case_consent Runs consent receipt, introspection, refresh, and revoke checks.
case_data Runs accounts, balances, transactions, sync, and income checks.
case_features Computes features and fetches evidence.
case_decision Computes features and replays a decision.
usage Prints the supported command-line cases.

Case selection

Case Behavior
health Public endpoints only.
consent Consent and token lifecycle.
data Accounts, balances, transactions, sync, and income endpoints.
features Feature compute plus evidence fetch.
decision Decision replay flow.
full Consent, data, features, and decision.
all Health plus the full flow.

Script-level validation

  • Rejects any REGION value other than us or jp.
  • Rejects unknown case names.
  • Prints ✅ use-case checks complete (<region>, case=<case>) on success.

Use-case flow

sequenceDiagram
    participant Runner as test-use-cases.sh
    participant API as Fastify API

    Runner->>API: healthz readyz openapi.json
    Runner->>API: create consent
    Runner->>API: exchange token
    Runner->>API: fetch data or features
    Runner->>API: replay decision or revoke consent
    Runner-->>Runner: use-case checks complete

Dev Auth Seeding

scripts/seed-dev-auth.sh

scripts/seed-dev-auth.sh

This script seeds the default local API client used by the smoke tests. It creates or reuses a tenant and upserts an API client record keyed by API_KEY.

Behavior

  • Defaults:
    • API_KEY=dev-key
    • TENANT_NAME=dev-tenant
    • CLIENT_NAME=dev-client
  • Creates a tenant if one does not already exist.
  • Upserts an apiClient record with:
    • clientId equal to API_KEY
    • clientSecretHash set to dev
    • scopes set to ["*"]
  • Prints:
    • tenant_id=...
    • api_key=...

Data flow

sequenceDiagram
    participant Seed as seed-dev-auth.sh
    participant DB as PrismaClient
    participant Tenant as tenant table
    participant Client as apiClient table

    Seed->>DB: create tenant
    Seed->>DB: upsert apiClient
    DB->>Tenant: write tenant row
    DB->>Client: write api client row
    Seed-->>Seed: print tenant_id and api_key

HTTP Endpoints Exercised by the Scripts

Public probes

Health Check

{
    "title": "Health Check",
    "description": "Public liveness probe used by the local bootstrap scripts.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/healthz",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Readiness Check

{
    "title": "Readiness Check",
    "description": "Public readiness probe used by the local bootstrap scripts.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/readyz",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

OpenAPI Document

{
    "title": "OpenAPI Document",
    "description": "Returns the OpenAPI JSON document validated by the smoke scripts.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/openapi.json",
    "headers": [],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

US lifecycle flow

{
    "title": "Create US Consent",
    "description": "Creates a US consent record for the smoke flow.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"applicant_id\": \"app_us_1\",\n    \"purpose\": \"GENERAL_PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"ACCOUNTS\",\n        \"BALANCES\",\n        \"TRANSACTIONS\",\n        \"INCOME\",\n        \"CASHFLOW_FEATURES\"\n    ],\n    \"expires_in_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"us_consent_123\"\n}"
        }
    }
}
{
    "title": "Exchange US Consent Token",
    "description": "Exchanges the authorization code for US access and refresh tokens.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/token",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"authorization_code\": \"ok\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"access_token\": \"us_access_token_example\",\n    \"refresh_token\": \"us_refresh_token_example\"\n}"
        }
    }
}
{
    "title": "Get US Consent Receipt",
    "description": "Fetches the receipt for a US consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/receipt",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get US Accounts

{
    "title": "Get US Accounts",
    "description": "Fetches the accounts dataset for a US consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/data/accounts",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get US Balances

{
    "title": "Get US Balances",
    "description": "Fetches the balances dataset for a US consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/data/balances",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get US Transactions

{
    "title": "Get US Transactions",
    "description": "Fetches the transactions dataset for a US consent within the requested date range.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/data/transactions",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "start_date",
            "required": true,
            "description": "Inclusive start date in ISO 8601 format"
        },
        {
            "key": "end_date",
            "required": true,
            "description": "Inclusive end date in ISO 8601 format"
        }
    ],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Sync US Transactions

{
    "title": "Sync US Transactions",
    "description": "Triggers the US transaction sync flow with a cursor.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions/sync",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "cursor",
            "required": true,
            "description": "Sync cursor value"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get US Income

{
    "title": "Get US Income",
    "description": "Fetches the income dataset for a US consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/data/income",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Compute US Features

{
    "title": "Compute US Features",
    "description": "Computes feature output and returns the evidence reference for the US flow.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/features/compute",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "json",
    "requestBody": "[]",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"evidence_ref\": \"us_evidence_123\"\n}"
        }
    }
}

Get US Evidence

{
    "title": "Get US Evidence",
    "description": "Fetches the evidence document by reference using the partner API key.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/evidence/{evidence_ref}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidence_ref",
            "required": true,
            "description": "Evidence reference returned by the feature compute call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Replay US Decision

{
    "title": "Replay US Decision",
    "description": "Replays the decision flow using an evidence reference.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/decisions/replay",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"evidence_ref\": \"us_evidence_123\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Refresh US Token

{
    "title": "Refresh US Token",
    "description": "Refreshes the US token pair using the partner API key.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/tokens/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"refresh_token\": \"us_refresh_token_example\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Introspect US Token

{
    "title": "Introspect US Token",
    "description": "Introspects a US access token with the partner API key.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/tokens/introspect",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"token\": \"us_access_token_example\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}
{
    "title": "Revoke US Consent",
    "description": "Revokes a US consent using the partner API key.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/us/consents/{consent_id}/revoke",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

JP lifecycle flow

{
    "title": "Create JP Consent",
    "description": "Creates a JP consent record for the smoke flow.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"applicant_id\": \"app_jp_1\",\n    \"purpose\": \"GENERAL_PERSONAL_FINANCE\",\n    \"data_categories\": [\n        \"ACCOUNTS\",\n        \"BALANCES\",\n        \"TRANSACTIONS\",\n        \"INCOME\",\n        \"CASHFLOW_FEATURES\"\n    ],\n    \"expires_in_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"consent_id\": \"jp_consent_123\"\n}"
        }
    }
}
{
    "title": "Exchange JP Consent Token",
    "description": "Exchanges the authorization code for JP access and refresh tokens.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/token",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"authorization_code\": \"ok\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"access_token\": \"jp_access_token_example\",\n    \"refresh_token\": \"jp_refresh_token_example\"\n}"
        }
    }
}
{
    "title": "Get JP Consent Receipt",
    "description": "Fetches the receipt for a JP consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/receipt",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get JP Accounts

{
    "title": "Get JP Accounts",
    "description": "Fetches the accounts dataset for a JP consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/data/accounts",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get JP Balances

{
    "title": "Get JP Balances",
    "description": "Fetches the balances dataset for a JP consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/data/balances",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get JP Transactions

{
    "title": "Get JP Transactions",
    "description": "Fetches the transactions dataset for a JP consent within the requested date range.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/data/transactions",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "start_date",
            "required": true,
            "description": "Inclusive start date in ISO 8601 format"
        },
        {
            "key": "end_date",
            "required": true,
            "description": "Inclusive end date in ISO 8601 format"
        }
    ],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Sync JP Transactions

{
    "title": "Sync JP Transactions",
    "description": "Triggers the JP transaction sync flow with a cursor.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/data/transactions/sync",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "cursor",
            "required": true,
            "description": "Sync cursor value"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Get JP Income

{
    "title": "Get JP Income",
    "description": "Fetches the income dataset for a JP consent.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/data/income",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Compute JP Features

{
    "title": "Compute JP Features",
    "description": "Computes feature output and returns the evidence reference for the JP flow.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/features/compute",
    "headers": [
        {
            "key": "authorization",
            "value": "Bearer <access_token>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "json",
    "requestBody": "[]",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"evidence_ref\": \"jp_evidence_123\"\n}"
        }
    }
}

Get JP Evidence

{
    "title": "Get JP Evidence",
    "description": "Fetches the evidence document by reference using the partner API key.",
    "method": "GET",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/evidence/{evidence_ref}",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "evidence_ref",
            "required": true,
            "description": "Evidence reference returned by the feature compute call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Replay JP Decision

{
    "title": "Replay JP Decision",
    "description": "Replays the decision flow using an evidence reference.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/decisions/replay",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"evidence_ref\": \"jp_evidence_123\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Refresh JP Token

{
    "title": "Refresh JP Token",
    "description": "Refreshes the JP token pair using the partner API key.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/tokens/refresh",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"refresh_token\": \"jp_refresh_token_example\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Introspect JP Token

{
    "title": "Introspect JP Token",
    "description": "Introspects a JP access token with the partner API key.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/tokens/introspect",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        },
        {
            "key": "content-type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"token\": \"jp_access_token_example\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}
{
    "title": "Revoke JP Consent",
    "description": "Revokes a JP consent using the partner API key.",
    "method": "POST",
    "baseUrl": "<LocalApiBaseUrl>",
    "endpoint": "/api/v1/jp/consents/{consent_id}/revoke",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <api_key>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_id",
            "required": true,
            "description": "Consent identifier returned by the consent creation call"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "[]"
        }
    }
}

Dependencies

  • pnpm for package management and Prisma execution.
  • Docker, via docker-compose or docker compose, for local PostgreSQL and Redis startup.
  • curl for all endpoint validation.
  • jq for JSON parsing in smoke checks.
  • lsof, ss, or netstat for API port detection in scripts/run-api.sh.
  • fuser as an alternative port killer in scripts/run-api.sh.
  • Prisma in packages/db for prisma db push.
  • Local RSA key generation through Node’s generateKeyPairSync in scripts/run-api.sh.

Error Handling

The scripts use strict shell modes and fail fast on command errors:

  • set -euo pipefail is used throughout the Bash scripts.
  • curl -fsS aborts on HTTP failures and produces non-zero exit codes for the smoke checks.
  • scripts/check-local-api.sh enforces a startup timeout when waiting for /healthz.
  • scripts/test-use-cases.sh rejects unsupported REGION values and unknown case names.
  • scripts/run-api.sh stops early when pnpm or Docker is unavailable.

Testing Considerations

  • Verify that scripts/run-api.sh can start with a free API port and can recover when the default port is already bound.
  • Verify that scripts/check-api.sh passes against a running local API before any auth seeding.
  • Verify that scripts/check-local-api.sh completes the full sequence: bootstrap, health probe, Prisma push, dev auth seeding, and smoke validation.
  • Verify that scripts/check-all-api-paths.sh works both with default AUTO_SEED_AUTH=1 and with pre-seeded auth.
  • Verify that scripts/test-use-cases.sh covers each case selector:
    • health
    • consent
    • data
    • features
    • decision
    • full
    • all
  • Verify both REGION=us and REGION=jp flows, because the paths and token flows are region-scoped.

Key Classes Reference

Class Responsibility
run-api.sh Boots Docker dependencies, prepares the database, generates local JWT keys, and starts the API.
check-api.sh Validates /healthz, /readyz, and /openapi.json.
check-local-api.sh Orchestrates startup, readiness polling, auth seeding, and the full smoke check.
check-all-api-paths.sh Runs the full US and JP path sweep, including optional dev auth seeding.
test-use-cases.sh Runs selectable health, consent, data, feature, and decision scenarios by region.
seed-dev-auth.sh Creates the default dev tenant and API client used by the smoke tests.
docker-compose.yml Provides the local runtime stack consumed by the bootstrap script.
docker-compose.api.yml Provides the API-focused compose layer consumed by the bootstrap script.