@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,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>