{ "openapi": "3.1.0", "info": { "title": "touch-api", "version": "0.0.0-derived", "summary": "NestJS + TypeORM API. Spec reconstructed from a single source file (src/app.module.ts).", "description": "# touch-api — reconstructed API contract\n\nGenerated from **one file only**: `src/app.module.ts` (provided as `api_structure.txt`).\nIt carries no controllers, so the endpoint list below is two-tier:\n\n| Tier | Meaning | Marker |\n|------|---------|--------|\n| **A — verified** | Literally readable in `src/app.module.ts`. | `x-source: \"api_structure.txt:src/app.module.ts\"` |\n| **B — inferred** | Derived from the module *name* + NestJS conventions. **Not** proof a route exists. | `x-source: \"inferred\"` |\n\n## Literally verified\n\n* NestJS (`@nestjs/common`, `@nestjs/config`, `@nestjs/typeorm`).\n* TypeORM datasource from `DB_STRING`: `ormConfig.url = configService.get(\"DB_STRING\")`,\n options loaded from `ormconfig.js` at the project root.\n* In-house packages `@touch-api/logging`, `@touch-api/ip-allowlist`.\n* 8 feature modules: `auth`, `account`, `common`, `message`, `settings`, `user`,\n `legacy-api-bridge`, `redis-storage`.\n* Global `IpAllowlistMiddleware` on `forRoutes(\"*\")` + `applyLoggingMiddlewares(consumer)`.\n* Allowlist **bypass paths** — the only routes this document can assert:\n `/`, `/health`, `/health/v2`.\n* Allowlist config: file `IP_ALLOWLIST_FILE` (default `/etc/touch-api/ip-allowlist.conf`),\n mode `IP_ALLOWLIST_MODE` (default `AllowlistMode.Off`), trusted header `x-real-ip`,\n `trustSocketFallback: false`, on-block log\n `ip-allowlist block|would-block ip=… path=…`.\n\n## Error envelope\n\nNestJS default exception filter: `{\"statusCode\":…,\"message\":…,\"error\":…}`. Tier B.\n", "contact": { "name": "touch-api (derived spec)", "url": "https://example.com/touch-api" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" }, "x-spec-provenance": { "generated_from": [ "src/app.module.ts" ], "raw_file": "/opt/2026-08-06-touchapi-api-cascade-research/api_structure.txt", "raw_file_bytes": 2248, "raw_file_lines": 61, "verified_route_basis": [ "/", "/health", "/health/v2" ], "module_candidates": [ "auth", "account", "common", "message", "settings", "user", "legacy-api-bridge", "redis-storage" ], "caveat": "No controllers, DTOs or entities were provided. Tier-B operations are reconstructions." } }, "servers": [ { "url": "http://localhost:3000", "description": "NestJS default port (assumed) — Tier B" }, { "url": "/", "description": "Same origin as this documentation" } ], "tags": [ { "name": "Health", "description": "Allowlist-bypass routes. **Verified** in `bypassPaths` — api_structure.txt:src/app.module.ts" }, { "name": "Auth", "description": "`AuthModule` / realizations/auth. Module import verified; endpoints inferred." }, { "name": "Account", "description": "`AccountModule` / realizations/account. Module import verified; endpoints inferred." }, { "name": "User", "description": "`UserModule` / realizations/user. Module import verified; endpoints inferred." }, { "name": "Message", "description": "`MessageModule` / realizations/message. Module import verified; endpoints inferred." }, { "name": "Settings", "description": "`SettingsModule` / realizations/settings. Module import verified; endpoints inferred." }, { "name": "Common", "description": "`CommonModule` / realizations/common. Module import verified; endpoints inferred." }, { "name": "Legacy API Bridge", "description": "`LegacyApiModule` / realizations/legacy-api-bridge. Module import verified; endpoints inferred." }, { "name": "Redis Storage", "description": "`RedisStorageModule` / realizations/redis-storage. Module import verified; endpoints inferred." }, { "name": "Infrastructure", "description": "Cross-cutting: IP allowlist, logging, config — api_structure.txt:src/app.module.ts" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "inferred: AuthModule in a NestJS service conventionally issues a JWT." }, "clientIpHeader": { "type": "apiKey", "in": "header", "name": "x-real-ip", "description": "**Verified.** `trustedHeader: \"x-real-ip\"` passed to IpAllowlistModule; `trustSocketFallback: false`. — api_structure.txt:src/app.module.ts" } }, "parameters": { "PageParam": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "LimitParam": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "IdParam": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError" }, "example": { "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" } } } }, "ForbiddenIp": { "description": "inferred: blocked by IpAllowlistMiddleware (mode=enforce); logged as `ip-allowlist block ip=… path=…`. — api_structure.txt:src/app.module.ts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError" }, "example": { "statusCode": 403, "message": "Forbidden", "error": "Forbidden" } } } }, "Throttled": { "description": "inferred: rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError" }, "example": { "statusCode": 429, "message": "Too Many Requests", "error": "Too Many Requests" } } } }, "InternalError": { "description": "inferred: NestJS default exception-filter envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError" }, "example": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } }, "NestError400x": { "description": "Validation error (400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError400x" } } } }, "NestError402": { "description": "Payment required (402).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError402" } } } }, "NestError404": { "description": "Not found (404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError404" } } } }, "NestError409": { "description": "Conflict (409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError409" } } } }, "NestError502x": { "description": "Bad gateway (502).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError502x" } } } }, "NestError504x": { "description": "Gateway timeout (504).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestError504x" } } } } }, "schemas": { "NestError": { "type": "object", "x-source": "inferred", "description": "inferred: NestJS default `HttpException` body.", "required": [ "statusCode", "message" ], "properties": { "statusCode": { "type": "integer", "example": 400 }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": [ "email must be an email" ] }, "error": { "type": "string", "example": "Bad Request" }, "timestamp": { "type": "string", "format": "date-time" }, "path": { "type": "string", "example": "/auth/login" } } }, "HealthProbe": { "type": "object", "x-source": "inferred", "description": "Minimal liveness body. The route is verified; the shape is inferred.", "properties": { "status": { "type": "string", "example": "ok" } } }, "HealthV2": { "type": "object", "x-source": "inferred", "description": "Dependency-aware readiness body. Route verified, composite shape inferred.", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "error" ], "example": "ok" }, "info": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/HealthIndicator" }, "example": { "database": { "status": "up" }, "redis": { "status": "up" } } }, "error": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/HealthIndicator" } }, "details": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/HealthIndicator" } } } }, "HealthIndicator": { "type": "object", "x-source": "inferred", "properties": { "status": { "type": "string", "enum": [ "up", "down" ], "example": "up" }, "message": { "type": "string" }, "latencyMs": { "type": "number", "example": 1.8 } } }, "Pagination": { "type": "object", "x-source": "inferred", "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 137 }, "totalPages": { "type": "integer", "example": 7 } } }, "AuthTokens": { "type": "object", "x-source": "inferred", "description": "inferred: issued by AuthModule.", "required": [ "accessToken" ], "properties": { "accessToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.sig" }, "refreshToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.ref" }, "tokenType": { "type": "string", "example": "Bearer" }, "expiresIn": { "type": "integer", "example": 3600 } } }, "Credentials": { "type": "object", "x-source": "inferred", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "S3cret-Passw0rd!" } } }, "RegisterRequest": { "type": "object", "x-source": "inferred", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "new.user@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "example": "S3cret-Passw0rd!" }, "displayName": { "type": "string", "maxLength": 64, "example": "New User" }, "locale": { "type": "string", "example": "en-US" } } }, "RefreshRequest": { "type": "object", "x-source": "inferred", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiJ9.ref" } } }, "User": { "type": "object", "x-source": "inferred", "description": "inferred: UserModule / TypeORM entity.", "properties": { "id": { "type": "string", "format": "uuid", "example": "3f1a1f4e-1c2b-4f1a-9c3d-2b7e5a0d9c11" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "displayName": { "type": "string", "example": "User Name" }, "status": { "type": "string", "enum": [ "active", "invited", "suspended", "deleted" ], "example": "active" }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "user" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-08-06T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-08-06T12:00:00.000Z" } } }, "Account": { "type": "object", "x-source": "inferred", "description": "inferred: AccountModule entity.", "properties": { "id": { "type": "string", "format": "uuid", "example": "8c2f0a52-77aa-4c2e-9f0e-6d1b2c3d4e5f" }, "ownerId": { "type": "string", "format": "uuid", "example": "3f1a1f4e-1c2b-4f1a-9c3d-2b7e5a0d9c11" }, "name": { "type": "string", "example": "Acme Inc." }, "plan": { "type": "string", "enum": [ "free", "pro", "enterprise" ], "example": "pro" }, "balance": { "type": "number", "example": 1234.56 }, "currency": { "type": "string", "example": "USD" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-08-06T12:00:00.000Z" } } }, "Message": { "type": "object", "x-source": "inferred", "description": "inferred: MessageModule entity.", "properties": { "id": { "type": "string", "format": "uuid", "example": "b71d3c90-4e21-4a77-8f3a-1c0d9e8f7a6b" }, "accountId": { "type": "string", "format": "uuid", "example": "8c2f0a52-77aa-4c2e-9f0e-6d1b2c3d4e5f" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "example": "outbound" }, "channel": { "type": "string", "enum": [ "sms", "email", "push" ], "example": "sms" }, "status": { "type": "string", "enum": [ "queued", "sent", "delivered", "failed" ], "example": "delivered" }, "to": { "type": "string", "example": "+15551234567" }, "body": { "type": "string", "example": "Your verification code is 4821" }, "providerMessageId": { "type": "string", "example": "SM-8f2c19" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-08-06T12:00:00.000Z" } } }, "SendMessageRequest": { "type": "object", "x-source": "inferred", "required": [ "to", "body", "channel" ], "properties": { "to": { "type": "string", "example": "+15551234567" }, "channel": { "type": "string", "enum": [ "sms", "email", "push" ], "example": "sms" }, "body": { "type": "string", "maxLength": 1600, "example": "Your verification code is 4821" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "campaign": "onboarding" } } } }, "Settings": { "type": "object", "x-source": "inferred", "description": "inferred: SettingsModule key/value store.", "additionalProperties": true, "example": { "notifications.email": true, "notifications.sms": false, "timezone": "Europe/Berlin", "language": "de-DE" } }, "LegacyEnvelope": { "type": "object", "x-source": "inferred", "description": "inferred: LegacyApiModule re-wrap of the upstream.", "properties": { "ok": { "type": "boolean", "example": true }, "legacyStatus": { "type": "integer", "example": 200 }, "data": { "example": { "id": 42, "state": "ACTIVE" } }, "warnings": { "type": "array", "items": { "type": "string" }, "example": [ "field `state` is deprecated" ] } } }, "RedisValue": { "type": "object", "x-source": "inferred", "description": "inferred: RedisStorageModule.", "properties": { "key": { "type": "string", "example": "session:3f1a1f4e" }, "value": { "example": { "userId": "3f1a1f4e-1c2b-4f1a-9c3d-2b7e5a0d9c11" } }, "ttlSeconds": { "type": "integer", "nullable": true, "example": 3600 } } }, "NestError400x": { "allOf": [ { "$ref": "#/components/schemas/NestError" } ], "x-source": "inferred", "description": "inferred: 400 validation failure.", "example": { "statusCode": 400, "message": [ "email must be an email", "password is too weak" ], "error": "Bad Request" } }, "NestError402": { "allOf": [ { "$ref": "#/components/schemas/NestError" } ], "x-source": "inferred", "description": "inferred: insufficient balance.", "example": { "statusCode": 402, "message": "Insufficient balance", "error": "Payment Required" } }, "NestError404": { "allOf": [ { "$ref": "#/components/schemas/NestError" } ], "x-source": "inferred", "description": "inferred: entity not found.", "example": { "statusCode": 404, "message": "Not Found", "error": "Not Found" } }, "NestError409": { "allOf": [ { "$ref": "#/components/schemas/NestError" } ], "x-source": "inferred", "description": "inferred: conflict, e.g. email already registered.", "example": { "statusCode": 409, "message": "Email already registered", "error": "Conflict" } }, "NestError502x": { "allOf": [ { "$ref": "#/components/schemas/NestError" } ], "x-source": "inferred", "description": "inferred: legacy upstream unavailable.", "example": { "statusCode": 502, "message": "Legacy upstream unavailable", "error": "Bad Gateway" } }, "NestError504x": { "allOf": [ { "$ref": "#/components/schemas/NestError" } ], "x-source": "inferred", "description": "inferred: legacy upstream timeout.", "example": { "statusCode": 504, "message": "Legacy upstream timeout", "error": "Gateway Timeout" } } } }, "x-middleware-pipeline": { "x-source": "api_structure.txt:src/app.module.ts", "order": [ { "name": "IpAllowlistMiddleware", "applied_to": "*", "description": "consumer.apply(IpAllowlistMiddleware).forRoutes(\"*\") — bypassed internally for /, /health, /health/v2." }, { "name": "applyLoggingMiddlewares(consumer)", "applied_to": "@touch-api/logging defined" } ], "allowlist": { "file": "process.env.IP_ALLOWLIST_FILE ?? /etc/touch-api/ip-allowlist.conf", "mode": "process.env.IP_ALLOWLIST_MODE ?? AllowlistMode.Off", "trustedHeader": "x-real-ip", "trustSocketFallback": false, "bypassPaths": [ "/", "/health", "/health/v2" ], "observability": "onBlocked -> Logger(\"IpAllowlist\").warn(`ip-allowlist ${enforced ? \"block\" : \"would-block\"} ip=${ip} path=${path}`)" } }, "x-runtime-config": { "x-source": "api_structure.txt:src/app.module.ts", "env": { "DB_STRING": "TypeORM datasource URL injected into ormconfig.js at boot.", "IP_ALLOWLIST_FILE": "Allowlist file path. Default: /etc/touch-api/ip-allowlist.conf", "IP_ALLOWLIST_MODE": "AllowlistMode enum. Default: Off (observe-only)." }, "ormconfig": "require(\"../ormconfig.js\") — TypeORM options live there.", "packages": [ "@nestjs/common", "@nestjs/config", "@nestjs/typeorm", "@touch-api/logging", "@touch-api/ip-allowlist" ] }, "paths": { "/": { "get": { "tags": [ "Health" ], "operationId": "rootProbe", "summary": "Root probe", "description": "**Verified route.** `/` is in `bypassPaths` of `IpAllowlistModule.forRoot(...)` in `src/app.module.ts`, so it exists and is exempt from the IP allowlist. Body shape is inferred. — api_structure.txt:src/app.module.ts", "x-source": "api_structure.txt:src/app.module.ts", "x-allowlist-bypass": true, "security": [], "responses": { "200": { "description": "Service reachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthProbe" }, "example": { "status": "ok" } } } }, "503": { "$ref": "#/components/responses/InternalError" } } } }, "/health": { "get": { "tags": [ "Health" ], "operationId": "healthV1", "summary": "Liveness / readiness probe (v1)", "description": "**Verified route.** Second entry of `bypassPaths: [\"/\", \"/health\", \"/health/v2\"]`. Never intercepted by `IpAllowlistMiddleware`. Body shape inferred. — api_structure.txt:src/app.module.ts", "x-source": "api_structure.txt:src/app.module.ts", "x-allowlist-bypass": true, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthProbe" }, "example": { "status": "ok" } } } }, "503": { "$ref": "#/components/responses/InternalError" } } } }, "/health/v2": { "get": { "tags": [ "Health" ], "operationId": "healthV2", "summary": "Detailed readiness probe (v2)", "description": "**Verified route.** Third entry of `bypassPaths`. Its versioned name implies a composite dependency report (TypeORM DB + RedisStorageModule); that composite body is inferred. — api_structure.txt:src/app.module.ts", "x-source": "api_structure.txt:src/app.module.ts", "x-allowlist-bypass": true, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthV2" }, "example": { "status": "ok", "info": { "database": { "status": "up", "latencyMs": 1.8 }, "redis": { "status": "up", "latencyMs": 0.4 } }, "error": {}, "details": {} } } } }, "503": { "description": "At least one dependency is down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthV2" }, "example": { "status": "error", "error": { "database": { "status": "down", "message": "connect ECONNREFUSED" } }, "details": {} } } } } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "operationId": "authLogin", "summary": "Log in and obtain tokens", "description": "inferred. `AuthModule` is imported in src/app.module.ts and conventionally exposes a credential login.", "x-source": "inferred", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credentials" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokens" }, "example": { "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.sig", "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.ref", "tokenType": "Bearer", "expiresIn": 3600 } } } }, "400": { "$ref": "#/components/responses/NestError400x" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenIp" }, "429": { "$ref": "#/components/responses/Throttled" } } } }, "/auth/register": { "post": { "tags": [ "Auth" ], "operationId": "authRegister", "summary": "Create an account", "description": "inferred. Registration flow of `AuthModule`.", "x-source": "inferred", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/NestError400x" }, "409": { "$ref": "#/components/responses/NestError409" }, "429": { "$ref": "#/components/responses/Throttled" } } } }, "/auth/refresh": { "post": { "tags": [ "Auth" ], "operationId": "authRefresh", "summary": "Exchange a refresh token", "description": "inferred. Rotating refresh of `AuthModule`.", "x-source": "inferred", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokens" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "operationId": "authLogout", "summary": "Invalidate the current session", "description": "inferred. Expected to revoke the refresh token, likely via RedisStorageModule.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Session revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/me": { "get": { "tags": [ "Auth" ], "operationId": "authMe", "summary": "Current authenticated principal", "description": "inferred. Typical `me` endpoint of an AuthModule.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/users": { "get": { "tags": [ "User" ], "operationId": "listUsers", "summary": "List users", "description": "inferred. Paginated CRUD list of `UserModule`.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "inferred: free-text filter." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "invited", "suspended", "deleted" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "id": "3f1a1f4e-1c2b-4f1a-9c3d-2b7e5a0d9c11", "email": "user@example.com", "displayName": "User Name", "status": "active", "roles": [ "user" ], "createdAt": "2026-08-06T12:00:00.000Z", "updatedAt": "2026-08-06T12:00:00.000Z" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenIp" } } } }, "/users/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdParam" } ], "get": { "tags": [ "User" ], "operationId": "getUser", "summary": "Get a user by id", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NestError404" } } }, "patch": { "tags": [ "User" ], "operationId": "updateUser", "summary": "Update a user", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/NestError400x" }, "404": { "$ref": "#/components/responses/NestError404" } } }, "delete": { "tags": [ "User" ], "operationId": "deleteUser", "summary": "Delete a user", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NestError404" } } } }, "/accounts": { "get": { "tags": [ "Account" ], "operationId": "listAccounts", "summary": "List accounts", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "id": "8c2f0a52-77aa-4c2e-9f0e-6d1b2c3d4e5f", "ownerId": "3f1a1f4e-1c2b-4f1a-9c3d-2b7e5a0d9c11", "name": "Acme Inc.", "plan": "pro", "balance": 1234.56, "currency": "USD", "createdAt": "2026-08-06T12:00:00.000Z" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Account" ], "operationId": "createAccount", "summary": "Create an account", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Inc." }, "plan": { "type": "string", "enum": [ "free", "pro", "enterprise" ], "example": "pro" }, "currency": { "type": "string", "example": "USD" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/NestError400x" } } } }, "/accounts/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdParam" } ], "get": { "tags": [ "Account" ], "operationId": "getAccount", "summary": "Get an account", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "404": { "$ref": "#/components/responses/NestError404" } } }, "patch": { "tags": [ "Account" ], "operationId": "updateAccount", "summary": "Update an account", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } } } } }, "/accounts/{id}/balance": { "get": { "tags": [ "Account" ], "operationId": "getAccountBalance", "summary": "Read account balance", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "balance": { "type": "number" }, "currency": { "type": "string" } } }, "example": { "accountId": "8c2f0a52-77aa-4c2e-9f0e-6d1b2c3d4e5f", "balance": 1234.56, "currency": "USD" } } } } } } }, "/messages": { "get": { "tags": [ "Message" ], "operationId": "listMessages", "summary": "List messages", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "sent", "delivered", "failed" ] } }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "sms", "email", "push" ] } }, { "name": "accountId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "id": "b71d3c90-4e21-4a77-8f3a-1c0d9e8f7a6b", "accountId": "8c2f0a52-77aa-4c2e-9f0e-6d1b2c3d4e5f", "direction": "outbound", "channel": "sms", "status": "delivered", "to": "+15551234567", "body": "Your verification code is 4821", "providerMessageId": "SM-8f2c19", "createdAt": "2026-08-06T12:00:00.000Z" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Message" ], "operationId": "sendMessage", "summary": "Send a message", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "202": { "description": "Accepted / queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/NestError400x" }, "402": { "$ref": "#/components/responses/NestError402" }, "429": { "$ref": "#/components/responses/Throttled" } } } }, "/messages/{id}": { "get": { "tags": [ "Message" ], "operationId": "getMessage", "summary": "Get a message", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "$ref": "#/components/responses/NestError404" } } } }, "/messages/{id}/status": { "get": { "tags": [ "Message" ], "operationId": "getMessageStatus", "summary": "Delivery status of a message", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "sent", "delivered", "failed" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "example": { "id": "b71d3c90-4e21-4a77-8f3a-1c0d9e8f7a6b", "status": "delivered", "updatedAt": "2026-08-06T12:00:05.000Z" } } } } } } }, "/settings": { "get": { "tags": [ "Settings" ], "operationId": "getSettings", "summary": "Read the settings of the current subject", "description": "inferred. `SettingsModule` implies a per-user/account key-value store.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "user", "account" ], "default": "user" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "Settings" ], "operationId": "patchSettings", "summary": "Merge-update settings", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } }, "400": { "$ref": "#/components/responses/NestError400x" } } } }, "/settings/{key}": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "notifications.email", "description": "inferred: dotted settings key." } ], "get": { "tags": [ "Settings" ], "operationId": "getSetting", "summary": "Read one settings key", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "value": {} } }, "example": { "key": "notifications.email", "value": true } } } }, "404": { "$ref": "#/components/responses/NestError404" } } }, "put": { "tags": [ "Settings" ], "operationId": "putSetting", "summary": "Set one settings key", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": {} }, "example": { "value": true } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "value": {} } } } } } } }, "delete": { "tags": [ "Settings" ], "operationId": "deleteSetting", "summary": "Delete one settings key", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Deleted" } } } }, "/common/countries": { "get": { "tags": [ "Common" ], "operationId": "commonCountries", "summary": "Reference list: countries", "description": "inferred. `CommonModule` conventionally hosts static reference data.", "x-source": "inferred", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "DE" }, "name": { "type": "string", "example": "Germany" }, "dialCode": { "type": "string", "example": "+49" } } } }, "example": [ { "code": "DE", "name": "Germany", "dialCode": "+49" }, { "code": "US", "name": "United States", "dialCode": "+1" } ] } } } } } }, "/common/timezones": { "get": { "tags": [ "Common" ], "operationId": "commonTimezones", "summary": "Reference list: timezones", "description": "inferred.", "x-source": "inferred", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Europe/Berlin", "UTC", "America/New_York" ] } } } } } }, "/common/currencies": { "get": { "tags": [ "Common" ], "operationId": "commonCurrencies", "summary": "Reference list: currencies", "description": "inferred.", "x-source": "inferred", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "EUR" }, "symbol": { "type": "string", "example": "€" }, "minorUnits": { "type": "integer", "example": 2 } } } }, "example": [ { "code": "EUR", "symbol": "€", "minorUnits": 2 } ] } } } } } }, "/legacy/{path}": { "x-note": "inferred: literal route prefix is a reconstruction; LegacyApiModule may reuse upstream paths.", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string" }, "example": "v1/customers/42", "description": "inferred: catch-all passthrough path." } ], "get": { "tags": [ "Legacy API Bridge" ], "operationId": "legacyProxyGet", "summary": "Proxy a GET call to the legacy upstream", "description": "inferred. `LegacyApiModule` is assumed to expose a catch-all that forwards to an older backend and normalises the reply. The module import is verified. — api_structure.txt:src/app.module.ts", "x-source": "inferred", "x-legacy-upstream": "unknown", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyEnvelope" }, "example": { "ok": true, "legacyStatus": 200, "data": { "id": 42, "state": "ACTIVE" }, "warnings": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/NestError502x" }, "504": { "$ref": "#/components/responses/NestError504x" } } }, "post": { "tags": [ "Legacy API Bridge" ], "operationId": "legacyProxyPost", "summary": "Proxy a POST call to the legacy upstream", "description": "inferred.", "x-source": "inferred", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "example": { "operation": "createCustomer", "payload": { "name": "Acme" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyEnvelope" } } } }, "400": { "$ref": "#/components/responses/NestError400x" } } } }, "/redis/{key}": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "session:3f1a1f4e" } ], "get": { "tags": [ "Redis Storage" ], "operationId": "redisGet", "summary": "Read a value from Redis", "description": "inferred. `RedisStorageModule` is verified as a module; whether it is exposed over HTTP is inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisValue" }, "example": { "key": "session:3f1a1f4e", "value": { "userId": "3f1a1f4e-1c2b-4f1a-9c3d-2b7e5a0d9c11" }, "ttlSeconds": 3600 } } } }, "404": { "$ref": "#/components/responses/NestError404" } } }, "put": { "tags": [ "Redis Storage" ], "operationId": "redisPut", "summary": "Write a value to Redis", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": {}, "ttlSeconds": { "type": "integer", "nullable": true } }, "example": { "value": { "userId": "3f1a1f4e-1c2b-4f1a-9c3d-2b7e5a0d9c11" }, "ttlSeconds": 3600 } } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisValue" } } } } } }, "delete": { "tags": [ "Redis Storage" ], "operationId": "redisDelete", "summary": "Delete a Redis key", "description": "inferred.", "x-source": "inferred", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Deleted" } } } } } }