@kelviq/mcp-server 0.2.3 → 0.4.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 (72) hide show
  1. package/README.md +26 -23
  2. package/dist/config.d.ts +9 -1
  3. package/dist/config.js +38 -7
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/api-reference/authentication.md +7 -3
  6. package/dist/docs/api-reference/introduction.md +143 -0
  7. package/dist/docs/backend-integration/node-sdk.md +148 -6
  8. package/dist/docs/backend-integration/python-sdk.md +195 -11
  9. package/dist/docs/changelog/api.md +119 -0
  10. package/dist/docs/changelog/app.md +693 -0
  11. package/dist/docs/changelog/mcp-server.md +61 -0
  12. package/dist/docs/changelog/node-sdk.md +153 -0
  13. package/dist/docs/changelog/python-sdk.md +182 -0
  14. package/dist/docs/cli/commands.md +225 -0
  15. package/dist/docs/cli/environments.md +95 -0
  16. package/dist/docs/cli/kelviq-config.md +141 -0
  17. package/dist/docs/cli/overview.md +223 -0
  18. package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
  19. package/dist/docs/guides/mcp-server.md +141 -194
  20. package/dist/docs/guides/sandbox.md +107 -0
  21. package/dist/docs/guides/webhooks.md +81 -0
  22. package/dist/docs/manifest.json +64 -8
  23. package/dist/docs/openapi.json +1206 -50
  24. package/dist/docs/product-catalog/one-time-payments.md +3 -1
  25. package/dist/docs/product-catalog/usage-based-billing.md +86 -7
  26. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  27. package/dist/prompts/index.d.ts +2 -0
  28. package/dist/prompts/index.js +107 -0
  29. package/dist/prompts/index.js.map +1 -0
  30. package/dist/schemas/kelviq.d.ts +30 -128
  31. package/dist/schemas/kelviq.js +50 -63
  32. package/dist/schemas/kelviq.js.map +1 -1
  33. package/dist/server.js +5 -2
  34. package/dist/server.js.map +1 -1
  35. package/dist/tools/checkout.js +2 -1
  36. package/dist/tools/checkout.js.map +1 -1
  37. package/dist/tools/customers.js +2 -0
  38. package/dist/tools/customers.js.map +1 -1
  39. package/dist/tools/docs.js +2 -0
  40. package/dist/tools/docs.js.map +1 -1
  41. package/dist/tools/entitlements.js +1 -0
  42. package/dist/tools/entitlements.js.map +1 -1
  43. package/dist/tools/features.js +4 -0
  44. package/dist/tools/features.js.map +1 -1
  45. package/dist/tools/index.js +0 -4
  46. package/dist/tools/index.js.map +1 -1
  47. package/dist/tools/licenses.js +3 -0
  48. package/dist/tools/licenses.js.map +1 -1
  49. package/dist/tools/offerings.js +1 -0
  50. package/dist/tools/offerings.js.map +1 -1
  51. package/dist/tools/plan-entitlements.js +4 -0
  52. package/dist/tools/plan-entitlements.js.map +1 -1
  53. package/dist/tools/plan-files.js +4 -1
  54. package/dist/tools/plan-files.js.map +1 -1
  55. package/dist/tools/plans.js +9 -15
  56. package/dist/tools/plans.js.map +1 -1
  57. package/dist/tools/portal.d.ts +11 -1
  58. package/dist/tools/portal.js +28 -2
  59. package/dist/tools/portal.js.map +1 -1
  60. package/dist/tools/product-files.js +2 -0
  61. package/dist/tools/product-files.js.map +1 -1
  62. package/dist/tools/product-settings.js +2 -0
  63. package/dist/tools/product-settings.js.map +1 -1
  64. package/dist/tools/products.js +6 -1
  65. package/dist/tools/products.js.map +1 -1
  66. package/dist/tools/promotions.js +1 -0
  67. package/dist/tools/promotions.js.map +1 -1
  68. package/dist/tools/subscriptions.js +6 -2
  69. package/dist/tools/subscriptions.js.map +1 -1
  70. package/dist/tools/usage.js +1 -0
  71. package/dist/tools/usage.js.map +1 -1
  72. package/package.json +5 -2
@@ -327,6 +327,8 @@ print(f"Checkout Session URL: {response.checkoutUrl}")
327
327
 
328
328
  * `defaultBillingCountry` (str): ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`) used to pre-fill the billing address country on the checkout page.
329
329
 
330
+ * `metadata` (dict): Arbitrary key-value pairs to attach to the checkout session. The keys are preserved exactly as supplied and the object is returned unchanged on the `checkout.completed` webhook's `metadata` field. Example: `{"order_ref": "ABC-123", "source": "pricing_page"}`.
331
+
330
332
  **Returns**:
331
333
 
332
334
  An instance of CreateCheckoutSessionResponse (Pydantic model), which includes:
@@ -653,7 +655,185 @@ An instance of ReportUsageResponse (Pydantic model), which includes:
653
655
 
654
656
  ## Subscriptions
655
657
 
656
- The subscriptions module allows you to manage customer subscriptions, including updates and cancellation. You can access these operations via the `subscriptions` attribute on an initialized Kelviq client instance.
658
+ The subscriptions module allows you to list, retrieve, create, update, and cancel customer subscriptions. You can access these operations via the `subscriptions` attribute on an initialized Kelviq client instance.
659
+
660
+ ### List subscriptions
661
+
662
+ Retrieves a paginated list of subscriptions for a customer.
663
+
664
+ **Synchronous:**
665
+
666
+ ```python
667
+ page = client.subscriptions.list(
668
+ customerId="cust_789",
669
+ page=1,
670
+ page_size=20,
671
+ )
672
+
673
+ for subscription in page.results:
674
+ print(subscription.id, subscription.status)
675
+ ```
676
+
677
+ **Asynchronous:**
678
+
679
+ ```python
680
+ page = await async_client.subscriptions.list(
681
+ customerId="cust_789",
682
+ page=1,
683
+ page_size=20,
684
+ )
685
+
686
+ for subscription in page.results:
687
+ print(subscription.id, subscription.status)
688
+ ```
689
+
690
+ ```json
691
+ {
692
+ "count": 1,
693
+ "next": null,
694
+ "previous": null,
695
+ "results": [
696
+ {
697
+ "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
698
+ "startDate": "2025-07-28",
699
+ "endDate": null,
700
+ "status": "active",
701
+ "trialDaysRemaining": 0,
702
+ "customerId": "cust_789",
703
+ "billingType": "SUBSCRIPTION",
704
+ "files": [],
705
+ "links": [],
706
+ "license": []
707
+ }
708
+ ]
709
+ }
710
+ ```
711
+
712
+ **Required Parameters:**
713
+
714
+ * `customerId` (str): The client-defined identifier of the customer whose subscriptions will be returned.
715
+
716
+ **Optional Parameters:**
717
+
718
+ * `page` (int): Page number to retrieve.
719
+ * `page_size` (int): Number of subscriptions to return per page.
720
+
721
+ **Returns:**
722
+
723
+ A `PaginatedSubscriptionResponse` containing `count`, `next`, `previous`, and a `results` list of `SubscriptionData` models.
724
+
725
+ ### Retrieve a subscription
726
+
727
+ Retrieves one subscription using its Kelviq subscription ID.
728
+
729
+ **Synchronous:**
730
+
731
+ ```python
732
+ subscription = client.subscriptions.retrieve(
733
+ subscriptionId="09d706ca-58f3-4fb2-818f-5b8623d67e6e",
734
+ )
735
+
736
+ print(subscription.id, subscription.status)
737
+ for file in subscription.files:
738
+ print(file.name, file.downloadUrl)
739
+ for link in subscription.links:
740
+ print(link.name, link.url)
741
+ for license in subscription.license:
742
+ print(license.licenseKey, license.activationLimit)
743
+ ```
744
+
745
+ **Asynchronous:**
746
+
747
+ ```python
748
+ subscription = await async_client.subscriptions.retrieve(
749
+ subscriptionId="09d706ca-58f3-4fb2-818f-5b8623d67e6e",
750
+ )
751
+
752
+ print(subscription.id, subscription.status)
753
+ ```
754
+
755
+ ```json
756
+ {
757
+ "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
758
+ "externalSubscriptionId": "sub_1RpoZoSBstCzyocS7iPmith3",
759
+ "startDate": "2025-07-28",
760
+ "endDate": null,
761
+ "billingPeriodStartTime": "2025-07-28T10:46:34Z",
762
+ "billingPeriodEndTime": "2025-08-28T10:46:34Z",
763
+ "amount": "261.00",
764
+ "recurrence": "month",
765
+ "currency": "usd",
766
+ "status": "active",
767
+ "trialDaysRemaining": 0,
768
+ "customerId": "cust_789",
769
+ "billingType": "SUBSCRIPTION",
770
+ "recurrenceUnit": 1,
771
+ "recurrenceType": "MONTH",
772
+ "files": [],
773
+ "links": [],
774
+ "license": []
775
+ }
776
+ ```
777
+
778
+ **Required Parameters:**
779
+
780
+ * `subscriptionId` (str): The Kelviq UUID of the subscription.
781
+
782
+ **Returns:**
783
+
784
+ A `SubscriptionData` model. A missing subscription raises `NotFoundError`.
785
+
786
+ ### Create a subscription
787
+
788
+ Creates a subscription directly for a customer without requiring a checkout session.
789
+
790
+ **Synchronous:**
791
+
792
+ ```python
793
+ from kelviq_sdk import ChargePeriod
794
+
795
+ subscription = client.subscriptions.create(
796
+ planIdentifier="plan-pro-monthly",
797
+ chargePeriod=ChargePeriod.MONTHLY,
798
+ customerId="cust_789",
799
+ successUrl="https://example.com/subscription/success",
800
+ features=[{"identifier": "seats", "quantity": 5}],
801
+ ipAddress="103.154.35.20",
802
+ )
803
+
804
+ print(subscription.id, subscription.status)
805
+ ```
806
+
807
+ **Asynchronous:**
808
+
809
+ ```python
810
+ subscription = await async_client.subscriptions.create(
811
+ planIdentifier="plan-pro-monthly",
812
+ chargePeriod="MONTHLY",
813
+ customerId="cust_789",
814
+ successUrl="https://example.com/subscription/success",
815
+ features=[{"identifier": "seats", "quantity": 5}],
816
+ ipAddress="103.154.35.20",
817
+ )
818
+
819
+ print(subscription.id, subscription.status)
820
+ ```
821
+
822
+ **Required Parameters:**
823
+
824
+ * `planIdentifier` (str): Identifier of the plan to subscribe to.
825
+ * `chargePeriod` (str | ChargePeriod): Billing period such as `MONTHLY`, `YEARLY`, `WEEKLY`, or `DAILY`.
826
+ * `customerId` (str): Client-defined identifier of the customer.
827
+
828
+ **Optional Parameters:**
829
+
830
+ * `successUrl` (str): URL to redirect to after successful subscription creation.
831
+ * `features` (List[Dict[str, Any]]): Feature identifiers and requested quantities.
832
+ * `ipAddress` (str): Customer IP address used for location-based pricing.
833
+
834
+ **Returns:**
835
+
836
+ A `CreateSubscriptionResponse` model containing the created subscription, including its plan files, links, and issued licenses when available.
657
837
 
658
838
  ### Updates an existing subscription to a new plan
659
839
 
@@ -686,7 +866,8 @@ try:
686
866
  ruleId="rule_ghi",
687
867
  ipAddress="103.154.35.20",
688
868
  features=[{'identifier': "seats", 'quantity': 10}],
689
- trialEnd="2025-12-31 23:59:59" # or "now" to end the trial immediately
869
+ trialEnd="2027-12-31 23:59:59", # or "now" to end the trial immediately
870
+ paymentBehavior="activate_on_payment",
690
871
  )
691
872
  print(response.subscriptionId)
692
873
  except Exception as e:
@@ -724,8 +905,9 @@ except Exception as e:
724
905
  * Example: `[{'identifier': 'seats', 'quantity': 10}, {'identifier': 'projects', 'quantity': 5}]`
725
906
  * `trialEnd` (str): Optional. Controls the trial period for the updated subscription. Accepts either:
726
907
  * The literal string `"now"` to end any active trial immediately.
727
- * 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.
908
+ * An ISO 8601 datetime string (e.g. `"2027-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.
728
909
  * If omitted, the existing trial behavior on the subscription is preserved.
910
+ * `paymentBehavior` (`Literal["activate_on_payment"]`): Optional. Set to `"activate_on_payment"` to keep the current subscription active while payment is pending. The new plan and features are applied only after payment succeeds. If the pending update expires, the current subscription remains unchanged. Omit this field to use the default immediate-update behavior.
729
911
 
730
912
  **Returns**:
731
913
 
@@ -1067,7 +1249,7 @@ All methods are available in both synchronous and asynchronous versions, dependi
1067
1249
  ### Creates a new customer portal session
1068
1250
 
1069
1251
  `create_session(...)`
1070
- This operation creates a new portal session for a customer, returning a pre-authenticated URL that you can redirect them to.
1252
+ This operation creates a new portal session for a customer. Combine the returned `customerPortalUrl` and `token` into a signed link (`{customerPortalUrl}?token={token}`) and redirect the customer there.
1071
1253
 
1072
1254
  **Synchronous**:
1073
1255
 
@@ -1075,8 +1257,10 @@ This operation creates a new portal session for a customer, returning a pre-auth
1075
1257
  session = client.portal.create_session(
1076
1258
  customerId="cust_789",
1077
1259
  )
1078
- # Redirect your customer to the portal
1079
- print(f"Portal URL: {session.customerPortalUrl}")
1260
+ # Build the signed portal link — customerPortalUrl alone does not
1261
+ # authenticate; the token must be appended as a query parameter.
1262
+ portal_link = f"{session.customerPortalUrl}?token={session.token}"
1263
+ print(f"Portal URL: {portal_link}")
1080
1264
  ```
1081
1265
 
1082
1266
  **Asynchronous**:
@@ -1085,15 +1269,15 @@ print(f"Portal URL: {session.customerPortalUrl}")
1085
1269
  session = await async_client.portal.create_session(
1086
1270
  customerId="cust_789",
1087
1271
  )
1088
- # Redirect your customer to the portal
1089
- print(f"Portal URL: {session.customerPortalUrl}")
1272
+ portal_link = f"{session.customerPortalUrl}?token={session.token}"
1273
+ print(f"Portal URL: {portal_link}")
1090
1274
  ```
1091
1275
 
1092
1276
  ```json
1093
1277
  {
1094
- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
1278
+ "token": "cpt-4f7c5dc4-da9f-447b-d447-6266dc35ed6d:23fca530-adeb-4685-b3d5-9928c6d38275",
1095
1279
  "email": "customer@example.com",
1096
- "customerPortalUrl": "https://portal.kelviq.com/session/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
1280
+ "customerPortalUrl": "https://www.kelviq.com/portal/aphelo/"
1097
1281
  }
1098
1282
  ```
1099
1283
 
@@ -1107,7 +1291,7 @@ An instance of `CreatePortalSessionResponse` (Pydantic model), which includes:
1107
1291
 
1108
1292
  * `token` (str): The session token that authenticates the customer portal session.
1109
1293
  * `email` (str): The email address of the customer.
1110
- * `customerPortalUrl` (str): The URL to redirect the customer to their customer portal. This link is pre-authenticated — no login required.
1294
+ * `customerPortalUrl` (str): The customer's billing portal base URL. **This URL alone does not authenticate the session** — append the `token` as a query parameter (`{customerPortalUrl}?token={token}`) to produce the signed link you share with the customer. The token expires, so create a fresh session per visit.
1111
1295
 
1112
1296
  ---
1113
1297
  ## Webhooks
@@ -0,0 +1,119 @@
1
+ ---
2
+ title: "API"
3
+ slug: "changelog/api"
4
+ section: "changelog"
5
+ description: "Changelog for the Kelviq API"
6
+ ---
7
+ <Update label="v1.3.1" description="July 21, 2026">
8
+
9
+ ### New Features
10
+
11
+ #### Activate Subscription Updates After Payment
12
+
13
+ `POST /subscriptions/{subscriptionId}/update/` now accepts the optional `paymentBehavior` field. Set it to `activate_on_payment` to keep the customer's current subscription active while payment for the change is pending.
14
+
15
+ ```json
16
+ {
17
+ "planIdentifier": "premium-plan",
18
+ "chargePeriod": "MONTHLY",
19
+ "paymentBehavior": "activate_on_payment"
20
+ }
21
+ ```
22
+
23
+ The new plan, billing period, and feature changes are applied only after payment succeeds. If the pending update expires before payment is completed, the current subscription remains unchanged. Omitting `paymentBehavior` preserves the existing immediate-update behavior.
24
+
25
+ </Update>
26
+
27
+ <Update label="v1.3.0" description="July 16, 2026">
28
+
29
+ ### New Features
30
+
31
+ #### List, Create, and Retrieve Refunds
32
+
33
+ The Refunds API now supports the complete refund workflow:
34
+
35
+ - **`GET /refunds/` — List refunds**: Returns a paginated list of refunds for the authenticated organization, with search, status, date-range, and pagination filters.
36
+ - **`POST /refunds/` — Create a refund**: Creates a full or partial refund for an order. Provide `amountUnits` or `amount` for a partial refund, or omit both to refund the remaining balance.
37
+ - **`GET /refunds/{refundId}/` — Retrieve a refund**: Returns a refund by its Kelviq UUID.
38
+
39
+ Create requests use `orderId` to identify the order. List results, newly created refunds, and retrieved refunds share the same response format, including the refund amount, reason, status, failure details, internal note, and associated order.
40
+
41
+ </Update>
42
+
43
+ <Update label="v1.2.0" description="July 14, 2026">
44
+
45
+ ### New Features
46
+
47
+ #### Subscription List, Create, and Retrieve APIs
48
+
49
+ The Subscriptions API now includes three new endpoints for reading and creating subscriptions:
50
+
51
+ - **`GET /subscriptions/` — List subscriptions**: Retrieves a paginated list for a customer. The `customer_id` query parameter is required.
52
+ - **`POST /subscriptions/create/` — Create a subscription**: Creates a subscription directly for a customer without requiring a checkout session.
53
+ - **`GET /subscriptions/{subscriptionId}/` — Retrieve a subscription**: Retrieves a subscription by its Kelviq UUID.
54
+
55
+ Subscription list, create, and retrieve responses now include:
56
+
57
+ - `files` — downloadable files attached to the subscription's plan.
58
+ - `links` — external links attached to the plan.
59
+ - `license` — issued licenses associated with the subscription.
60
+
61
+ #### One-Time Charges
62
+
63
+ The new `POST /charges/` endpoint immediately charges a customer's saved payment method without creating a checkout session. The `chargePeriod` must be `ONE_TIME`.
64
+
65
+ </Update>
66
+
67
+ <Update label="v1.1.0" description="May 7, 2026">
68
+
69
+ ### New Features
70
+
71
+ #### Enhanced Checkout Configuration
72
+ 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:
73
+
74
+ * **`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.
75
+ * **`discountsEnabled`**: A boolean to explicitly allow or disallow discount code application on the checkout page.
76
+ * **`defaultBillingCountry`**: Pre-fills the billing country field (e.g., `"IN"`).
77
+
78
+ **Example Payload:**
79
+
80
+ ```json
81
+ {
82
+ "planIdentifier": "base",
83
+ "successUrl": "[https://kelviq.com/checkout/success](https://kelviq.com/checkout/success)",
84
+ "chargePeriod": "MONTHLY",
85
+ "customerId": "sachin",
86
+ "lockEmail": true,
87
+ "discountsEnabled": false,
88
+ "defaultBillingCountry": "IN"
89
+ }
90
+ ```
91
+
92
+ </Update>
93
+
94
+ <Update label="v1.0.0" description="May 7, 2026">
95
+
96
+ ### New Features
97
+
98
+ #### Custom Dynamic Amount Support
99
+ 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.
100
+
101
+ * **`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.
102
+
103
+ * **`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.
104
+
105
+ * **`currency_code`**: The three-letter ISO currency code (e.g., "INR", "USD") that defines the currency in which the custom_amount should be processed.
106
+
107
+ ```json
108
+ {
109
+ "planIdentifier": "automatic-pricing",
110
+ "successUrl": "[https://www.kelviq.com/](https://www.kelviq.com/)",
111
+ "chargePeriod": "MONTHLY",
112
+ "customerId": "sam-altman0010",
113
+ "custom_amount": 1200,
114
+ "tax_behavior": "INCLUSIVE",
115
+ "currency_code": "INR"
116
+ }
117
+ ```
118
+
119
+ </Update>