@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.
- package/LICENSE +21 -0
- package/README.md +322 -0
- package/dist/config.d.ts +16 -0
- package/dist/config.js +45 -0
- package/dist/config.js.map +1 -0
- package/dist/docs/README.md +128 -0
- package/dist/docs/api-reference/authentication.md +41 -0
- package/dist/docs/backend-integration/node-sdk.md +1040 -0
- package/dist/docs/backend-integration/python-sdk.md +1198 -0
- package/dist/docs/changelog/app.md +80 -0
- package/dist/docs/changelog/checkout-api.md +59 -0
- package/dist/docs/changelog/js-promotions-ui.md +14 -0
- package/dist/docs/changelog/js-sdk.md +281 -0
- package/dist/docs/changelog/node-sdk.md +378 -0
- package/dist/docs/changelog/python-sdk.md +456 -0
- package/dist/docs/changelog/react-sdk.md +580 -0
- package/dist/docs/checkout/checkout-configuration.md +434 -0
- package/dist/docs/coustomers-management/overview.md +111 -0
- package/dist/docs/customer-portal/overview.md +81 -0
- package/dist/docs/frontend-integration/js-sdk.md +676 -0
- package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
- package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
- package/dist/docs/frontend-integration/react-sdk.md +1187 -0
- package/dist/docs/frontend-integration/react-ui.md +771 -0
- package/dist/docs/getstarted/fees.md +160 -0
- package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
- package/dist/docs/getstarted/merchant-of-record.md +64 -0
- package/dist/docs/getstarted/review-process.md +190 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
- package/dist/docs/guides/subscription-integration.md +291 -0
- package/dist/docs/guides/webhooks.md +963 -0
- package/dist/docs/legal/approved-prohibited-policy.md +252 -0
- package/dist/docs/legal/buyer-terms.md +177 -0
- package/dist/docs/legal/compliant-user-flow.md +216 -0
- package/dist/docs/legal/master-service-agreement.md +404 -0
- package/dist/docs/legal/payment-flow-diagram.md +188 -0
- package/dist/docs/legal/seller-terms.md +169 -0
- package/dist/docs/manifest.json +415 -0
- package/dist/docs/monetization/offerings.md +156 -0
- package/dist/docs/monetization/pricing-tables.md +226 -0
- package/dist/docs/monetization/targeting-rules.md +278 -0
- package/dist/docs/openapi.json +5479 -0
- package/dist/docs/payouts/overview.md +43 -0
- package/dist/docs/payouts/payout-account.md +12 -0
- package/dist/docs/payouts/transactions.md +23 -0
- package/dist/docs/product-catalog/digital-downloads.md +117 -0
- package/dist/docs/product-catalog/discounts.md +69 -0
- package/dist/docs/product-catalog/entitlements.md +428 -0
- package/dist/docs/product-catalog/free-and-trials.md +36 -0
- package/dist/docs/product-catalog/license-keys.md +324 -0
- package/dist/docs/product-catalog/links.md +92 -0
- package/dist/docs/product-catalog/location-based-pricing.md +41 -0
- package/dist/docs/product-catalog/one-time-payments.md +24 -0
- package/dist/docs/product-catalog/plans.md +199 -0
- package/dist/docs/product-catalog/products.md +60 -0
- package/dist/docs/product-catalog/subscriptions.md +29 -0
- package/dist/docs/product-catalog/tax-settings.md +37 -0
- package/dist/docs/product-catalog/usage-based-billing.md +119 -0
- package/dist/docs/promotions/create-a-promotion.md +75 -0
- package/dist/docs/promotions/customize-banner.md +41 -0
- package/dist/docs/promotions/integrate.md +38 -0
- package/dist/docs/promotions/overview.md +51 -0
- package/dist/docs/quickstart/core-concepts.md +146 -0
- package/dist/docs/quickstart/dashboard-setup.md +129 -0
- package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
- package/dist/docs/sales/checkout-sessions.md +58 -0
- package/dist/docs/sales/orders.md +76 -0
- package/dist/http/client.d.ts +28 -0
- package/dist/http/client.js +76 -0
- package/dist/http/client.js.map +1 -0
- package/dist/http/errors.d.ts +20 -0
- package/dist/http/errors.js +58 -0
- package/dist/http/errors.js.map +1 -0
- package/dist/resources/docs-index.d.ts +25 -0
- package/dist/resources/docs-index.js +109 -0
- package/dist/resources/docs-index.js.map +1 -0
- package/dist/resources/index.d.ts +2 -0
- package/dist/resources/index.js +73 -0
- package/dist/resources/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +1304 -0
- package/dist/schemas/kelviq.js +468 -0
- package/dist/schemas/kelviq.js.map +1 -0
- package/dist/server.d.ts +2 -0
- package/dist/server.js +41 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/_util.d.ts +15 -0
- package/dist/tools/_util.js +15 -0
- package/dist/tools/_util.js.map +1 -0
- package/dist/tools/checkout.d.ts +3 -0
- package/dist/tools/checkout.js +18 -0
- package/dist/tools/checkout.js.map +1 -0
- package/dist/tools/customers.d.ts +3 -0
- package/dist/tools/customers.js +32 -0
- package/dist/tools/customers.js.map +1 -0
- package/dist/tools/docs.d.ts +2 -0
- package/dist/tools/docs.js +43 -0
- package/dist/tools/docs.js.map +1 -0
- package/dist/tools/entitlements.d.ts +3 -0
- package/dist/tools/entitlements.js +22 -0
- package/dist/tools/entitlements.js.map +1 -0
- package/dist/tools/features.d.ts +3 -0
- package/dist/tools/features.js +55 -0
- package/dist/tools/features.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.js +44 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/licenses.d.ts +3 -0
- package/dist/tools/licenses.js +44 -0
- package/dist/tools/licenses.js.map +1 -0
- package/dist/tools/media.d.ts +3 -0
- package/dist/tools/media.js +18 -0
- package/dist/tools/media.js.map +1 -0
- package/dist/tools/offerings.d.ts +3 -0
- package/dist/tools/offerings.js +21 -0
- package/dist/tools/offerings.js.map +1 -0
- package/dist/tools/partner.d.ts +3 -0
- package/dist/tools/partner.js +55 -0
- package/dist/tools/partner.js.map +1 -0
- package/dist/tools/plan-entitlements.d.ts +3 -0
- package/dist/tools/plan-entitlements.js +56 -0
- package/dist/tools/plan-entitlements.js.map +1 -0
- package/dist/tools/plan-files.d.ts +3 -0
- package/dist/tools/plan-files.js +43 -0
- package/dist/tools/plan-files.js.map +1 -0
- package/dist/tools/plans.d.ts +3 -0
- package/dist/tools/plans.js +120 -0
- package/dist/tools/plans.js.map +1 -0
- package/dist/tools/portal.d.ts +3 -0
- package/dist/tools/portal.js +18 -0
- package/dist/tools/portal.js.map +1 -0
- package/dist/tools/product-files.d.ts +3 -0
- package/dist/tools/product-files.js +31 -0
- package/dist/tools/product-files.js.map +1 -0
- package/dist/tools/product-settings.d.ts +3 -0
- package/dist/tools/product-settings.js +31 -0
- package/dist/tools/product-settings.js.map +1 -0
- package/dist/tools/products.d.ts +3 -0
- package/dist/tools/products.js +69 -0
- package/dist/tools/products.js.map +1 -0
- package/dist/tools/promotions.d.ts +3 -0
- package/dist/tools/promotions.js +19 -0
- package/dist/tools/promotions.js.map +1 -0
- package/dist/tools/subscriptions.d.ts +3 -0
- package/dist/tools/subscriptions.js +63 -0
- package/dist/tools/subscriptions.js.map +1 -0
- package/dist/tools/usage.d.ts +3 -0
- package/dist/tools/usage.js +18 -0
- package/dist/tools/usage.js.map +1 -0
- package/package.json +88 -0
|
@@ -0,0 +1,512 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Subscription Integration for Next.js"
|
|
3
|
+
slug: "guides/subscription-integration-for-nextjs"
|
|
4
|
+
section: "guides"
|
|
5
|
+
description: "A step-by-step guide to add subscription billing and entitlements to your Next.js app."
|
|
6
|
+
---
|
|
7
|
+
Integrate Kelviq subscription billing into your Next.js application using the App Router and React SDK.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Prerequisites
|
|
12
|
+
|
|
13
|
+
- Next.js 14+ with App Router
|
|
14
|
+
- A Kelviq account with plans configured
|
|
15
|
+
- API keys from **Settings → API keys** in the dashboard
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Step 1: Get Your API Keys
|
|
20
|
+
|
|
21
|
+
1. Sign up at [app.kelviq.com](https://app.kelviq.com)
|
|
22
|
+
2. Navigate to **Settings → API Keys**
|
|
23
|
+
3. Copy two keys:
|
|
24
|
+
- **Server API Key** — For API routes (keep secret)
|
|
25
|
+
- **Client API Key** — For React SDK (safe to expose)
|
|
26
|
+
|
|
27
|
+
### Add to Environment Variables
|
|
28
|
+
|
|
29
|
+
Add these to your `.env.local` file:
|
|
30
|
+
|
|
31
|
+
```env
|
|
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
|
|
37
|
+
|
|
38
|
+
# 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/
|
|
41
|
+
|
|
42
|
+
# Your app URL (for redirects)
|
|
43
|
+
NEXT_PUBLIC_APP_URL=https://yourdomain.com
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Never expose your server API key to the frontend or commit it to version control.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Step 2: Define Your Plans
|
|
51
|
+
|
|
52
|
+
### In Kelviq Dashboard
|
|
53
|
+
|
|
54
|
+
1. Go to **Plans** section
|
|
55
|
+
2. Create each subscription tier with:
|
|
56
|
+
- **Plan Identifier**: `base`, `pro`, `enterprise` (code-friendly names)
|
|
57
|
+
- **Price**: Monthly/yearly pricing
|
|
58
|
+
- **Features**: List of included features
|
|
59
|
+
|
|
60
|
+
### Define Entitlements
|
|
61
|
+
|
|
62
|
+
For each plan, configure entitlements (feature access):
|
|
63
|
+
|
|
64
|
+
| Type | Description | Example |
|
|
65
|
+
|------|-------------|---------|
|
|
66
|
+
| **Boolean (FLAG)** | Feature is on/off | `export-data` |
|
|
67
|
+
| **Metered (METER)** | Feature has usage limits | `max-projects: 10` |
|
|
68
|
+
| **Config (CUSTOMIZABLE)** | Feature has configurable value | `team-size: 5` |
|
|
69
|
+
|
|
70
|
+
**Example Plan Structure:**
|
|
71
|
+
|
|
72
|
+
| Feature | Base ($9/mo) | Pro ($49/mo) | Enterprise ($199/mo) |
|
|
73
|
+
|---------|--------------|--------------|----------------------|
|
|
74
|
+
| max-projects | 10 | 100 | Unlimited |
|
|
75
|
+
| export-data | No | Yes | Yes |
|
|
76
|
+
| team-size | 1 | 5 | 50 |
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Step 3: Install the React SDK
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
npm install @kelviq/react-sdk
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Step 4: Create Customers (Optional)
|
|
89
|
+
|
|
90
|
+
You have two options for creating customers in Kelviq:
|
|
91
|
+
|
|
92
|
+
### Option 1: Auto-create during checkout
|
|
93
|
+
|
|
94
|
+
Skip this step entirely. When creating a checkout session, pass the customer's `email` or `customerId` — Kelviq will automatically create the customer record if it doesn't exist.
|
|
95
|
+
|
|
96
|
+
### Option 2: Create customer explicitly
|
|
97
|
+
|
|
98
|
+
Create a customer record when a user signs up. This gives you more control and lets you track customers before they subscribe.
|
|
99
|
+
|
|
100
|
+
**Create API Route** — `app/api/customer/route.ts`:
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
import { NextRequest, NextResponse } from "next/server";
|
|
104
|
+
|
|
105
|
+
export async function POST(request: NextRequest) {
|
|
106
|
+
const { customerId, name, email } = await request.json();
|
|
107
|
+
|
|
108
|
+
const response = await fetch(
|
|
109
|
+
`${process.env.KELVIQ_API_BASE_URL}/customers/`,
|
|
110
|
+
{
|
|
111
|
+
method: "POST",
|
|
112
|
+
headers: {
|
|
113
|
+
"Content-Type": "application/json",
|
|
114
|
+
Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
|
|
115
|
+
},
|
|
116
|
+
body: JSON.stringify({ customerId, name, email }),
|
|
117
|
+
}
|
|
118
|
+
);
|
|
119
|
+
|
|
120
|
+
const data = await response.json();
|
|
121
|
+
return NextResponse.json(data, { status: response.status });
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**Call from Client Component:**
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
async function createKelviqCustomer(userId: string) {
|
|
129
|
+
await fetch("/api/customer", {
|
|
130
|
+
method: "POST",
|
|
131
|
+
headers: { "Content-Type": "application/json" },
|
|
132
|
+
body: JSON.stringify({
|
|
133
|
+
customerId: userId, // Your internal user ID
|
|
134
|
+
name: "John Doe",
|
|
135
|
+
email: "john@example.com",
|
|
136
|
+
}),
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Pre-creating customers is useful when you want to track users in the Kelviq dashboard before they subscribe, or when you need to store additional customer metadata.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Step 5: Implement Checkout
|
|
146
|
+
|
|
147
|
+
Allow users to subscribe to a plan.
|
|
148
|
+
|
|
149
|
+
### Create Checkout API Route
|
|
150
|
+
|
|
151
|
+
Create `app/api/checkout/route.ts`:
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
import { NextRequest, NextResponse } from "next/server";
|
|
155
|
+
|
|
156
|
+
export async function POST(request: NextRequest) {
|
|
157
|
+
const { planIdentifier, customerId, chargePeriod } = await request.json();
|
|
158
|
+
|
|
159
|
+
const response = await fetch(
|
|
160
|
+
`${process.env.KELVIQ_API_BASE_URL}/checkout/`,
|
|
161
|
+
{
|
|
162
|
+
method: "POST",
|
|
163
|
+
headers: {
|
|
164
|
+
"Content-Type": "application/json",
|
|
165
|
+
Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
|
|
166
|
+
},
|
|
167
|
+
body: JSON.stringify({
|
|
168
|
+
planIdentifier,
|
|
169
|
+
chargePeriod: chargePeriod || "MONTHLY",
|
|
170
|
+
customerId, // Customer auto-created if new
|
|
171
|
+
successUrl: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
|
|
172
|
+
}),
|
|
173
|
+
}
|
|
174
|
+
);
|
|
175
|
+
|
|
176
|
+
const data = await response.json();
|
|
177
|
+
return NextResponse.json(data);
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Pricing Page
|
|
182
|
+
|
|
183
|
+
Create `app/pricing/page.tsx`:
|
|
184
|
+
|
|
185
|
+
```tsx
|
|
186
|
+
"use client";
|
|
187
|
+
|
|
188
|
+
const plans = [
|
|
189
|
+
{ id: "base", name: "Base", price: 9 },
|
|
190
|
+
{ id: "pro", name: "Pro", price: 49 },
|
|
191
|
+
{ id: "enterprise", name: "Enterprise", price: 199 },
|
|
192
|
+
];
|
|
193
|
+
|
|
194
|
+
export default function PricingPage() {
|
|
195
|
+
const handleSubscribe = async (planId: string) => {
|
|
196
|
+
const response = await fetch("/api/checkout", {
|
|
197
|
+
method: "POST",
|
|
198
|
+
headers: { "Content-Type": "application/json" },
|
|
199
|
+
body: JSON.stringify({
|
|
200
|
+
planIdentifier: planId,
|
|
201
|
+
customerId: getCurrentUserId(), // Your auth system
|
|
202
|
+
}),
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
const { checkoutUrl } = await response.json();
|
|
206
|
+
window.location.href = checkoutUrl;
|
|
207
|
+
};
|
|
208
|
+
|
|
209
|
+
return (
|
|
210
|
+
<div>
|
|
211
|
+
{plans.map(plan => (
|
|
212
|
+
<div key={plan.id}>
|
|
213
|
+
<h3>{plan.name}</h3>
|
|
214
|
+
<p>${plan.price}/month</p>
|
|
215
|
+
<button onClick={() => handleSubscribe(plan.id)}>
|
|
216
|
+
Subscribe
|
|
217
|
+
</button>
|
|
218
|
+
</div>
|
|
219
|
+
))}
|
|
220
|
+
</div>
|
|
221
|
+
);
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Create `app/success/page.tsx`:
|
|
226
|
+
|
|
227
|
+
```tsx
|
|
228
|
+
export default function SuccessPage() {
|
|
229
|
+
return (
|
|
230
|
+
<div>
|
|
231
|
+
<h1>Payment Successful!</h1>
|
|
232
|
+
<p>Your subscription is now active.</p>
|
|
233
|
+
<a href="/dashboard">Go to Dashboard</a>
|
|
234
|
+
</div>
|
|
235
|
+
);
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Step 6: Manage Subscriptions
|
|
242
|
+
|
|
243
|
+
### Fetch Current Subscription
|
|
244
|
+
|
|
245
|
+
Create `app/api/subscriptions/route.ts`:
|
|
246
|
+
|
|
247
|
+
```typescript
|
|
248
|
+
import { NextRequest, NextResponse } from "next/server";
|
|
249
|
+
|
|
250
|
+
export async function GET(request: NextRequest) {
|
|
251
|
+
const customerId = request.nextUrl.searchParams.get("customerId");
|
|
252
|
+
|
|
253
|
+
const response = await fetch(
|
|
254
|
+
`${process.env.KELVIQ_API_BASE_URL}/subscriptions/?customer_id=${customerId}`,
|
|
255
|
+
{
|
|
256
|
+
headers: {
|
|
257
|
+
Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
|
|
258
|
+
},
|
|
259
|
+
}
|
|
260
|
+
);
|
|
261
|
+
|
|
262
|
+
const data = await response.json();
|
|
263
|
+
return NextResponse.json(data);
|
|
264
|
+
}
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### Update Subscription (Upgrade/Downgrade)
|
|
268
|
+
|
|
269
|
+
Create `app/api/subscriptions/update/route.ts`:
|
|
270
|
+
|
|
271
|
+
```typescript
|
|
272
|
+
import { NextRequest, NextResponse } from "next/server";
|
|
273
|
+
|
|
274
|
+
export async function POST(request: NextRequest) {
|
|
275
|
+
const { subscriptionId, planIdentifier, chargePeriod } = await request.json();
|
|
276
|
+
|
|
277
|
+
const response = await fetch(
|
|
278
|
+
`${process.env.KELVIQ_API_BASE_URL}/subscriptions/${subscriptionId}/update/`,
|
|
279
|
+
{
|
|
280
|
+
method: "POST",
|
|
281
|
+
headers: {
|
|
282
|
+
"Content-Type": "application/json",
|
|
283
|
+
Authorization: `Bearer ${process.env.KELVIQ_API_KEY}`,
|
|
284
|
+
},
|
|
285
|
+
body: JSON.stringify({
|
|
286
|
+
planIdentifier,
|
|
287
|
+
chargePeriod: chargePeriod || "MONTHLY",
|
|
288
|
+
}),
|
|
289
|
+
}
|
|
290
|
+
);
|
|
291
|
+
|
|
292
|
+
const data = await response.json();
|
|
293
|
+
return NextResponse.json(data);
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
### Handle Upgrades/Downgrades in Client
|
|
298
|
+
|
|
299
|
+
```typescript
|
|
300
|
+
async function handlePlanChange(newPlanId: string) {
|
|
301
|
+
// Fetch current subscription
|
|
302
|
+
const res = await fetch(`/api/subscriptions?customerId=${userId}`);
|
|
303
|
+
const { results } = await res.json();
|
|
304
|
+
const current = results.find(s => s.status === "active");
|
|
305
|
+
|
|
306
|
+
if (current) {
|
|
307
|
+
// Update existing subscription
|
|
308
|
+
await fetch("/api/subscriptions/update", {
|
|
309
|
+
method: "POST",
|
|
310
|
+
headers: { "Content-Type": "application/json" },
|
|
311
|
+
body: JSON.stringify({
|
|
312
|
+
subscriptionId: current.id,
|
|
313
|
+
planIdentifier: newPlanId,
|
|
314
|
+
chargePeriod: "MONTHLY",
|
|
315
|
+
}),
|
|
316
|
+
});
|
|
317
|
+
|
|
318
|
+
alert("Plan updated!");
|
|
319
|
+
} else {
|
|
320
|
+
// No subscription, redirect to checkout
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
## Step 7: Gate Features with Entitlements
|
|
328
|
+
|
|
329
|
+
Dynamically enable/disable features based on subscription.
|
|
330
|
+
|
|
331
|
+
### Setup KelviqProvider
|
|
332
|
+
|
|
333
|
+
Wrap your app in `app/layout.tsx`:
|
|
334
|
+
|
|
335
|
+
```tsx
|
|
336
|
+
import { KelviqProvider } from "@kelviq/react-sdk";
|
|
337
|
+
|
|
338
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
339
|
+
return (
|
|
340
|
+
<html lang="en">
|
|
341
|
+
<body>
|
|
342
|
+
<KelviqProvider
|
|
343
|
+
customerId={getCurrentUserId()}
|
|
344
|
+
accessToken={process.env.NEXT_PUBLIC_KELVIQ_CLIENT_KEY!}
|
|
345
|
+
apiUrl={process.env.NEXT_PUBLIC_KELVIQ_EDGE_URL!}
|
|
346
|
+
>
|
|
347
|
+
{children}
|
|
348
|
+
</KelviqProvider>
|
|
349
|
+
</body>
|
|
350
|
+
</html>
|
|
351
|
+
);
|
|
352
|
+
}
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### Access Entitlements in Components
|
|
356
|
+
|
|
357
|
+
```tsx
|
|
358
|
+
"use client";
|
|
359
|
+
|
|
360
|
+
import { useKelviq, useAllEntitlements } from "@kelviq/react-sdk";
|
|
361
|
+
|
|
362
|
+
export function MyFeature() {
|
|
363
|
+
const { isLoading, error } = useKelviq();
|
|
364
|
+
const entitlementsState = useAllEntitlements();
|
|
365
|
+
const entitlements = entitlementsState?.data;
|
|
366
|
+
|
|
367
|
+
if (isLoading) return <div>Loading...</div>;
|
|
368
|
+
if (error) return <div>Error loading features</div>;
|
|
369
|
+
|
|
370
|
+
// Boolean entitlement example
|
|
371
|
+
const canExport = entitlements?.["export-data"]?.hasAccess ?? false;
|
|
372
|
+
|
|
373
|
+
// Metered entitlement example
|
|
374
|
+
const maxProjects = entitlements?.["max-projects"]?.usageLimit;
|
|
375
|
+
const currentProjects = entitlements?.["max-projects"]?.currentUsage ?? 0;
|
|
376
|
+
const remainingProjects = entitlements?.["max-projects"]?.remaining;
|
|
377
|
+
|
|
378
|
+
// Config entitlement example
|
|
379
|
+
const teamSize = entitlements?.["team-size"]?.usageLimit ?? 1;
|
|
380
|
+
|
|
381
|
+
return (
|
|
382
|
+
<div>
|
|
383
|
+
|
|
384
|
+
{canExport ? (
|
|
385
|
+
<button onClick={handleExport}>Export Data</button>
|
|
386
|
+
) : (
|
|
387
|
+
<div>
|
|
388
|
+
Export locked. <a href="/pricing">Upgrade to unlock</a>
|
|
389
|
+
</div>
|
|
390
|
+
)}
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
<div>
|
|
394
|
+
<p>Projects: {currentProjects} / {maxProjects ?? "Unlimited"}</p>
|
|
395
|
+
<button
|
|
396
|
+
disabled={maxProjects !== null && currentProjects >= maxProjects}
|
|
397
|
+
onClick={createProject}
|
|
398
|
+
>
|
|
399
|
+
{remainingProjects > 0 ? "Create Project" : "Limit Reached"}
|
|
400
|
+
</button>
|
|
401
|
+
</div>
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
<p>Team size: {teamSize} members</p>
|
|
405
|
+
</div>
|
|
406
|
+
);
|
|
407
|
+
}
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
### Entitlement Response Structure (React SDK)
|
|
411
|
+
|
|
412
|
+
```typescript
|
|
413
|
+
interface Entitlement {
|
|
414
|
+
featureId: string;
|
|
415
|
+
featureType: "BOOLEAN" | "METER" | "CUSTOMIZABLE";
|
|
416
|
+
hasAccess: boolean;
|
|
417
|
+
usageLimit: number | null; // For METER (summed) and CUSTOMIZABLE (first item)
|
|
418
|
+
currentUsage: number; // For METER (summed) and CUSTOMIZABLE (first item)
|
|
419
|
+
remaining: number | null; // For METER: usageLimit - currentUsage (null = unlimited)
|
|
420
|
+
hardLimit: boolean; // true if any item has a hard limit
|
|
421
|
+
items: RawEntitlement[]; // Raw API entries for this featureId
|
|
422
|
+
}
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
---
|
|
426
|
+
|
|
427
|
+
## Common Patterns
|
|
428
|
+
|
|
429
|
+
```tsx
|
|
430
|
+
"use client";
|
|
431
|
+
|
|
432
|
+
import { useAllEntitlements } from "@kelviq/react-sdk";
|
|
433
|
+
|
|
434
|
+
function LockedFeature({ featureId }: { featureId: string }) {
|
|
435
|
+
const entitlements = useAllEntitlements()?.data;
|
|
436
|
+
const hasAccess = entitlements?.[featureId]?.hasAccess ?? false;
|
|
437
|
+
|
|
438
|
+
if (!hasAccess) {
|
|
439
|
+
return (
|
|
440
|
+
<div className="locked">
|
|
441
|
+
<span>Feature locked</span>
|
|
442
|
+
<a href="/pricing">Upgrade to unlock</a>
|
|
443
|
+
</div>
|
|
444
|
+
);
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
return null;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
// Usage
|
|
451
|
+
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
```tsx
|
|
455
|
+
"use client";
|
|
456
|
+
|
|
457
|
+
import { useAllEntitlements } from "@kelviq/react-sdk";
|
|
458
|
+
|
|
459
|
+
function UsageBar({ featureId }: { featureId: string }) {
|
|
460
|
+
const entitlements = useAllEntitlements()?.data;
|
|
461
|
+
const feature = entitlements?.[featureId];
|
|
462
|
+
|
|
463
|
+
const current = feature?.currentUsage ?? 0;
|
|
464
|
+
const max = feature?.usageLimit;
|
|
465
|
+
const percentage = max ? (current / max) * 100 : 0;
|
|
466
|
+
|
|
467
|
+
return (
|
|
468
|
+
<div>
|
|
469
|
+
<p>{current} / {max ?? "Unlimited"} used</p>
|
|
470
|
+
{max && (
|
|
471
|
+
<div className="progress-bar">
|
|
472
|
+
<div style={{ width: `${percentage}%` }} />
|
|
473
|
+
</div>
|
|
474
|
+
)}
|
|
475
|
+
</div>
|
|
476
|
+
);
|
|
477
|
+
}
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
```tsx
|
|
481
|
+
"use client";
|
|
482
|
+
|
|
483
|
+
import { useAllEntitlements } from "@kelviq/react-sdk";
|
|
484
|
+
|
|
485
|
+
function DashboardFeatures() {
|
|
486
|
+
const entitlements = useAllEntitlements()?.data;
|
|
487
|
+
|
|
488
|
+
const canExport = entitlements?.["export-data"]?.hasAccess;
|
|
489
|
+
const canInviteTeam = entitlements?.["team-features"]?.hasAccess;
|
|
490
|
+
const maxProjects = entitlements?.["max-projects"]?.usageLimit;
|
|
491
|
+
|
|
492
|
+
return (
|
|
493
|
+
<div>
|
|
494
|
+
<h1>Dashboard</h1>
|
|
495
|
+
|
|
496
|
+
{canExport && }
|
|
497
|
+
{canInviteTeam && }
|
|
498
|
+
|
|
499
|
+
|
|
500
|
+
</div>
|
|
501
|
+
);
|
|
502
|
+
}
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
---
|
|
506
|
+
|
|
507
|
+
## Need Help?
|
|
508
|
+
|
|
509
|
+
Have questions or need implementation support?
|
|
510
|
+
|
|
511
|
+
- Email us at **hi@kelviq.com**
|
|
512
|
+
- [Book a demo](https://tidycal.com/neravath/15-minute-meeting)
|