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