@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,456 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Python SDK"
|
|
3
|
+
slug: "changelog/python-sdk"
|
|
4
|
+
section: "changelog"
|
|
5
|
+
description: "Changelog for kelviq-sdk (Python)"
|
|
6
|
+
---
|
|
7
|
+
<Update label="v2.5.0" description="May 10, 2026">
|
|
8
|
+
|
|
9
|
+
### New Features
|
|
10
|
+
|
|
11
|
+
#### Subscription Update — `trialEnd` Parameter
|
|
12
|
+
|
|
13
|
+
`subscriptions.update()` now accepts an optional `trialEnd` parameter to control the trial period when updating a subscription.
|
|
14
|
+
|
|
15
|
+
Pass either:
|
|
16
|
+
|
|
17
|
+
- The literal string `"now"` to end any active trial immediately.
|
|
18
|
+
- An ISO 8601 datetime string (e.g. `"2025-12-31 23:59:59"`) to set a new trial end date. The datetime must be in the future. Naive datetimes are interpreted as UTC.
|
|
19
|
+
- Omit the parameter to preserve the existing trial behavior on the subscription.
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
# End the trial now
|
|
23
|
+
response = client.subscriptions.update(
|
|
24
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
25
|
+
planIdentifier="premium-plan",
|
|
26
|
+
chargePeriod="MONTHLY",
|
|
27
|
+
trialEnd="now",
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
# Extend the trial to a specific future date
|
|
31
|
+
response = client.subscriptions.update(
|
|
32
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
33
|
+
planIdentifier="premium-plan",
|
|
34
|
+
chargePeriod="MONTHLY",
|
|
35
|
+
trialEnd="2025-12-31 23:59:59",
|
|
36
|
+
)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
**Async variant:**
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
response = await async_client.subscriptions.update(
|
|
43
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
44
|
+
planIdentifier="premium-plan",
|
|
45
|
+
chargePeriod="MONTHLY",
|
|
46
|
+
trialEnd="2025-12-31 23:59:59",
|
|
47
|
+
)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The SDK validates `trialEnd` client-side — invalid datetime strings or past datetimes raise `InvalidRequestError` before the request is sent.
|
|
51
|
+
|
|
52
|
+
</Update>
|
|
53
|
+
|
|
54
|
+
<Update label="v2.4.0" description="May 4, 2026">
|
|
55
|
+
|
|
56
|
+
### New Features
|
|
57
|
+
|
|
58
|
+
#### Checkout Session — New Optional Parameters
|
|
59
|
+
|
|
60
|
+
Three new optional parameters on `checkout.create_session()` give you more control over the hosted checkout page.
|
|
61
|
+
|
|
62
|
+
**`discounts_enabled`** — controls whether the coupon/discount code field is shown. Defaults to `True` on the server.
|
|
63
|
+
|
|
64
|
+
**`lock_email`** — when `True`, the email field is pre-filled and locked so the customer cannot change it. Defaults to `False`.
|
|
65
|
+
|
|
66
|
+
**`default_billing_country`** — ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`) used to pre-fill the billing address country field.
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
response = client.checkout.create_session(
|
|
70
|
+
planIdentifier="plan-pro-monthly",
|
|
71
|
+
chargePeriod="MONTHLY",
|
|
72
|
+
customerId="cust_789",
|
|
73
|
+
successUrl="https://example.com/success",
|
|
74
|
+
discountsEnabled=False,
|
|
75
|
+
lockEmail=True,
|
|
76
|
+
defaultBillingCountry="US",
|
|
77
|
+
)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**Async variant:**
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
response = await async_client.checkout.create_session(
|
|
84
|
+
planIdentifier="plan-pro-monthly",
|
|
85
|
+
chargePeriod="MONTHLY",
|
|
86
|
+
customerId="cust_789",
|
|
87
|
+
successUrl="https://example.com/success",
|
|
88
|
+
discountsEnabled=False,
|
|
89
|
+
lockEmail=True,
|
|
90
|
+
defaultBillingCountry="US",
|
|
91
|
+
)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
</Update>
|
|
95
|
+
|
|
96
|
+
<Update label="v2.3.0" description="April 25, 2026">
|
|
97
|
+
|
|
98
|
+
### New Features
|
|
99
|
+
|
|
100
|
+
#### Webhook Verification
|
|
101
|
+
|
|
102
|
+
A new `validate_event` helper lets you securely verify incoming webhook requests from Kelviq in one step. It validates the HMAC-SHA256 signature using the three headers Kelviq attaches to every webhook delivery, then returns the parsed event dictionary.
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from flask import Flask, request
|
|
106
|
+
from kelviq_sdk import validate_event, WebhookVerificationError
|
|
107
|
+
|
|
108
|
+
app = Flask(__name__)
|
|
109
|
+
|
|
110
|
+
@app.route('/webhook', methods=['POST'])
|
|
111
|
+
def webhook():
|
|
112
|
+
try:
|
|
113
|
+
event = validate_event(
|
|
114
|
+
payload=request.data,
|
|
115
|
+
headers=request.headers,
|
|
116
|
+
secret='<YOUR_WEBHOOK_SECRET>',
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
# Process the event
|
|
120
|
+
print('Event type:', event.get('type'))
|
|
121
|
+
|
|
122
|
+
return "", 202
|
|
123
|
+
except WebhookVerificationError as e:
|
|
124
|
+
return "", 403
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**`validate_event(payload, headers, secret)`**
|
|
128
|
+
|
|
129
|
+
- `payload` — Raw request body as `bytes` or `str`. Must be the unparsed body — do not pass a pre-parsed dictionary.
|
|
130
|
+
- `headers` — Any mapping of header name to value (e.g. `request.headers` in Flask). Header lookup is case-insensitive.
|
|
131
|
+
- `secret` — Your webhook signing secret (`kq_whsec_...`) from the Kelviq dashboard.
|
|
132
|
+
|
|
133
|
+
Returns the parsed event as `Dict[str, Any]`. Raises `WebhookVerificationError` if a required header is missing, the signature format is invalid, or the signature does not match.
|
|
134
|
+
|
|
135
|
+
#### `WebhookVerificationError`
|
|
136
|
+
|
|
137
|
+
New exception class raised by `validate_event` when verification fails. Extends `Exception`.
|
|
138
|
+
|
|
139
|
+
</Update>
|
|
140
|
+
|
|
141
|
+
<Update label="v2.2.0" description="April 13, 2026">
|
|
142
|
+
|
|
143
|
+
### New Features
|
|
144
|
+
|
|
145
|
+
#### License Management Module
|
|
146
|
+
|
|
147
|
+
A new `client.license` module provides full lifecycle management for software licenses. All methods are available in both synchronous and asynchronous clients.
|
|
148
|
+
|
|
149
|
+
**`license.activate(licenseKey, customerId?, instanceName?, metadata?)`**
|
|
150
|
+
|
|
151
|
+
Activates a license key and creates a new instance. Returns a `LicenseActivateResponse` (Pydantic model) containing the `instanceId`, `activatedAt`, `expiresOn`, and the full `LicenseDetails` object.
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
response = client.license.activate(
|
|
155
|
+
licenseKey="LIC-XXXX-YYYY-ZZZZ",
|
|
156
|
+
customerId="cust_789",
|
|
157
|
+
instanceName="My MacBook Pro",
|
|
158
|
+
metadata={"os": "macOS", "arch": "arm64"},
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
print(response.instanceId)
|
|
162
|
+
print(response.license.activationUsage) # e.g. 1
|
|
163
|
+
print(response.license.plan.product.name) # e.g. "Kelviq Engine"
|
|
164
|
+
print(response.license.subscription.billingType) # "SUBSCRIPTION"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
**`license.deactivate(licenseKey, instanceId)`**
|
|
168
|
+
|
|
169
|
+
Deactivates a specific license instance. Returns a `LicenseDeactivateResponse` with `message` and `deactivatedAt`.
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
response = client.license.deactivate(
|
|
173
|
+
licenseKey="LIC-XXXX-YYYY-ZZZZ",
|
|
174
|
+
instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
|
|
175
|
+
)
|
|
176
|
+
print(response.message) # "License instance deactivated successfully."
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
**`license.validate(licenseKey, instanceId?)`**
|
|
180
|
+
|
|
181
|
+
Validates a license key and optionally a specific instance. Returns a `LicenseValidateResponse` with `valid`, `code`, `detail`, `metadata`, and the full `LicenseDetails`.
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
response = client.license.validate(
|
|
185
|
+
licenseKey="LIC-XXXX-YYYY-ZZZZ",
|
|
186
|
+
instanceId="8f3e2b1a-5c6d-4e9f-8a0b-1c2d3e4f5g6h",
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
if response.valid:
|
|
190
|
+
print(f"Valid — code: {response.code}")
|
|
191
|
+
else:
|
|
192
|
+
print(f"Invalid — {response.detail}")
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
#### New Pydantic Models
|
|
196
|
+
|
|
197
|
+
- **`LicenseDetails`** — Full license object with `id`, `licenseKey`, `activatedOn`, `expiresOn`, `activationUsage`, `activationLimit`, `enabled`, `customer`, `plan`, and `subscription`.
|
|
198
|
+
- **`LicenseCustomer`** — `customerId`, `name`, `email` nested within `LicenseDetails`.
|
|
199
|
+
- **`LicensePlan`** — Expanded with `description`, `version`, `isLatest`, and `product` (nested `LicensePlanProduct` model).
|
|
200
|
+
- **`LicensePlanProduct`** — `id`, `identifier`, `name`, `taxCode`, `createdOn`, `modifiedOn`.
|
|
201
|
+
- **`LicenseActivateResponse`**, **`LicenseDeactivateResponse`**, **`LicenseValidateResponse`** — Typed Pydantic response models for each operation.
|
|
202
|
+
|
|
203
|
+
#### `SubscriptionData` New Fields
|
|
204
|
+
|
|
205
|
+
Three new fields derived from the subscription's `recurrence` string are now included in `SubscriptionData` (returned within `LicenseDetails.subscription` and customer subscription summaries):
|
|
206
|
+
|
|
207
|
+
- **`billingType`** — `"SUBSCRIPTION"` if the plan has a recurrence, `"ONE_TIME"` otherwise.
|
|
208
|
+
- **`recurrenceUnit`** — Integer unit from the recurrence string (e.g. `1` from `"1 month"`), or `None`.
|
|
209
|
+
- **`recurrenceType`** — Recurrence period in uppercase (e.g. `"MONTH"`), or `None`.
|
|
210
|
+
|
|
211
|
+
</Update>
|
|
212
|
+
|
|
213
|
+
<Update label="v2.1.0" description="April 2, 2026">
|
|
214
|
+
|
|
215
|
+
### New Features
|
|
216
|
+
|
|
217
|
+
#### Customer Portal Module
|
|
218
|
+
|
|
219
|
+
A new `client.portal` module lets you create pre-authenticated customer portal sessions server-side and redirect customers directly to their self-serve portal. Available on both synchronous and asynchronous clients.
|
|
220
|
+
|
|
221
|
+
**`portal.create_session(customerId)`**
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
session = client.portal.create_session(customerId="cust_789")
|
|
225
|
+
|
|
226
|
+
# Redirect your customer — no login required
|
|
227
|
+
print(session.customerPortalUrl)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
**Async variant:**
|
|
231
|
+
|
|
232
|
+
```python
|
|
233
|
+
session = await async_client.portal.create_session(customerId="cust_789")
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Returns `CreatePortalSessionResponse` (Pydantic model) with:
|
|
237
|
+
|
|
238
|
+
- `token` (str) — Session token authenticating the portal session.
|
|
239
|
+
- `email` (str) — The customer's email address.
|
|
240
|
+
- `customerPortalUrl` (str) — Pre-authenticated URL to redirect the customer to.
|
|
241
|
+
|
|
242
|
+
</Update>
|
|
243
|
+
|
|
244
|
+
<Update label="v2.0.0" description="February 27, 2026">
|
|
245
|
+
|
|
246
|
+
### New Features
|
|
247
|
+
|
|
248
|
+
#### Entitlements Aggregation Engine
|
|
249
|
+
|
|
250
|
+
When a customer has multiple active subscriptions, the API can return duplicate `featureId` entries. The SDK now automatically aggregates them into a single `Entitlement` model while preserving the raw data.
|
|
251
|
+
|
|
252
|
+
```python
|
|
253
|
+
entitlement = client.entitlements.get_entitlement("cust_123", "email-sends")
|
|
254
|
+
|
|
255
|
+
# Aggregated values across all subscriptions
|
|
256
|
+
print(entitlement.hasAccess) # True
|
|
257
|
+
print(entitlement.usageLimit) # 1500 (e.g., 1000 from base + 500 from top-up)
|
|
258
|
+
print(entitlement.currentUsage) # 200
|
|
259
|
+
print(entitlement.remaining) # 1300
|
|
260
|
+
|
|
261
|
+
# Per-subscription details
|
|
262
|
+
for item in entitlement.items:
|
|
263
|
+
print(item.usageLimit, item.resetAt)
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
**Aggregation rules:**
|
|
267
|
+
|
|
268
|
+
| Field | Aggregation Strategy |
|
|
269
|
+
|---|---|
|
|
270
|
+
| `hasAccess` | `True` if **any** raw entry grants access |
|
|
271
|
+
| `usageLimit` | **Summed** across all entries (for `METER` feature types) |
|
|
272
|
+
| `currentUsage` | **Summed** across all entries (for `METER` feature types) |
|
|
273
|
+
| `remaining` | Computed as `usageLimit - currentUsage` |
|
|
274
|
+
| `hardLimit` | `True` if **any** entry has a hard limit |
|
|
275
|
+
|
|
276
|
+
> **Note:** `resetAt` is intentionally **not** aggregated at the top level because each subscription item can have a different reset date. Access individual reset dates via `entitlement.items[i].resetAt`.
|
|
277
|
+
|
|
278
|
+
#### New `Entitlement` Pydantic Model
|
|
279
|
+
|
|
280
|
+
A new model representing an aggregated entitlement:
|
|
281
|
+
|
|
282
|
+
- `featureId`, `featureType`, `hasAccess`, `hardLimit`, `usageLimit`, `currentUsage`, `remaining`
|
|
283
|
+
- `items: List[EntitlementDetail]` — the raw entries that were aggregated into this model
|
|
284
|
+
|
|
285
|
+
#### `get_entitlements(customerId)` — All Entitlements as a Map
|
|
286
|
+
|
|
287
|
+
Returns a `Dict[str, Entitlement]` keyed by `featureId`. Each value is an aggregated model with an `.items` list containing the original raw entries.
|
|
288
|
+
|
|
289
|
+
```python
|
|
290
|
+
entitlements = client.entitlements.get_entitlements("cust_123")
|
|
291
|
+
|
|
292
|
+
for feature_id, entitlement in entitlements.items():
|
|
293
|
+
print(f"{feature_id}: hasAccess={entitlement.hasAccess}, remaining={entitlement.remaining}")
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
#### `get_raw_entitlement(customerId, featureId)` — Raw API Response for a Feature
|
|
297
|
+
|
|
298
|
+
Returns the raw API response (`CheckEntitlementsResponse`) for a specific feature without any aggregation.
|
|
299
|
+
|
|
300
|
+
```python
|
|
301
|
+
raw = client.entitlements.get_raw_entitlement("cust_123", "email-sends")
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
#### `get_raw_entitlements(customerId)` — Full Raw API Response
|
|
305
|
+
|
|
306
|
+
Returns the raw API response for all entitlements without any aggregation.
|
|
307
|
+
|
|
308
|
+
```python
|
|
309
|
+
raw = client.entitlements.get_raw_entitlements("cust_123")
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
#### Enum Helpers for IDE Autocompletion
|
|
313
|
+
|
|
314
|
+
New `str`-based `Enum` classes:
|
|
315
|
+
|
|
316
|
+
- **`ChargePeriod`** — `ONE_TIME`, `MONTHLY`, `YEARLY`, `WEEKLY`, `DAILY`, `THREE_MONTHS`, `SIX_MONTHS`
|
|
317
|
+
- **`CancellationType`** — `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, `SPECIFIC_DATE`
|
|
318
|
+
|
|
319
|
+
```python
|
|
320
|
+
from kelviq_sdk import ChargePeriod, CancellationType
|
|
321
|
+
|
|
322
|
+
response = client.checkout.create_session(
|
|
323
|
+
planIdentifier="pro-plan",
|
|
324
|
+
chargePeriod=ChargePeriod.MONTHLY,
|
|
325
|
+
successUrl="https://example.com/success"
|
|
326
|
+
)
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Raw string values (e.g., `"MONTHLY"`) continue to work everywhere — fully backward-compatible.
|
|
330
|
+
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
### Changed
|
|
334
|
+
|
|
335
|
+
- **`get_entitlement(customerId, featureId)`** now returns `Optional[Entitlement]` (aggregated) instead of raw `CheckEntitlementsResponse`. Use `get_raw_entitlement()` for the original response.
|
|
336
|
+
- **`get_all_entitlements` removed** — Use `get_entitlements()` instead.
|
|
337
|
+
- **`resetAt` removed from top-level `Entitlement`** — Access individual reset dates via the `.items` list.
|
|
338
|
+
|
|
339
|
+
</Update>
|
|
340
|
+
|
|
341
|
+
<Update label="v1.1.0" description="February 27, 2026">
|
|
342
|
+
|
|
343
|
+
### New Features
|
|
344
|
+
|
|
345
|
+
#### Entitlements Aggregation Engine
|
|
346
|
+
|
|
347
|
+
When a customer has multiple active subscriptions, the API can return duplicate `featureId` entries. The SDK now automatically aggregates them into a single `Entitlement` model while preserving the raw data.
|
|
348
|
+
|
|
349
|
+
```python
|
|
350
|
+
entitlement = client.entitlements.get_entitlement("cust_123", "email-sends")
|
|
351
|
+
|
|
352
|
+
# Aggregated values across all subscriptions
|
|
353
|
+
print(entitlement.has_access) # True
|
|
354
|
+
print(entitlement.usage_limit) # 1500 (e.g., 1000 from base + 500 from top-up)
|
|
355
|
+
print(entitlement.current_usage) # 200
|
|
356
|
+
print(entitlement.remaining) # 1300
|
|
357
|
+
|
|
358
|
+
# Per-subscription details
|
|
359
|
+
for item in entitlement.items:
|
|
360
|
+
print(item.usage_limit, item.reset_at)
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
**Aggregation rules:**
|
|
364
|
+
|
|
365
|
+
| Field | Aggregation Strategy |
|
|
366
|
+
|---|---|
|
|
367
|
+
| `hasAccess` | `True` if **any** raw entry grants access |
|
|
368
|
+
| `usageLimit` | **Summed** across all entries (for `METER` feature types) |
|
|
369
|
+
| `currentUsage` | **Summed** across all entries (for `METER` feature types) |
|
|
370
|
+
| `remaining` | Computed as `usageLimit - currentUsage` |
|
|
371
|
+
| `hardLimit` | `True` if **any** entry has a hard limit |
|
|
372
|
+
|
|
373
|
+
> **Note:** `resetAt` is intentionally **not** aggregated at the top level because each subscription item can have a different reset date. Access individual reset dates via `entitlement.items[i].resetAt`.
|
|
374
|
+
|
|
375
|
+
#### New `Entitlement` Pydantic Model
|
|
376
|
+
|
|
377
|
+
A new model representing an aggregated entitlement:
|
|
378
|
+
|
|
379
|
+
- `featureId`, `featureType`, `hasAccess`, `hardLimit`, `usageLimit`, `currentUsage`, `remaining`
|
|
380
|
+
- `items: List[EntitlementDetail]` — the raw entries that were aggregated into this model
|
|
381
|
+
|
|
382
|
+
#### `get_entitlements(customerId)` — All Entitlements as a Map
|
|
383
|
+
|
|
384
|
+
Returns a `Dict[str, Entitlement]` keyed by `featureId`. Each value is an aggregated model with an `.items` list containing the original raw entries.
|
|
385
|
+
|
|
386
|
+
```python
|
|
387
|
+
entitlements = client.entitlements.get_entitlements("cust_123")
|
|
388
|
+
|
|
389
|
+
for feature_id, entitlement in entitlements.items():
|
|
390
|
+
print(f"{feature_id}: hasAccess={entitlement.has_access}, remaining={entitlement.remaining}")
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
#### `get_raw_entitlement(customerId, featureId)` — Raw API Response for a Feature
|
|
394
|
+
|
|
395
|
+
Returns the raw API response (`CheckEntitlementsResponse`) for a specific feature without any aggregation. Includes the `customerId` wrapper.
|
|
396
|
+
|
|
397
|
+
```python
|
|
398
|
+
raw = client.entitlements.get_raw_entitlement("cust_123", "email-sends")
|
|
399
|
+
# CheckEntitlementsResponse with customerId wrapper
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
#### `get_raw_entitlements(customerId)` — Full Raw API Response
|
|
403
|
+
|
|
404
|
+
Returns the raw API response for all entitlements without any aggregation.
|
|
405
|
+
|
|
406
|
+
```python
|
|
407
|
+
raw = client.entitlements.get_raw_entitlements("cust_123")
|
|
408
|
+
# CheckEntitlementsResponse with customerId wrapper and all raw entries
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
#### Enum Helpers for IDE Autocompletion
|
|
412
|
+
|
|
413
|
+
New `str`-based `Enum` classes that improve developer experience with IDE autocompletion and prevent typos:
|
|
414
|
+
|
|
415
|
+
- **`ChargePeriod`** — `ONE_TIME`, `MONTHLY`, `YEARLY`, `WEEKLY`, `DAILY`, `THREE_MONTHS`, `SIX_MONTHS`
|
|
416
|
+
- **`CancellationType`** — `IMMEDIATE`, `CURRENT_PERIOD_ENDS`, `SPECIFIC_DATE`
|
|
417
|
+
|
|
418
|
+
```python
|
|
419
|
+
from kelviq_sdk import ChargePeriod, CancellationType
|
|
420
|
+
|
|
421
|
+
# With enums — IDE autocompletion and typo prevention
|
|
422
|
+
response = client.checkout.create_session(
|
|
423
|
+
planIdentifier="pro-plan",
|
|
424
|
+
chargePeriod=ChargePeriod.MONTHLY,
|
|
425
|
+
successUrl="https://example.com/success"
|
|
426
|
+
)
|
|
427
|
+
|
|
428
|
+
# Cancel with enum
|
|
429
|
+
client.subscriptions.cancel(
|
|
430
|
+
subscriptionId="sub_123",
|
|
431
|
+
cancellationType=CancellationType.CURRENT_PERIOD_ENDS,
|
|
432
|
+
)
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
Raw string values (e.g., `"MONTHLY"`) continue to work everywhere — the enums are fully backward-compatible.
|
|
436
|
+
|
|
437
|
+
---
|
|
438
|
+
|
|
439
|
+
### Changed
|
|
440
|
+
|
|
441
|
+
- **`get_entitlement(customerId, featureId)`** now returns `Optional[Entitlement]` (aggregated) instead of raw `CheckEntitlementsResponse`. Use `get_raw_entitlement()` if you need the original response.
|
|
442
|
+
- **`get_all_entitlements` removed** — Use `get_entitlements()` instead, which returns a `Dict[str, Entitlement]` keyed by `featureId`.
|
|
443
|
+
- **`resetAt` removed from top-level `Entitlement`** — Access individual reset dates via the `.items` list.
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
### Fixed
|
|
448
|
+
|
|
449
|
+
- Removed invalid JavaScript-style comments (`// Server-generated UUID`) from JSON response blocks in documentation.
|
|
450
|
+
- Fixed `//` comments to `#` comments in Python code snippets.
|
|
451
|
+
- Fixed trailing comma in Checkout response JSON block.
|
|
452
|
+
- Fixed typo: "newly created customer" → "**updated** customer" in `customers.update` return description.
|
|
453
|
+
- Removed placeholder text from "Supported Functionalities" section.
|
|
454
|
+
- Updated entitlements description to explain multi-subscription aggregation and the `items` attribute.
|
|
455
|
+
|
|
456
|
+
</Update>
|