@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,80 @@
1
+ ---
2
+ title: "App"
3
+ slug: "changelog/app"
4
+ section: "changelog"
5
+ description: "Changelog for the Kelviq Dashboard"
6
+ ---
7
+ <Update label="v1.5" description="May 15, 2026">
8
+
9
+ ### Payments & Billing
10
+ - **UPI Payments Support** — You can now accept payments via UPI. Customers can pay seamlessly using their preferred UPI apps (like Google Pay, PhonePe, or Paytm).
11
+ - **Usage-Based Billing** — You can now bill customers based on their actual consumption. This provides maximum flexibility for products using credits, seats, or data metrics.
12
+
13
+ ### Customer Experience
14
+ - **Signed Customer Portal Links** — Added the option to generate and send a signed customer portal link directly from the order details page for secure, instant access.
15
+
16
+ ### Tax & Compliance
17
+ - **Tax Information** — Tax detail is added in transaction.
18
+ - **Tax Categories** — You can now define **Tax Categories** (B2B, B2C, Ebook, Online Course, etc.) during product creation.
19
+ - **Business Tax ID Support** — Control how valid business tax IDs are handled for tax-inclusive pricing. When enabled, Kelviq automatically removes the included tax amount from the checkout total if a customer provides a valid business tax ID during checkout. When disabled, customers continue paying the listed tax-inclusive price with no tax deduction applied.
20
+
21
+ </Update>
22
+
23
+ <Update label="v1.4" description="May 04, 2026">
24
+
25
+ ### Platform Improvements
26
+ - **Webhook Enhancements** — New webhook options in settings, including **Webhook Logs** for easier debugging and a new **Plan Changed** webhook event.
27
+ - **Analytics Refresh** — The analytics dashboard has a fresh new look for better data visualization and clarity.
28
+ - **Early Payout Access** — The Payouts tab is now enabled even before business verification is complete, allowing you to prepare your financial setup easily.
29
+
30
+ ### Fixes
31
+ - **File Uploads** — Resolved an issue that caused duplicate files to be created during multiple file uploads.
32
+
33
+ </Update>
34
+
35
+ <Update label="v1.3" description="April 22, 2026">
36
+
37
+ ### New Features
38
+ - **Promotions** — A new framework for managing promotional offers and campaigns directly within the dashboard.
39
+ - **Tax Information in Transactions** — Detailed tax breakdowns are now included in transaction records, providing full transparency for accounting.
40
+ - **Zapier Integration** — Connect Kelviq with thousands of other apps. Automate your workflow by triggering actions in external tools whenever a subscription or payment event occurs.
41
+
42
+ </Update>
43
+
44
+ <Update label="v1.2" description="April 10, 2026">
45
+
46
+ ### Improvements
47
+ - **Webhooks Foundation** — Added initial webhook configuration options within the settings menu to prepare for advanced automation.
48
+ - **Product UI Refinement** — The entire product card is now clickable for faster navigation, and we've added field validation for regional pricing minimum values.
49
+
50
+ </Update>
51
+
52
+ <Update label="v1.1" description="February 27, 2026">
53
+
54
+ ### New Features
55
+
56
+ - **Multiple subscriptions per customer** — Kelviq now supports customers having multiple active subscriptions. Use this to set up add-ons, credit packs, or top-ups alongside a base plan. Our SDKs automatically aggregate entitlements across all subscriptions, so your app always sees the correct combined usage and limits.
57
+ - **New Subscriptions page** — A dedicated page to view and manage all subscriptions in one place.
58
+ - **New Payout Details page** — View detailed breakdowns for individual payouts.
59
+ - **Transactions & Details page under Payouts** — Browse all payout transactions with a detail view for each entry.
60
+ - **Discount coupons on checkout URLs** — You can now attach discount coupons directly to checkout URLs, allowing you to share pre-discounted links with customers.
61
+ - **Block size 1 for package pricing** — Package pricing now supports a block size of 1, giving you more granular control over package-based plans.
62
+ - **Updated Publish modal UI** — The publish modal has been redesigned for a cleaner, more intuitive experience.
63
+
64
+ ### Improvements
65
+
66
+ - **Flat & package pricing for one-time charges** — Flat-rate and package pricing models are now available for one-time products, not just recurring plans.
67
+ - **Copy charge period on hover** — Hover over a charge period in the pricing section to quickly copy it to your clipboard.
68
+ - **Plan details page UI improvements** — The plan details page has been refreshed with a cleaner layout and better readability.
69
+ - **Improved refund error messages** — Refund errors now include clearer descriptions to help you understand what went wrong.
70
+ - **Improved Analytics UI** — The analytics dashboard has been updated with a more polished interface.
71
+ - **Download invoice in subscription detail page** — You can now download invoices directly from any subscription's detail page.
72
+ - **Cancel subscription from customer detail page** — Added the ability to cancel a customer's subscription directly from their detail page without navigating away.
73
+
74
+ ### Fixes
75
+
76
+ - **Entitlements override indicator** — Fixed an issue where entitlements were incorrectly shown as "overridden" in the UI when the values hadn't actually changed during feature copying.
77
+ - **Refund button disabled when not applicable** — The refund payment button is now correctly disabled when a payment has already been refunded or the subscription is in a trial period.
78
+ - **Billing info badge for one-time orders** — Fixed the billing info badge not appearing for one-time orders in the order list and detail pages.
79
+
80
+ </Update>
@@ -0,0 +1,59 @@
1
+ ---
2
+ title: "Checkout API"
3
+ slug: "changelog/checkout-api"
4
+ section: "changelog"
5
+ description: "Changelog for Checkout API"
6
+ ---
7
+ <Update label="Latest Updates" description="May 7, 2026">
8
+
9
+ ### New Features
10
+
11
+ #### Custom Dynamic Amount Support
12
+ Added support for custom dynamic amounts on the checkout page. You can now pass a specific `custom_amount` directly via the checkout API, which is ideal for usage-based, variable, or custom-quoted pricing models.
13
+
14
+ * **`custom_amount`**: The specific numeric amount to be charged to the customer. This overrides static plan pricing and is ideal for usage-based, variable, or custom-quoted pricing models.
15
+
16
+ * **`tax_behavior`**: Specifies how taxes should be applied to the custom amount. For example, setting it to "INCLUSIVE" means the tax is already factored into the custom_amount, while "EXCLUSIVE" would add the tax on top of the base amount.
17
+
18
+ * **`currency_code`**: The three-letter ISO currency code (e.g., "INR", "USD") that defines the currency in which the custom_amount should be processed.
19
+
20
+ ```json
21
+ {
22
+ "planIdentifier": "automatic-pricing",
23
+ "successUrl": "[https://www.kelviq.com/](https://www.kelviq.com/)",
24
+ "chargePeriod": "MONTHLY",
25
+ "customerId": "sam-altman0010",
26
+ "custom_amount": 1200,
27
+ "tax_behavior": "INCLUSIVE",
28
+ "currency_code": "INR"
29
+ }
30
+ ```
31
+
32
+ </Update>
33
+
34
+ <Update label="v2.1.0" description="May 7, 2026">
35
+
36
+ ### New Features
37
+
38
+ #### Enhanced Checkout Configuration
39
+ You can now pass additional configuration parameters when [creating a checkout session via the API](https://docs.kelviq.com/api-reference/checkout/create-a-checkout-session). These new fields allow for tighter control over the customer experience:
40
+
41
+ * **`lockEmail`**: When set to `true`, the email address field on the checkout page is disabled, preventing customers from changing the email associated with the session.
42
+ * **`discountsEnabled`**: A boolean to explicitly allow or disallow discount code application on the checkout page.
43
+ * **`defaultBillingCountry`**: Pre-fills the billing country field (e.g., `"IN"`).
44
+
45
+ **Example Payload:**
46
+
47
+ ```json
48
+ {
49
+ "planIdentifier": "base",
50
+ "successUrl": "[https://kelviq.com/checkout/success](https://kelviq.com/checkout/success)",
51
+ "chargePeriod": "MONTHLY",
52
+ "customerId": "sachin",
53
+ "lockEmail": true,
54
+ "discountsEnabled": false,
55
+ "defaultBillingCountry": "IN"
56
+ }
57
+ ```
58
+
59
+ </Update>
@@ -0,0 +1,14 @@
1
+ ---
2
+ title: "JS Promotions UI"
3
+ slug: "changelog/js-promotions-ui"
4
+ section: "changelog"
5
+ description: "Changelog for @kelviq/js-promotions-ui"
6
+ ---
7
+ <Update label="v0.0.4" description="May 7, 2026">
8
+
9
+ ### Changed
10
+
11
+ #### Close Icon Update
12
+ The close icon across all promotion UI components has been updated for better visibility and brand alignment. This change ensures a more consistent user experience when dismissing active promotions.
13
+
14
+ </Update>
@@ -0,0 +1,281 @@
1
+ ---
2
+ title: "JS SDK"
3
+ slug: "changelog/js-sdk"
4
+ section: "changelog"
5
+ description: "Changelog for @kelviq/js-sdk"
6
+ ---
7
+ <Update label="v2.1.0" description="May 9, 2026">
8
+ ### New Features
9
+
10
+ #### Product Offerings — Pricing API Support
11
+
12
+ The SDK can now fetch and display product pricing data. Pass a `productId` to the client to enable pricing methods.
13
+
14
+ ```ts
15
+ const client = kelviqSDK({
16
+ productId: 'your-product-id',
17
+ accessToken: 'your-access-token',
18
+ });
19
+ ```
20
+
21
+ If `customerId` is also set, it is forwarded to the pricing API so the response reflects that customer's subscription state.
22
+
23
+ ---
24
+
25
+ ##### `fetchPricing(forceRefresh?)` — Fetch and Cache Pricing
26
+
27
+ Fetches product offering data for the configured `productId`. Subsequent calls return the cached result unless `forceRefresh` is `true`.
28
+
29
+ ```ts
30
+ const pricing = await client.fetchPricing();
31
+ console.log(pricing.plans, pricing.currencyCode, pricing.billingPeriods);
32
+
33
+ await client.fetchPricing(true); // bypass cache
34
+ ```
35
+
36
+ ##### `getPricing()` — Read from Cache
37
+
38
+ Returns cached pricing data synchronously, or `null` if not yet fetched.
39
+
40
+ ```ts
41
+ const pricing = client.getPricing();
42
+ ```
43
+
44
+ ##### `getPlan(identifier)` — Look Up a Single Plan
45
+
46
+ Finds an enabled plan by identifier from the pricing cache. Returns `null` if not found or pricing hasn't been fetched.
47
+
48
+ ```ts
49
+ const plan = client.getPlan('pro-plan');
50
+ console.log(plan?.displayName, plan?.price.priceType);
51
+ ```
52
+
53
+ ##### `isPricingLoading()` — Loading State
54
+
55
+ Returns `true` while a pricing fetch is in progress.
56
+
57
+ ```ts
58
+ if (client.isPricingLoading()) { /* show spinner */ }
59
+ ```
60
+
61
+ ##### `getLastPricingError()` — Error State
62
+
63
+ Returns the last `Error` from a failed pricing fetch, or `null`.
64
+
65
+ ```ts
66
+ const err = client.getLastPricingError();
67
+ ```
68
+
69
+ ##### `clearPricingCache()` — Reset Cache
70
+
71
+ Clears cached pricing data and resets loading and error states.
72
+
73
+ ```ts
74
+ client.clearPricingCache();
75
+ ```
76
+
77
+ ---
78
+
79
+ ##### `renderPricing(options?)` — DOM Binding
80
+
81
+ Scans the DOM for elements with `data-kq-price` attributes and populates them with localized formatted prices. Requires pricing data to be fetched first.
82
+
83
+ ```html
84
+ <span data-kq-price="pro-plan" data-kq-period="MONTHLY">Loading...</span>
85
+ ```
86
+
87
+ ```ts
88
+ await client.fetchPricing();
89
+ client.renderPricing();
90
+
91
+ // Scope to a container
92
+ client.renderPricing({ container: document.getElementById('pricing-section') });
93
+
94
+ // With format options
95
+ client.renderPricing({ formatOptions: { compact: true } });
96
+ ```
97
+
98
+ | Attribute | Required | Description |
99
+ |---|---|---|
100
+ | `data-kq-price` | Yes | Plan identifier |
101
+ | `data-kq-period` | No | Billing period (e.g. `MONTHLY`, `YEARLY`). Falls back to the first available charge. |
102
+
103
+ ---
104
+
105
+ ##### `kqFormatPrice(amount, currencySymbol, options?)` — Price Formatter
106
+
107
+ Standalone named export for formatting a numeric amount with a currency symbol.
108
+
109
+ ```ts
110
+ import { kqFormatPrice } from '@kelviq/js-sdk';
111
+
112
+ kqFormatPrice(9.99, '$', { pricingLocale: 'en-US' }); // "$9.99"
113
+ kqFormatPrice(1200, '€', { compact: true, pricingLocale: 'de-DE' }); // "€1,2K"
114
+ kqFormatPrice(9.99, '$', { includeCurrencySymbol: false }); // "9.99"
115
+ ```
116
+
117
+ | Option | Type | Default | Description |
118
+ |---|---|---|---|
119
+ | `compact` | `boolean` | `false` | Use compact notation (e.g. `1.2K`) |
120
+ | `locale` | `string` | `pricingLocale` | Override locale for number formatting |
121
+ | `pricingLocale` | `string` | `'en-US'` | Locale from the pricing API |
122
+ | `includeCurrencySymbol` | `boolean` | `true` | Prepend the currency symbol |
123
+
124
+ ---
125
+
126
+ ##### New Types and Exports
127
+
128
+ ```ts
129
+ export { kqFormatPrice } from './formatPrice';
130
+ export type { KQFormatPriceOptions } from './formatPrice';
131
+ export type {
132
+ RawPricingFeature,
133
+ RawPricingCharge,
134
+ RawPricingPrice,
135
+ RawPricingPlan,
136
+ RawPricingBillingPeriod,
137
+ RawPricingApiResponse,
138
+ } from './types';
139
+ ```
140
+
141
+ </Update>
142
+
143
+ <Update label="v2.0.0" description="February 27, 2026">
144
+
145
+ ### New Features
146
+
147
+ #### Hybrid Aggregation Engine
148
+
149
+ If a customer has multiple subscriptions (e.g., a base plan + a top-up), the API may return duplicate `featureId` entries. The SDK now automatically aggregates them into a single `Entitlement` object per feature — no manual merging required.
150
+
151
+ **Aggregation rules:**
152
+
153
+ | Feature Type | `hasAccess` | `currentUsage` | `usageLimit` | `hardLimit` |
154
+ |---|---|---|---|---|
155
+ | **METER** | `true` if `remaining > 0` or unlimited | Summed | Summed | `true` if any item sets it |
156
+ | **BOOLEAN** | `true` if any item grants access | `0` | `null` | `false` |
157
+ | **CUSTOMIZABLE** | `true` if any item grants access | First item's value | First item's value | First item's value |
158
+
159
+ Per-item details (like `resetAt` and individual `hardLimit` values) are available on `entitlement.items[]`.
160
+
161
+ #### `getEntitlements()` — Fetch All Entitlements
162
+
163
+ Returns all aggregated entitlements as a map keyed by `featureId`. Replaces the old `getAllEntitlements()` method.
164
+
165
+ ```typescript
166
+ const entitlements = kq.getEntitlements();
167
+ // { "email-sends": Entitlement, "api-calls": Entitlement, ... }
168
+ ```
169
+
170
+ #### `getRawEntitlement(featureId)` — Raw Data for a Single Feature
171
+
172
+ Returns the un-aggregated raw API items for a specific `featureId`. Useful when you need per-subscription details.
173
+
174
+ ```typescript
175
+ const rawItems = kq.getRawEntitlement("email-sends");
176
+ // [{ featureId: 'email-sends', featureType: 'METER', hasAccess: true, ... }, ...]
177
+ ```
178
+
179
+ #### `getRawEntitlements()` — Full Raw API Response
180
+
181
+ Returns the complete raw API response including the `customerId` wrapper, before any aggregation.
182
+
183
+ ```typescript
184
+ const raw = kq.getRawEntitlements();
185
+ // { customerId: 'cust_123', entitlements: [...] }
186
+ ```
187
+
188
+ #### `ready()` — Wait for Initial Fetch
189
+
190
+ Returns a promise that resolves once the initial entitlement fetch completes. If `initializeAndFetch` was not set, resolves immediately.
191
+
192
+ ```typescript
193
+ const kq = kelviqSDK({
194
+ customerId: "cust_123",
195
+ accessToken: "your-access-token",
196
+ });
197
+
198
+ await kq.ready();
199
+ // Entitlements are now available
200
+ const emails = kq.getEntitlement("email-sends");
201
+ console.log(emails.hasAccess, emails.remaining);
202
+ ```
203
+
204
+ #### New Type Exports
205
+
206
+ `RawEntitlement` and `RawEntitlementsApiResponse` are now exported for consumers who need to type the raw API objects in their own code.
207
+
208
+ ---
209
+
210
+ ### Breaking Changes
211
+
212
+ #### Unified `Entitlement` Interface
213
+
214
+ The separate `BooleanEntitlement`, `ConfigEntitlement`, and `MeteredEntitlement` types have been replaced with a single, unified `Entitlement` interface:
215
+
216
+ ```typescript
217
+ interface Entitlement {
218
+ featureId: string;
219
+ featureType: "METER" | "BOOLEAN" | "CUSTOMIZABLE";
220
+ hasAccess: boolean; // true if at least one item grants access
221
+ hardLimit: boolean; // true if any item has hardLimit set
222
+ currentUsage: number; // SUM of all items' currentUsage (METER only)
223
+ usageLimit: number | null; // SUM of all items' usageLimit (METER only)
224
+ remaining: number | null; // usageLimit - currentUsage
225
+ items: RawEntitlement[]; // Original API objects for this featureId
226
+ }
227
+ ```
228
+
229
+ **Migration:** Replace all references to `BooleanEntitlement`, `ConfigEntitlement`, `MeteredEntitlement`, and `AnyEntitlement` with `Entitlement`.
230
+
231
+ #### `getEntitlement()` No Longer Accepts a Type Argument
232
+
233
+ The generic type parameter and second `type` argument have been removed. The SDK now determines the feature type automatically.
234
+
235
+ ```typescript
236
+ // Before
237
+ const emailQuota = kq.getEntitlement<MeteredEntitlement>("email-sends", "metered");
238
+ console.log(emailQuota.used, emailQuota.limit);
239
+
240
+ // After
241
+ const emailQuota = kq.getEntitlement("email-sends");
242
+ console.log(emailQuota.currentUsage, emailQuota.usageLimit);
243
+ ```
244
+
245
+ #### Renamed Fields
246
+
247
+ | Before | After | Notes |
248
+ |---|---|---|
249
+ | `used` | `currentUsage` | Aligned with the raw API field name |
250
+ | `limit` | `usageLimit` | Aligned with the raw API field name |
251
+ | `type` | `featureType` | Now uses uppercase API values (`"METER"`, `"BOOLEAN"`, `"CUSTOMIZABLE"`) |
252
+ | `configuration` | _(removed)_ | No longer surfaced at the top level |
253
+ | `resetAt` | _(removed)_ | Access via `entitlement.items[].resetAt` (may differ per subscription) |
254
+
255
+ #### Removed Exports
256
+
257
+ The following types are no longer exported:
258
+
259
+ - `BooleanEntitlement`, `ConfigEntitlement`, `MeteredEntitlement`, `AnyEntitlement`
260
+ - `EntitlementMap` is now `Record<string, Entitlement>` (no union type)
261
+
262
+ #### `getAllEntitlements()` Removed
263
+
264
+ Use `getEntitlements()` instead, which returns the aggregated map.
265
+
266
+ ---
267
+
268
+ ### Changed
269
+
270
+ - **`fetchAllEntitlements()` deduplicates concurrent calls** — Instead of rejecting with "already in progress", it returns the same in-flight promise. This makes `initializeAndFetch: true` safely composable with `await fetchAllEntitlements()`.
271
+ - **`fetchAllEntitlements()` stores raw data** — Now stores both the full raw API response and the aggregated cache internally.
272
+ - **`clearCache()` clears raw data** — Now also clears the stored raw API response.
273
+
274
+ ---
275
+
276
+ ### Fixed
277
+
278
+ - **`initializeAndFetch: false` was ignored** — The factory used `||` instead of `??`, so passing `false` had no effect and entitlements were always fetched on initialization. Fixed to use nullish coalescing (`??`).
279
+ - **Options table in documentation** — Filled in missing type values for `accessToken` (`string`) and `onError` (`(error: Error) => void`).
280
+
281
+ </Update>