Skip to content

Commit ec728c7

Browse files
wobsorianoCopilotburmecia
authored
feat(clerk): Add billing endpoints (supabase#539)
* feat(clerk): add billing endpoints support Add support for Clerk billing API endpoints following the Orb FDW pattern: - billing/plans - billing/subscription_items - billing/statements - users/billing/subscription (requires user_id WHERE clause) - organizations/billing/subscription (requires organization_id WHERE clause) - billing/statements/payment_attempts (requires statement_id WHERE clause) Implements parameterized URL handling using Context and quals extraction, matching the pattern used in Orb FDW for endpoints like credits/ledger. * fix paginated response * fix fields * keep user and org subscriptions * add rest of billing endpoints * Update wasm-wrappers/fdw/clerk_fdw/src/lib.rs Co-authored-by: Copilot <[email protected]> * apply review * chore: apply copilot suggestions * chore: remove markdown file * chore: run format * chore: return empty result instead of error * upgrade version and docs * add Cargo.lock --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Bo Lu <[email protected]>
1 parent e255686 commit ec728c7

4 files changed

Lines changed: 572 additions & 42 deletions

File tree

‎docs/catalog/clerk.md‎

Lines changed: 285 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ The Clerk Wrapper is a WebAssembly(Wasm) foreign data wrapper which allows you t
1717

1818
| Version | Wasm Package URL | Checksum | Required Wrappers Version |
1919
| ------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
20+
| 0.2.1 | `https://github.com/supabase/wrappers/releases/download/wasm_clerk_fdw_v0.2.1/clerk_fdw.wasm` | `tbd` | >=0.5.0 |
2021
| 0.2.0 | `https://github.com/supabase/wrappers/releases/download/wasm_clerk_fdw_v0.2.0/clerk_fdw.wasm` | `89337bb11779d4d654cd3e54391aabd02509d213db6995f7dd58951774bf0e37` | >=0.5.0 |
2122
| 0.1.0 | `https://github.com/supabase/wrappers/releases/download/wasm_clerk_fdw_v0.1.0/clerk_fdw.wasm` | `613be26b59fa4c074e0b93f0db617fcd7b468d4d02edece0b1f85fdb683ebdc4` | >=0.4.0 |
2223

@@ -107,20 +108,27 @@ The full list of foreign table options are below:
107108

108109
Supported objects are listed below:
109110

110-
| Object name |
111-
| ------------------------ |
112-
| allowlist_identifiers |
113-
| blocklist_identifiers |
114-
| domains |
115-
| invitations |
116-
| jwt_templates |
117-
| oauth_applications |
118-
| organizations |
119-
| organization_invitations |
120-
| organization_memberships |
121-
| redirect_urls |
122-
| saml_connections |
123-
| users |
111+
| Object name |
112+
| ---------------------------------- |
113+
| allowlist_identifiers |
114+
| billing_payment_attempts |
115+
| billing_plans |
116+
| billing_statement |
117+
| billing_statements |
118+
| billing_subscription_items |
119+
| blocklist_identifiers |
120+
| domains |
121+
| invitations |
122+
| jwt_templates |
123+
| oauth_applications |
124+
| organizations |
125+
| organization_billing_subscriptions |
126+
| organization_invitations |
127+
| organization_memberships |
128+
| redirect_urls |
129+
| saml_connections |
130+
| user_billing_subscriptions |
131+
| users |
124132

125133
## Entities
126134

@@ -558,6 +566,244 @@ create foreign table clerk.users (
558566

559567
- The `attrs` column contains additional attributes in JSON format
560568

569+
### User Billing Subscriptions
570+
571+
This retrieves the billing subscription for a specific user.
572+
573+
Ref: [Clerk API docs](https://clerk.com/docs/reference/backend-api/tag/billing#operation/GetUserBillingSubscription)
574+
575+
#### Operations
576+
577+
| Object | Select | Insert | Update | Delete | Truncate |
578+
| --------------------------- | :----: | :----: | :----: | :----: | :------: |
579+
| users/billing/subscription | ✅ | ❌ | ❌ | ❌ | ❌ |
580+
581+
#### Usage
582+
583+
```sql
584+
create foreign table clerk.user_billing_subscriptions (
585+
user_id text,
586+
id text,
587+
status text,
588+
payer_id text,
589+
created_at timestamp,
590+
updated_at timestamp,
591+
attrs jsonb
592+
)
593+
server clerk_server
594+
options (
595+
object 'users/billing/subscription'
596+
);
597+
```
598+
599+
#### Notes
600+
601+
- The `attrs` column contains additional attributes in JSON format
602+
- The query must specify `user_id` in the WHERE clause
603+
604+
### Organization Billing Subscriptions
605+
606+
This retrieves the billing subscription for a specific organization.
607+
608+
Ref: [Clerk API docs](https://clerk.com/docs/reference/backend-api/tag/billing#operation/GetOrganizationBillingSubscription)
609+
610+
#### Operations
611+
612+
| Object | Select | Insert | Update | Delete | Truncate |
613+
| --------------------------------- | :----: | :----: | :----: | :----: | :------: |
614+
| organizations/billing/subscription | ✅ | ❌ | ❌ | ❌ | ❌ |
615+
616+
#### Usage
617+
618+
```sql
619+
create foreign table clerk.organization_billing_subscriptions (
620+
organization_id text,
621+
id text,
622+
status text,
623+
payer_id text,
624+
created_at timestamp,
625+
updated_at timestamp,
626+
attrs jsonb
627+
)
628+
server clerk_server
629+
options (
630+
object 'organizations/billing/subscription'
631+
);
632+
```
633+
634+
#### Notes
635+
636+
- The `attrs` column contains additional attributes in JSON format
637+
- The query must specify `organization_id` in the WHERE clause
638+
639+
### Billing Plans
640+
641+
This is a list of all billing plans.
642+
643+
Ref: [Clerk API docs](https://clerk.com/docs/reference/backend-api/tag/billing#operation/ListBillingPlans)
644+
645+
#### Operations
646+
647+
| Object | Select | Insert | Update | Delete | Truncate |
648+
| ------------- | :----: | :----: | :----: | :----: | :------: |
649+
| billing/plans | ✅ | ❌ | ❌ | ❌ | ❌ |
650+
651+
#### Usage
652+
653+
```sql
654+
create foreign table clerk.billing_plans (
655+
id text,
656+
name text,
657+
description text,
658+
slug text,
659+
is_default boolean,
660+
is_recurring boolean,
661+
attrs jsonb
662+
)
663+
server clerk_server
664+
options (
665+
object 'billing/plans'
666+
);
667+
```
668+
669+
#### Notes
670+
671+
- The `attrs` column contains additional attributes in JSON format
672+
673+
### Billing Subscription Items
674+
675+
This is a list of all billing subscription items.
676+
677+
Ref: [Clerk API docs](https://clerk.com/docs/reference/backend-api/tag/billing#operation/ListBillingSubscriptionItems)
678+
679+
#### Operations
680+
681+
| Object | Select | Insert | Update | Delete | Truncate |
682+
| -------------------------- | :----: | :----: | :----: | :----: | :------: |
683+
| billing/subscription_items | ✅ | ❌ | ❌ | ❌ | ❌ |
684+
685+
#### Usage
686+
687+
```sql
688+
create foreign table clerk.billing_subscription_items (
689+
id text,
690+
status text,
691+
plan_id text,
692+
plan_period text,
693+
payer_id text,
694+
is_free_trial boolean,
695+
created_at timestamp,
696+
updated_at timestamp,
697+
attrs jsonb
698+
)
699+
server clerk_server
700+
options (
701+
object 'billing/subscription_items'
702+
);
703+
```
704+
705+
#### Notes
706+
707+
- The `attrs` column contains additional attributes in JSON format
708+
709+
### Billing Statements
710+
711+
This is a list of all billing statements.
712+
713+
Ref: [Clerk API docs](https://clerk.com/docs/reference/backend-api/tag/billing#operation/ListBillingStatements)
714+
715+
#### Operations
716+
717+
| Object | Select | Insert | Update | Delete | Truncate |
718+
| ------------------ | :----: | :----: | :----: | :----: | :------: |
719+
| billing/statements | ✅ | ❌ | ❌ | ❌ | ❌ |
720+
721+
#### Usage
722+
723+
```sql
724+
create foreign table clerk.billing_statements (
725+
id text,
726+
status text,
727+
timestamp timestamp,
728+
attrs jsonb
729+
)
730+
server clerk_server
731+
options (
732+
object 'billing/statements'
733+
);
734+
```
735+
736+
#### Notes
737+
738+
- The `attrs` column contains additional attributes in JSON format
739+
740+
### Billing Statement
741+
742+
This retrieves a specific billing statement by ID.
743+
744+
Ref: [Clerk API docs](https://clerk.com/docs/reference/backend-api/tag/billing#operation/GetBillingStatement)
745+
746+
#### Operations
747+
748+
| Object | Select | Insert | Update | Delete | Truncate |
749+
| ----------------- | :----: | :----: | :----: | :----: | :------: |
750+
| billing/statement | ✅ | ❌ | ❌ | ❌ | ❌ |
751+
752+
#### Usage
753+
754+
```sql
755+
create foreign table clerk.billing_statement (
756+
statement_id text,
757+
id text,
758+
status text,
759+
timestamp timestamp,
760+
attrs jsonb
761+
)
762+
server clerk_server
763+
options (
764+
object 'billing/statement'
765+
);
766+
```
767+
768+
#### Notes
769+
770+
- The `attrs` column contains additional attributes in JSON format
771+
- The query must specify `statement_id` in the WHERE clause
772+
773+
### Billing Payment Attempts
774+
775+
This retrieves payment attempts for a specific billing statement.
776+
777+
Ref: [Clerk API docs](https://clerk.com/docs/reference/backend-api/tag/billing#operation/ListBillingStatementPaymentAttempts)
778+
779+
#### Operations
780+
781+
| Object | Select | Insert | Update | Delete | Truncate |
782+
| ------------------------ | :----: | :----: | :----: | :----: | :------: |
783+
| billing/payment_attempts | ✅ | ❌ | ❌ | ❌ | ❌ |
784+
785+
#### Usage
786+
787+
```sql
788+
create foreign table clerk.billing_payment_attempts (
789+
statement_id text,
790+
id text,
791+
status text,
792+
created_at timestamp,
793+
updated_at timestamp,
794+
attrs jsonb
795+
)
796+
server clerk_server
797+
options (
798+
object 'billing/payment_attempts'
799+
);
800+
```
801+
802+
#### Notes
803+
804+
- The `attrs` column contains additional attributes in JSON format
805+
- The query must specify `statement_id` in the WHERE clause
806+
561807
## Query Pushdown Support
562808

563809
This FDW doesn't support query pushdown.
@@ -623,3 +869,28 @@ select
623869
from clerk.users u
624870
cross join json_array_elements((attrs->'email_addresses')::json) e;
625871
```
872+
873+
### Billing examples
874+
875+
```sql
876+
-- Query all billing plans
877+
SELECT * FROM clerk.billing_plans;
878+
879+
-- Query all billing statements
880+
SELECT * FROM clerk.billing_statements;
881+
882+
-- Query all billing subscription items
883+
SELECT * FROM clerk.billing_subscription_items;
884+
885+
-- Query a specific statement (requires WHERE clause)
886+
SELECT * FROM clerk.billing_statement WHERE statement_id = 'stmt_xxx';
887+
888+
-- Query payment attempts for a statement (requires WHERE clause)
889+
SELECT * FROM clerk.billing_payment_attempts WHERE statement_id = 'stmt_xxx';
890+
891+
-- Query subscription for a specific user (requires WHERE clause)
892+
SELECT * FROM clerk.user_billing_subscriptions WHERE user_id = 'user_xxx';
893+
894+
-- Query subscription for a specific organization (requires WHERE clause)
895+
SELECT * FROM clerk.organization_billing_subscriptions WHERE organization_id = 'org_xxx';
896+
```

‎wasm-wrappers/fdw/Cargo.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎wasm-wrappers/fdw/clerk_fdw/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "clerk_fdw"
3-
version = "0.2.0"
3+
version = "0.2.1"
44
edition = { workspace = true }
55
homepage = { workspace = true }
66
rust-version = { workspace = true }

0 commit comments

Comments
 (0)