7441c9f298
All findings from the inaugural LeadValidator audit resolved and confirmed. Release gate: PASS. VV_ISSUE_002 (BLOCKER): 15 OpenAPI specs verified present covering all 20 route groups (46 endpoints documented in docs/openapi/) VV_ISSUE_003 (MAJOR): Remove any types from src/db/pool.ts — replaced pool.query shim with unknown[] + Object.defineProperty, zero any types, eslint-disable suppressions removed VV_ISSUE_004 (MAJOR): Remove raw Pool from ScaffoldController and HealthDetailedController — injected AgentRepository/CredentialRepository and DbProbe interface respectively; added CredentialRepository.findActiveClientId() VV_ISSUE_005 (MAJOR): Add unit tests for 5 untested services — ComplianceStatusStore, EventPublisher, MarketplaceService, OIDCTrustPolicyService, UsageService VV_ISSUE_006 (MAJOR): Add integration tests for 7 missing route groups — analytics, billing, tiers, webhooks, marketplace, oidc-trust-policies, oidc-token-exchange VV_ISSUE_001 (MINOR): Create missing design.md and tasks.md in 4 OpenSpec archives — all archives now complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
258 lines
8.5 KiB
YAML
258 lines
8.5 KiB
YAML
openapi: "3.0.3"
|
|
|
|
info:
|
|
title: SentryAgent.ai — SDK Scaffold Generator
|
|
version: 1.0.0
|
|
description: |
|
|
SDK scaffold generator endpoint for the SentryAgent.ai AgentIdP platform.
|
|
|
|
The scaffold endpoint generates a ready-to-run agent project ZIP archive
|
|
pre-configured with the agent's credentials, API URL, and chosen SDK.
|
|
|
|
The generated scaffold includes:
|
|
- Language-specific project structure (TypeScript / Python / Go / Java / Rust)
|
|
- Pre-filled `.env.example` with `CLIENT_ID` and `API_URL`
|
|
- Agent authentication boilerplate using the SentryAgent.ai SDK
|
|
- README with quickstart instructions
|
|
- Docker / CI configuration (where applicable)
|
|
|
|
**Authentication:** Requires a valid Bearer JWT.
|
|
**Rate limit:** 10 requests per minute per tenant (separate from the global limit).
|
|
The scaffold endpoint responds with `Retry-After` on rate limit.
|
|
|
|
**Supported languages:** `typescript`, `python`, `go`, `java`, `rust`
|
|
|
|
servers:
|
|
- url: http://localhost:3000/api/v1
|
|
description: Local development server
|
|
- url: https://api.sentryagent.ai/v1
|
|
description: Production server
|
|
|
|
tags:
|
|
- name: SDK Scaffold
|
|
description: Generate a ready-to-run agent SDK project scaffold
|
|
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
JWT access token obtained via `POST /token`.
|
|
Include as `Authorization: Bearer <token>`.
|
|
|
|
schemas:
|
|
ScaffoldLanguage:
|
|
type: string
|
|
enum:
|
|
- typescript
|
|
- python
|
|
- go
|
|
- java
|
|
- rust
|
|
description: Target programming language for the scaffold project.
|
|
example: typescript
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
description: Standard error response envelope.
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
example: "AGENT_NOT_FOUND"
|
|
message:
|
|
type: string
|
|
example: "Agent with the specified ID was not found."
|
|
details:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
responses:
|
|
Unauthorized:
|
|
description: Missing or invalid Bearer token.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "UNAUTHORIZED"
|
|
message: "A valid Bearer token is required to access this resource."
|
|
|
|
Forbidden:
|
|
description: Valid token but insufficient permissions.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "FORBIDDEN"
|
|
message: "You do not have permission to access this agent's scaffold."
|
|
|
|
NotFound:
|
|
description: Agent not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "AGENT_NOT_FOUND"
|
|
message: "Agent with the specified ID was not found."
|
|
|
|
TooManyRequests:
|
|
description: |
|
|
Scaffold-specific rate limit exceeded (10 requests per minute per tenant).
|
|
Retry after the duration specified in the `Retry-After` header.
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: integer
|
|
description: Number of seconds to wait before retrying.
|
|
example: 60
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "RATE_LIMIT_EXCEEDED"
|
|
message: "Scaffold rate limit exceeded. Please retry after 60 seconds."
|
|
|
|
InternalServerError:
|
|
description: Unexpected server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "INTERNAL_SERVER_ERROR"
|
|
message: "An unexpected error occurred. Please try again later."
|
|
|
|
security:
|
|
- BearerAuth: []
|
|
|
|
paths:
|
|
/sdk/scaffold/{agentId}:
|
|
get:
|
|
operationId: getAgentScaffold
|
|
tags:
|
|
- SDK Scaffold
|
|
summary: Generate and download an agent SDK scaffold ZIP
|
|
description: |
|
|
Generates a ready-to-run agent project scaffold for the specified agent
|
|
and streams it as a ZIP file download.
|
|
|
|
The scaffold is customized with:
|
|
- The agent's `CLIENT_ID` pre-filled in `.env.example`
|
|
- The platform API URL (`API_URL`) configured for the environment
|
|
- The agent's name, type, and capabilities reflected in project metadata
|
|
- Language-specific SDK integration boilerplate
|
|
|
|
**Rate limit:** 10 requests per minute per tenant.
|
|
Exceeding this limit returns `429 Too Many Requests` with a `Retry-After` header.
|
|
|
|
**Language selection:** Pass the desired `language` query parameter.
|
|
Defaults to `typescript` when omitted.
|
|
|
|
**Authorization:** The authenticated agent (from Bearer token) must belong to
|
|
the same organization as the target agent (`agentId`). Cross-tenant scaffold
|
|
generation is not permitted.
|
|
parameters:
|
|
- name: agentId
|
|
in: path
|
|
required: true
|
|
description: UUID of the agent to generate a scaffold for.
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
- name: language
|
|
in: query
|
|
required: false
|
|
description: |
|
|
Target programming language for the scaffold.
|
|
Defaults to `typescript` when omitted.
|
|
schema:
|
|
$ref: '#/components/schemas/ScaffoldLanguage'
|
|
example: typescript
|
|
responses:
|
|
'200':
|
|
description: |
|
|
Scaffold ZIP archive generated and streamed successfully.
|
|
|
|
The response body is a ZIP archive containing the generated project files.
|
|
Save it locally and unzip to get started:
|
|
```
|
|
curl -O -J -H "Authorization: Bearer <token>" \
|
|
"https://api.sentryagent.ai/v1/sdk/scaffold/a1b2c3d4-e5f6-7890-abcd-ef1234567890?language=typescript"
|
|
unzip screener-001-scaffold.zip
|
|
cd screener-001-scaffold && npm install
|
|
```
|
|
headers:
|
|
Content-Disposition:
|
|
schema:
|
|
type: string
|
|
description: |
|
|
Filename for the ZIP download.
|
|
Format: `attachment; filename="<agent-name>-scaffold.zip"`
|
|
example: 'attachment; filename="screener-001-scaffold.zip"'
|
|
Content-Type:
|
|
schema:
|
|
type: string
|
|
example: "application/zip"
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: integer
|
|
description: Scaffold rate limit (requests per minute per tenant).
|
|
example: 10
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: integer
|
|
description: Remaining scaffold requests in the current window.
|
|
example: 9
|
|
content:
|
|
application/zip:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
description: ZIP archive of the generated scaffold project.
|
|
'400':
|
|
description: Invalid `language` query parameter.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "VALIDATION_ERROR"
|
|
message: "Invalid language. Supported languages are: typescript, python, go, java, rust."
|
|
details:
|
|
field: "language"
|
|
provided: "ruby"
|
|
supported:
|
|
- typescript
|
|
- python
|
|
- go
|
|
- java
|
|
- rust
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'422':
|
|
description: Agent is decommissioned — cannot generate scaffold for inactive agents.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "AGENT_DECOMMISSIONED"
|
|
message: "Cannot generate scaffold for a decommissioned agent."
|
|
'429':
|
|
$ref: '#/components/responses/TooManyRequests'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|