@kelviq/mcp-server 0.4.0 → 1.0.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 (63) hide show
  1. package/README.md +34 -26
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +23 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +114 -34
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +102 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/server.js +10 -1
  62. package/dist/server.js.map +1 -1
  63. package/package.json +1 -1
@@ -30,21 +30,32 @@ Add these to your `.env.local` file:
30
30
 
31
31
  ```env
32
32
  # Backend (server-side only)
33
- KELVIQ_API_KEY=server-xxxxxxxx
34
-
35
- # API URLs
36
- KELVIQ_API_BASE_URL=https://api.kelviq.com/api/v1
33
+ KELVIQ_SERVER_API_KEY=server-xxxxxxxx
34
+ KELVIQ_ENV=sandbox
37
35
 
38
36
  # Frontend (can be exposed to client)
39
- NEXT_PUBLIC_KELVIQ_CLIENT_KEY=client-xxxxxxxx
40
- NEXT_PUBLIC_KELVIQ_EDGE_URL=https://edge.api.kelviq.com/api/v1/
37
+ NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY=client-xxxxxxxx
38
+ NEXT_PUBLIC_KELVIQ_ENV=sandbox
41
39
 
42
40
  # Your app URL (for redirects)
43
41
  NEXT_PUBLIC_APP_URL=https://yourdomain.com
44
42
  ```
45
43
 
44
+ Build with sandbox keys — keys only work against their own environment. When you go live, switch both keys to production keys and set both `KELVIQ_ENV` values to `production`.
45
+
46
46
  Never expose your server API key to the frontend or commit it to version control.
47
47
 
48
+ ### Point API Routes at the Right Environment
49
+
50
+ Create `lib/kelviq.ts` so every API route calls the host that matches `KELVIQ_ENV`:
51
+
52
+ ```typescript
53
+ export const KELVIQ_API_URL =
54
+ process.env.KELVIQ_ENV === "production"
55
+ ? "https://api.kelviq.com/api/v1"
56
+ : "https://sandboxapi.kelviq.com/api/v1";
57
+ ```
58
+
48
59
  ---
49
60
 
50
61
  ## Step 2: Define Your Plans
@@ -101,17 +112,18 @@ Create a customer record when a user signs up. This gives you more control and l
101
112
 
102
113
  ```typescript
103
114
  import { NextRequest, NextResponse } from "next/server";
115
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
104
116
 
105
117
  export async function POST(request: NextRequest) {
106
118
  const { customerId, name, email } = await request.json();
107
119
 
108
120
  const response = await fetch(
109
- `${process.env.KELVIQ_API_BASE_URL}/customers/`,
121
+ `${KELVIQ_API_URL}/customers/`,
110
122
  {
111
123
  method: "POST",
112
124
  headers: {
113
125
  "Content-Type": "application/json",
114
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
126
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
115
127
  },
116
128
  body: JSON.stringify({ customerId, name, email }),
117
129
  }
@@ -152,17 +164,18 @@ Create `app/api/checkout/route.ts`:
152
164
 
153
165
  ```typescript
154
166
  import { NextRequest, NextResponse } from "next/server";
167
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
155
168
 
156
169
  export async function POST(request: NextRequest) {
157
170
  const { planIdentifier, customerId, chargePeriod } = await request.json();
158
171
 
159
172
  const response = await fetch(
160
- `${process.env.KELVIQ_API_BASE_URL}/checkout/`,
173
+ `${KELVIQ_API_URL}/checkout/`,
161
174
  {
162
175
  method: "POST",
163
176
  headers: {
164
177
  "Content-Type": "application/json",
165
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
178
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
166
179
  },
167
180
  body: JSON.stringify({
168
181
  planIdentifier,
@@ -246,15 +259,16 @@ Create `app/api/subscriptions/route.ts`:
246
259
 
247
260
  ```typescript
248
261
  import { NextRequest, NextResponse } from "next/server";
262
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
249
263
 
250
264
  export async function GET(request: NextRequest) {
251
265
  const customerId = request.nextUrl.searchParams.get("customerId");
252
266
 
253
267
  const response = await fetch(
254
- `${process.env.KELVIQ_API_BASE_URL}/subscriptions/?customer_id=${customerId}`,
268
+ `${KELVIQ_API_URL}/subscriptions/?customer_id=${customerId}`,
255
269
  {
256
270
  headers: {
257
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
271
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
258
272
  },
259
273
  }
260
274
  );
@@ -270,21 +284,28 @@ Create `app/api/subscriptions/update/route.ts`:
270
284
 
271
285
  ```typescript
272
286
  import { NextRequest, NextResponse } from "next/server";
287
+ import { KELVIQ_API_URL } from "@/lib/kelviq";
273
288
 
274
289
  export async function POST(request: NextRequest) {
275
- const { subscriptionId, planIdentifier, chargePeriod } = await request.json();
290
+ const {
291
+ subscriptionId,
292
+ planIdentifier,
293
+ chargePeriod,
294
+ paymentBehavior,
295
+ } = await request.json();
276
296
 
277
297
  const response = await fetch(
278
- `${process.env.KELVIQ_API_BASE_URL}/subscriptions/${subscriptionId}/update/`,
298
+ `${KELVIQ_API_URL}/subscriptions/${subscriptionId}/update/`,
279
299
  {
280
300
  method: "POST",
281
301
  headers: {
282
302
  "Content-Type": "application/json",
283
- Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
303
+ Authorization: `Bearer ${process.env.KELVIQ_SERVER_API_KEY}`,
284
304
  },
285
305
  body: JSON.stringify({
286
306
  planIdentifier,
287
307
  chargePeriod: chargePeriod || "MONTHLY",
308
+ paymentBehavior,
288
309
  }),
289
310
  }
290
311
  );
@@ -312,16 +333,21 @@ async function handlePlanChange(newPlanId: string) {
312
333
  subscriptionId: current.id,
313
334
  planIdentifier: newPlanId,
314
335
  chargePeriod: "MONTHLY",
336
+ paymentBehavior: "activate_on_payment",
315
337
  }),
316
338
  });
317
339
 
318
- alert("Plan updated!");
340
+ alert("Plan change started. The new plan becomes active after payment succeeds.");
319
341
  } else {
320
342
  // No subscription, redirect to checkout
321
343
  }
322
344
  }
323
345
  ```
324
346
 
347
+ With `activate_on_payment`, the existing subscription remains `active` while payment is pending. If the payment method requires UPI approval or 3DS authentication, the updated subscription starts as `incomplete`. After payment succeeds, the updated subscription becomes `active` and the previous subscription becomes `superseded`. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes `incomplete_expired` and the existing subscription stays active.
348
+
349
+ Do not unlock the new plan immediately after this route returns. Check the updated subscription status or fetch the customer's current entitlements first.
350
+
325
351
  ---
326
352
 
327
353
  ## Step 7: Gate Features with Entitlements
@@ -341,8 +367,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
341
367
  <body>
342
368
  <KelviqProvider
343
369
  customerId={getCurrentUserId()}
344
- accessToken={process.env.NEXT_PUBLIC_KELVIQ_CLIENT_KEY!}
345
- apiUrl={process.env.NEXT_PUBLIC_KELVIQ_EDGE_URL!}
370
+ accessToken={process.env.NEXT_PUBLIC_KELVIQ_CLIENT_API_KEY!}
371
+ environment={process.env.NEXT_PUBLIC_KELVIQ_ENV === "production" ? "production" : "sandbox"}
346
372
  >
347
373
  {children}
348
374
  </KelviqProvider>
@@ -95,7 +95,7 @@ Redirect user to `checkoutUrl` → They complete payment → Redirected back to
95
95
  | Parameter | Description |
96
96
  |-----------|-------------|
97
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"` |
98
+ | `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, `"ONE_TIME"`, `"WEEKLY"`, `"DAILY"`, `"TWENTY_EIGHT_DAYS"`, `"THREE_MONTHS"`, `"SIX_MONTHS"` |
99
99
  | `successUrl` | URL to redirect after successful payment |
100
100
 
101
101
  ### Optional Parameters
@@ -155,6 +155,8 @@ const activeSubscription = results.find(s => s.status === "active");
155
155
  }
156
156
  ```
157
157
 
158
+ Kelviq handles failed card payment retries and emails the customer a link to pay. Your application does not need its own retry process or payment recovery screen. See [Failed subscription payments](/product-catalog/subscriptions#failed-subscription-payments).
159
+
158
160
  ---
159
161
 
160
162
  ## Step 4: Update Subscription
@@ -174,7 +176,8 @@ const response = await fetch(
174
176
  },
175
177
  body: JSON.stringify({
176
178
  planIdentifier: "enterprise",
177
- chargePeriod: "MONTHLY"
179
+ chargePeriod: "MONTHLY",
180
+ paymentBehavior: "activate_on_payment"
178
181
  })
179
182
  }
180
183
  );
@@ -197,6 +200,25 @@ const data = await response.json();
197
200
  | `planIdentifier` | The identifier of the new plan |
198
201
  | `chargePeriod` | Billing cycle: `"MONTHLY"`, `"YEARLY"`, etc. |
199
202
 
203
+ ### Optional Parameters
204
+
205
+ | Parameter | Description |
206
+ |-----------|-------------|
207
+ | `paymentBehavior` | Set to `"activate_on_payment"` to keep the current subscription active until payment for the change succeeds. Omit it to apply the update immediately. |
208
+
209
+ ### Activation after payment
210
+
211
+ Use `activate_on_payment` when a plan change should not affect access until Kelviq has collected payment.
212
+
213
+ | Payment path | What happens |
214
+ | --- | --- |
215
+ | Saved card with no customer action | Kelviq processes the payment immediately. The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
216
+ | UPI, 3DS, or another method requiring customer action | The updated subscription starts as `incomplete`. The existing subscription stays `active` until payment succeeds. |
217
+ | Payment succeeds | The updated subscription becomes `active`, and the previous subscription becomes `superseded`. |
218
+ | The immediate charge fails, or payment is not completed before expiry | The updated subscription becomes `incomplete_expired`. The existing subscription remains `active`. |
219
+
220
+ Do not grant the new plan's entitlements just because the update request returned successfully. Confirm that the updated subscription is `active`, or read the customer's current entitlements.
221
+
200
222
  ---
201
223
 
202
224
  ## Step 5: Check Entitlements
@@ -277,8 +299,10 @@ Use your **Client API Key** for this endpoint, not your Server API Key.
277
299
  → Show/hide features based on access
278
300
 
279
301
  4. User wants to upgrade
280
- → Update subscription via API
281
- → Entitlements update automatically
302
+ → Update the subscription with paymentBehavior: "activate_on_payment"
303
+ → Keep the existing subscription active while payment is pending
304
+ → After payment succeeds, the new subscription becomes active
305
+ → The previous subscription becomes superseded
282
306
  ```
283
307
 
284
308
  ---