@kelviq/mcp-server 1.0.0 → 1.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 (46) hide show
  1. package/README.md +25 -7
  2. package/dist/docs/README.md +16 -0
  3. package/dist/docs/backend-integration/node-sdk.md +41 -17
  4. package/dist/docs/backend-integration/python-sdk.md +16 -17
  5. package/dist/docs/changelog.md +4076 -0
  6. package/dist/docs/cli/commands.md +140 -5
  7. package/dist/docs/cli/environments.md +3 -3
  8. package/dist/docs/cli/kelviq-config.md +28 -7
  9. package/dist/docs/cli/overview.md +11 -9
  10. package/dist/docs/guides/agent-toolkit.md +3 -3
  11. package/dist/docs/guides/mcp-server.md +36 -5
  12. package/dist/docs/guides/webhooks.md +1 -1
  13. package/dist/docs/manifest.json +5 -61
  14. package/dist/docs/product-catalog/free-and-trials.md +13 -0
  15. package/dist/docs/product-catalog/license-keys.md +13 -0
  16. package/dist/http/client.d.ts +7 -0
  17. package/dist/http/client.js +9 -0
  18. package/dist/http/client.js.map +1 -1
  19. package/dist/prompts/index.js +11 -11
  20. package/dist/prompts/index.js.map +1 -1
  21. package/dist/schemas/kelviq.d.ts +200 -0
  22. package/dist/schemas/kelviq.js +178 -3
  23. package/dist/schemas/kelviq.js.map +1 -1
  24. package/dist/server.js +2 -0
  25. package/dist/server.js.map +1 -1
  26. package/dist/tools/_resolve.d.ts +4 -0
  27. package/dist/tools/_resolve.js +46 -0
  28. package/dist/tools/_resolve.js.map +1 -0
  29. package/dist/tools/connection.d.ts +12 -0
  30. package/dist/tools/connection.js +44 -0
  31. package/dist/tools/connection.js.map +1 -0
  32. package/dist/tools/discounts.d.ts +3 -0
  33. package/dist/tools/discounts.js +86 -0
  34. package/dist/tools/discounts.js.map +1 -0
  35. package/dist/tools/index.js +7 -0
  36. package/dist/tools/index.js.map +1 -1
  37. package/dist/tools/offerings.js +6 -2
  38. package/dist/tools/offerings.js.map +1 -1
  39. package/dist/tools/plan-entitlements.js +11 -3
  40. package/dist/tools/plan-entitlements.js.map +1 -1
  41. package/dist/tools/plans.js +6 -2
  42. package/dist/tools/plans.js.map +1 -1
  43. package/dist/tools/webhooks.d.ts +10 -0
  44. package/dist/tools/webhooks.js +114 -0
  45. package/dist/tools/webhooks.js.map +1 -0
  46. package/package.json +1 -1
package/README.md CHANGED
@@ -13,7 +13,7 @@ capabilities at once:
13
13
  inside the package and exposed as MCP resources plus `docs_search` /
14
14
  `docs_read` tools, so the LLM can ground its answers in the canonical docs.
15
15
 
16
- > **45 tools** across **9 domains**, plus a resource for every docs page and
16
+ > **57 tools** across **12 domains**, plus a resource for every docs page and
17
17
  > the full OpenAPI spec. Works offline for docs Q&A — only API tools require a
18
18
  > key.
19
19
 
@@ -114,6 +114,14 @@ precedence over `KELVIQ_ENV`.
114
114
 
115
115
  ## Tools
116
116
 
117
+ Tools that take a product or feature reference (`plan_create`,
118
+ `plan_entitlements_add`, `discount_create`, `offering_get_product`) accept
119
+ either the UUID or the human-readable identifier; identifiers are resolved
120
+ through the retrieve endpoints before anything is written.
121
+
122
+ ### Connection
123
+ - `connection_check` — reports the environment (env, base/edge URLs) and whether the server key is accepted, without printing it
124
+
117
125
  ### Customers
118
126
  - `customer_create` — create a customer
119
127
  - `customer_update` — patch an existing customer
@@ -134,9 +142,17 @@ precedence over `KELVIQ_ENV`.
134
142
  - `usage_report` — report metered usage (`SET` or `DELTA`)
135
143
 
136
144
  ### Offerings & Promotions
137
- - `offering_get_product` — public pricing scoped to a product UUID
145
+ - `offering_get_product` — public pricing scoped to a product (UUID or identifier)
138
146
  - `promotion_get` — resolve the active promotion for the caller's location *(uses Client API key, edge host)*
139
147
 
148
+ ### Discounts
149
+ - `discount_list` / `discount_create` (`appliesTo[].product` takes a UUID or identifier) / `discount_retrieve` / `discount_archive`
150
+ - `discount_update` — enable or disable a code (nothing else can change after creation)
151
+
152
+ ### Webhooks
153
+ - `webhook_endpoint_list` / `webhook_endpoint_create` / `webhook_endpoint_retrieve` / `webhook_endpoint_update` / `webhook_endpoint_delete` — signing secrets are hidden unless `revealSecret: true`
154
+ - `webhook_log_list` — delivery attempts from the last 30 days
155
+
140
156
  ### Catalog: Products
141
157
  - `product_list` / `product_create` / `product_retrieve` / `product_update` / `product_archive`
142
158
  - `product_settings_get` / `product_settings_update` — VPN/Tor/proxy policy, default currency, product URL
@@ -146,11 +162,11 @@ precedence over `KELVIQ_ENV`.
146
162
  - `feature_list` / `feature_create` / `feature_retrieve` / `feature_archive`
147
163
 
148
164
  ### Catalog: Plans
149
- - `plan_list` / `plan_create` / `plan_retrieve` / `plan_update` / `plan_archive`
165
+ - `plan_list` / `plan_create` (`product` takes a UUID or identifier) / `plan_retrieve` / `plan_update` / `plan_archive`
150
166
  - `plan_publish` — release the latest draft, optionally migrate existing customers
151
167
  - `plan_discard_draft` — drop the current draft, keep the published version
152
168
  - `plan_prices_list` — per-currency pricing on a plan
153
- - `plan_entitlements_list` / `plan_entitlements_add` / `plan_entitlement_update` / `plan_entitlement_delete`
169
+ - `plan_entitlements_list` / `plan_entitlements_add` (`feature` takes a UUID or identifier) / `plan_entitlement_update` / `plan_entitlement_delete`
154
170
  - `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
155
171
 
156
172
  ### Docs (no API key required)
@@ -172,7 +188,7 @@ Once wired into your MCP client, try prompts like:
172
188
 
173
189
  - *"Search Kelviq docs for license keys"* → `docs_search` + `docs_read`
174
190
  - *"List my Kelviq products"* → `product_list`
175
- - *"Create a plan named 'Pro Monthly' under product UUID `…`, then publish it"* → `plan_create` → `plan_publish`
191
+ - *"Create a plan named 'Pro Monthly' under product `acme-app`, then publish it"* → `plan_create` → `plan_publish`
176
192
  - *"What entitlements does customer `acme-42` have for `seats`?"* → `entitlements_get`
177
193
  - *"Create a checkout session for plan `pro-monthly`, success URL `https://example.com/ok`"* → `checkout_create_session`
178
194
  - *"What prices are configured on plan `pro-monthly`?"* → `plan_prices_list`
@@ -189,7 +205,7 @@ npx -y @modelcontextprotocol/inspector \
189
205
  npx -y @kelviq/mcp-server@latest
190
206
  ```
191
207
 
192
- Opens a browser UI where you can browse all 45 tools, fill in arguments, and
208
+ Opens a browser UI where you can browse all 57 tools, fill in arguments, and
193
209
  run them against the real Kelviq API. Pre-fill env vars by exporting them
194
210
  before the command:
195
211
 
@@ -238,7 +254,9 @@ PATH. Either:
238
254
  ### Tool returns `{"error": {"status": "Configuration error", …}}`
239
255
 
240
256
  Means a required env var is missing. The error message names which one. Set
241
- it in your MCP client config and reconnect.
257
+ it in your MCP client config and reconnect. Ask the LLM to run
258
+ `connection_check` to see which environment the server is using and whether
259
+ the server key is accepted — it never prints the key.
242
260
 
243
261
  ### API tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
244
262
 
@@ -120,6 +120,22 @@ To contribute to Kelviq docs:
120
120
  - Link to related documentation
121
121
  - Keep sections concise and focused
122
122
 
123
+ ### Changelog
124
+
125
+ All release notes live in one page, `changelog.mdx`, newest first. Add each release as an `<Update>` at the top of the page, tagged with the product exactly as it appears in the filter. The product filter above the entries matches on that tag, and so does the sidebar:
126
+
127
+ ```mdx
128
+ <Update label="v2.9.0" description="October 1, 2026" tags={["Node SDK"]}>
129
+ ...
130
+ </Update>
131
+ ```
132
+
133
+ Keep the label a plain string; an expression label loses its anchor link. Products are `App`, `JS SDK`, `React SDK`, `Node SDK`, `Python SDK`, `JS Promotions UI`, `MCP Server`, `CLI`, and `API`.
134
+
135
+ The sidebar lists the same products, as anchors under the Changelog tab in `docs.json`. They must be written as absolute URLs (`https://docs.kelviq.com/changelog#node-sdk`): Mintlify rewrites a relative href containing a hash to `/`. Absolute URLs would open in a new tab, so `ChangelogFilter` rewrites them back to same-page links once the page loads. To add a product, add it in three places: the `products` list passed to `<ChangelogFilter>`, the anchors in `docs.json`, and the redirect if the product had its own page before.
136
+
137
+ Those anchors would otherwise carry an icon and no group title, so `custom.css` hides the icon, heads the list with "Changelog", and highlights whichever product is selected. Those rules only apply while `ChangelogFilter` is on screen, which it marks with `data-changelog-page` on the body.
138
+
123
139
  ## Need Help?
124
140
 
125
141
  - **Can't find something?** - Use the search feature (top of page)
@@ -1506,25 +1506,38 @@ app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
1506
1506
 
1507
1507
  Use `express.raw()` (not `express.json()`) so that the raw request body is preserved for signature verification. Parsing the body as JSON before verification will break the signature check.
1508
1508
 
1509
+ On a framework built on the Fetch API — Next.js route handlers, Hono, Remix, SvelteKit, Cloudflare Workers — `request.headers` is a `Headers` object, not a plain object. Convert it with `Object.fromEntries`, and read the body with `request.text()` so it stays unparsed:
1510
+
1511
+ ```typescript
1512
+ import { validateEvent, WebhookVerificationError } from '@kelviq/node-sdk';
1513
+
1514
+ export async function POST(request: Request) {
1515
+ const body = await request.text();
1516
+
1517
+ try {
1518
+ const event = validateEvent(
1519
+ body,
1520
+ Object.fromEntries(request.headers),
1521
+ process.env.KELVIQ_WEBHOOK_SECRET!,
1522
+ );
1523
+
1524
+ console.log('Event type:', event.type);
1525
+
1526
+ return new Response(null, { status: 202 });
1527
+ } catch (err) {
1528
+ if (err instanceof WebhookVerificationError) {
1529
+ return new Response(null, { status: 403 });
1530
+ }
1531
+ throw err;
1532
+ }
1533
+ }
1534
+ ```
1535
+
1536
+ Passing a `Headers` object straight to `validateEvent` fails with `Missing required webhook headers`, because the helper reads headers as plain object entries.
1537
+
1509
1538
  ### Webhook event types
1510
1539
 
1511
- | Event | Description |
1512
- |---|---|
1513
- | `checkout.completed` | A checkout session was completed |
1514
- | `customer.created` | A new customer was created |
1515
- | `customer.updated` | A customer's details were updated |
1516
- | `order.created` | A new order was placed |
1517
- | `order.updated` | An order was updated |
1518
- | `order.refunded` | An order was refunded |
1519
- | `subscription.created` | A new subscription was created |
1520
- | `subscription.updated` | A subscription was updated |
1521
- | `subscription.cancelled` | A subscription was cancelled |
1522
- | `subscription.plan_changed` | A subscription plan was changed |
1523
- | `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
1524
- | `invoice.created` | A new invoice was created |
1525
- | `invoice.paid` | An invoice was paid |
1526
- | `refund.created` | A refund was initiated |
1527
- | `refund.updated` | A refund status changed |
1540
+ See [Webhook event types](/guides/webhooks#event-types) for the complete list of supported events and their descriptions.
1528
1541
 
1529
1542
  ### Best practices
1530
1543
 
@@ -1547,4 +1560,15 @@ const client = new Kelviq({
1547
1560
 
1548
1561
  ```
1549
1562
 
1563
+ To pick the environment from the `KELVIQ_ENV` variable that the Kelviq CLI and MCP server also read, use `environmentFromEnv()`: it returns `'sandbox'` when `KELVIQ_ENV` is unset or empty, `'production'` or `'sandbox'` when it is set to one of those, and throws on any other value.
1564
+
1565
+ ```typescript
1566
+ import { Kelviq, environmentFromEnv } from '@kelviq/node-sdk';
1567
+
1568
+ const client = new Kelviq({
1569
+ accessToken: process.env.KELVIQ_SERVER_API_KEY!,
1570
+ environment: environmentFromEnv(), // reads KELVIQ_ENV: sandbox when unset
1571
+ });
1572
+ ```
1573
+
1550
1574
  The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.
@@ -1774,23 +1774,7 @@ Always pass the **raw** request body (e.g. `request.data` in Flask) to `validate
1774
1774
 
1775
1775
  ### Webhook event types
1776
1776
 
1777
- | Event | Description |
1778
- |---|---|
1779
- | `checkout.completed` | A checkout session was completed |
1780
- | `customer.created` | A new customer was created |
1781
- | `customer.updated` | A customer's details were updated |
1782
- | `order.created` | A new order was placed |
1783
- | `order.updated` | An order was updated |
1784
- | `order.refunded` | An order was refunded |
1785
- | `subscription.created` | A new subscription was created |
1786
- | `subscription.updated` | A subscription was updated |
1787
- | `subscription.cancelled` | A subscription was cancelled |
1788
- | `subscription.plan_changed` | A subscription plan was changed |
1789
- | `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
1790
- | `invoice.created` | A new invoice was created |
1791
- | `invoice.paid` | An invoice was paid |
1792
- | `refund.created` | A refund was initiated |
1793
- | `refund.updated` | A refund status changed |
1777
+ See [Webhook event types](/guides/webhooks#event-types) for the complete list of supported events and their descriptions.
1794
1778
 
1795
1779
  ### Best practices
1796
1780
 
@@ -1816,5 +1800,20 @@ client = Kelviq.create_sync_client(
1816
1800
  environment="sandbox"
1817
1801
  )
1818
1802
  ```
1803
+ ### Reading the environment from `KELVIQ_ENV`
1804
+
1805
+ `environment_from_env()` turns the `KELVIQ_ENV` convention shared with the Kelviq CLI and MCP server into the `environment` argument: `"sandbox"` when the variable is unset or empty, `"production"` or `"sandbox"` when it is set to one of those, and a `ValueError` naming any other value.
1806
+
1807
+ ```python
1808
+ import os
1809
+ from kelviq_sdk import Kelviq, environment_from_env
1810
+
1811
+ client = Kelviq.create_sync_client(
1812
+ access_token=os.environ["KELVIQ_SERVER_API_KEY"],
1813
+ environment=environment_from_env(), # reads KELVIQ_ENV: sandbox when unset
1814
+ )
1815
+ ```
1816
+
1817
+ `environment="production"` and `environment="prod"` mean the same thing.
1819
1818
 
1820
1819
  The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.