@kelviq/mcp-server 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +322 -0
  3. package/dist/config.d.ts +16 -0
  4. package/dist/config.js +45 -0
  5. package/dist/config.js.map +1 -0
  6. package/dist/docs/README.md +128 -0
  7. package/dist/docs/api-reference/authentication.md +41 -0
  8. package/dist/docs/backend-integration/node-sdk.md +1040 -0
  9. package/dist/docs/backend-integration/python-sdk.md +1198 -0
  10. package/dist/docs/changelog/app.md +80 -0
  11. package/dist/docs/changelog/checkout-api.md +59 -0
  12. package/dist/docs/changelog/js-promotions-ui.md +14 -0
  13. package/dist/docs/changelog/js-sdk.md +281 -0
  14. package/dist/docs/changelog/node-sdk.md +378 -0
  15. package/dist/docs/changelog/python-sdk.md +456 -0
  16. package/dist/docs/changelog/react-sdk.md +580 -0
  17. package/dist/docs/checkout/checkout-configuration.md +434 -0
  18. package/dist/docs/coustomers-management/overview.md +111 -0
  19. package/dist/docs/customer-portal/overview.md +81 -0
  20. package/dist/docs/frontend-integration/js-sdk.md +676 -0
  21. package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
  22. package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
  23. package/dist/docs/frontend-integration/react-sdk.md +1187 -0
  24. package/dist/docs/frontend-integration/react-ui.md +771 -0
  25. package/dist/docs/getstarted/fees.md +160 -0
  26. package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
  27. package/dist/docs/getstarted/merchant-of-record.md +64 -0
  28. package/dist/docs/getstarted/review-process.md +190 -0
  29. package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
  30. package/dist/docs/guides/subscription-integration.md +291 -0
  31. package/dist/docs/guides/webhooks.md +963 -0
  32. package/dist/docs/legal/approved-prohibited-policy.md +252 -0
  33. package/dist/docs/legal/buyer-terms.md +177 -0
  34. package/dist/docs/legal/compliant-user-flow.md +216 -0
  35. package/dist/docs/legal/master-service-agreement.md +404 -0
  36. package/dist/docs/legal/payment-flow-diagram.md +188 -0
  37. package/dist/docs/legal/seller-terms.md +169 -0
  38. package/dist/docs/manifest.json +415 -0
  39. package/dist/docs/monetization/offerings.md +156 -0
  40. package/dist/docs/monetization/pricing-tables.md +226 -0
  41. package/dist/docs/monetization/targeting-rules.md +278 -0
  42. package/dist/docs/openapi.json +5479 -0
  43. package/dist/docs/payouts/overview.md +43 -0
  44. package/dist/docs/payouts/payout-account.md +12 -0
  45. package/dist/docs/payouts/transactions.md +23 -0
  46. package/dist/docs/product-catalog/digital-downloads.md +117 -0
  47. package/dist/docs/product-catalog/discounts.md +69 -0
  48. package/dist/docs/product-catalog/entitlements.md +428 -0
  49. package/dist/docs/product-catalog/free-and-trials.md +36 -0
  50. package/dist/docs/product-catalog/license-keys.md +324 -0
  51. package/dist/docs/product-catalog/links.md +92 -0
  52. package/dist/docs/product-catalog/location-based-pricing.md +41 -0
  53. package/dist/docs/product-catalog/one-time-payments.md +24 -0
  54. package/dist/docs/product-catalog/plans.md +199 -0
  55. package/dist/docs/product-catalog/products.md +60 -0
  56. package/dist/docs/product-catalog/subscriptions.md +29 -0
  57. package/dist/docs/product-catalog/tax-settings.md +37 -0
  58. package/dist/docs/product-catalog/usage-based-billing.md +119 -0
  59. package/dist/docs/promotions/create-a-promotion.md +75 -0
  60. package/dist/docs/promotions/customize-banner.md +41 -0
  61. package/dist/docs/promotions/integrate.md +38 -0
  62. package/dist/docs/promotions/overview.md +51 -0
  63. package/dist/docs/quickstart/core-concepts.md +146 -0
  64. package/dist/docs/quickstart/dashboard-setup.md +129 -0
  65. package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
  66. package/dist/docs/sales/checkout-sessions.md +58 -0
  67. package/dist/docs/sales/orders.md +76 -0
  68. package/dist/http/client.d.ts +28 -0
  69. package/dist/http/client.js +76 -0
  70. package/dist/http/client.js.map +1 -0
  71. package/dist/http/errors.d.ts +20 -0
  72. package/dist/http/errors.js +58 -0
  73. package/dist/http/errors.js.map +1 -0
  74. package/dist/resources/docs-index.d.ts +25 -0
  75. package/dist/resources/docs-index.js +109 -0
  76. package/dist/resources/docs-index.js.map +1 -0
  77. package/dist/resources/index.d.ts +2 -0
  78. package/dist/resources/index.js +73 -0
  79. package/dist/resources/index.js.map +1 -0
  80. package/dist/schemas/kelviq.d.ts +1304 -0
  81. package/dist/schemas/kelviq.js +468 -0
  82. package/dist/schemas/kelviq.js.map +1 -0
  83. package/dist/server.d.ts +2 -0
  84. package/dist/server.js +41 -0
  85. package/dist/server.js.map +1 -0
  86. package/dist/tools/_util.d.ts +15 -0
  87. package/dist/tools/_util.js +15 -0
  88. package/dist/tools/_util.js.map +1 -0
  89. package/dist/tools/checkout.d.ts +3 -0
  90. package/dist/tools/checkout.js +18 -0
  91. package/dist/tools/checkout.js.map +1 -0
  92. package/dist/tools/customers.d.ts +3 -0
  93. package/dist/tools/customers.js +32 -0
  94. package/dist/tools/customers.js.map +1 -0
  95. package/dist/tools/docs.d.ts +2 -0
  96. package/dist/tools/docs.js +43 -0
  97. package/dist/tools/docs.js.map +1 -0
  98. package/dist/tools/entitlements.d.ts +3 -0
  99. package/dist/tools/entitlements.js +22 -0
  100. package/dist/tools/entitlements.js.map +1 -0
  101. package/dist/tools/features.d.ts +3 -0
  102. package/dist/tools/features.js +55 -0
  103. package/dist/tools/features.js.map +1 -0
  104. package/dist/tools/index.d.ts +3 -0
  105. package/dist/tools/index.js +44 -0
  106. package/dist/tools/index.js.map +1 -0
  107. package/dist/tools/licenses.d.ts +3 -0
  108. package/dist/tools/licenses.js +44 -0
  109. package/dist/tools/licenses.js.map +1 -0
  110. package/dist/tools/media.d.ts +3 -0
  111. package/dist/tools/media.js +18 -0
  112. package/dist/tools/media.js.map +1 -0
  113. package/dist/tools/offerings.d.ts +3 -0
  114. package/dist/tools/offerings.js +21 -0
  115. package/dist/tools/offerings.js.map +1 -0
  116. package/dist/tools/partner.d.ts +3 -0
  117. package/dist/tools/partner.js +55 -0
  118. package/dist/tools/partner.js.map +1 -0
  119. package/dist/tools/plan-entitlements.d.ts +3 -0
  120. package/dist/tools/plan-entitlements.js +56 -0
  121. package/dist/tools/plan-entitlements.js.map +1 -0
  122. package/dist/tools/plan-files.d.ts +3 -0
  123. package/dist/tools/plan-files.js +43 -0
  124. package/dist/tools/plan-files.js.map +1 -0
  125. package/dist/tools/plans.d.ts +3 -0
  126. package/dist/tools/plans.js +120 -0
  127. package/dist/tools/plans.js.map +1 -0
  128. package/dist/tools/portal.d.ts +3 -0
  129. package/dist/tools/portal.js +18 -0
  130. package/dist/tools/portal.js.map +1 -0
  131. package/dist/tools/product-files.d.ts +3 -0
  132. package/dist/tools/product-files.js +31 -0
  133. package/dist/tools/product-files.js.map +1 -0
  134. package/dist/tools/product-settings.d.ts +3 -0
  135. package/dist/tools/product-settings.js +31 -0
  136. package/dist/tools/product-settings.js.map +1 -0
  137. package/dist/tools/products.d.ts +3 -0
  138. package/dist/tools/products.js +69 -0
  139. package/dist/tools/products.js.map +1 -0
  140. package/dist/tools/promotions.d.ts +3 -0
  141. package/dist/tools/promotions.js +19 -0
  142. package/dist/tools/promotions.js.map +1 -0
  143. package/dist/tools/subscriptions.d.ts +3 -0
  144. package/dist/tools/subscriptions.js +63 -0
  145. package/dist/tools/subscriptions.js.map +1 -0
  146. package/dist/tools/usage.d.ts +3 -0
  147. package/dist/tools/usage.js +18 -0
  148. package/dist/tools/usage.js.map +1 -0
  149. package/package.json +88 -0
@@ -0,0 +1,291 @@
1
+ ---
2
+ title: "Subscription Integration"
3
+ slug: "guides/subscription-integration"
4
+ section: "guides"
5
+ description: "A simple guide to add subscription billing to your SaaS in 5 API calls."
6
+ ---
7
+ Add subscription billing to your SaaS with just a few API calls. This guide covers the REST API — for framework-specific guides, see [Next.js Integration](/guides/subscription-integration-for-nextjs).
8
+
9
+ ---
10
+
11
+ ## Overview
12
+
13
+ Kelviq handles your subscription billing with these endpoints:
14
+
15
+ | Step | Endpoint | Purpose |
16
+ |------|----------|---------|
17
+ | 1 | Create Customer | Register user (optional) |
18
+ | 2 | Create Checkout | Start payment flow |
19
+ | 3 | Get Subscription | Check active plans |
20
+ | 4 | Update Subscription | Upgrade/downgrade |
21
+ | 5 | Check Entitlements | Gate features |
22
+
23
+ ---
24
+
25
+ ## Step 1: Create Customer (Optional)
26
+
27
+ You have two options for creating customers:
28
+
29
+ ### Option 1: Auto-create during checkout
30
+
31
+ Skip this step. Pass `email` or `customerId` in the checkout request — Kelviq will auto-create the customer.
32
+
33
+ ### Option 2: Create customer explicitly
34
+
35
+ Create a customer record when a user signs up.
36
+
37
+ ```javascript
38
+ const response = await fetch("https://api.kelviq.com/api/v1/customers/", {
39
+ method: "POST",
40
+ headers: {
41
+ "Content-Type": "application/json",
42
+ "Authorization": "Bearer YOUR_SERVER_API_KEY"
43
+ },
44
+ body: JSON.stringify({
45
+ customerId: "user-123",
46
+ name: "John Doe",
47
+ email: "john@example.com"
48
+ })
49
+ });
50
+
51
+ const customer = await response.json();
52
+ ```
53
+
54
+ Pre-creating customers is useful when you want to track users in the dashboard before they subscribe.
55
+
56
+ ---
57
+
58
+ ## Step 2: Create Checkout Session
59
+
60
+ When a user wants to subscribe, create a checkout session and redirect them.
61
+
62
+ ### Request
63
+
64
+ ```javascript
65
+ const response = await fetch("https://api.kelviq.com/api/v1/checkout/", {
66
+ method: "POST",
67
+ headers: {
68
+ "Content-Type": "application/json",
69
+ "Authorization": "Bearer YOUR_SERVER_API_KEY"
70
+ },
71
+ body: JSON.stringify({
72
+ planIdentifier: "pro",
73
+ chargePeriod: "MONTHLY",
74
+ customerId: "user-123",
75
+ successUrl: "https://yourapp.com/success"
76
+ })
77
+ });
78
+
79
+ const { checkoutUrl } = await response.json();
80
+ ```
81
+
82
+ ### Response
83
+
84
+ ```json
85
+ {
86
+ "checkoutUrl": "https://www.kelviq.com/checkout/cs_fBhCIBerpe1pAsRW6P4wYc8WHqMdfdr457hd3oOLjhAFx/",
87
+ "checkoutSessionId": "cs_test_b1sNi7D6u9iMCUFV1UZi9ZwerfaiXKdOOmr3DCUW6XdCZIr5Id1F7G"
88
+ }
89
+ ```
90
+
91
+ Redirect user to `checkoutUrl` → They complete payment → Redirected back to your `successUrl`
92
+
93
+ ### Required Parameters
94
+
95
+ | Parameter | Description |
96
+ |-----------|-------------|
97
+ | `planIdentifier` | The identifier of the plan (e.g., `"pro"`, `"enterprise"`) |
98
+ | `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
99
+ | `successUrl` | URL to redirect after successful payment |
100
+
101
+ ### Optional Parameters
102
+
103
+ | Parameter | Description |
104
+ |-----------|-------------|
105
+ | `customerId` | Your customer ID (auto-creates if new) |
106
+ | `offeringId` | UUID of the offering |
107
+ | `pricingTableId` | UUID of the pricing table |
108
+ | `ipAddress` | Customer IP for location-based pricing |
109
+
110
+ ---
111
+
112
+ ## Step 3: Get Subscription Details
113
+
114
+ Check if a customer has an active subscription.
115
+
116
+ ### Request
117
+
118
+ ```javascript
119
+ const response = await fetch(
120
+ "https://api.kelviq.com/api/v1/subscriptions/?customer_id=user-123",
121
+ {
122
+ headers: {
123
+ "Authorization": "Bearer YOUR_SERVER_API_KEY"
124
+ }
125
+ }
126
+ );
127
+
128
+ const { results } = await response.json();
129
+ const activeSubscription = results.find(s => s.status === "active");
130
+ ```
131
+
132
+ ### Response
133
+
134
+ ```json
135
+ {
136
+ "count": 1,
137
+ "next": null,
138
+ "previous": null,
139
+ "results": [
140
+ {
141
+ "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
142
+ "status": "active",
143
+ "plan": {
144
+ "name": "Pro Plan",
145
+ "identifier": "pro"
146
+ },
147
+ "amount": "49.00",
148
+ "recurrence": "month",
149
+ "currency": "usd",
150
+ "startDate": "2024-01-01",
151
+ "endDate": null,
152
+ "customerId": "user-123"
153
+ }
154
+ ]
155
+ }
156
+ ```
157
+
158
+ ---
159
+
160
+ ## Step 4: Update Subscription
161
+
162
+ Allow users to upgrade or downgrade their plan.
163
+
164
+ ### Request
165
+
166
+ ```javascript
167
+ const response = await fetch(
168
+ "https://api.kelviq.com/api/v1/subscriptions/09d706ca-58f3-4fb2-818f-5b8623d67e6e/update/",
169
+ {
170
+ method: "POST",
171
+ headers: {
172
+ "Content-Type": "application/json",
173
+ "Authorization": "Bearer YOUR_SERVER_API_KEY"
174
+ },
175
+ body: JSON.stringify({
176
+ planIdentifier: "enterprise",
177
+ chargePeriod: "MONTHLY"
178
+ })
179
+ }
180
+ );
181
+
182
+ const data = await response.json();
183
+ ```
184
+
185
+ ### Response
186
+
187
+ ```json
188
+ {
189
+ "subscriptionId": "09d706ca-58f3-4fb2-818f-5b8623d67e6e"
190
+ }
191
+ ```
192
+
193
+ ### Required Parameters
194
+
195
+ | Parameter | Description |
196
+ |-----------|-------------|
197
+ | `planIdentifier` | The identifier of the new plan |
198
+ | `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, etc. |
199
+
200
+ ---
201
+
202
+ ## Step 5: Check Entitlements
203
+
204
+ Check what features a customer has access to based on their subscription.
205
+
206
+ ### Request
207
+
208
+ ```javascript
209
+ const response = await fetch(
210
+ "https://edge.api.kelviq.com/api/v1/entitlements/?customerId=user-123",
211
+ {
212
+ headers: {
213
+ "Authorization": "Bearer YOUR_CLIENT_API_KEY"
214
+ }
215
+ }
216
+ );
217
+
218
+ const { entitlements } = await response.json();
219
+ ```
220
+
221
+ Use your **Client API Key** for this endpoint, not your Server API Key.
222
+
223
+ ### Response
224
+
225
+ ```json
226
+ {
227
+ "customerId": "user-123",
228
+ "entitlements": [
229
+ {
230
+ "featureId": "export-data",
231
+ "featureType": "BOOLEAN",
232
+ "hasAccess": true
233
+ },
234
+ {
235
+ "featureId": "max-projects",
236
+ "featureType": "METER",
237
+ "hasAccess": true,
238
+ "usageLimit": 100,
239
+ "currentUsage": 45,
240
+ "remaining": 55
241
+ },
242
+ {
243
+ "featureId": "team-size",
244
+ "featureType": "CUSTOMIZABLE",
245
+ "hasAccess": true,
246
+ "usageLimit": 5
247
+ }
248
+ ]
249
+ }
250
+ ```
251
+
252
+ ### Entitlement Types
253
+
254
+ | Type | Description | Fields |
255
+ |------|-------------|--------|
256
+ | **BOOLEAN** | Feature on/off | `hasAccess` |
257
+ | **METER** | Usage-based limits | `usageLimit`, `currentUsage`, `remaining` |
258
+ | **CUSTOMIZABLE** | Configurable value | `usageLimit` |
259
+
260
+ ---
261
+
262
+ ## Complete Flow
263
+
264
+ ```
265
+ 1. User signs up
266
+ → Create customer via API (or auto-create via email)
267
+
268
+ 2. User visits pricing page
269
+ → Create checkout session
270
+ → Redirect to checkout URL
271
+ → User completes payment
272
+ → Redirect back to your app
273
+
274
+ 3. In your app
275
+ → Get subscription details
276
+ → Check entitlements
277
+ → Show/hide features based on access
278
+
279
+ 4. User wants to upgrade
280
+ → Update subscription via API
281
+ → Entitlements update automatically
282
+ ```
283
+
284
+ ---
285
+
286
+ ## Need Help?
287
+
288
+ Have questions or need implementation support?
289
+
290
+ - Email us at **hi@kelviq.com**
291
+ - [Book a demo](https://tidycal.com/neravath/15-minute-meeting)