@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
@@ -6,6 +6,13 @@ description: "Every Kelviq CLI command, flag by flag."
6
6
  ---
7
7
  All commands support `--help`. The CLI targets your **sandbox** environment unless you pass `--prod` — see [Environments & authentication](/cli/environments).
8
8
 
9
+ Every command reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory before it runs, so a project's env file works without exporting anything. A variable already set in your shell always wins. Two global flags control this:
10
+
11
+ | Flag | Description |
12
+ |---|---|
13
+ | `--env-file <path>` | Read this dotenv file instead of `.env.local`/`.env`. Repeat it for several files; a missing file is an error. |
14
+ | `--no-env-file` | Don't read any env file. |
15
+
9
16
  Output is colorized on interactive terminals (green creates, yellow updates, red archives) and automatically plain when piped. Disable colors explicitly with the global `--no-color` flag or the `NO_COLOR` environment variable.
10
17
 
11
18
  ---
@@ -15,17 +22,24 @@ Output is colorized on interactive terminals (green creates, yellow updates, red
15
22
  Writes a starter `kelviq.config.ts` to the current directory.
16
23
 
17
24
  ```shell
18
- kelviq init
25
+ kelviq init # the saas template
26
+ kelviq init --template usage # metered usage with an overage price
27
+ kelviq init --template license # a plan that issues license keys
19
28
  kelviq init -o pricing/kelviq.config.ts
20
29
  kelviq init --force
21
30
  ```
22
31
 
23
32
  | Flag | Description |
24
33
  |---|---|
34
+ | `--template <name>` | Which starter catalog to write: `saas` (default), `usage`, or `license`. |
25
35
  | `-o, --output <path>` | Where to write the file. Defaults to `kelviq.config.ts` in the current directory. |
26
36
  | `--force` | Overwrite the file if it already exists. Without it, `init` refuses rather than clobbering your edits. |
27
37
 
28
- The starter file defines one product, one feature, and one plan using the typed builders from `@kelviq/cli/config` — see the [format reference](/cli/kelviq-config).
38
+ Each template is a complete catalog that `kelviq push` accepts as written, using the typed builders from `@kelviq/cli/config` — see the [format reference](/cli/kelviq-config):
39
+
40
+ - **`saas`** — a product with a free plan and a Pro plan billed monthly or yearly, gating a boolean feature and a configurable limit.
41
+ - **`usage`** — a `METER` feature with the details the API requires, a free plan with a hard monthly allowance, and a Pro plan with an included quantity plus a tiered pay-as-you-go overage price.
42
+ - **`license`** — a Pro plan whose orders issue license keys valid on up to three devices.
29
43
 
30
44
  ---
31
45
 
@@ -79,22 +93,37 @@ Removing a key locally does not revoke it. To revoke a key, delete it from the [
79
93
 
80
94
  ## kelviq env
81
95
 
82
- Shows which environment and keys the CLI is configured with. Read-only — it never calls the API.
96
+ Shows which environment and keys the CLI is configured with, and which env files it read.
83
97
 
84
98
  ```shell
85
99
  kelviq env
100
+ kelviq env --check
86
101
  ```
87
102
 
88
103
  ```text
89
104
  Environment : sandbox (default — use --prod to target production)
105
+ KELVIQ_ENV : unset (sandbox) — unprefixed KELVIQ_* vars apply to sandbox
90
106
  Sandbox URL : https://sandboxapi.kelviq.com/api/v1
91
107
  Prod URL : https://api.kelviq.com/api/v1
92
108
  Sandbox key : set
93
109
  Prod key : missing
94
110
  Org : unknown — Kelviq has no key-introspection endpoint yet
111
+ Env files : /path/to/app/.env.local (KELVIQ_SERVER_API_KEY, KELVIQ_ENV)
95
112
  ```
96
113
 
97
- Key rows show `set` or `missing` only — `env` reports what's configured locally and does not validate keys against the API. `kelviq env --json` emits the same report as JSON (never any part of a key's value).
114
+ | Flag | Description |
115
+ |---|---|
116
+ | `--check` | Make one authenticated read per configured key and report whether the API accepted it. |
117
+ | `--json` | Machine-readable output. Never includes any part of a key's value. |
118
+
119
+ Without `--check`, key rows show `set` or `missing` only and nothing is sent to the API. With `--check`, each configured key gets one `GET /catalog/products/` call against its own environment's host and a result line:
120
+
121
+ ```text
122
+ Sandbox check : ok
123
+ Prod check : skipped (no key configured)
124
+ ```
125
+
126
+ `ok` means the key was accepted. `rejected` (HTTP 401 or 403) almost always means the key belongs to the other environment. The command exits non-zero when any configured key fails, or when no key is configured, so a script or agent can gate on it. `--check --json` adds `sandboxCheck` and `prodCheck` objects (`{ ok, status, httpStatus?, message? }`) to the JSON document.
98
127
 
99
128
  ---
100
129
 
@@ -173,7 +202,11 @@ Push stamps a `managed-by: kelviq-cli` entry into the `metadata` of every featur
173
202
 
174
203
  A plan **with** a `prices` array in config always pushes that complete array, replacing the plan's entire remote price set. A plan **without** a `prices` key never touches remote prices at all. Omitting `prices` means "leave pricing alone," not "this plan is free."
175
204
 
176
- If you hand-author prices, set `freeTrial`, `trialPeriod`, `enabled`, and `taxBehavior` explicitly. Omitting them makes your price compare unequal to the server's stored defaults forever, so every push re-replaces that plan's prices (harmless but noisy — each one drafts the plan again). Configs generated by `kelviq pull` don't have this problem.
205
+ Prices are compared on the fields your config sets. A field you omit — `freeTrial`, `taxBehavior`, a charge's `paymentType` or `reset` — is left to the server's default and never counts as a difference, so a hand-authored price diffs clean after its first push.
206
+
207
+ ### METER features are checked before anything is written
208
+
209
+ The API rejects a `METER` feature created without `featureDetails` (`featureSubType` and `units`). Push checks for this while building the plan and stops before any write, naming the feature and the shape to add — see [feature()](/cli/kelviq-config#feature).
177
210
 
178
211
  ### Features can't be updated — by design
179
212
 
@@ -223,3 +256,105 @@ kelviq promote # then do it
223
256
  ```
224
257
 
225
258
  Promotion is one-way — sandbox to production. There is no reverse mode.
259
+
260
+ ---
261
+
262
+ ## kelviq status
263
+
264
+ Shows the live catalog of an environment without writing a config file: products, features, and the latest version of every plan with its price and entitlement counts. Read-only — the check to run after a push to confirm what landed.
265
+
266
+ ```shell
267
+ kelviq status
268
+ kelviq status --prod
269
+ kelviq status --json
270
+ ```
271
+
272
+ ```text
273
+ Environment : sandbox
274
+
275
+ Products (1)
276
+ my-app My App
277
+
278
+ Features (2)
279
+ api-calls METER API calls
280
+ history-retention CUSTOMIZABLE History retention (days)
281
+
282
+ Plans (2)
283
+ free Free product my-app · v1 · 1 price · 1 entitlement · visible
284
+ pro Pro product my-app · v2 · 1 price · 2 entitlements · visible · license keys
285
+ ```
286
+
287
+ | Flag | Description |
288
+ |---|---|
289
+ | `--prod` | Read production instead of sandbox. |
290
+ | `--json` | Emit `{ environment, products, features, plans }`, each plan as `{ identifier, name, product, version, isLatest, isVisible, prices, entitlements, licenseKeys }`. |
291
+
292
+ A plan with no prices is flagged, since it can't be bought. The API reports a plan's version number rather than a draft/published state, so that's what `status` shows.
293
+
294
+ ---
295
+
296
+ ## kelviq webhook
297
+
298
+ Registers the app's webhook endpoint and gets the signing secret into the app's env file without it ever appearing on screen.
299
+
300
+ ```shell
301
+ kelviq webhook list
302
+ kelviq webhook add https://app.example.com/api/kelviq/webhooks \
303
+ --events checkout.completed,subscription.created,subscription.updated,subscription.cancelled,invoice.payment_failed \
304
+ --write-secret .env.local
305
+ ```
306
+
307
+ ### kelviq webhook add
308
+
309
+ | Flag | Description |
310
+ |---|---|
311
+ | `<url>` | The public https URL that receives events. Localhost and private addresses are rejected by the API. |
312
+ | `--events <list>` | Comma-separated event types — see the [event list](/guides/webhooks#event-types). Required. |
313
+ | `--write-secret <file>` | Write the signing secret into this dotenv file, replacing or appending a `KELVIQ_WEBHOOK_SECRET=` line. The value is never printed. |
314
+ | `--variable <name>` | Variable name to write instead of `KELVIQ_WEBHOOK_SECRET`. |
315
+ | `--print-secret` | Print the secret to stdout instead. Off by default. |
316
+ | `--prod` | Target production instead of sandbox. |
317
+ | `--yes` | Skip the confirmation prompt (required in non-interactive sessions). |
318
+ | `--json` | Machine-readable output. The endpoint's `secret` is always `[hidden]` unless `--print-secret` is passed. |
319
+
320
+ `add` is idempotent on the URL: an endpoint that already exists for the same URL is reused instead of registered twice, and its events are extended when the ones you pass aren't all covered. With neither `--write-secret` nor `--print-secret`, the secret stays hidden and the output tells you how to get it.
321
+
322
+ ### kelviq webhook list
323
+
324
+ Lists endpoints with their URL, state, id and events. Secrets are never shown. `--prod` and `--json` as above.
325
+
326
+ ---
327
+
328
+ ## kelviq discount
329
+
330
+ Creates and lists discount codes. Only enabling or disabling a code can change after creation, so `create` restates everything and asks before writing.
331
+
332
+ ```shell
333
+ kelviq discount list
334
+ kelviq discount create --name "Launch offer" --code LAUNCH20 --percent 20 \
335
+ --duration repeating --months 3 --product my-app --plans pro-monthly
336
+ kelviq discount create --name "Ten off" --code TENOFF --amount 10 --currency USD
337
+ ```
338
+
339
+ ### kelviq discount create
340
+
341
+ | Flag | Description |
342
+ |---|---|
343
+ | `--name <text>` | Shown on the customer's invoice. Required. |
344
+ | `--code <CODE>` | What customers enter at checkout: uppercase letters and digits. Required. |
345
+ | `--percent <n>` | Percentage off, 1–100. Exactly one of `--percent` or `--amount`. |
346
+ | `--amount <x>` | Fixed amount off in normal currency units; needs `--currency`. |
347
+ | `--currency <code>` | ISO currency code for `--amount`. |
348
+ | `--duration <once\|repeating\|forever>` | How long the discount applies. Default `once`. |
349
+ | `--months <n>` | With `--duration repeating`: how many **billing periods** it applies for. Not calendar months — `3` on a yearly plan is three years, so scope a "first 3 months" code to monthly plans. |
350
+ | `--product <identifier>` | Limit the code to one product, by identifier or UUID. The CLI resolves the identifier to the UUID the API wants. |
351
+ | `--plans <list>` | With `--product`: comma-separated plan identifiers. Omit to cover every plan of the product. |
352
+ | `--max-redemptions <n>` | Total number of uses across all customers. |
353
+ | `--redeem-by <datetime>` | ISO 8601 date/time after which the code stops working. |
354
+ | `--prod` / `--yes` / `--json` | As for `webhook add`. |
355
+
356
+ Discount codes need a Merchant of Record organization.
357
+
358
+ ### kelviq discount list
359
+
360
+ Lists codes with amount, duration and state. `--search <text>` filters by name or code; `--prod` and `--json` as above.
@@ -53,7 +53,7 @@ Server API Keys have full API access. Never expose them in client-side code, com
53
53
 
54
54
  ## Environment variables
55
55
 
56
- Environment variables **override** the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys. `KELVIQ_SERVER_API_KEY` and `KELVIQ_ENV` work the same way as in the [MCP server](/guides/mcp-server); the environment-named keys are CLI-only.
56
+ Environment variables **override** the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys. They can come from the shell or from the project's env file: before every command, the CLI reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory, never overriding a variable the shell already sets. Pass `--env-file <path>` to read a specific file instead, or `--no-env-file` to read none. `kelviq env` lists the files it read. `KELVIQ_SERVER_API_KEY` and `KELVIQ_ENV` work the same way as in the [MCP server](/guides/mcp-server); the environment-named keys are CLI-only.
57
57
 
58
58
  | Variable | Purpose |
59
59
  |---|---|
@@ -88,7 +88,7 @@ If a command needs a key and finds none — neither in the environment nor store
88
88
 
89
89
  ## Checking your setup
90
90
 
91
- `kelviq env` prints the full picture without calling the API:
91
+ `kelviq env` prints the full picture without calling the API, and `kelviq env --check` adds one authenticated read per configured key:
92
92
 
93
93
  ```text
94
94
  Environment : sandbox (default — use --prod to target production)
@@ -100,4 +100,4 @@ Prod key : missing
100
100
  Org : unknown — Kelviq has no key-introspection endpoint yet
101
101
  ```
102
102
 
103
- `set` means a key is configured (stored or via environment variable) — not that it's valid. Kelviq has no key-introspection endpoint yet, so the CLI can't verify a key or display your organization name; an invalid key surfaces on the first real API call, such as `kelviq pull`.
103
+ `set` means a key is configured (stored, from an env file, or from the shell) — not that it's valid. `kelviq env --check` verifies each key with one read against its own environment and exits non-zero if any configured key is rejected. Kelviq has no key-introspection endpoint yet, so the CLI can't display your organization name.
@@ -23,11 +23,15 @@ export const apiCalls = feature({
23
23
  identifier: 'api-calls',
24
24
  name: 'API calls',
25
25
  type: 'METER',
26
+ featureDetails: {
27
+ featureSubType: 'PRE_AGGREGATED_USAGE',
28
+ units: { singular: 'call', plural: 'calls' },
29
+ },
26
30
  });
27
31
 
28
- export const seats = feature({
29
- identifier: 'seats',
30
- name: 'Seats',
32
+ export const historyRetention = feature({
33
+ identifier: 'history-retention',
34
+ name: 'History retention (days)',
31
35
  type: 'CUSTOMIZABLE',
32
36
  });
33
37
 
@@ -36,13 +40,29 @@ export const pro = plan({
36
40
  name: 'Pro',
37
41
  product: 'my-app',
38
42
  entitlements: [
39
- { feature: 'seats', value: 5 },
43
+ { feature: 'history-retention', value: 30 },
40
44
  { feature: 'api-calls', value: 10000, reset: 'EVERY_MONTH', hardLimit: false },
41
45
  ],
42
46
  prices: [
43
47
  {
44
48
  priceType: 'PAID',
45
49
  currency: 'USD',
50
+ freeTrial: false,
51
+ trialPeriod: 0,
52
+ enabled: true,
53
+ taxBehavior: 'EXCLUSIVE',
54
+ chargeCatalogPrice: [
55
+ {
56
+ feature: null,
57
+ priceModel: 'FLAT',
58
+ paymentType: 'ADVANCE_COMMITMENT',
59
+ reset: 'NEVER',
60
+ charges: [
61
+ { chargePeriod: 'MONTHLY', priceData: { amount: 29 } },
62
+ { chargePeriod: 'YEARLY', priceData: { amount: 290 } },
63
+ ],
64
+ },
65
+ ],
46
66
  },
47
67
  ],
48
68
  });
@@ -81,9 +101,9 @@ The plan lifecycle (draft → published) is also deliberately absent: the config
81
101
  |---|---|---|---|
82
102
  | `identifier` | slug | yes | Stable identifier, referenced from plan entitlements. |
83
103
  | `name` | string | yes | Display name. |
84
- | `type` | enum | yes | `BOOLEAN` (on/off), `CUSTOMIZABLE` (a configurable limit), or `METER` (usage-tracked). |
104
+ | `type` | enum | yes | `BOOLEAN` (on/off), `CUSTOMIZABLE` (a setting the plan configures, such as days of history retention), or `METER` (a counted quantity — usage that resets, or seats a customer buys). Seats are a `METER`, not `CUSTOMIZABLE`: only a meter can carry a per-unit price and take a quantity at checkout — see [seat-based pricing](/product-catalog/seat-based-pricing). |
85
105
  | `description` | string | no | Free-text description. |
86
- | `featureDetails` | object | no | Type-specific detail payload, passed through to the API. |
106
+ | `featureDetails` | object | for `METER` | Type-specific detail payload, passed through to the API. A `METER` feature needs `featureSubType` (`PRE_AGGREGATED_USAGE`) and `units` (`{ singular, plural }`): `kelviq push` refuses to create one without them, before writing anything, because the API rejects it. See [Create a feature](/product-catalog/create-a-feature). |
87
107
  | `meter` | object | no | Meter configuration for `METER` features, passed through to the API. |
88
108
  | `metadata` | object | no | Arbitrary key-value metadata. |
89
109
 
@@ -164,9 +184,10 @@ The price envelope is validated; the charge structures inside it are deliberatel
164
184
  | `freeTrial` | boolean | no | Whether the price includes a free trial. |
165
185
  | `trialPeriod` | number | no | Trial length in days. |
166
186
  | `taxBehavior` | enum | no | `INCLUSIVE`, `EXCLUSIVE`, or `UNSPECIFIED`. |
187
+ | `enabled` | boolean | no | Whether the price is available for purchase. |
167
188
  | `chargeCatalogPrice` | array of objects | no | The full charge structure (price models, tiers, billing periods). Passed through verbatim — see the plan-prices endpoints in the [API Reference](/api-reference/introduction) for the shape. |
168
189
 
169
- A pulled config reproduces your remote prices in full, including nested charge structures. You rarely need to author `chargeCatalogPrice` by hand — pull an existing plan and adapt it. If you do author prices by hand, set `freeTrial`, `trialPeriod`, `enabled`, and `taxBehavior` explicitly — omitting them makes `kelviq push` see a difference against the server's stored defaults on every run (see the [push reference](/cli/commands#kelviq-push)).
190
+ A pulled config reproduces your remote prices in full, including nested charge structures. To author one by hand, start from `kelviq init --template saas|usage|license` or pull an existing plan and adapt it. Fields you leave out — `freeTrial`, `taxBehavior`, a charge's `paymentType` or `reset` — take the server's defaults, and `kelviq push` compares prices only on the fields you set, so leaving them out never shows up as a change.
170
191
 
171
192
  ---
172
193
 
@@ -19,9 +19,9 @@ export const app = product({
19
19
  taxCode: 'saas',
20
20
  });
21
21
 
22
- export const seats = feature({
23
- identifier: 'seats',
24
- name: 'Seats',
22
+ export const historyRetention = feature({
23
+ identifier: 'history-retention',
24
+ name: 'History retention (days)',
25
25
  type: 'CUSTOMIZABLE',
26
26
  });
27
27
 
@@ -29,7 +29,7 @@ export const pro = plan({
29
29
  identifier: 'pro',
30
30
  name: 'Pro',
31
31
  product: 'my-app',
32
- entitlements: [{ feature: 'seats', value: 5 }],
32
+ entitlements: [{ feature: 'history-retention', value: 30 }],
33
33
  });
34
34
  ```
35
35
 
@@ -118,7 +118,7 @@ A typed, self-contained TypeScript file is something coding assistants are genui
118
118
  kelviq init
119
119
  ```
120
120
 
121
- Writes a starter `kelviq.config.ts` to edit by hand — useful when you're designing pricing for a new product and want to sketch the model in code (with autocomplete and validation) before anything exists in Kelviq.
121
+ Writes a complete starter `kelviq.config.ts` to edit by hand — useful when you're designing pricing for a new product and want to sketch the model in code (with autocomplete and validation) before anything exists in Kelviq. `--template usage` and `--template license` start from a metered or a license-key catalog instead of the default SaaS one.
122
122
 
123
123
  ---
124
124
 
@@ -162,7 +162,7 @@ kelviq --version
162
162
  kelviq login
163
163
  ```
164
164
 
165
- `login` opens the dashboard's [API keys page](https://app.kelviq.com/settings/api-keys) in your browser and prompts you to paste a **Server API Key**. Input is masked and the key is stored locally with owner-only file permissions.
165
+ `login` opens the dashboard's [API keys page](https://app.kelviq.com/settings/api-keys) in your browser and prompts you to paste a **Server API Key**. Input is masked and the key is stored locally with owner-only file permissions. If the key is already in your project's `.env.local` or `.env` as `KELVIQ_SERVER_API_KEY`, skip this step: the CLI reads it from there.
166
166
 
167
167
  The CLI targets your **sandbox** environment by default. To store a production key too, run `kelviq login --prod`. See [Environments & authentication](/cli/environments) for how keys are stored and how to use environment variables instead (for example, in CI).
168
168
 
@@ -185,10 +185,10 @@ kelviq init
185
185
  ### Step 4: Check where you're pointed
186
186
 
187
187
  ```shell
188
- kelviq env
188
+ kelviq env --check
189
189
  ```
190
190
 
191
- Prints which environment the CLI targets and which keys are configured — useful before any command that touches your account.
191
+ Prints which environment the CLI targets, which keys are configured and which env files were read, and with `--check` confirms each key is accepted by the API — useful before any command that touches your account. Keys can also live in the project's `.env.local` or `.env`: every command reads `KELVIQ_*` variables from there, so an app's existing env file is enough.
192
192
 
193
193
  ### Step 5: Make a change and deploy it
194
194
 
@@ -214,6 +214,9 @@ When you're happy, `kelviq push --publish` makes the changed plans live, and `ke
214
214
  | [`kelviq pull`](/cli/commands#kelviq-pull) | Write your remote catalog to `kelviq.config.ts`. |
215
215
  | [`kelviq push`](/cli/commands#kelviq-push) | Deploy a `kelviq.config.ts`: diff, confirm, draft-first writes, optional publish and prune. |
216
216
  | [`kelviq promote`](/cli/commands#kelviq-promote) | Move the sandbox catalog to production with the same preview and gates. |
217
+ | [`kelviq status`](/cli/commands#kelviq-status) | Show the live catalog: products, features, each plan's latest version with price and entitlement counts. |
218
+ | [`kelviq webhook`](/cli/commands#kelviq-webhook) | Register the app's webhook endpoint and write its signing secret into an env file without printing it. |
219
+ | [`kelviq discount`](/cli/commands#kelviq-discount) | Create and list discount codes, with the product given by identifier. |
217
220
 
218
221
  See the full [command reference](/cli/commands) for every flag, and the [`kelviq.config.ts` reference](/cli/kelviq-config) for the file format.
219
222
 
@@ -221,5 +224,4 @@ See the full [command reference](/cli/commands) for every flag, and the [`kelviq
221
224
 
222
225
  ## What's coming
223
226
 
224
- - **Catalog browse commands** — list and inspect products, features, and plans without a full pull.
225
227
  - **Browser-based login** — a pairing flow that mints a scoped key from your dashboard session, replacing paste-a-key.
@@ -6,7 +6,7 @@ description: "Install Kelviq into Claude Code with one plugin — or add the Kel
6
6
  ---
7
7
  The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus five **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
8
8
 
9
- Skills are the missing half of tool access. The MCP server gives your agent 45 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
9
+ Skills are the missing half of tool access. The MCP server gives your agent 57 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
10
10
 
11
11
  **The Agent Toolkit is new.** The skills and their names are stable, but content will keep improving alongside the platform. The bundled MCP server is always the latest published `@kelviq/mcp-server` — no toolkit update needed when the server improves.
12
12
 
@@ -32,7 +32,7 @@ export KELVIQ_CLIENT_API_KEY="<your-sandbox-client-key>" # only needed for pro
32
32
 
33
33
  Get keys at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
34
34
 
35
- **Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 45 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
35
+ **Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 57 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
36
36
 
37
37
  No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work without any credentials, so your agent can answer Kelviq questions from the documentation immediately. API tools return a clear `Configuration error` until a key is set.
38
38
 
@@ -98,7 +98,7 @@ Wraps the [Kelviq CLI](/cli/overview) loop for agents: `kelviq pull` → edit `k
98
98
 
99
99
  The toolkit layers three things, each doing what it's best at:
100
100
 
101
- 1. **Tools** (from the MCP server) do the work — 45 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
101
+ 1. **Tools** (from the MCP server) do the work — 57 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
102
102
  2. **Skills** (from this toolkit) supply the judgment — which tool, in what order, with which confirmations. They activate automatically based on what you ask.
103
103
  3. **Prompts** (from the MCP server) are guided, step-by-step flows you invoke explicitly — `setup_product`, `launch_plan`, and `diagnose_customer`. The skills route to them rather than duplicating them.
104
104
 
@@ -10,7 +10,7 @@ Instead of asking your assistant to "write me a curl command," you describe the
10
10
 
11
11
  **Using Claude Code?** The fastest install is the [Agent Toolkit](/guides/agent-toolkit) plugin — two commands set up this MCP server *and* five Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.
12
12
 
13
- **45 tools** spanning customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and the full OpenAPI spec, and **3 guided prompts** for the most common workflows. Every tool carries [MCP safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
13
+ **57 tools** spanning connection checks, customers, checkout, subscriptions, discounts, webhooks, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and the full OpenAPI spec, and **3 guided prompts** for the most common workflows. Every tool carries [MCP safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
14
14
 
15
15
  ---
16
16
 
@@ -56,7 +56,7 @@ claude mcp add kelviq \
56
56
 
57
57
  The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
58
58
 
59
- Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 45 tools`.
59
+ Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 57 tools`.
60
60
 
61
61
  Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
62
62
 
@@ -211,6 +211,14 @@ Docs tools (`docs_search`, `docs_read`) work with no API keys at all. Even witho
211
211
 
212
212
  Tools are grouped by domain. Each tool name uses `domain_action` form (`customer_create`, `plan_publish`). The LLM picks the right tool from the description automatically — you rarely need to name a tool explicitly.
213
213
 
214
+ Wherever a tool takes a product or feature reference (`plan_create`, `plan_entitlements_add`, `discount_create`'s `appliesTo`, `offering_get_product`), it accepts the identifier or the UUID; the server resolves an identifier before calling the API.
215
+
216
+ ### Connection
217
+
218
+ | Tool | Description |
219
+ |------|-------------|
220
+ | `connection_check` | One authenticated read with the server key. Returns the environment, both API hosts and whether the key is `ok`, `missing`, `rejected` or errored, never the key itself. The first thing to call when something returns 401/403. |
221
+
214
222
  ### Customers
215
223
 
216
224
  | Tool | Description |
@@ -251,6 +259,29 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
251
259
  | `offering_get_product` | Fetch public pricing scoped to a product UUID. Includes localized prices + customer subscription state. |
252
260
  | `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key. |
253
261
 
262
+ ### Discounts
263
+
264
+ | Tool | Description |
265
+ |------|-------------|
266
+ | `discount_list` | List discount codes. Optional `search` across name and code, paginated. |
267
+ | `discount_create` | Create a percentage or fixed-amount code, optionally limited to a product (identifier or UUID) and its plans with `appliesTo`. Merchant of Record organizations only. |
268
+ | `discount_retrieve` | Fetch one discount, including how often it's been redeemed and whether it's active. |
269
+ | `discount_update` | Enable or disable a code with `isActive`. Nothing else can change after creation. |
270
+ | `discount_archive` | Archive a code so it can no longer be used. |
271
+
272
+ ### Webhooks
273
+
274
+ | Tool | Description |
275
+ |------|-------------|
276
+ | `webhook_endpoint_list` | List endpoints with their URLs, events and enabled state. |
277
+ | `webhook_endpoint_create` | Register a public URL for the events you choose. Localhost and private addresses are rejected. |
278
+ | `webhook_endpoint_retrieve` | Fetch one endpoint. |
279
+ | `webhook_endpoint_update` | Change an endpoint's URL, events or enabled state. |
280
+ | `webhook_endpoint_delete` | Delete an endpoint. Deliveries stop immediately. |
281
+ | `webhook_log_list` | Delivery attempts from the last 30 days, with status codes and retries. |
282
+
283
+ Signing secrets are hidden in webhook tool results. Pass `revealSecret: true` only when you need the value — your app reads the secret from its env file, so it rarely needs to appear in a conversation.
284
+
254
285
  ### Catalog: Products
255
286
 
256
287
  | Tool | Description |
@@ -281,7 +312,7 @@ Plans are versioned. Updates create a draft; `plan_publish` releases it.
281
312
  | Tool | Description |
282
313
  |------|-------------|
283
314
  | `plan_list` | List all plans in the account. |
284
- | `plan_create` | Create a plan under a product. Plan starts in `DRAFT`. |
315
+ | `plan_create` | Create a plan under a product (by identifier or UUID). Plan starts in `DRAFT`. |
285
316
  | `plan_retrieve` | Fetch one plan. |
286
317
  | `plan_update` | Patch a plan. Updates to a published plan automatically create a new draft. |
287
318
  | `plan_archive` | Archive a plan. Existing subscriptions keep working. |
@@ -289,7 +320,7 @@ Plans are versioned. Updates create a draft; `plan_publish` releases it.
289
320
  | `plan_discard_draft` | Drop the current draft, keep the published version. |
290
321
  | `plan_prices_list` | List all prices configured on a plan. |
291
322
  | `plan_entitlements_list` | List feature entitlements on a plan. |
292
- | `plan_entitlements_add` | Attach feature entitlements. |
323
+ | `plan_entitlements_add` | Attach feature entitlements, each feature by identifier or UUID. |
293
324
  | `plan_entitlement_update` | Patch a single entitlement's `details`. |
294
325
  | `plan_entitlement_delete` | Remove an entitlement. |
295
326
  | `plan_file_update` | Edit display fields of a plan-attached file. |
@@ -406,7 +437,7 @@ A required env var is missing. The error message names which one — set it in y
406
437
 
407
438
  ### Tool returns HTTP 401 or 403
408
439
 
409
- Almost always, the key belongs to the other environment: a sandbox key only works against sandbox, and a production key only against production.
440
+ Ask your assistant to call `connection_check`: it reports the environment the server is using and whether the key was accepted, without showing the key. Almost always, the key belongs to the other environment: a sandbox key only works against sandbox, and a production key only against production.
410
441
 
411
442
  - The server uses sandbox unless `KELVIQ_ENV=production`. If your key is a production key, add `KELVIQ_ENV=production` to the server's environment and reconnect.
412
443
  - The error message includes a hint naming the environment the server is using, and the startup log shows it too (`kelviq-mcp ready (env=…`). Make sure it matches your key.
@@ -1158,7 +1158,7 @@ Optionally, also check that `webhook-timestamp` is within a few minutes of your
1158
1158
 
1159
1159
  ## Code Examples
1160
1160
 
1161
- Use `express.raw()` (not `express.json()`) in Node.js so that `req.body` contains the unmodified request bytes. Parsing the body before verification will break the signature check.
1161
+ Use `express.raw()` (not `express.json()`) in Node.js so that `req.body` contains the unmodified request bytes. Parsing the body before verification will break the signature check. On a framework built on the Fetch API (Next.js route handlers, Hono, Remix, Cloudflare Workers), read the body with `await request.text()` and take each header with `request.headers.get(...)`, since `request.headers` is a `Headers` object rather than a plain object.
1162
1162
 
1163
1163
  ```javascript Node.js
1164
1164
  const crypto = require('crypto');
@@ -28,67 +28,11 @@
28
28
  "path": "backend-integration/python-sdk.md"
29
29
  },
30
30
  {
31
- "slug": "changelog/api",
32
- "section": "changelog",
33
- "title": "API",
34
- "description": "Changelog for the Kelviq API",
35
- "path": "changelog/api.md"
36
- },
37
- {
38
- "slug": "changelog/app",
39
- "section": "changelog",
40
- "title": "App",
41
- "description": "Changelog for the Kelviq Dashboard",
42
- "path": "changelog/app.md"
43
- },
44
- {
45
- "slug": "changelog/cli",
46
- "section": "changelog",
47
- "title": "CLI",
48
- "description": "Changelog for @kelviq/cli",
49
- "path": "changelog/cli.md"
50
- },
51
- {
52
- "slug": "changelog/js-promotions-ui",
53
- "section": "changelog",
54
- "title": "JS Promotions UI",
55
- "description": "Changelog for @kelviq/js-promotions-ui",
56
- "path": "changelog/js-promotions-ui.md"
57
- },
58
- {
59
- "slug": "changelog/js-sdk",
60
- "section": "changelog",
61
- "title": "JS SDK",
62
- "description": "Changelog for @kelviq/js-sdk",
63
- "path": "changelog/js-sdk.md"
64
- },
65
- {
66
- "slug": "changelog/mcp-server",
67
- "section": "changelog",
68
- "title": "MCP Server",
69
- "description": "Changelog for @kelviq/mcp-server",
70
- "path": "changelog/mcp-server.md"
71
- },
72
- {
73
- "slug": "changelog/node-sdk",
74
- "section": "changelog",
75
- "title": "Node SDK",
76
- "description": "Changelog for @kelviq/node-sdk",
77
- "path": "changelog/node-sdk.md"
78
- },
79
- {
80
- "slug": "changelog/python-sdk",
81
- "section": "changelog",
82
- "title": "Python SDK",
83
- "description": "Changelog for kelviq-sdk (Python)",
84
- "path": "changelog/python-sdk.md"
85
- },
86
- {
87
- "slug": "changelog/react-sdk",
88
- "section": "changelog",
89
- "title": "React SDK",
90
- "description": "Changelog for @kelviq/react-sdk",
91
- "path": "changelog/react-sdk.md"
31
+ "slug": "changelog",
32
+ "section": "root",
33
+ "title": "Changelog",
34
+ "description": "Every Kelviq release across the dashboard, API, SDKs, and developer tools",
35
+ "path": "changelog.md"
92
36
  },
93
37
  {
94
38
  "slug": "checkout/apply-a-discount-code",
@@ -20,6 +20,19 @@ Use a free plan to offer a permanent zero cost tier. This is perfect for open so
20
20
 
21
21
  Users who select this plan bypass the payment step entirely. They still get access to the customer portal and any deliverables or entitlements attached to the plan.
22
22
 
23
+ ### Putting new signups on a free plan
24
+
25
+ Entitlement checks return `false` for a customer Kelviq has never seen, so a free plan only takes effect once the customer has a subscription to it. To enrol someone at signup rather than sending them through checkout:
26
+
27
+ 1. Create the customer **with an email address** — `customers.create` in the SDK, or `POST /customers/`.
28
+ 2. Create the subscription — `POST /subscriptions/create/` with the plan's identifier and `chargePeriod: "ONE_TIME"`.
29
+
30
+ Keep that order. Creating a subscription for a customer Kelviq has not seen fails with `Subscription requires a customer with a valid email address` — and the failed attempt still registers the customer, without an email. From then on `POST /customers/` answers `Customer already exists`, and the portal refuses that customer too. Recover by patching the email onto the existing record with `PATCH /customers/{customerId}/`, after which the subscription call succeeds. Treat `Customer already exists` as a signal to patch rather than an error to surface.
31
+
32
+ Enrolling this way also records a $0 order for the plan.
33
+
34
+ Check for an existing subscription first, with `customer_id` on `GET /subscriptions/`. Creating a second subscription for the same customer is allowed: the new one becomes `active` and the previous one becomes `superseded`. Nothing breaks, but enrolling on every visit churns through subscription records for no reason.
35
+
23
36
  ## Free trials
24
37
 
25
38
  Free trials let customers test a paid plan for a specific number of days before their card is charged.
@@ -154,6 +154,17 @@ For each active instance, you can click **Revoke** to:
154
154
 
155
155
  Your customers (or their software) can interact with licenses using these API endpoints. Use these to integrate license checking into your application.
156
156
 
157
+ ### 3.0 Reading a customer's key from your server
158
+
159
+ A customer's keys come back with their purchase records, authenticated with your server API key. Orders, subscriptions and invoices all carry a `license` array, and each entry holds `licenseKey` alongside `activationUsage`, `activationLimit` and `expiresOn`.
160
+
161
+ Which record to read depends on how the plan is sold:
162
+
163
+ - **One-time purchases** produce an order, not a subscription. Read `GET /orders/`, where each order's `billingType` is `ONE_TIME`. Orders have no customer filter — pass the customer's id or email as `search` to narrow the list to them.
164
+ - **Recurring plans** produce a subscription. Read `GET /subscriptions/?customer_id=<id>`.
165
+
166
+ This matters for how much you ask of the customer. A signed-in web app already knows who the customer is, so it can read the key server-side and activate on their behalf — there is no need to make them find an email and paste a key back into a session you control. Ask for the key only where the software has no way to look it up itself: a desktop app, CLI, plugin, or anything running off your server, which cannot hold a server API key.
167
+
157
168
  ### 3.1 Activate a License
158
169
 
159
170
  Activates a license key on a specific device/instance.
@@ -247,6 +258,8 @@ Removes an activation from a specific device/instance.
247
258
  6. License is now active on customer's device
248
259
  ```
249
260
 
261
+ For software the customer signs in to, skip steps 3 and 4: read the key from their subscription as in [3.0](#3-0-reading-a-customer-s-key-from-your-server) and call Activate for them.
262
+
250
263
  ### Workflow B: Customer Switches Devices
251
264
 
252
265
  ```
@@ -22,6 +22,13 @@ export type Result<T> = {
22
22
  export declare class KelviqHttpClient {
23
23
  private readonly config;
24
24
  constructor(config: KelviqConfig);
25
+ /** Where requests go, for diagnostics. Deliberately excludes the API keys. */
26
+ connectionInfo(): {
27
+ env: KelviqConfig['env'];
28
+ envExplicit: boolean;
29
+ baseUrl: string;
30
+ edgeUrl: string;
31
+ };
25
32
  request<T = unknown>(init: RequestInit): Promise<Result<T>>;
26
33
  private buildUrl;
27
34
  private missingKeyError;