@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,580 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "React SDK"
|
|
3
|
+
slug: "changelog/react-sdk"
|
|
4
|
+
section: "changelog"
|
|
5
|
+
description: "Changelog for @kelviq/react-sdk"
|
|
6
|
+
---
|
|
7
|
+
<Update label="v2.1.1" description="May 9, 2026">
|
|
8
|
+
### Improvements
|
|
9
|
+
|
|
10
|
+
#### `KelviqProvider` — `customerId` and `plansEnabled` Props for Pricing
|
|
11
|
+
|
|
12
|
+
The pricing request now forwards two additional optional props to the product offerings API.
|
|
13
|
+
|
|
14
|
+
**`customerId`** — when provided, the pricing response is personalized to that customer (e.g. reflecting their existing subscription state):
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
<KelviqProvider
|
|
18
|
+
accessToken="..."
|
|
19
|
+
productId="your-product-id"
|
|
20
|
+
customerId="cust_123"
|
|
21
|
+
config={{ fetchPricingOnMount: true }}
|
|
22
|
+
>
|
|
23
|
+
|
|
24
|
+
</KelviqProvider>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**`plansEnabled`** — a comma-separated list of plan identifiers to include in the response. When omitted, all active plans are returned:
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
<KelviqProvider
|
|
31
|
+
accessToken="..."
|
|
32
|
+
productId="your-product-id"
|
|
33
|
+
plansEnabled="free-plan,pro-plan"
|
|
34
|
+
config={{ fetchPricingOnMount: true }}
|
|
35
|
+
>
|
|
36
|
+
|
|
37
|
+
</KelviqProvider>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Both props are reactive — updating either value will trigger a new pricing fetch automatically.
|
|
41
|
+
|
|
42
|
+
</Update>
|
|
43
|
+
|
|
44
|
+
<Update label="v2.1.0" description="May 9, 2026">
|
|
45
|
+
### New Features
|
|
46
|
+
|
|
47
|
+
#### Product Offerings — Pricing & Feature Components
|
|
48
|
+
|
|
49
|
+
The SDK now supports fetching and displaying product pricing and plan features, with localized currency based on user location.
|
|
50
|
+
|
|
51
|
+
##### Setup
|
|
52
|
+
|
|
53
|
+
Pass `productId` and enable `fetchPricingOnMount` in your provider config:
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
<KelviqProvider
|
|
57
|
+
accessToken="..."
|
|
58
|
+
productId="your-product-id"
|
|
59
|
+
config={{ fetchPricingOnMount: true }}
|
|
60
|
+
>
|
|
61
|
+
|
|
62
|
+
</KelviqProvider>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
##### `usePricing()` — Pricing Data Hook
|
|
66
|
+
|
|
67
|
+
Returns the full pricing API response as an `AsyncState`. Only populated when `fetchPricingOnMount` is enabled, or after calling `refreshPricing()` from `useKelviq()`.
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
const { data, isLoading, error } = usePricing();
|
|
71
|
+
console.log(data?.currencyCode, data?.plans);
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
##### `` — Render-Prop Price Component
|
|
75
|
+
|
|
76
|
+
Displays localized pricing for a plan and billing period:
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
}
|
|
80
|
+
fallback={<p>Unavailable</p>}
|
|
81
|
+
>
|
|
82
|
+
{({ formattedPrice, isFree, hasFreeTrial, trialPeriod }) => (
|
|
83
|
+
<div>
|
|
84
|
+
<span>{formattedPrice}</span>
|
|
85
|
+
{hasFreeTrial && <span>Try free for {trialPeriod} days</span>}
|
|
86
|
+
</div>
|
|
87
|
+
)}
|
|
88
|
+
</KQPrice>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The render prop receives:
|
|
92
|
+
|
|
93
|
+
| Field | Type | Description |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `plan` | `RawPricingPlan` | Full plan object |
|
|
96
|
+
| `charge` | `RawPricingCharge \| null` | Charge for the requested billing period |
|
|
97
|
+
| `amount` | `number` | Raw numeric amount |
|
|
98
|
+
| `formattedPrice` | `string` | Localized price string (e.g. `$9.99`) or `"Free"` |
|
|
99
|
+
| `currencySymbol` | `string` | e.g. `$` |
|
|
100
|
+
| `currencyCode` | `string` | e.g. `USD` |
|
|
101
|
+
| `pricingLocale` | `string` | e.g. `en-US` |
|
|
102
|
+
| `isFree` | `boolean` | `true` when `priceType === 'FREE'` |
|
|
103
|
+
| `hasFreeTrial` | `boolean` | Whether a free trial is available |
|
|
104
|
+
| `trialPeriod` | `number` | Trial length in days |
|
|
105
|
+
|
|
106
|
+
##### `` — Render-Prop Feature Component
|
|
107
|
+
|
|
108
|
+
Iterates over enabled features for a plan. Supports optional filtering by feature type:
|
|
109
|
+
|
|
110
|
+
```tsx
|
|
111
|
+
}
|
|
112
|
+
fallback={<p>No features available</p>}
|
|
113
|
+
>
|
|
114
|
+
{({ feature, plan, index }) => (
|
|
115
|
+
<li key={feature.id}>
|
|
116
|
+
{feature.displayName}
|
|
117
|
+
</li>
|
|
118
|
+
)}
|
|
119
|
+
</KQFeatureList>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
| Prop | Type | Description |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| `planIdentifier` | `string` | The plan to list features for |
|
|
125
|
+
| `featureType` | `'BOOLEAN' \| 'METER'` | Optional filter by feature type |
|
|
126
|
+
| `loadingComponent` | `ReactNode` | Shown while data loads |
|
|
127
|
+
| `fallback` | `ReactNode` | Shown when plan not found or no features match |
|
|
128
|
+
| `children` | `(data) => ReactNode` | Render prop called for each enabled feature |
|
|
129
|
+
|
|
130
|
+
##### `kqFormatPrice()` — Price Formatter Utility
|
|
131
|
+
|
|
132
|
+
Standalone utility for formatting a numeric amount with a currency symbol:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
import { kqFormatPrice } from '@kelviq/react-sdk';
|
|
136
|
+
|
|
137
|
+
kqFormatPrice(9.99, '$', { pricingLocale: 'en-US' }); // "$9.99"
|
|
138
|
+
kqFormatPrice(1200, '€', { compact: true, pricingLocale: 'de-DE' }); // "€1,2K"
|
|
139
|
+
kqFormatPrice(0, '$', { includeCurrencySymbol: false }); // "0"
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
| Option | Type | Default | Description |
|
|
143
|
+
|---|---|---|---|
|
|
144
|
+
| `compact` | `boolean` | `false` | Use compact notation (e.g. `1.2K`) |
|
|
145
|
+
| `locale` | `string` | `pricingLocale` | Override locale for number formatting |
|
|
146
|
+
| `pricingLocale` | `string` | `'en-US'` | Locale from the pricing API |
|
|
147
|
+
| `includeCurrencySymbol` | `boolean` | `true` | Prepend the currency symbol |
|
|
148
|
+
|
|
149
|
+
##### New Types
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
RawPricingFeature
|
|
153
|
+
RawPricingCharge
|
|
154
|
+
RawPricingPrice
|
|
155
|
+
RawPricingPlan
|
|
156
|
+
RawPricingBillingPeriod
|
|
157
|
+
RawPricingApiResponse
|
|
158
|
+
|
|
159
|
+
KQFormatPriceOptions
|
|
160
|
+
KQPriceProps
|
|
161
|
+
KQFeatureListProps
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
##### New Exports
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
export { usePricing } from './hooks/usePricing';
|
|
168
|
+
export { KQPrice } from './components/KQPrice';
|
|
169
|
+
export { KQFeatureList } from './components/KQFeatureList';
|
|
170
|
+
export { kqFormatPrice } from './utils/formatPrice';
|
|
171
|
+
export type * from './types/api.types';
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
</Update>
|
|
175
|
+
<Update label="v2.0.0" description="February 27, 2026">
|
|
176
|
+
### New Features
|
|
177
|
+
|
|
178
|
+
#### Duplicate `featureId` Aggregation
|
|
179
|
+
|
|
180
|
+
The SDK now handles customers with multiple subscriptions that grant entitlements to the same feature. Raw entries are grouped by `featureId` and aggregated automatically:
|
|
181
|
+
|
|
182
|
+
- **METER**: `usageLimit` and `currentUsage` are summed across entries; `remaining` is recalculated
|
|
183
|
+
- **BOOLEAN / CUSTOMIZABLE**: `hasAccess` is OR'd across entries (any `true` → `true`)
|
|
184
|
+
The raw un-aggregated entries are preserved in the `items` array on each `Entitlement`.
|
|
185
|
+
|
|
186
|
+
#### `getEntitlements()` — Convenience Accessor
|
|
187
|
+
|
|
188
|
+
Returns the aggregated entitlements map directly, without the `AsyncState` wrapper:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
const { getEntitlements } = useKelviq();
|
|
192
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
193
|
+
|
|
194
|
+
const emailFeature = entitlements["email-sends"];
|
|
195
|
+
console.log(emailFeature.hasAccess, emailFeature.remaining);
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
#### `getRawEntitlements()` — Raw API Response
|
|
199
|
+
|
|
200
|
+
Access the un-aggregated API response with the `customerId` wrapper:
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
const { getRawEntitlements } = useKelviq();
|
|
204
|
+
const raw = getRawEntitlements();
|
|
205
|
+
// { customerId: "cust_123", entitlements: [...] }
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
#### `getRawEntitlement(featureId)` — Raw Data for a Single Feature
|
|
209
|
+
|
|
210
|
+
Returns the raw API response filtered to a specific featureId:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
const { getRawEntitlement } = useKelviq();
|
|
214
|
+
const raw = getRawEntitlement("email-sends");
|
|
215
|
+
// { customerId: "cust_123", entitlements: [/* only "email-sends" entries */] }
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
#### `updateEntitlement()` — Client-Side Entitlement Mutation
|
|
219
|
+
|
|
220
|
+
Update an entitlement in-place, for example after recording a usage increment on the client side. The `remaining` field is automatically recalculated.
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
const { updateEntitlement } = useKelviq();
|
|
224
|
+
updateEntitlement("email-sends", { currentUsage: 5 });
|
|
225
|
+
// `remaining` is automatically recalculated
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Accepts `Partial<Omit<Entitlement, 'featureId' | 'featureType' | 'items'>>`.
|
|
229
|
+
|
|
230
|
+
#### `environment` Prop on `KelviqProvider`
|
|
231
|
+
|
|
232
|
+
Supports `'production'` (default) and `'sandbox'`, which selects the appropriate default API URL:
|
|
233
|
+
|
|
234
|
+
```tsx
|
|
235
|
+
<KelviqProvider environment="sandbox" customerId="cust_123" accessToken="...">
|
|
236
|
+
|
|
237
|
+
</KelviqProvider>
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
### Breaking Changes
|
|
243
|
+
|
|
244
|
+
#### Unified `Entitlement` Type
|
|
245
|
+
|
|
246
|
+
The three separate entitlement interfaces and their union type have been replaced by a single unified `Entitlement` interface:
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
// Before — three separate types
|
|
250
|
+
interface BooleanEntitlement { type: 'boolean'; featureKey: string; hasAccess: boolean; }
|
|
251
|
+
interface ConfigEntitlement { type: 'customizable'; featureKey: string; hasAccess: boolean; configuration: number | null; }
|
|
252
|
+
interface MeteredEntitlement { type: 'metered'; featureKey: string; hasAccess: boolean; limit: number | null; used: number; remaining: number | null; resetAt: string | null; hardLimit: boolean; }
|
|
253
|
+
|
|
254
|
+
// After — one unified type
|
|
255
|
+
interface Entitlement {
|
|
256
|
+
featureId: string;
|
|
257
|
+
featureType: 'METER' | 'BOOLEAN' | 'CUSTOMIZABLE';
|
|
258
|
+
hasAccess: boolean;
|
|
259
|
+
currentUsage: number;
|
|
260
|
+
usageLimit: number | null;
|
|
261
|
+
remaining: number | null;
|
|
262
|
+
hardLimit: boolean;
|
|
263
|
+
items: AnyRawEntitlementData[];
|
|
264
|
+
}
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
#### `featureKey` Renamed to `featureId`
|
|
268
|
+
|
|
269
|
+
All props, parameters, and type fields now use `featureId` to match the backend API naming:
|
|
270
|
+
|
|
271
|
+
```tsx
|
|
272
|
+
// Before
|
|
273
|
+
<ShowWhenBooleanEntitled featureKey="my-feature">
|
|
274
|
+
|
|
275
|
+
</ShowWhenBooleanEntitled>
|
|
276
|
+
|
|
277
|
+
// After
|
|
278
|
+
<ShowWhenBooleanEntitled featureId="my-feature">
|
|
279
|
+
|
|
280
|
+
</ShowWhenBooleanEntitled>
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
#### `Config` Renamed to `Customizable`
|
|
284
|
+
|
|
285
|
+
| Before | After |
|
|
286
|
+
|---|---|
|
|
287
|
+
| `useConfigEntitlement` | `useCustomizableEntitlement` |
|
|
288
|
+
| `ShowWhenConfigEntitled` | `ShowWhenCustomizableEntitled` |
|
|
289
|
+
| `ConfigEntitlement` type | Unified `Entitlement` |
|
|
290
|
+
|
|
291
|
+
#### `type` Field Renamed to `featureType` with Uppercase Values
|
|
292
|
+
|
|
293
|
+
| Before | After |
|
|
294
|
+
|---|---|
|
|
295
|
+
| `type: 'boolean'` | `featureType: 'BOOLEAN'` |
|
|
296
|
+
| `type: 'customizable'` | `featureType: 'CUSTOMIZABLE'` |
|
|
297
|
+
| `type: 'metered'` | `featureType: 'METER'` |
|
|
298
|
+
|
|
299
|
+
#### `configuration` Field Removed
|
|
300
|
+
|
|
301
|
+
`ConfigEntitlement.configuration` has been removed. Customizable entitlements now use the same `usageLimit`, `currentUsage`, and `remaining` fields as metered entitlements.
|
|
302
|
+
|
|
303
|
+
#### Hooks Return `Entitlement | null` Directly
|
|
304
|
+
|
|
305
|
+
All entitlement hooks now return the entitlement object directly (or `null`) instead of an `AsyncState` wrapper. Use the top-level `isLoading` and `error` from `useKelviq()` for loading/error states.
|
|
306
|
+
|
|
307
|
+
```ts
|
|
308
|
+
// Before
|
|
309
|
+
const { data, isLoading, error } = useMeteredEntitlement("my-feature");
|
|
310
|
+
if (isLoading) return ;
|
|
311
|
+
console.log(data?.used);
|
|
312
|
+
|
|
313
|
+
// After
|
|
314
|
+
const entitlement = useMeteredEntitlement("my-feature");
|
|
315
|
+
const { isLoading, error } = useKelviq();
|
|
316
|
+
if (isLoading) return ;
|
|
317
|
+
console.log(entitlement?.currentUsage);
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
#### `getEntitlement()` Simplified
|
|
321
|
+
|
|
322
|
+
The generic type parameter and second argument have been removed:
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
// Before
|
|
326
|
+
getEntitlement<MeteredEntitlement>("my-feature", "metered")
|
|
327
|
+
|
|
328
|
+
// After
|
|
329
|
+
getEntitlement("my-feature") // returns Entitlement | null
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
#### `hasAccess()` Returns `boolean` (Never `undefined`)
|
|
333
|
+
|
|
334
|
+
`hasAccess(featureId)` now returns `false` when data is unavailable instead of `undefined`. No need for nullish checks.
|
|
335
|
+
|
|
336
|
+
#### Metered Field Renames
|
|
337
|
+
|
|
338
|
+
| Before | After | Notes |
|
|
339
|
+
|---|---|---|
|
|
340
|
+
| `limit` | `usageLimit` | Aligned with the API |
|
|
341
|
+
| `used` | `currentUsage` | Aligned with the API |
|
|
342
|
+
| `resetAt` | _(removed)_ | Now per-item: `entitlement.items[].resetAt` |
|
|
343
|
+
| `hardLimit` | `hardLimit` | Now aggregated: `true` if any item sets it |
|
|
344
|
+
|
|
345
|
+
#### `allEntitlements.data` Shape Changed
|
|
346
|
+
|
|
347
|
+
The map is now keyed by `featureId` (previously `featureKey`) and contains unified `Entitlement` objects. Use the new `getEntitlements()` convenience method:
|
|
348
|
+
|
|
349
|
+
```ts
|
|
350
|
+
// Before
|
|
351
|
+
const { allEntitlements } = useKelviq();
|
|
352
|
+
const myFeature = allEntitlements.data?.["my-feature"]; // AnyEntitlement | undefined
|
|
353
|
+
|
|
354
|
+
// After
|
|
355
|
+
const { getEntitlements } = useKelviq();
|
|
356
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
357
|
+
const myFeature = entitlements["my-feature"]; // Entitlement | undefined
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
362
|
+
### Migration Checklist
|
|
363
|
+
|
|
364
|
+
1. Replace all `featureKey` props/params with `featureId`
|
|
365
|
+
2. Replace `entitlement.type` with `entitlement.featureType` and update values to uppercase
|
|
366
|
+
3. Replace `useConfigEntitlement` with `useCustomizableEntitlement`
|
|
367
|
+
4. Replace `ShowWhenConfigEntitled` with `ShowWhenCustomizableEntitled`
|
|
368
|
+
5. Replace `ConfigEntitlement.configuration` with `usageLimit` / `currentUsage` / `remaining`
|
|
369
|
+
6. Update hook consumers: hooks now return `Entitlement | null` directly (not `AsyncState`)
|
|
370
|
+
7. Remove type parameters from `getEntitlement()` calls
|
|
371
|
+
8. Replace `limit` → `usageLimit`, `used` → `currentUsage`
|
|
372
|
+
9. Replace `entitlement.resetAt` with `entitlement.items[].resetAt`
|
|
373
|
+
10. Use `getEntitlements()` instead of `allEntitlements.data`
|
|
374
|
+
11. Use `getRawEntitlements()` for un-aggregated API data
|
|
375
|
+
</Update>
|
|
376
|
+
|
|
377
|
+
<Update label="v2.0.0" description="February 27, 2026">
|
|
378
|
+
|
|
379
|
+
### New Features
|
|
380
|
+
|
|
381
|
+
#### Duplicate `featureId` Aggregation
|
|
382
|
+
|
|
383
|
+
The SDK now handles customers with multiple subscriptions that grant entitlements to the same feature. Raw entries are grouped by `featureId` and aggregated automatically:
|
|
384
|
+
|
|
385
|
+
- **METER**: `usageLimit` and `currentUsage` are summed across entries; `remaining` is recalculated
|
|
386
|
+
- **BOOLEAN / CUSTOMIZABLE**: `hasAccess` is OR'd across entries (any `true` → `true`)
|
|
387
|
+
|
|
388
|
+
The raw un-aggregated entries are preserved in the `items` array on each `Entitlement`.
|
|
389
|
+
|
|
390
|
+
#### `getEntitlements()` — Convenience Accessor
|
|
391
|
+
|
|
392
|
+
Returns the aggregated entitlements map directly, without the `AsyncState` wrapper:
|
|
393
|
+
|
|
394
|
+
```ts
|
|
395
|
+
const { getEntitlements } = useKelviq();
|
|
396
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
397
|
+
|
|
398
|
+
const emailFeature = entitlements["email-sends"];
|
|
399
|
+
console.log(emailFeature.hasAccess, emailFeature.remaining);
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
#### `getRawEntitlements()` — Raw API Response
|
|
403
|
+
|
|
404
|
+
Access the un-aggregated API response with the `customerId` wrapper:
|
|
405
|
+
|
|
406
|
+
```ts
|
|
407
|
+
const { getRawEntitlements } = useKelviq();
|
|
408
|
+
const raw = getRawEntitlements();
|
|
409
|
+
// { customerId: "cust_123", entitlements: [...] }
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
#### `getRawEntitlement(featureId)` — Raw Data for a Single Feature
|
|
413
|
+
|
|
414
|
+
Returns the raw API response filtered to a specific featureId:
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
const { getRawEntitlement } = useKelviq();
|
|
418
|
+
const raw = getRawEntitlement("email-sends");
|
|
419
|
+
// { customerId: "cust_123", entitlements: [/* only "email-sends" entries */] }
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
#### `updateEntitlement()` — Client-Side Entitlement Mutation
|
|
423
|
+
|
|
424
|
+
Update an entitlement in-place, for example after recording a usage increment on the client side. The `remaining` field is automatically recalculated.
|
|
425
|
+
|
|
426
|
+
```ts
|
|
427
|
+
const { updateEntitlement } = useKelviq();
|
|
428
|
+
updateEntitlement("email-sends", { currentUsage: 5 });
|
|
429
|
+
// `remaining` is automatically recalculated
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
Accepts `Partial<Omit<Entitlement, 'featureId' | 'featureType' | 'items'>>`.
|
|
433
|
+
|
|
434
|
+
#### `environment` Prop on `KelviqProvider`
|
|
435
|
+
|
|
436
|
+
Supports `'production'` (default) and `'sandbox'`, which selects the appropriate default API URL:
|
|
437
|
+
|
|
438
|
+
```tsx
|
|
439
|
+
<KelviqProvider environment="sandbox" customerId="cust_123" accessToken="...">
|
|
440
|
+
|
|
441
|
+
</KelviqProvider>
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
---
|
|
445
|
+
|
|
446
|
+
### Breaking Changes
|
|
447
|
+
|
|
448
|
+
#### Unified `Entitlement` Type
|
|
449
|
+
|
|
450
|
+
The three separate entitlement interfaces and their union type have been replaced by a single unified `Entitlement` interface:
|
|
451
|
+
|
|
452
|
+
```ts
|
|
453
|
+
// Before — three separate types
|
|
454
|
+
interface BooleanEntitlement { type: 'boolean'; featureKey: string; hasAccess: boolean; }
|
|
455
|
+
interface ConfigEntitlement { type: 'customizable'; featureKey: string; hasAccess: boolean; configuration: number | null; }
|
|
456
|
+
interface MeteredEntitlement { type: 'metered'; featureKey: string; hasAccess: boolean; limit: number | null; used: number; remaining: number | null; resetAt: string | null; hardLimit: boolean; }
|
|
457
|
+
|
|
458
|
+
// After — one unified type
|
|
459
|
+
interface Entitlement {
|
|
460
|
+
featureId: string;
|
|
461
|
+
featureType: 'METER' | 'BOOLEAN' | 'CUSTOMIZABLE';
|
|
462
|
+
hasAccess: boolean;
|
|
463
|
+
currentUsage: number;
|
|
464
|
+
usageLimit: number | null;
|
|
465
|
+
remaining: number | null;
|
|
466
|
+
hardLimit: boolean;
|
|
467
|
+
items: AnyRawEntitlementData[];
|
|
468
|
+
}
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
#### `featureKey` Renamed to `featureId`
|
|
472
|
+
|
|
473
|
+
All props, parameters, and type fields now use `featureId` to match the backend API naming:
|
|
474
|
+
|
|
475
|
+
```tsx
|
|
476
|
+
// Before
|
|
477
|
+
<ShowWhenBooleanEntitled featureKey="my-feature">
|
|
478
|
+
|
|
479
|
+
</ShowWhenBooleanEntitled>
|
|
480
|
+
|
|
481
|
+
// After
|
|
482
|
+
<ShowWhenBooleanEntitled featureId="my-feature">
|
|
483
|
+
|
|
484
|
+
</ShowWhenBooleanEntitled>
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
#### `Config` Renamed to `Customizable`
|
|
488
|
+
|
|
489
|
+
| Before | After |
|
|
490
|
+
|---|---|
|
|
491
|
+
| `useConfigEntitlement` | `useCustomizableEntitlement` |
|
|
492
|
+
| `ShowWhenConfigEntitled` | `ShowWhenCustomizableEntitled` |
|
|
493
|
+
| `ConfigEntitlement` type | Unified `Entitlement` |
|
|
494
|
+
|
|
495
|
+
#### `type` Field Renamed to `featureType` with Uppercase Values
|
|
496
|
+
|
|
497
|
+
| Before | After |
|
|
498
|
+
|---|---|
|
|
499
|
+
| `type: 'boolean'` | `featureType: 'BOOLEAN'` |
|
|
500
|
+
| `type: 'customizable'` | `featureType: 'CUSTOMIZABLE'` |
|
|
501
|
+
| `type: 'metered'` | `featureType: 'METER'` |
|
|
502
|
+
|
|
503
|
+
#### `configuration` Field Removed
|
|
504
|
+
|
|
505
|
+
`ConfigEntitlement.configuration` has been removed. Customizable entitlements now use the same `usageLimit`, `currentUsage`, and `remaining` fields as metered entitlements.
|
|
506
|
+
|
|
507
|
+
#### Hooks Return `Entitlement | null` Directly
|
|
508
|
+
|
|
509
|
+
All entitlement hooks now return the entitlement object directly (or `null`) instead of an `AsyncState` wrapper. Use the top-level `isLoading` and `error` from `useKelviq()` for loading/error states.
|
|
510
|
+
|
|
511
|
+
```ts
|
|
512
|
+
// Before
|
|
513
|
+
const { data, isLoading, error } = useMeteredEntitlement("my-feature");
|
|
514
|
+
if (isLoading) return ;
|
|
515
|
+
console.log(data?.used);
|
|
516
|
+
|
|
517
|
+
// After
|
|
518
|
+
const entitlement = useMeteredEntitlement("my-feature");
|
|
519
|
+
const { isLoading, error } = useKelviq();
|
|
520
|
+
if (isLoading) return ;
|
|
521
|
+
console.log(entitlement?.currentUsage);
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
#### `getEntitlement()` Simplified
|
|
525
|
+
|
|
526
|
+
The generic type parameter and second argument have been removed:
|
|
527
|
+
|
|
528
|
+
```ts
|
|
529
|
+
// Before
|
|
530
|
+
getEntitlement<MeteredEntitlement>("my-feature", "metered")
|
|
531
|
+
|
|
532
|
+
// After
|
|
533
|
+
getEntitlement("my-feature") // returns Entitlement | null
|
|
534
|
+
```
|
|
535
|
+
|
|
536
|
+
#### `hasAccess()` Returns `boolean` (Never `undefined`)
|
|
537
|
+
|
|
538
|
+
`hasAccess(featureId)` now returns `false` when data is unavailable instead of `undefined`. No need for nullish checks.
|
|
539
|
+
|
|
540
|
+
#### Metered Field Renames
|
|
541
|
+
|
|
542
|
+
| Before | After | Notes |
|
|
543
|
+
|---|---|---|
|
|
544
|
+
| `limit` | `usageLimit` | Aligned with the API |
|
|
545
|
+
| `used` | `currentUsage` | Aligned with the API |
|
|
546
|
+
| `resetAt` | _(removed)_ | Now per-item: `entitlement.items[].resetAt` |
|
|
547
|
+
| `hardLimit` | `hardLimit` | Now aggregated: `true` if any item sets it |
|
|
548
|
+
|
|
549
|
+
#### `allEntitlements.data` Shape Changed
|
|
550
|
+
|
|
551
|
+
The map is now keyed by `featureId` (previously `featureKey`) and contains unified `Entitlement` objects. Use the new `getEntitlements()` convenience method:
|
|
552
|
+
|
|
553
|
+
```ts
|
|
554
|
+
// Before
|
|
555
|
+
const { allEntitlements } = useKelviq();
|
|
556
|
+
const myFeature = allEntitlements.data?.["my-feature"]; // AnyEntitlement | undefined
|
|
557
|
+
|
|
558
|
+
// After
|
|
559
|
+
const { getEntitlements } = useKelviq();
|
|
560
|
+
const entitlements = getEntitlements(); // Record<string, Entitlement>
|
|
561
|
+
const myFeature = entitlements["my-feature"]; // Entitlement | undefined
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
---
|
|
565
|
+
|
|
566
|
+
### Migration Checklist
|
|
567
|
+
|
|
568
|
+
1. Replace all `featureKey` props/params with `featureId`
|
|
569
|
+
2. Replace `entitlement.type` with `entitlement.featureType` and update values to uppercase
|
|
570
|
+
3. Replace `useConfigEntitlement` with `useCustomizableEntitlement`
|
|
571
|
+
4. Replace `ShowWhenConfigEntitled` with `ShowWhenCustomizableEntitled`
|
|
572
|
+
5. Replace `ConfigEntitlement.configuration` with `usageLimit` / `currentUsage` / `remaining`
|
|
573
|
+
6. Update hook consumers: hooks now return `Entitlement | null` directly (not `AsyncState`)
|
|
574
|
+
7. Remove type parameters from `getEntitlement()` calls
|
|
575
|
+
8. Replace `limit` → `usageLimit`, `used` → `currentUsage`
|
|
576
|
+
9. Replace `entitlement.resetAt` with `entitlement.items[].resetAt`
|
|
577
|
+
10. Use `getEntitlements()` instead of `allEntitlements.data`
|
|
578
|
+
11. Use `getRawEntitlements()` for un-aggregated API data
|
|
579
|
+
|
|
580
|
+
</Update>
|