Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughUnhides several payments API routes and enriches them with OpenAPI metadata and examples; changes update-quantity to return an empty object. Adds OpenAPI tuple handling. Introduces SDK type documentation components and new SDK type pages (Customer, Item, ServerItem), adds Payments functional tag and docs platform entries. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Reader as Docs Viewer
participant Page as TypeFromJson
participant Server as /sdk-docs/types.json
participant Renderer as TypeDocumentation
Reader->>Page: open type page (typeName)
activate Page
Note right of Page #DDEBF7: fetch type definitions (async)
Page->>Server: GET /sdk-docs/types.json
alt fetch OK
Server-->>Page: JSON with types
Page->>Page: extract typeInfo for typeName
Page-->>Renderer: render TypeDocumentation(typeInfo, platform)
Renderer-->>Reader: show header, TOC, members, source
else fetch error
Server-->>Page: error
Page-->>Reader: show error/fallback UI
end
deactivate Page
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
🧰 Additional context used📓 Path-based instructions (2)apps/backend/src/app/api/latest/**📄 CodeRabbit inference engine (AGENTS.md)
Files:
**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
🧬 Code graph analysis (1)apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts (1)
⏰ 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). (10)
🔇 Additional comments (2)
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 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Greptile Overview
Summary
This PR adds comprehensive SDK and API documentation for Stack Auth's payments system. The changes expose previously hidden payment endpoints to the public API and create detailed documentation for payment-related types and methods.The core additions include:
API Documentation: Multiple payment endpoints are being exposed from hidden internal APIs to public documented endpoints by setting hidden: false and adding extensive OpenAPI metadata. This includes endpoints for creating purchase URLs, validating purchase codes, managing item quantities, and retrieving item information.
SDK Type Documentation: New documentation files are created for Customer, Item, and ServerItem types, which form the foundation of Stack Auth's payment system. The Customer interface provides payment functionality that both User and Team types extend, enabling consistent payment operations across different entity types.
Payment Methods Integration: Existing User and Team documentation is extended with payment capabilities including createCheckoutUrl() for Stripe integration and getItem()/useItem() methods for managing quantifiable resources like credits, API quotas, and storage limits.
Infrastructure Updates: Supporting changes include adding 'Payments' to the documentation generation system, creating a new TypeScript component for rendering SDK type documentation, adding tuple schema support to OpenAPI generation, and updating navigation structures.
The payment system appears to be built around a flexible item management concept where teams and users can purchase and manage quantifiable resources. The Item type handles read-only access while ServerItem provides server-side methods with race-condition protection for safe quantity modifications. All payment operations integrate with Stripe and include proper validation, security checks, and redirect URL validation.
Important Files Changed
Changed Files
| Filename | Score | Overview |
|---|---|---|
| apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts | 4/5 | Exposes payment endpoint with comprehensive OpenAPI documentation for creating Stripe checkout URLs |
| apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts | 4/5 | Converts hidden endpoint to public API for updating item quantities with full OpenAPI metadata |
| apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts | 4/5 | Makes purchase code validation endpoint public with proper documentation and security validation |
| apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts | 5/5 | Simple conversion from hidden to public API endpoint for retrieving item information |
| apps/backend/src/lib/openapi.tsx | 4/5 | Adds tuple schema support to OpenAPI generation for better header documentation |
| docs/templates/sdk/types/item.mdx | 5/5 | Creates comprehensive documentation for Item and ServerItem types with detailed examples |
| docs/templates/sdk/types/customer.mdx | 4/5 | Adds new Customer interface documentation covering payment methods and item management |
| docs/templates/sdk/types/user.mdx | 5/5 | Extends CurrentUser documentation with payment functionality and proper type definitions |
| docs/templates/sdk/types/team.mdx | 5/5 | Adds payment methods to Team documentation following established patterns |
| docs/src/components/sdk/type-documentation.tsx | 4/5 | Creates new TypeScript component for rendering SDK type documentation with some implementation concerns |
| docs/templates/sdk/index.mdx | 5/5 | Adds 'Payments & Items' section to SDK documentation navigation |
| docs/templates/sdk/meta.json | 5/5 | Updates navigation structure to include new payment-related documentation pages |
| docs/docs-platform.yml | 5/5 | Configures new SDK documentation entries for customer and item types |
| docs/scripts/generate-functional-api-docs.mjs | 5/5 | Adds 'Payments' tag to enable documentation generation for payment endpoints |
Confidence score: 4/5
- This PR is safe to merge with moderate confidence as it primarily consists of documentation changes and API exposure
- Score reflects comprehensive documentation additions but some implementation concerns in the new TypeScript component and potential edge cases in API validation
- Pay close attention to the new TypeScript documentation component and redirect URL validation in payment endpoints
14 files reviewed, 4 comments
![recurseml[bot]](https://avatars.githubusercontent.com/in/1054195?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review by RecurseML
🔍 Review performed on 017b43f..5bb462a
✨ No bugs found, your code is sparkling clean
✅ Files analyzed, no issues (15)
• apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts
• apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
• apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
• apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx
• apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts
• apps/backend/src/lib/openapi.tsx
• docs/docs-platform.yml
• docs/scripts/generate-functional-api-docs.mjs
• docs/src/components/sdk/type-documentation.tsx
• docs/templates/sdk/index.mdx
• docs/templates/sdk/meta.json
• docs/templates/sdk/types/customer.mdx
• docs/templates/sdk/types/item.mdx
• docs/templates/sdk/types/team.mdx
• docs/templates/sdk/types/user.mdx
![ellipsis-dev[bot]](https://avatars.githubusercontent.com/in/64358?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (15)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts(2 hunks)apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts(2 hunks)apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts(2 hunks)apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx(1 hunks)apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts(1 hunks)apps/backend/src/lib/openapi.tsx(1 hunks)docs/docs-platform.yml(1 hunks)docs/scripts/generate-functional-api-docs.mjs(1 hunks)docs/src/components/sdk/type-documentation.tsx(1 hunks)docs/templates/sdk/index.mdx(1 hunks)docs/templates/sdk/meta.json(1 hunks)docs/templates/sdk/types/customer.mdx(1 hunks)docs/templates/sdk/types/item.mdx(1 hunks)docs/templates/sdk/types/team.mdx(2 hunks)docs/templates/sdk/types/user.mdx(2 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
apps/backend/src/lib/openapi.tsxapps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.tsapps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsxapps/backend/src/app/api/latest/payments/purchases/validate-code/route.tsdocs/src/components/sdk/type-documentation.tsxapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
apps/backend/src/app/api/latest/**
📄 CodeRabbit inference engine (AGENTS.md)
apps/backend/src/app/api/latest/**: Organize backend API routes by resource under /api/latest (e.g., auth at /api/latest/auth/, users at /api/latest/users/, teams at /api/latest/teams/, oauth providers at /api/latest/oauth-providers/)
Use the custom route handler system in the backend to ensure consistent API responses
Files:
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.tsapps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsxapps/backend/src/app/api/latest/payments/purchases/validate-code/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
🧬 Code graph analysis (6)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
packages/stack-shared/src/schema-fields.ts (5)
yupString(187-190)inlineProductSchema(593-614)urlSchema(334-342)yupObject(247-251)yupNumber(191-194)
apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx (1)
packages/stack-shared/src/schema-fields.ts (3)
yupObject(247-251)yupString(187-190)yupNumber(191-194)
apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts (1)
packages/stack-shared/src/schema-fields.ts (3)
yupObject(247-251)yupString(187-190)urlSchema(334-342)
docs/src/components/sdk/type-documentation.tsx (2)
docs/src/components/ui/method-layout.tsx (5)
CollapsibleTypesSection(291-432)MethodLayout(79-88)MethodContent(90-99)MethodAside(101-118)AsideSection(120-137)docs/src/components/mdx/sdk-components.tsx (2)
ParamField(455-486)ClickableTableOfContents(531-612)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts (1)
packages/stack-shared/src/schema-fields.ts (3)
yupString(187-190)yupObject(247-251)yupNumber(191-194)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
POST(13-129)packages/stack-shared/src/schema-fields.ts (3)
yupString(187-190)yupObject(247-251)yupNumber(191-194)
⏰ 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). (10)
- GitHub Check: Vercel Agent Review
- GitHub Check: docker
- GitHub Check: restart-dev-and-test
- GitHub Check: setup-tests
- GitHub Check: build (22.x)
- GitHub Check: lint_and_build (latest)
- GitHub Check: all-good
- GitHub Check: build (22.x)
- GitHub Check: docker
- GitHub Check: Security Check
🔇 Additional comments (20)
apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts (2)
22-26: LGTM! Well-documented API endpoint.The metadata additions make this endpoint discoverable in OpenAPI documentation. The summary and description clearly explain the endpoint's purpose.
29-40: LGTM! Clear field documentation.The openapiField metadata provides helpful descriptions and realistic example values for both fields.
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (3)
15-18: LGTM! Clear endpoint documentation.The metadata additions properly document the endpoint's purpose and make it discoverable in OpenAPI specs.
27-56: LGTM! Comprehensive field documentation.All request body fields have clear descriptions and realistic example values that help API consumers understand the expected input.
62-67: LGTM! Response field properly documented.The response field documentation provides a clear example of the checkout URL format.
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts (3)
11-14: LGTM! Clear endpoint documentation.The metadata additions make this GET endpoint discoverable with appropriate summary and description.
23-40: LGTM! Well-documented path parameters.All three path parameters have clear descriptions and consistent example values that match the patterns used in other payment routes.
47-64: LGTM! Complete response documentation.The response fields are well-documented with clear descriptions and appropriate example values.
apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx (3)
13-16: LGTM! Clear endpoint documentation.The metadata additions properly describe the endpoint's Stripe integration purpose.
20-37: LGTM! Well-documented request fields.All request body fields have clear descriptions and appropriate example values for creating a Stripe purchase session.
44-49: LGTM! Response field properly documented.The client_secret field documentation includes a realistic example value for the Stripe client secret format.
docs/templates/sdk/types/team.mdx (2)
484-527: LGTM! Clear payment integration documentation.The
createCheckoutUrlmethod documentation is well-structured with clear parameters, return type, and a practical example showing team-level purchases.
529-606: LGTM! Comprehensive item retrieval documentation.Both
getItemanduseItem(React hook) methods are thoroughly documented with clear descriptions, parameters, and helpful examples demonstrating quota monitoring use cases.docs/templates/sdk/types/user.mdx (2)
1568-1609: LGTM! Clear user-level payment documentation.The
createCheckoutUrlmethod documentation is well-structured and the example appropriately demonstrates user-level product purchases.
1611-1685: LGTM! Comprehensive item management documentation.Both
getItemanduseItemmethods are thoroughly documented with clear examples showing credit management use cases, including thenonNegativeQuantityproperty usage.apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (4)
11-14: LGTM! Clear quantity update documentation.The metadata additions properly describe the item quantity update functionality with appropriate detail about negative balance control.
23-48: LGTM! Well-documented parameters.All path parameters and the query parameter are clearly documented with consistent example values and helpful descriptions.
51-68: LGTM! Comprehensive request body documentation.The delta field documentation clearly explains the positive/negative concept for increasing/decreasing quantities, and optional fields have appropriate descriptions and examples.
75-80: LGTM! Response field properly documented.The response field documentation clearly identifies the returned quantity change record ID.
apps/backend/src/lib/openapi.tsx (1)
209-219: Tuple mapping is correct for header parameters
All discoveredyupTupleusages in API routes are header definitions; treating them as arrays fits OpenAPI’s model.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/src/components/sdk/type-documentation.tsx(1 hunks)docs/templates/sdk/types/customer.mdx(1 hunks)docs/templates/sdk/types/item.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/templates/sdk/types/item.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/templates/sdk/types/customer.mdx
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
docs/src/components/sdk/type-documentation.tsx
🧬 Code graph analysis (1)
docs/src/components/sdk/type-documentation.tsx (3)
docs/src/components/ui/method-layout.tsx (5)
CollapsibleTypesSection(291-432)MethodLayout(79-88)MethodContent(90-99)MethodAside(101-118)AsideSection(120-137)docs/src/components/mdx/sdk-components.tsx (2)
ParamField(455-486)ClickableTableOfContents(531-612)packages/stack-shared/src/utils/promises.tsx (1)
runAsynchronously(343-366)
⏰ 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). (10)
- GitHub Check: Vercel Agent Review
- GitHub Check: build (22.x)
- GitHub Check: all-good
- GitHub Check: docker
- GitHub Check: lint_and_build (latest)
- GitHub Check: restart-dev-and-test
- GitHub Check: docker
- GitHub Check: build (22.x)
- GitHub Check: setup-tests
- GitHub Check: Security Check
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/src/components/sdk/type-documentation.tsx (1)
304-331: Optional simplification: runAsynchronously may be unnecessary.Since
loadTypeInfoalready wraps all async operations in try-catch and updates state rather than throwing, therunAsynchronouslywrapper on line 330 doesn't provide additional error handling. The error handling withinloadTypeInfois comprehensive and sufficient.Consider this simplification:
- runAsynchronously(loadTypeInfo()); + loadTypeInfo();Additionally, for improved type safety, you could add a type assertion for the JSON response:
const typesData = await response.json(); - const foundType = typesData[typeName]; + const foundType = (typesData as Record<string, TypeInfo>)[typeName];
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/src/components/sdk/type-documentation.tsx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
docs/src/components/sdk/type-documentation.tsx
🧬 Code graph analysis (1)
docs/src/components/sdk/type-documentation.tsx (3)
docs/src/components/ui/method-layout.tsx (5)
CollapsibleTypesSection(291-432)MethodLayout(79-88)MethodContent(90-99)MethodAside(101-118)AsideSection(120-137)docs/src/components/mdx/sdk-components.tsx (2)
ParamField(455-486)ClickableTableOfContents(531-612)packages/stack-shared/src/utils/promises.tsx (1)
runAsynchronously(343-366)
⏰ 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). (10)
- GitHub Check: Vercel Agent Review
- GitHub Check: docker
- GitHub Check: setup-tests
- GitHub Check: build (22.x)
- GitHub Check: restart-dev-and-test
- GitHub Check: lint_and_build (latest)
- GitHub Check: all-good
- GitHub Check: docker
- GitHub Check: build (22.x)
- GitHub Check: Security Check
🔇 Additional comments (5)
docs/src/components/sdk/type-documentation.tsx (5)
1-48: LGTM: Well-structured type definitions and imports.The component setup is clean with appropriate client-side directive, and the TypeScript interfaces accurately model the expected JSON structure for type documentation.
58-103: Well done: Anchor generation now matches section IDs.The
buildAnchorIdfunction correctly sanitizes both type and member names to match the anchor logic inCollapsibleTypesSection, resolving the previous review concern about ToC link mismatches.
105-217: LGTM: Signature guard properly implemented.The
primarySignatureextraction and consistent use of optional chaining/nullish coalescing throughout this function successfully addresses the previous review concern about dereferencing potentially empty signature arrays.
219-296: LGTM: Clean component structure.The component provides a well-organized documentation layout with proper heading hierarchy and conditional rendering for optional sections (mixins, members).
333-358: LGTM: Excellent user feedback.The component provides clear, accessible feedback for loading, error, and empty states with appropriate styling and messaging.
...p/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts
Outdated
Show resolved
Hide resolved
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (1)
74-74: Response body change acknowledged (breaking but intentional).The response no longer includes the
idfield, aligning with the past review comment that the internal identifier serves no client purpose. This is a breaking API change but was explicitly requested.The transaction logic correctly creates the
ItemQuantityChangerecord without capturing its ID since it's no longer returned.Optional: Consider 204 No Content status code.
For operations that succeed without returning data, HTTP 204 (No Content) is more semantically appropriate than 200 with an empty body. However, this may be a framework convention, so only apply if it aligns with your API patterns.
response: yupObject({ - statusCode: yupNumber().oneOf([200]).defined(), + statusCode: yupNumber().oneOf([204]).defined(), bodyType: yupString().oneOf(["json"]).defined(), body: yupObject({}).defined(), }),And:
return { - statusCode: 200, + statusCode: 204, bodyType: "json", body: {}, };Also applies to: 96-118, 123-123
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts(5 hunks)apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts(2 hunks)apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx(1 hunks)apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx
- apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
🧰 Additional context used
📓 Path-based instructions (2)
apps/backend/src/app/api/latest/**
📄 CodeRabbit inference engine (AGENTS.md)
apps/backend/src/app/api/latest/**: Organize backend API routes by resource under /api/latest (e.g., auth at /api/latest/auth/, users at /api/latest/users/, teams at /api/latest/teams/, oauth providers at /api/latest/oauth-providers/)
Use the custom route handler system in the backend to ensure consistent API responses
Files:
apps/backend/src/app/api/latest/payments/purchases/validate-code/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
apps/backend/src/app/api/latest/payments/purchases/validate-code/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
🧬 Code graph analysis (2)
apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts (1)
packages/stack-shared/src/schema-fields.ts (3)
yupObject(247-251)yupString(187-190)urlSchema(334-342)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)
packages/stack-shared/src/schema-fields.ts (3)
yupString(187-190)yupObject(247-251)yupNumber(191-194)apps/backend/src/prisma-client.tsx (1)
retryTransaction(147-222)
⏰ 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). (10)
- GitHub Check: setup-tests
- GitHub Check: restart-dev-and-test
- GitHub Check: Vercel Agent Review
- GitHub Check: all-good
- GitHub Check: build (22.x)
- GitHub Check: docker
- GitHub Check: build (22.x)
- GitHub Check: lint_and_build (latest)
- GitHub Check: docker
- GitHub Check: Security Check
🔇 Additional comments (5)
apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts (2)
22-25: LGTM! Endpoint properly documented for OpenAPI.The metadata updates unhide this endpoint and add appropriate OpenAPI documentation (summary, description, and tags). This aligns with the PR's objective to document payment APIs.
29-40: LGTM! Field documentation added with appropriate metadata.The
openapiFieldmetadata enriches the OpenAPI schema with clear descriptions and realistic example values. The description forfull_codeaccurately describes its source (query parameter in the purchase URL) even though it's passed in the request body here.apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (3)
11-14: LGTM! Route documentation added.The route is now properly documented with OpenAPI metadata, making it visible in the public API documentation. The summary, description, and tags are clear and follow documentation best practices.
23-68: LGTM! Comprehensive OpenAPI field documentation.The OpenAPI metadata for all request parameters is well-structured with clear descriptions and appropriate example values. The field types align correctly with the schema definitions.
96-118: LGTM! Transaction logic is correct and well-structured.The transaction properly:
- Uses
retryTransactionfor resilience against transient failures- Validates quantity constraints before modification (respecting
allowNegative)- Creates the quantity change record with appropriate field transformations (
typedToUppercaseforcustomerType)- Maintains transactional integrity by scoping all operations within the transaction
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
62-66: Consider adding an example value for documentation completeness.All request fields include
exampleValue, but the responseurlfield does not. Adding one would improve API documentation consistency and help consumers understand the expected format.Apply this diff:
url: yupString().defined().meta({ openapiField: { - description: "The secure checkout URL for completing the purchase" + description: "The secure checkout URL for completing the purchase", + exampleValue: "https://dashboard.stack-auth.com/purchase/proj_abc123_code456?return_url=https%3A%2F%2Fmyapp.com%2Fpurchase-success" } }),
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts(2 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
apps/backend/src/app/api/latest/**
📄 CodeRabbit inference engine (AGENTS.md)
apps/backend/src/app/api/latest/**: Organize backend API routes by resource under /api/latest (e.g., auth at /api/latest/auth/, users at /api/latest/users/, teams at /api/latest/teams/, oauth providers at /api/latest/oauth-providers/)
Use the custom route handler system in the backend to ensure consistent API responses
Files:
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
🧬 Code graph analysis (1)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
packages/stack-shared/src/schema-fields.ts (5)
yupString(187-190)inlineProductSchema(593-614)urlSchema(334-342)yupObject(247-251)yupNumber(191-194)
⏰ 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). (10)
- GitHub Check: build (22.x)
- GitHub Check: build (22.x)
- GitHub Check: lint_and_build (latest)
- GitHub Check: restart-dev-and-test
- GitHub Check: docker
- GitHub Check: all-good
- GitHub Check: setup-tests
- GitHub Check: docker
- GitHub Check: Vercel Agent Review
- GitHub Check: Security Check
🔇 Additional comments (1)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
14-19: LGTM! Well-documented route metadata.The route is now properly exposed with clear documentation. The summary and description accurately describe the endpoint's purpose without implementation details.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
apps/e2e/tests/backend/endpoints/api/v1/payments/items.test.ts(3 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.test.{ts,tsx,js}
📄 CodeRabbit inference engine (AGENTS.md)
In tests, prefer .toMatchInlineSnapshot where possible; refer to snapshot-serializer.ts for snapshot formatting and handling of non-deterministic values
Files:
apps/e2e/tests/backend/endpoints/api/v1/payments/items.test.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
apps/e2e/tests/backend/endpoints/api/v1/payments/items.test.ts
🧬 Code graph analysis (1)
apps/e2e/tests/backend/endpoints/api/v1/payments/items.test.ts (1)
apps/e2e/tests/helpers.ts (1)
it(11-11)
⏰ 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). (10)
- GitHub Check: Vercel Agent Review
- GitHub Check: docker
- GitHub Check: all-good
- GitHub Check: setup-tests
- GitHub Check: docker
- GitHub Check: build (22.x)
- GitHub Check: restart-dev-and-test
- GitHub Check: build (22.x)
- GitHub Check: lint_and_build (latest)
- GitHub Check: Security Check
🔇 Additional comments (2)
apps/e2e/tests/backend/endpoints/api/v1/payments/items.test.ts (2)
140-140: LGTM!The test name accurately reflects the updated behavior where the endpoint returns a success status without an ID.
415-421: LGTM!The inline snapshot correctly reflects the new behavior where the endpoint returns an empty body on success.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts(2 hunks)apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts(2 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
🧰 Additional context used
📓 Path-based instructions (2)
apps/backend/src/app/api/latest/**
📄 CodeRabbit inference engine (AGENTS.md)
apps/backend/src/app/api/latest/**: Organize backend API routes by resource under /api/latest (e.g., auth at /api/latest/auth/, users at /api/latest/users/, teams at /api/latest/teams/, oauth providers at /api/latest/oauth-providers/)
Use the custom route handler system in the backend to ensure consistent API responses
Files:
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
🧬 Code graph analysis (1)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
POST(13-142)packages/stack-shared/src/schema-fields.ts (3)
yupString(187-190)yupObject(247-251)yupNumber(191-194)
⏰ 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). (10)
- GitHub Check: all-good
- GitHub Check: Vercel Agent Review
- GitHub Check: docker
- GitHub Check: build (22.x)
- GitHub Check: restart-dev-and-test
- GitHub Check: setup-tests
- GitHub Check: docker
- GitHub Check: lint_and_build (latest)
- GitHub Check: build (22.x)
- GitHub Check: Security Check
🔇 Additional comments (2)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)
11-14: LGTM: Route visibility and documentation improvements.The route is now properly documented with a clear summary, description, and tagged under "Payments". Making it public (
hidden: false) with comprehensive OpenAPI metadata aligns with the PR's objective to document the payments API.
23-68: LGTM: Comprehensive OpenAPI metadata for all parameters.All path parameters, query parameters, and body fields now have clear descriptions and appropriate example values. The metadata follows the patterns established in other payment routes and will generate accurate API documentation.
...p/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
45-48: Inconsistent punctuation in description.The
product_iddescription on Line 41 ends with a period, but this description does not. For consistency, consider adding a period at the end.Apply this diff to add consistent punctuation:
product_inline: inlineProductSchema.optional().meta({ openapiField: { - description: "Inline product definition. Either this or product_id should be given." + description: "Inline product definition. Either this or product_id should be given." } }),
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts(2 hunks)apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts(2 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
apps/backend/src/app/api/latest/**
📄 CodeRabbit inference engine (AGENTS.md)
apps/backend/src/app/api/latest/**: Organize backend API routes by resource under /api/latest (e.g., auth at /api/latest/auth/, users at /api/latest/users/, teams at /api/latest/teams/, oauth providers at /api/latest/oauth-providers/)
Use the custom route handler system in the backend to ensure consistent API responses
Files:
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Prefer ES6 Map over Record when representing key–value collections
Files:
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
🧬 Code graph analysis (2)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
packages/stack-shared/src/schema-fields.ts (5)
yupString(187-190)inlineProductSchema(593-614)urlSchema(334-342)yupObject(247-251)yupNumber(191-194)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)
apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)
POST(13-142)packages/stack-shared/src/schema-fields.ts (3)
yupString(187-190)yupObject(247-251)yupNumber(191-194)
⏰ 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). (10)
- GitHub Check: all-good
- GitHub Check: Vercel Agent Review
- GitHub Check: docker
- GitHub Check: build (22.x)
- GitHub Check: restart-dev-and-test
- GitHub Check: setup-tests
- GitHub Check: docker
- GitHub Check: lint_and_build (latest)
- GitHub Check: build (22.x)
- GitHub Check: Security Check
🔇 Additional comments (2)
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)
11-14: LGTM! Clear OpenAPI metadata.The metadata additions appropriately document this endpoint for the payments API. The summary and description clearly explain the endpoint's purpose and capabilities.
23-68: LGTM! Comprehensive parameter documentation.The OpenAPI field metadata for all parameters is thorough and helpful. Examples are realistic and descriptions clearly explain each field's purpose.
...p/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts
Show resolved
Hide resolved
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts
Show resolved
Hide resolved
2 participants
Adds SDK and API docs for payments.
High-level PR Summary
This PR adds comprehensive SDK and API documentation for Stack Auth's payment functionality. It includes documentation for payment-related types (
Customer,Item,ServerItem), extends existing user and team documentation with payment methods (createCheckoutUrl,getItem,useItem), and enhances API endpoint documentation for payment operations including item management, purchase URLs, and checkout sessions. The changes also include infrastructure improvements for generating payment-related documentation and OpenAPI schema support for tuple types.⏱️ Estimated Review Time: 30-90 minutes
💡 Review Order Suggestion
docs/docs-platform.ymldocs/templates/sdk/meta.jsondocs/templates/sdk/index.mdxdocs/scripts/generate-functional-api-docs.mjsdocs/templates/sdk/types/customer.mdxdocs/templates/sdk/types/item.mdxdocs/templates/sdk/types/user.mdxdocs/templates/sdk/types/team.mdxapps/backend/src/lib/openapi.tsxapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.tsapps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.tsapps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.tsapps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsxapps/backend/src/app/api/latest/payments/purchases/validate-code/route.tsdocs/src/components/sdk/type-documentation.tsxImportant
Adds comprehensive SDK and API documentation for payment functionalities, including new types and methods, and enhances OpenAPI schema generation.
Customer,Item, andServerItemtypes.createCheckoutUrl,getItem,useItem.generate-functional-api-docs.mjsto includePaymentsin functional tags.Customer,Item,ServerItem.docs-platform.ymlto include new documentation paths.type-documentation.tsxfor rendering type documentation.This description was created by
for 96491d7. You can customize this summary. It will automatically update as commits are pushed.
Summary by CodeRabbit
New Features
Documentation
Tests
Chores