@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.
- package/README.md +34 -26
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +114 -34
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +102 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/server.js +10 -1
- package/dist/server.js.map +1 -1
- 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
|
-
|
|
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
|
-
|
|
40
|
-
|
|
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
|
-
`${
|
|
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.
|
|
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
|
-
`${
|
|
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.
|
|
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
|
-
`${
|
|
268
|
+
`${KELVIQ_API_URL}/subscriptions/?customer_id=${customerId}`,
|
|
255
269
|
{
|
|
256
270
|
headers: {
|
|
257
|
-
Authorization: `Bearer ${process.env.
|
|
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 {
|
|
290
|
+
const {
|
|
291
|
+
subscriptionId,
|
|
292
|
+
planIdentifier,
|
|
293
|
+
chargePeriod,
|
|
294
|
+
paymentBehavior,
|
|
295
|
+
} = await request.json();
|
|
276
296
|
|
|
277
297
|
const response = await fetch(
|
|
278
|
-
`${
|
|
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.
|
|
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
|
|
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.
|
|
345
|
-
|
|
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
|
|
281
|
-
→
|
|
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
|
---
|