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