@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.
- package/README.md +25 -7
- package/dist/docs/README.md +16 -0
- package/dist/docs/backend-integration/node-sdk.md +41 -17
- package/dist/docs/backend-integration/python-sdk.md +16 -17
- package/dist/docs/changelog.md +4076 -0
- package/dist/docs/cli/commands.md +140 -5
- package/dist/docs/cli/environments.md +3 -3
- package/dist/docs/cli/kelviq-config.md +28 -7
- package/dist/docs/cli/overview.md +11 -9
- package/dist/docs/guides/agent-toolkit.md +3 -3
- package/dist/docs/guides/mcp-server.md +36 -5
- package/dist/docs/guides/webhooks.md +1 -1
- package/dist/docs/manifest.json +5 -61
- package/dist/docs/product-catalog/free-and-trials.md +13 -0
- package/dist/docs/product-catalog/license-keys.md +13 -0
- package/dist/http/client.d.ts +7 -0
- package/dist/http/client.js +9 -0
- package/dist/http/client.js.map +1 -1
- package/dist/prompts/index.js +11 -11
- package/dist/prompts/index.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +200 -0
- package/dist/schemas/kelviq.js +178 -3
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +2 -0
- package/dist/server.js.map +1 -1
- package/dist/tools/_resolve.d.ts +4 -0
- package/dist/tools/_resolve.js +46 -0
- package/dist/tools/_resolve.js.map +1 -0
- package/dist/tools/connection.d.ts +12 -0
- package/dist/tools/connection.js +44 -0
- package/dist/tools/connection.js.map +1 -0
- package/dist/tools/discounts.d.ts +3 -0
- package/dist/tools/discounts.js +86 -0
- package/dist/tools/discounts.js.map +1 -0
- package/dist/tools/index.js +7 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/offerings.js +6 -2
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +11 -3
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plans.js +6 -2
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/webhooks.d.ts +10 -0
- package/dist/tools/webhooks.js +114 -0
- package/dist/tools/webhooks.js.map +1 -0
- 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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
29
|
-
identifier: '
|
|
30
|
-
name: '
|
|
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: '
|
|
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
|
|
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 |
|
|
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.
|
|
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
|
|
23
|
-
identifier: '
|
|
24
|
-
name: '
|
|
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: '
|
|
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
|
|
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
|
|
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,
|
|
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 —
|
|
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
|
-
**
|
|
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,
|
|
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');
|
package/dist/docs/manifest.json
CHANGED
|
@@ -28,67 +28,11 @@
|
|
|
28
28
|
"path": "backend-integration/python-sdk.md"
|
|
29
29
|
},
|
|
30
30
|
{
|
|
31
|
-
"slug": "changelog
|
|
32
|
-
"section": "
|
|
33
|
-
"title": "
|
|
34
|
-
"description": "
|
|
35
|
-
"path": "changelog
|
|
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
|
```
|
package/dist/http/client.d.ts
CHANGED
|
@@ -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;
|