chore(backend): Add webhook event types for Commerce related events #6338
Conversation
We recently introduced webhook events for Commerce: payment attempts and subscription events. This commit adds type safety so developer can create type-safe webhook handlers.
🦋 Changeset detectedLatest commit: c5b082b The changes in this PR will be included in the next version bump. This PR includes changesets to release 11 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/elements
@clerk/clerk-expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/clerk-react
@clerk/react-router
@clerk/remix
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/themes
@clerk/types
@clerk/upgrade
@clerk/vue
commit: |
📝 WalkthroughWalkthroughThis change introduces new commerce-related resource types and webhook events to the backend API. It adds several TypeScript interfaces representing commerce entities such as payers, payees, payment attempts, subscriptions, subscription items, plans, payment sources, amounts, totals, credits, and payment failure reasons. These interfaces are incorporated into the resource model and exported for use elsewhere in the codebase. Additionally, new webhook event types are defined for commerce payment attempts, subscriptions, and subscription items, and these are included in the union of recognized webhook events. No existing code or interfaces are modified or removed. Estimated code review effort2 (10–30 minutes) 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (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). (5)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
packages/backend/src/api/resources/JSON.ts (1)
778-783: Consider extending ClerkResourceJSON for consistency.The
CommercePayeeJSONinterface doesn't extendClerkResourceJSONunlike other commerce entities. Consider whether this should be consistent with the pattern used by other commerce interfaces.-export interface CommercePayeeJSON { +export interface CommercePayeeJSON extends ClerkResourceJSON { + object: typeof ObjectType.CommercePayee; id: string; gateway_type: string; gateway_external_id: string; gateway_status: string; }Note: This would require adding
CommercePayee: 'commerce_payee'to the ObjectType constant.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
packages/backend/src/api/resources/JSON.ts(2 hunks)packages/backend/src/api/resources/Webhooks.ts(3 hunks)packages/backend/src/index.ts(1 hunks)
🧰 Additional context used
📓 Path-based instructions (7)
**/*.{js,jsx,ts,tsx}
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
packages/**/*.ts
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
packages/**/*.{ts,tsx,d.ts}
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
packages/**/index.{js,ts}
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
**/*.{ts,tsx}
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
- .cursor/rules/typescript.mdc
**/index.ts
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/react.mdc
- .cursor/rules/typescript.mdc
**/*
Instructions used from:
Sources:
⚙️ CodeRabbit Configuration File
🧠 Learnings (4)
📓 Common learnings
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/nextjs.mdc:0-0
Timestamp: 2025-06-30T10:31:43.578Z
Learning: Applies to app/api/**/*.ts : Use TypeScript interfaces for API response types
Learnt from: panteliselef
PR: clerk/javascript#6327
File: .changeset/eight-socks-lead.md:2-4
Timestamp: 2025-07-16T10:43:17.696Z
Learning: In the Clerk JavaScript repository, APIs marked with @experimental JSDoc annotations can have breaking changes released with minor version bumps rather than major version bumps, as consumers are warned about the instability of experimental features. The billing feature specifically has an @experimental annotation stating "This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change."
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/nextjs.mdc:0-0
Timestamp: 2025-06-30T10:31:43.578Z
Learning: Applies to app/api/**/*.ts : Document API endpoints with TypeScript interfaces
packages/backend/src/index.ts (5)
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Applies to packages/**/*.{ts,tsx,d.ts} : Packages should export TypeScript types alongside runtime code
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Applies to packages/**/index.{js,ts} : Use tree-shaking friendly exports
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Proper tree-shaking friendly exports
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Use ES6 imports/exports consistently
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/index.ts : Avoid barrel files (index.ts re-exports) as they can cause circular dependencies
packages/backend/src/api/resources/Webhooks.ts (2)
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/react.mdc:0-0
Timestamp: 2025-06-30T10:32:37.848Z
Learning: Applies to **/*.tsx : Use proper event types for handlers
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Use `type` for unions, primitives, and computed types
packages/backend/src/api/resources/JSON.ts (8)
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Use `interface` for object shapes that might be extended
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/nextjs.mdc:0-0
Timestamp: 2025-06-30T10:31:43.578Z
Learning: Applies to app/api/**/*.ts : Use TypeScript interfaces for API response types
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/nextjs.mdc:0-0
Timestamp: 2025-06-30T10:31:43.578Z
Learning: Applies to app/api/**/*.ts : Document API endpoints with TypeScript interfaces
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/__tests__/**/*.{ts,tsx} : Implement proper mock types that match interfaces in tests
Learnt from: wobsoriano
PR: clerk/javascript#6229
File: packages/backend/src/api/endpoints/MachineTokensApi.ts:47-89
Timestamp: 2025-07-01T15:20:41.834Z
Learning: In the Clerk JavaScript repository, for the MachineTokensApi class (packages/backend/src/api/endpoints/MachineTokensApi.ts), the maintainers prefer to rely on TypeScript types and readable property names for API documentation rather than JSDoc comments.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Use mapped types for transforming object types
Learnt from: panteliselef
PR: clerk/javascript#6327
File: .changeset/eight-socks-lead.md:2-4
Timestamp: 2025-07-16T10:43:17.696Z
Learning: In the Clerk JavaScript repository, APIs marked with @experimental JSDoc annotations can have breaking changes released with minor version bumps rather than major version bumps, as consumers are warned about the instability of experimental features. The billing feature specifically has an @experimental annotation stating "This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change."
Learnt from: panteliselef
PR: clerk/javascript#6327
File: .changeset/eight-socks-lead.md:2-4
Timestamp: 2025-07-16T10:43:17.696Z
Learning: In the Clerk JavaScript repository, APIs marked with @experimental JSDoc annotations can have breaking changes released with minor version bumps rather than major version bumps, as consumers are warned about the instability of experimental features.
🧬 Code Graph Analysis (1)
packages/backend/src/api/resources/JSON.ts (2)
packages/backend/src/index.ts (12)
CommercePayerJSON(103-103)ClerkResourceJSON(59-59)CommercePayeeJSON(104-104)CommerceAmountJSON(105-105)CommerceTotalsJSON(106-106)CommercePaymentSourceJSON(107-107)CommercePaymentFailedReasonJSON(108-108)CommerceSubscriptionCreditJSON(109-109)CommercePlanJSON(110-110)CommerceSubscriptionItemJSON(111-111)CommercePaymentAttemptJSON(112-112)CommerceSubscriptionJSON(113-113)packages/types/src/json.ts (4)
ClerkResourceJSON(35-39)CommercePaymentSourceJSON(693-703)CommercePlanJSON(629-666)CommerceSubscriptionJSON(781-797)
⏰ 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). (5)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: Build Packages
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: semgrep/ci
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (15)
packages/backend/src/index.ts (1)
103-113: LGTM! Commerce JSON type exports follow established patterns.The new commerce-related JSON type exports are correctly added to the existing JSON types section and follow the established naming conventions and export patterns.
packages/backend/src/api/resources/Webhooks.ts (3)
2-4: LGTM! Import additions for commerce JSON types.The new imports for commerce-related JSON types are correctly added and follow the established import pattern.
68-89: LGTM! Comprehensive commerce webhook event types added.The new webhook event types are well-structured and follow the established pattern:
CommercePaymentAttemptWebhookEventcovers payment attempt lifecycle eventsCommerceSubscriptionWebhookEventhandles subscription state changesCommerceSubscriptionItemWebhookEventprovides comprehensive coverage of subscription item statesThe event type names are descriptive and follow consistent naming conventions.
103-105: LGTM! Webhook event union type properly updated.The new commerce webhook event types are correctly added to the
WebhookEventunion type, maintaining type safety for webhook event handling.packages/backend/src/api/resources/JSON.ts (11)
66-69: LGTM! ObjectType entries for commerce entities follow established pattern.The new ObjectType entries for commerce entities are correctly added and follow the established naming convention with snake_case values.
764-776: LGTM! CommercePayerJSON interface is well-structured.The interface properly extends
ClerkResourceJSONand includes comprehensive payer information for both user and organization contexts with appropriate optional fields.
785-790: LGTM! CommerceAmountJSON interface provides comprehensive amount representation.The interface includes both raw amount and formatted display values with proper currency information.
792-796: LGTM! CommerceTotalsJSON interface provides clear billing breakdown.The interface properly composes
CommerceAmountJSONfor different total types, providing a clear billing structure.
798-807: LGTM! CommercePaymentSourceJSON interface covers payment method details.The interface includes comprehensive payment source information with appropriate optional fields for card-specific details.
809-812: LGTM! CommercePaymentFailedReasonJSON interface provides clear error information.The interface includes both general error codes and specific decline codes for comprehensive error handling.
814-819: LGTM! CommerceSubscriptionCreditJSON interface provides comprehensive credit tracking.The interface includes both amount and cycle information with percentage calculations for credit management.
821-838: LGTM! CommercePlanJSON interface provides comprehensive plan details.The interface includes all necessary plan information including pricing, billing periods, and configuration flags.
840-856: LGTM! CommerceSubscriptionItemJSON interface is well-structured.The interface properly extends
ClerkResourceJSONand includes comprehensive subscription item details with proper composition of related interfaces.
858-877: LGTM! CommercePaymentAttemptJSON interface provides comprehensive payment attempt tracking.The interface properly extends
ClerkResourceJSONand includes all necessary payment attempt details with proper composition of related interfaces for payer, payee, totals, and payment source information.
879-893: LGTM! CommerceSubscriptionJSON interface provides comprehensive subscription management.The interface properly extends
ClerkResourceJSONand includes all necessary subscription details with proper composition of related interfaces for payer and subscription items.
| currency_symbol: string; | ||
| } | ||
|
|
||
| export interface CommerceTotalsJSON { |
There was a problem hiding this comment.
For FAPI we also have total_due_now and credit. They may not be needed here, but wanted to mention it just in case.
Use union types for every status field.
No longer being used.
mauricioabreu
deleted the
mauricio-antunes/com-1039-export-billing-webhook-types-from-clerkbackend
branch
We recently introduced webhook events for Commerce: payment attempts and subscription events.
This commit adds type safety so developer can create type-safe webhook handlers.
Description
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit