docs: document waitpoint token API endpoints #3130
Conversation
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Repository UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
WalkthroughAdds a new "Waitpoints API" navigation group and five documentation pages (create, list, retrieve, complete, complete-callback). Extends the OpenAPI spec (docs/v3-openapi.yaml) with five new endpoints under /api/v1/waitpoints/tokens (create, list, retrieve, complete, callback-complete), six new schemas (Create*/Complete*/List*/WaitpointTokenObject), and a new security scheme Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/v3-openapi.yaml (1)
2732-2739: Tightenfilter[status]typing to improve generated client safety.At Line 2732 the schema is a free-form string, but Line 2738 constrains values. Encoding this as a CSV array enum will give SDKs and validators stronger typing.
♻️ Proposed schema refinement
- in: query name: "filter[status]" + style: form + explode: false schema: - type: string + type: array + items: + type: string + enum: [WAITING, COMPLETED, TIMED_OUT] required: false description: >- Comma-separated list of statuses to filter by. Allowed values: `WAITING`, `COMPLETED`, `TIMED_OUT`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3-openapi.yaml` around lines 2732 - 2739, Change the parameter schema for "filter[status]" from a free-form string to a CSV-style array so generated clients get enum typing: replace schema: type: string with schema: type: array, items: { type: string, enum: ["WAITING","COMPLETED","TIMED_OUT"] }, and add serialization hints style: form and explode: false (keep the description and example as a CSV string or provide an array example) so clients/validators treat it as an array-of-enum parsed from a comma-separated value.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/v3-openapi.yaml`:
- Around line 3134-3135: The OpenAPI contract is missing the publicAccessToken
field in the CreateWaitpointTokenResponse schema even though docs say
wait.createToken() / POST /api/v1/waitpoints/tokens returns it; update the
CreateWaitpointTokenResponse schema to include a new property named
publicAccessToken (string, description indicating it's a short-lived JWT scoped
to the waitpoint token) and mark it required if callers depend on its presence,
ensuring the schema aligns with the documented auth flow for
wait.createToken()/POST /api/v1/waitpoints/tokens.
---
Nitpick comments:
In `@docs/v3-openapi.yaml`:
- Around line 2732-2739: Change the parameter schema for "filter[status]" from a
free-form string to a CSV-style array so generated clients get enum typing:
replace schema: type: string with schema: type: array, items: { type: string,
enum: ["WAITING","COMPLETED","TIMED_OUT"] }, and add serialization hints style:
form and explode: false (keep the description and example as a CSV string or
provide an array example) so clients/validators treat it as an array-of-enum
parsed from a comma-separated value.
ℹ️ Review info
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/v3-openapi.yaml
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Mintlify Deployment
- GitHub Check: Analyze (python)
- GitHub Check: Analyze (javascript-typescript)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{js,ts,jsx,tsx,json,md,yaml,yml}
📄 CodeRabbit inference engine (AGENTS.md)
Format code using Prettier before committing
Files:
docs/v3-openapi.yaml
🧠 Learnings (5)
📓 Common learnings
Learnt from: matt-aitken
Repo: triggerdotdev/trigger.dev PR: 2025
File: apps/webapp/app/routes/api.v1.waitpoints.http-callback.$waitpointFriendlyId.callback.ts:0-0
Timestamp: 2025-05-07T09:59:03.771Z
Learning: Matt implemented a cryptographic hash in webhook callback URLs using HMAC-SHA256 with the API key as the secret to prevent unauthorized completion of waitpoints in the Trigger.dev platform.
Learnt from: matt-aitken
Repo: triggerdotdev/trigger.dev PR: 2025
File: apps/webapp/app/routes/api.v1.waitpoints.http-callback.$waitpointFriendlyId.callback.ts:0-0
Timestamp: 2025-05-07T09:59:03.771Z
Learning: Matt implemented a cryptographic hash in webhook callback URLs using HMAC-SHA256 with the API key as the secret to prevent unauthorized completion of waitpoints in the Trigger.dev platform.
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use the `task()` function from `trigger.dev/sdk/v3` to define tasks with id and run properties
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `idempotencyKeys.create()` to create idempotency keys for preventing duplicate task executions
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `schemaTask()` from `trigger.dev/sdk/v3` with Zod schema for payload validation
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerByTaskAndWait()` to batch trigger tasks by passing task instances and wait for results
Applied to files:
docs/v3-openapi.yaml
🔇 Additional comments (1)
docs/v3-openapi.yaml (1)
2807-2839: Callback auth docs are clear and correctly scoped.Nice job documenting that
callbackHashin the URL is the authenticator and that no API key is required for this endpoint; this makes the intended external-webhook flow explicit.Based on learnings: “Matt implemented a cryptographic hash in webhook callback URLs using HMAC-SHA256 with the API key as the secret to prevent unauthorized completion of waitpoints in the Trigger.dev platform.”
| A short-lived JWT scoped to a specific waitpoint token. Returned as `publicAccessToken` | ||
| when you call `wait.createToken()` or `POST /api/v1/waitpoints/tokens`. |
There was a problem hiding this comment.
publicAccessToken is documented as returned but missing from the create response schema.
Line 3134 says the token is returned by wait.createToken() / POST /api/v1/waitpoints/tokens, but CreateWaitpointTokenResponse (Line 4716 onward) does not include that field. This leaves the documented auth flow untyped in the OpenAPI contract.
🐛 Proposed contract fix
CreateWaitpointTokenResponse:
type: object
required:
- id
- isCached
- url
+ - publicAccessToken
properties:
id:
type: string
description: The unique ID of the waitpoint token.
example: waitpoint_abc123
isCached:
type: boolean
description: >-
`true` if an existing token was returned because the same `idempotencyKey`
was used within its TTL window.
url:
type: string
description: >-
An HTTP callback URL. A POST request to this URL (with an optional JSON body)
will complete the waitpoint without needing an API key.
example: https://api.trigger.dev/api/v1/waitpoints/tokens/waitpoint_abc123/callback/abc123hash
+ publicAccessToken:
+ type: string
+ description: >-
+ A short-lived JWT scoped to this waitpoint token, usable with
+ `POST /api/v1/waitpoints/tokens/{waitpointId}/complete`.
+ example: eyJhbGciOi...Also applies to: 4716-4736
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/v3-openapi.yaml` around lines 3134 - 3135, The OpenAPI contract is
missing the publicAccessToken field in the CreateWaitpointTokenResponse schema
even though docs say wait.createToken() / POST /api/v1/waitpoints/tokens returns
it; update the CreateWaitpointTokenResponse schema to include a new property
named publicAccessToken (string, description indicating it's a short-lived JWT
scoped to the waitpoint token) and mark it required if callers depend on its
presence, ensuring the schema aligns with the documented auth flow for
wait.createToken()/POST /api/v1/waitpoints/tokens.
There was a problem hiding this comment.
publicAccessToken is not in the HTTP response body. The server returns only { id, isCached, url }
(confirmed by both the route handler and the CreateWaitpointTokenResponseBody Zod schema). The
SDK's prepareData hook generates the JWT client-side from the x-trigger-jwt-claims response header
after the HTTP call completes — it never comes over the wire. The OpenAPI spec correctly documents
the actual API contract.
There was a problem hiding this comment.
@isshaddad, thank you for the clarification! You're absolutely right—I was mistaken. The OpenAPI spec correctly documents the HTTP contract, which returns only { id, isCached, url } in the response body. The publicAccessToken is derived client-side by the SDK from the x-trigger-jwt-claims response header, so it's correct to exclude it from CreateWaitpointTokenResponse.
The security scheme description is also fine since it describes where users obtain the token (via the SDK method or the HTTP endpoint + header processing), not strictly the HTTP response body schema.
Apologies for the noise!
✏️ Learnings added
Learnt from: isshaddad
Repo: triggerdotdev/trigger.dev PR: 3130
File: docs/v3-openapi.yaml:3134-3135
Timestamp: 2026-02-25T17:28:11.906Z
Learning: In the Trigger.dev codebase, the `publicAccessToken` returned by the SDK's `wait.createToken()` method is not part of the HTTP response body from `POST /api/v1/waitpoints/tokens`. The server returns only `{ id, isCached, url }`. The SDK's `prepareData` hook generates the JWT client-side from the `x-trigger-jwt-claims` response header after the HTTP call completes. The OpenAPI spec correctly documents only the HTTP response body, not SDK transformations.
<!-- [/add_learning]
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: matt-aitken
Repo: triggerdotdev/trigger.dev PR: 2025
File: apps/webapp/app/routes/api.v1.waitpoints.http-callback.$waitpointFriendlyId.callback.ts:0-0
Timestamp: 2025-05-07T09:59:03.771Z
Learning: Matt implemented a cryptographic hash in webhook callback URLs using HMAC-SHA256 with the API key as the secret to prevent unauthorized completion of waitpoints in the Trigger.dev platform.
Learnt from: matt-aitken
Repo: triggerdotdev/trigger.dev PR: 2025
File: apps/webapp/app/routes/api.v1.waitpoints.http-callback.$waitpointFriendlyId.callback.ts:0-0
Timestamp: 2025-05-07T09:59:03.771Z
Learning: Matt implemented a cryptographic hash in webhook callback URLs using HMAC-SHA256 with the API key as the secret to prevent unauthorized completion of waitpoints in the Trigger.dev platform.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
2 participants
Adds REST API documentation for the 5 waitpoint token endpoints (
/api/v1/waitpoints/tokens), including create, list, retrieve, complete, and HTTP callback. Also adds thepublicAccessTokensecurity scheme used by the complete endpoint.Mintlify
0 threads from 0 users in Mintlify