mirror of
https://github.com/claude-did-this/claude-hub.git
synced 2026-02-14 19:30:02 +01:00
65a590784c
* feat: Implement Claude orchestration with session management - Add CLAUDE_WEBHOOK_SECRET for webhook authentication - Fix Docker volume mounting for Claude credentials - Capture Claude's internal session ID from stream-json output - Update entrypoint script to support OUTPUT_FORMAT=stream-json - Fix environment variable naming (REPOSITORY -> REPO_FULL_NAME) - Enable parallel session execution with proper authentication - Successfully tested creating PRs via orchestrated sessions This enables the webhook to create and manage Claude Code sessions that can: - Clone repositories - Create feature branches - Implement code changes - Commit and push changes - Create pull requests All while capturing Claude's internal session ID for potential resumption. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Update SessionManager tests for new implementation - Update test to expect docker volume create instead of docker create - Add unref() method to mock process objects to fix test environment error - Update spawn expectations to match new docker run implementation - Fix tests for both startSession and queueSession methods Tests now pass in CI environment. * feat: Add Claude API documentation and improve session validation - Add comprehensive Swagger/OpenAPI documentation for Claude webhook API - Add improved validation for session dependencies to handle edge cases - Add hackathon-specific Docker Compose configuration - Update SessionHandler to validate dependency UUIDs and filter invalid values - Update SessionManager to properly handle sessions without dependencies - Add API endpoint documentation with examples and schemas 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * test: Add comprehensive tests for SessionHandler dependency validation Add test coverage for dependency validation logic in SessionHandler: - Filter out invalid dependency values (empty strings, whitespace, "none") - Validate UUID format for dependencies - Handle mixed valid and invalid dependencies - Support empty dependency arrays - Handle arrays with only filtered values This improves test coverage from ~91% to ~97% for SessionHandler. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Address PR #181 review comments - Remove unused docker-compose.hackathon.yml file - Extract UUID regex to constant for better maintainability - Document breaking changes in BREAKING_CHANGES.md - Add comprehensive examples to Swagger documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
569 lines
17 KiB
YAML
569 lines
17 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Claude Webhook API
|
|
description: |
|
|
API for creating and managing Claude Code sessions for automated code generation, analysis, and orchestration.
|
|
This API enables parallel execution of multiple Claude instances for complex software engineering tasks.
|
|
version: 1.0.0
|
|
contact:
|
|
name: Claude Hub Support
|
|
url: https://github.com/claude-hub/claude-hub
|
|
|
|
servers:
|
|
- url: https://your-domain.com
|
|
description: Production server
|
|
- url: http://localhost:3002
|
|
description: Local development server
|
|
|
|
security:
|
|
- bearerAuth: []
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
summary: Health check
|
|
description: Check the health status of the API and its dependencies
|
|
tags:
|
|
- System
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Service is healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HealthCheckResponse'
|
|
|
|
/api/webhooks/health:
|
|
get:
|
|
summary: Webhook health check
|
|
description: Check the health status of webhook providers
|
|
tags:
|
|
- System
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Webhook providers are healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
example: healthy
|
|
providers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
handlerCount:
|
|
type: integer
|
|
|
|
/api/webhooks/github:
|
|
post:
|
|
summary: GitHub webhook endpoint (legacy)
|
|
description: Legacy endpoint for GitHub webhooks. Use /api/webhooks/github instead.
|
|
deprecated: true
|
|
tags:
|
|
- Webhooks
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
responses:
|
|
'200':
|
|
description: Webhook processed successfully
|
|
'401':
|
|
description: Invalid webhook signature
|
|
'404':
|
|
description: Webhook event not handled
|
|
|
|
/api/webhooks/{provider}:
|
|
post:
|
|
summary: Generic webhook endpoint
|
|
description: Process webhooks from various providers (github, claude)
|
|
tags:
|
|
- Webhooks
|
|
security: []
|
|
parameters:
|
|
- name: provider
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
enum: [github, claude]
|
|
description: The webhook provider name
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/ClaudeWebhookRequest'
|
|
- $ref: '#/components/schemas/GitHubWebhookPayload'
|
|
examples:
|
|
createSession:
|
|
summary: Create a new Claude session
|
|
value:
|
|
type: session.create
|
|
session:
|
|
type: implementation
|
|
project:
|
|
repository: acme/webapp
|
|
branch: feature/user-auth
|
|
requirements: Implement JWT authentication middleware for Express.js with refresh token support
|
|
context: Use existing User model, bcrypt for passwords, and jsonwebtoken library
|
|
dependencies: []
|
|
createSessionWithDependencies:
|
|
summary: Create a session that depends on others
|
|
value:
|
|
type: session.create
|
|
session:
|
|
type: testing
|
|
project:
|
|
repository: acme/webapp
|
|
branch: feature/user-auth
|
|
requirements: Write comprehensive integration tests for the JWT authentication middleware
|
|
context: Test all edge cases including token expiration, invalid tokens, and refresh flow
|
|
dependencies:
|
|
- 550e8400-e29b-41d4-a716-446655440000
|
|
- 660e8400-e29b-41d4-a716-446655440001
|
|
startSession:
|
|
summary: Start an existing session
|
|
value:
|
|
type: session.start
|
|
sessionId: 550e8400-e29b-41d4-a716-446655440000
|
|
orchestrate:
|
|
summary: Create an orchestration with multiple sessions
|
|
value:
|
|
type: orchestrate
|
|
autoStart: true
|
|
project:
|
|
repository: acme/webapp
|
|
branch: feature/complete-auth
|
|
requirements: |
|
|
Implement a complete authentication system:
|
|
1. JWT middleware with refresh tokens
|
|
2. User registration and login endpoints
|
|
3. Password reset functionality
|
|
4. Integration tests for all auth endpoints
|
|
context: Use existing User model, PostgreSQL database, and follow REST API conventions
|
|
responses:
|
|
'200':
|
|
description: Webhook processed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WebhookResponse'
|
|
examples:
|
|
sessionCreated:
|
|
summary: Session created successfully
|
|
value:
|
|
success: true
|
|
message: Session created successfully
|
|
data:
|
|
session:
|
|
id: 550e8400-e29b-41d4-a716-446655440000
|
|
type: implementation
|
|
status: initializing
|
|
containerId: claude-session-550e8400
|
|
project:
|
|
repository: acme/webapp
|
|
branch: feature/user-auth
|
|
requirements: Implement JWT authentication middleware for Express.js with refresh token support
|
|
context: Use existing User model, bcrypt for passwords, and jsonwebtoken library
|
|
dependencies: []
|
|
sessionStarted:
|
|
summary: Session started with dependencies
|
|
value:
|
|
success: true
|
|
message: Session queued, waiting for dependencies
|
|
data:
|
|
session:
|
|
id: 660e8400-e29b-41d4-a716-446655440001
|
|
status: pending
|
|
waitingFor:
|
|
- 550e8400-e29b-41d4-a716-446655440000
|
|
'400':
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'401':
|
|
description: Unauthorized - Invalid token or signature
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'404':
|
|
description: Provider not found or session not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'409':
|
|
description: Conflict - Session already started
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'429':
|
|
description: Too many requests
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: Too many webhook requests
|
|
message:
|
|
type: string
|
|
example: Too many webhook requests from this IP, please try again later.
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
description: Use CLAUDE_WEBHOOK_SECRET as the bearer token
|
|
|
|
schemas:
|
|
HealthCheckResponse:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [ok, degraded]
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
startup:
|
|
type: object
|
|
properties:
|
|
totalStartupTime:
|
|
type: integer
|
|
milestones:
|
|
type: array
|
|
items:
|
|
type: object
|
|
docker:
|
|
type: object
|
|
properties:
|
|
available:
|
|
type: boolean
|
|
error:
|
|
type: string
|
|
nullable: true
|
|
checkTime:
|
|
type: integer
|
|
nullable: true
|
|
claudeCodeImage:
|
|
type: object
|
|
properties:
|
|
available:
|
|
type: boolean
|
|
error:
|
|
type: string
|
|
nullable: true
|
|
checkTime:
|
|
type: integer
|
|
nullable: true
|
|
healthCheckDuration:
|
|
type: integer
|
|
|
|
ClaudeWebhookRequest:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/SessionCreateRequest'
|
|
- $ref: '#/components/schemas/SessionStartRequest'
|
|
- $ref: '#/components/schemas/SessionGetRequest'
|
|
- $ref: '#/components/schemas/SessionOutputRequest'
|
|
- $ref: '#/components/schemas/SessionListRequest'
|
|
- $ref: '#/components/schemas/OrchestrateRequest'
|
|
discriminator:
|
|
propertyName: type
|
|
mapping:
|
|
session.create: '#/components/schemas/SessionCreateRequest'
|
|
session.start: '#/components/schemas/SessionStartRequest'
|
|
session.get: '#/components/schemas/SessionGetRequest'
|
|
session.output: '#/components/schemas/SessionOutputRequest'
|
|
session.list: '#/components/schemas/SessionListRequest'
|
|
orchestrate: '#/components/schemas/OrchestrateRequest'
|
|
|
|
SessionCreateRequest:
|
|
type: object
|
|
required:
|
|
- type
|
|
- session
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [session.create]
|
|
session:
|
|
type: object
|
|
required:
|
|
- type
|
|
- project
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [implementation, analysis, testing, review, coordination]
|
|
description: Type of Claude session
|
|
project:
|
|
type: object
|
|
required:
|
|
- repository
|
|
- requirements
|
|
properties:
|
|
repository:
|
|
type: string
|
|
pattern: '^[a-zA-Z0-9-]+/[a-zA-Z0-9-_.]+$'
|
|
example: acme/webapp
|
|
description: GitHub repository in owner/repo format
|
|
branch:
|
|
type: string
|
|
example: feature/user-auth
|
|
description: Target branch name
|
|
requirements:
|
|
type: string
|
|
example: Implement JWT authentication middleware for Express.js
|
|
description: Clear description of what Claude should do
|
|
context:
|
|
type: string
|
|
example: Use existing User model and bcrypt for password hashing
|
|
description: Additional context about the codebase or requirements
|
|
dependencies:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
description: Array of session IDs that must complete before this session starts
|
|
|
|
SessionStartRequest:
|
|
type: object
|
|
required:
|
|
- type
|
|
- sessionId
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [session.start]
|
|
sessionId:
|
|
type: string
|
|
format: uuid
|
|
example: 550e8400-e29b-41d4-a716-446655440000
|
|
|
|
SessionGetRequest:
|
|
type: object
|
|
required:
|
|
- type
|
|
- sessionId
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [session.get]
|
|
sessionId:
|
|
type: string
|
|
format: uuid
|
|
|
|
SessionOutputRequest:
|
|
type: object
|
|
required:
|
|
- type
|
|
- sessionId
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [session.output]
|
|
sessionId:
|
|
type: string
|
|
format: uuid
|
|
|
|
SessionListRequest:
|
|
type: object
|
|
required:
|
|
- type
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [session.list]
|
|
orchestrationId:
|
|
type: string
|
|
format: uuid
|
|
description: Filter sessions by orchestration ID
|
|
|
|
OrchestrateRequest:
|
|
type: object
|
|
required:
|
|
- type
|
|
- project
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [orchestrate]
|
|
sessionType:
|
|
type: string
|
|
enum: [coordination]
|
|
default: coordination
|
|
autoStart:
|
|
type: boolean
|
|
default: false
|
|
description: Whether to start the session immediately
|
|
project:
|
|
type: object
|
|
required:
|
|
- repository
|
|
- requirements
|
|
properties:
|
|
repository:
|
|
type: string
|
|
pattern: '^[a-zA-Z0-9-]+/[a-zA-Z0-9-_.]+$'
|
|
branch:
|
|
type: string
|
|
requirements:
|
|
type: string
|
|
context:
|
|
type: string
|
|
|
|
WebhookResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
data:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: false
|
|
error:
|
|
type: string
|
|
example: Session not found
|
|
|
|
Session:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
type:
|
|
type: string
|
|
enum: [implementation, analysis, testing, review, coordination]
|
|
status:
|
|
type: string
|
|
enum: [pending, initializing, running, completed, failed, cancelled]
|
|
containerId:
|
|
type: string
|
|
nullable: true
|
|
claudeSessionId:
|
|
type: string
|
|
nullable: true
|
|
project:
|
|
type: object
|
|
properties:
|
|
repository:
|
|
type: string
|
|
branch:
|
|
type: string
|
|
requirements:
|
|
type: string
|
|
context:
|
|
type: string
|
|
dependencies:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
startedAt:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
completedAt:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
output:
|
|
type: object
|
|
nullable: true
|
|
error:
|
|
type: string
|
|
nullable: true
|
|
|
|
SessionOutput:
|
|
type: object
|
|
properties:
|
|
logs:
|
|
type: array
|
|
items:
|
|
type: string
|
|
artifacts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [file, commit, pr, issue, comment]
|
|
path:
|
|
type: string
|
|
content:
|
|
type: string
|
|
sha:
|
|
type: string
|
|
url:
|
|
type: string
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
summary:
|
|
type: string
|
|
example: Implemented JWT authentication middleware with refresh token support
|
|
nextSteps:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: [Add rate limiting, Implement password reset flow]
|
|
|
|
GitHubWebhookPayload:
|
|
type: object
|
|
description: GitHub webhook payload (simplified schema)
|
|
properties:
|
|
action:
|
|
type: string
|
|
repository:
|
|
type: object
|
|
properties:
|
|
full_name:
|
|
type: string
|
|
sender:
|
|
type: object
|
|
properties:
|
|
login:
|
|
type: string
|
|
|
|
tags:
|
|
- name: System
|
|
description: System health and status endpoints
|
|
- name: Webhooks
|
|
description: Webhook processing endpoints
|
|
- name: Sessions
|
|
description: Claude session management operations |