feat: add typed request/response examples for /api/webhooks in openap… - #1135
Merged
greatest0fallt1me merged 6 commits intoJul 30, 2026
Merged
Conversation
…i.yaml
- Replace all bare ype: object webhook schemas with proper \ references
to new typed component schemas, giving tooling (validators, code generators,
documentation renderers) a machine-readable contract
- Fix duplicate /api/webhooks/{developerId} path key (GET and DELETE were
both declared as top-level keys — OpenAPI spec allows only one per path);
consolidated under a single path item with both HTTP methods
- Add typed component schemas:
WebhookEventType — enum of all four supported event types
WebhookRetryPolicy — maxRetries (0-10) and baseDelayMs (100-60000)
WebhookRegisterRequest — required: developerId, url, events; optional secret + retryPolicy
WebhookRegisterResponse — 201 confirmation envelope
WebhookConfig — GET response (secrets excluded)
WebhookDeleteResponse — 200 deletion confirmation
WebhookRotateSecretResponse — new secret + previous_expires_at
WebhookRetryPolicyUpdateRequest / Response
WebhookDeliveryPayload — required: event, timestamp, developerId, data
WebhookDeliveryResponse — 200 echoed-payload envelope
- Enrich examples across all six operations:
POST /api/webhooks — registerFull, registerMinimal; 4×400 error cases
GET /api/webhooks/{developerId} — found (with retryPolicy), foundNoRetryPolicy; 404
DELETE /api/webhooks/{developerId} — removed; 404
POST .../rotate-secret — rotated (64-char hex secret + expiry); 404
PATCH .../retry-policy — setCustomPolicy, setMaxRetriesOnly; 200;
maxRetriesOutOfRange + emptyRetryPolicy 400s; 404
POST .../deliver/{developerId} — newApiCall, settlementCompleted, lowBalanceAlert;
missingSignature 400; invalidSignature 401; 404
- Document X-Callora-Signature-256 and X-Callora-Timestamp header params on deliver endpoint
- Add src/routes/webhooks.openapi.test.ts with 8 describe groups:
path presence (including duplicate-key regression), register, get config,
delete, rotate-secret, retry-policy, deliver, and component schemas
Closes #<issue-number>
…s and OpenAPI docs (CalloraOrg#1134) - Validators (createTenantSchema, updateTenantSchema, tenantParamsSchema) with .strict() mode, field trimming, slug lowercasing, and metadata key limits were already in place in src/validators/tenants.ts - Routes (POST, PATCH, GET) were already wired to bodyValidator() and validate({ params, body }) in src/routes/tenants.ts producing structured ValidationError 400 envelopes with per-field details arrays - Add /api/tenants and /api/tenants/{tenantId} to src/openapi.yaml with: - Typed component schemas: TenantPlan, TenantMetadata, TenantRecord, TenantCreateRequest, TenantUpdateRequest, TenantResponse, TenantListResponse - Full request/response examples for all operations (create, update, list) - Structured 400 error examples: missingName, invalidEmail, unknownKey, invalidPlan, invalidParamAndEmptyBody with VALIDATION_ERROR code and per-field details array - ETag / 304 conditional-GET documentation for GET /api/tenants - 401 examples for all three operations - Add src/routes/tenants.openapi.test.ts covering: - OpenAPI YAML contract assertions (path presence, schema names, example keys) - POST integration: 400 per-field details, UNRECOGNIZED_KEYS, enum rejection, 201 success, whitespace trim, unauthenticated 401 - PATCH integration: combined param+body error collection, strict-schema unknown-key rejection, 200 success, 401 - GET integration: 200 list envelope, strong ETag header, 304 on match, 401 Closes #<issue-number>
- Wire strong SHA-256 ETag middleware (etagMiddleware) to GET /api/apis for RFC 7232 conditional GET support - Remove etagMiddleware from GET /:id (uses Express built-in weak ETag) - Add ?status query param validation to GET /api/apis with 400 on unknown values - Include status param in listings cache key to avoid cross-filter cache collision - Enrich GET /api/apis listing rows with developer info and endpoints - Extend ListingsCacheKeyParams and buildCacheKey to accept optional status field Closes CalloraOrg#682
…CalloraOrg#1137) Adds rateLimitAccessLogMiddleware that emits channel:rate_limit entries with req-id, latency, status, response size, and actor for every /api/rate-limit/* request. Closes CalloraOrg#767
* feat: add ETag/304 caching to GET /api/apis * feat: add Zod-validated /api/tenants schema with structured 400 errors and OpenAPI docs (CalloraOrg#1134) - Validators (createTenantSchema, updateTenantSchema, tenantParamsSchema) with .strict() mode, field trimming, slug lowercasing, and metadata key limits were already in place in src/validators/tenants.ts - Routes (POST, PATCH, GET) were already wired to bodyValidator() and validate({ params, body }) in src/routes/tenants.ts producing structured ValidationError 400 envelopes with per-field details arrays - Add /api/tenants and /api/tenants/{tenantId} to src/openapi.yaml with: - Typed component schemas: TenantPlan, TenantMetadata, TenantRecord, TenantCreateRequest, TenantUpdateRequest, TenantResponse, TenantListResponse - Full request/response examples for all operations (create, update, list) - Structured 400 error examples: missingName, invalidEmail, unknownKey, invalidPlan, invalidParamAndEmptyBody with VALIDATION_ERROR code and per-field details array - ETag / 304 conditional-GET documentation for GET /api/tenants - 401 examples for all three operations - Add src/routes/tenants.openapi.test.ts covering: - OpenAPI YAML contract assertions (path presence, schema names, example keys) - POST integration: 400 per-field details, UNRECOGNIZED_KEYS, enum rejection, 201 success, whitespace trim, unauthenticated 401 - PATCH integration: combined param+body error collection, strict-schema unknown-key rejection, 200 success, 401 - GET integration: 200 list envelope, strong ETag header, 304 on match, 401 Closes #<issue-number> * feat: ETag on /api/apis (CalloraOrg#1136) - Wire strong SHA-256 ETag middleware (etagMiddleware) to GET /api/apis for RFC 7232 conditional GET support - Remove etagMiddleware from GET /:id (uses Express built-in weak ETag) - Add ?status query param validation to GET /api/apis with 400 on unknown values - Include status param in listings cache key to avoid cross-filter cache collision - Enrich GET /api/apis listing rows with developer info and endpoints - Extend ListingsCacheKeyParams and buildCacheKey to accept optional status field Closes CalloraOrg#682 * feat(rate-limit): add structured JSON access logs for /api/rate-limit (CalloraOrg#1137) Adds rateLimitAccessLogMiddleware that emits channel:rate_limit entries with req-id, latency, status, response size, and actor for every /api/rate-limit/* request. Closes CalloraOrg#767 --------- Co-authored-by: Oluwaseyitan Animasaun <nvmseyi@Oluwaseyitans-MacBook-Pro.local> Co-authored-by: Haneefah Sanni <121475253+MissHarah@users.noreply.github.com> Co-authored-by: Isihaq123 <165170348+Isihaq123@users.noreply.github.com> Co-authored-by: dfwbigcharlie <charliechinedu19@gmail.com> Co-authored-by: greatest0fallt1me <192479186+greatest0fallt1me@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaced all bare type: object schemas with $ref references to 11 new typed component schemas: WebhookEventType, WebhookRetryPolicy, WebhookRegisterRequest, WebhookRegisterResponse, WebhookConfig, WebhookDeleteResponse, WebhookRotateSecretResponse, WebhookRetryPolicyUpdateRequest, WebhookRetryPolicyUpdateResponse, WebhookDeliveryPayload, and WebhookDeliveryResponse.
Fixed the duplicate /api/webhooks/{developerId} path key by consolidating GET and DELETE under a single path item.
Added multiple request and response examples per operation including three delivery event types, two retry policy update examples, and all error cases (400, 401, 404).
Documented the X-Callora-Signature-256 and X-Callora-Timestamp header parameters on the deliver endpoint.
Created src/routes/webhooks.openapi.test.ts with 8 describe groups and 25 assertions covering path presence, all operations, and all component schemas.
Closes #1068