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/usand/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
- Loads environment values from
.envif the file exists. - Resolves ports for PostgreSQL and Redis, then rewrites
DATABASE_URLandREDIS_URLto match the chosen ports. - Frees the requested API port if it is already bound.
- Starts the compose stack with
docker_compose up -d. - Ensures the target database exists in PostgreSQL.
- Runs
pnpm install. - Pushes Prisma schema changes with
pnpm -C packages/db prisma db push. - Creates ephemeral JWT key pairs when the regional token keys are not already present.
- 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 pipefailfor 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
- Starts
scripts/run-api.shin the background. - Polls
GET /healthzuntil it succeeds or the timeout is reached. - Reads the published PostgreSQL and Redis ports from Docker Compose.
- Runs
pnpm -C packages/db prisma db pushagainst the runtime database. - Runs
scripts/check-api.shfor the public probes. - Runs
scripts/seed-dev-auth.shwith the runtime database and Redis URLs. - Runs
scripts/check-all-api-paths.shagainst the local base URL. - 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-keyby default. - Uses
AUTO_SEED_AUTH=1by 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
REGIONvalue other thanusorjp. - 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-keyTENANT_NAME=dev-tenantCLIENT_NAME=dev-client
- Creates a tenant if one does not already exist.
- Upserts an
apiClientrecord with:clientIdequal toAPI_KEYclientSecretHashset todevscopesset 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
Create US Consent
{
"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}"
}
}
}
Exchange US Consent Token
{
"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}"
}
}
}
Get US Consent Receipt
{
"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": "[]"
}
}
}
Revoke US Consent
{
"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
Create JP Consent
{
"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}"
}
}
}
Exchange JP Consent Token
{
"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}"
}
}
}
Get JP Consent Receipt
{
"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": "[]"
}
}
}
Revoke JP Consent
{
"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
pnpmfor package management and Prisma execution.- Docker, via
docker-composeordocker compose, for local PostgreSQL and Redis startup. curlfor all endpoint validation.jqfor JSON parsing in smoke checks.lsof,ss, ornetstatfor API port detection inscripts/run-api.sh.fuseras an alternative port killer inscripts/run-api.sh.- Prisma in
packages/dbforprisma db push. - Local RSA key generation through Node’s
generateKeyPairSyncinscripts/run-api.sh.
Error Handling
The scripts use strict shell modes and fail fast on command errors:
set -euo pipefailis used throughout the Bash scripts.curl -fsSaborts on HTTP failures and produces non-zero exit codes for the smoke checks.scripts/check-local-api.shenforces a startup timeout when waiting for/healthz.scripts/test-use-cases.shrejects unsupportedREGIONvalues and unknown case names.scripts/run-api.shstops early whenpnpmor Docker is unavailable.
Testing Considerations
- Verify that
scripts/run-api.shcan start with a free API port and can recover when the default port is already bound. - Verify that
scripts/check-api.shpasses against a running local API before any auth seeding. - Verify that
scripts/check-local-api.shcompletes the full sequence: bootstrap, health probe, Prisma push, dev auth seeding, and smoke validation. - Verify that
scripts/check-all-api-paths.shworks both with defaultAUTO_SEED_AUTH=1and with pre-seeded auth. - Verify that
scripts/test-use-cases.shcovers each case selector:healthconsentdatafeaturesdecisionfullall
- Verify both
REGION=usandREGION=jpflows, 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. |