@kelviq/mcp-server 1.1.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 +18 -8
- 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 +108 -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 +14 -6
- package/dist/docs/guides/webhooks.md +1 -1
- 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 +1 -0
- package/dist/schemas/kelviq.js +6 -4
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +1 -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.js +14 -2
- package/dist/tools/discounts.js.map +1 -1
- package/dist/tools/index.js +3 -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/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
|
-
> **
|
|
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,11 +142,11 @@ 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
|
|
|
140
148
|
### Discounts
|
|
141
|
-
- `discount_list` / `discount_create` / `discount_retrieve` / `discount_archive`
|
|
149
|
+
- `discount_list` / `discount_create` (`appliesTo[].product` takes a UUID or identifier) / `discount_retrieve` / `discount_archive`
|
|
142
150
|
- `discount_update` — enable or disable a code (nothing else can change after creation)
|
|
143
151
|
|
|
144
152
|
### Webhooks
|
|
@@ -154,11 +162,11 @@ precedence over `KELVIQ_ENV`.
|
|
|
154
162
|
- `feature_list` / `feature_create` / `feature_retrieve` / `feature_archive`
|
|
155
163
|
|
|
156
164
|
### Catalog: Plans
|
|
157
|
-
- `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`
|
|
158
166
|
- `plan_publish` — release the latest draft, optionally migrate existing customers
|
|
159
167
|
- `plan_discard_draft` — drop the current draft, keep the published version
|
|
160
168
|
- `plan_prices_list` — per-currency pricing on a plan
|
|
161
|
-
- `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`
|
|
162
170
|
- `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
|
|
163
171
|
|
|
164
172
|
### Docs (no API key required)
|
|
@@ -180,7 +188,7 @@ Once wired into your MCP client, try prompts like:
|
|
|
180
188
|
|
|
181
189
|
- *"Search Kelviq docs for license keys"* → `docs_search` + `docs_read`
|
|
182
190
|
- *"List my Kelviq products"* → `product_list`
|
|
183
|
-
- *"Create a plan named 'Pro Monthly' under product
|
|
191
|
+
- *"Create a plan named 'Pro Monthly' under product `acme-app`, then publish it"* → `plan_create` → `plan_publish`
|
|
184
192
|
- *"What entitlements does customer `acme-42` have for `seats`?"* → `entitlements_get`
|
|
185
193
|
- *"Create a checkout session for plan `pro-monthly`, success URL `https://example.com/ok`"* → `checkout_create_session`
|
|
186
194
|
- *"What prices are configured on plan `pro-monthly`?"* → `plan_prices_list`
|
|
@@ -197,7 +205,7 @@ npx -y @modelcontextprotocol/inspector \
|
|
|
197
205
|
npx -y @kelviq/mcp-server@latest
|
|
198
206
|
```
|
|
199
207
|
|
|
200
|
-
Opens a browser UI where you can browse all
|
|
208
|
+
Opens a browser UI where you can browse all 57 tools, fill in arguments, and
|
|
201
209
|
run them against the real Kelviq API. Pre-fill env vars by exporting them
|
|
202
210
|
before the command:
|
|
203
211
|
|
|
@@ -246,7 +254,9 @@ PATH. Either:
|
|
|
246
254
|
### Tool returns `{"error": {"status": "Configuration error", …}}`
|
|
247
255
|
|
|
248
256
|
Means a required env var is missing. The error message names which one. Set
|
|
249
|
-
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.
|
|
250
260
|
|
|
251
261
|
### API tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
|
|
252
262
|
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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.
|
package/dist/docs/changelog.md
CHANGED
|
@@ -6,6 +6,114 @@ description: "Every Kelviq release across the dashboard, API, SDKs, and develope
|
|
|
6
6
|
---
|
|
7
7
|
import { ChangelogFilter } from "/snippets/changelog-filter.jsx";
|
|
8
8
|
|
|
9
|
+
<Update label="v0.4.0" description="September 16, 2026" tags={["CLI"]}>
|
|
10
|
+
|
|
11
|
+
### New Features
|
|
12
|
+
|
|
13
|
+
#### Env files, a live key check, and the live catalog
|
|
14
|
+
|
|
15
|
+
- Every command reads `KELVIQ_*` variables from `.env.local` and then `.env` in the working directory, so an app's env file is enough. A variable set in the shell always wins; `--env-file <path>` reads a specific file and `--no-env-file` reads none.
|
|
16
|
+
- `kelviq env --check` makes one authenticated read per configured key and reports `ok`, `rejected` or `error`, exiting non-zero when a key fails. Nothing from the key is printed.
|
|
17
|
+
- `kelviq status` shows the live catalog: products, features, and each plan's latest version with its price and entitlement counts, visibility and license-key state. `--json` for scripts.
|
|
18
|
+
|
|
19
|
+
#### Webhooks and discounts from the terminal
|
|
20
|
+
|
|
21
|
+
- `kelviq webhook add <url> --events … --write-secret .env.local` registers the app's endpoint, reusing one that already has the same URL, and writes the signing secret into the env file as `KELVIQ_WEBHOOK_SECRET` without printing it. `kelviq webhook list` shows endpoints with secrets hidden.
|
|
22
|
+
- `kelviq discount create` creates a code after restating it for confirmation, with `--product` taking the product's identifier. `kelviq discount list` lists codes.
|
|
23
|
+
|
|
24
|
+
#### Starter templates
|
|
25
|
+
|
|
26
|
+
`kelviq init --template saas|usage|license` writes a complete catalog that pushes as written: a SaaS product with free and Pro plans, a metered product with an included quantity and tiered overage, or a plan that issues license keys.
|
|
27
|
+
|
|
28
|
+
### Improvements
|
|
29
|
+
|
|
30
|
+
- `kelviq push` compares prices only on the fields your config sets. Leaving out `freeTrial`, `taxBehavior`, or a charge's `paymentType` and `reset` no longer shows a difference on every run.
|
|
31
|
+
- `kelviq push` and `kelviq promote` stop before writing when a `METER` feature would be created without `featureDetails`, naming the feature and the fields to add.
|
|
32
|
+
|
|
33
|
+
</Update>
|
|
34
|
+
|
|
35
|
+
<Update label="v1.2.0" description="September 16, 2026" tags={["MCP Server"]}>
|
|
36
|
+
|
|
37
|
+
### New Features
|
|
38
|
+
|
|
39
|
+
#### `connection_check`
|
|
40
|
+
|
|
41
|
+
A read-only tool that makes one authenticated read with the server key and reports the environment, both API hosts and whether the key is `ok`, `missing` or `rejected`, without ever including the key. Ask for it first when a tool returns 401 or 403.
|
|
42
|
+
|
|
43
|
+
### Improvements
|
|
44
|
+
|
|
45
|
+
- `plan_create`, `plan_entitlements_add`, `discount_create`'s `appliesTo` and `offering_get_product` accept a product or feature **identifier** as well as a UUID. The server resolves the identifier before calling the API, so the assistant no longer has to look up UUIDs first.
|
|
46
|
+
- The bundled documentation is refreshed with every release, so `docs_search` and `docs_read` match the current docs.
|
|
47
|
+
|
|
48
|
+
</Update>
|
|
49
|
+
|
|
50
|
+
<Update label="v2.9.0" description="September 17, 2026" tags={["Python SDK"]}>
|
|
51
|
+
|
|
52
|
+
### New Features
|
|
53
|
+
|
|
54
|
+
#### `environment_from_env()`
|
|
55
|
+
|
|
56
|
+
Resolves the client's `environment` argument from `KELVIQ_ENV`, the variable the CLI and MCP server share: `"sandbox"` when unset, `"production"` or `"sandbox"` when set to one of those, and a `ValueError` naming any other value.
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from kelviq_sdk import Kelviq, environment_from_env
|
|
60
|
+
|
|
61
|
+
client = Kelviq.create_sync_client(
|
|
62
|
+
access_token=os.environ["KELVIQ_SERVER_API_KEY"],
|
|
63
|
+
environment=environment_from_env(),
|
|
64
|
+
)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Improvements
|
|
68
|
+
|
|
69
|
+
- `environment="production"` is accepted alongside `"prod"`, so a value read straight from `KELVIQ_ENV` works.
|
|
70
|
+
- An environment name the SDK doesn't know now logs a warning. It still falls back to the production hosts.
|
|
71
|
+
|
|
72
|
+
</Update>
|
|
73
|
+
|
|
74
|
+
<Update label="v2.9.0" description="September 16, 2026" tags={["Node SDK"]}>
|
|
75
|
+
|
|
76
|
+
### New Features
|
|
77
|
+
|
|
78
|
+
#### `environmentFromEnv()`
|
|
79
|
+
|
|
80
|
+
Turns the `KELVIQ_ENV` convention shared with the CLI and MCP server into a typed `environment` option: `sandbox` when unset, `production` or `sandbox` when set to one of those, and an error naming any other value.
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
import { Kelviq, environmentFromEnv } from '@kelviq/node-sdk';
|
|
84
|
+
|
|
85
|
+
const client = new Kelviq({
|
|
86
|
+
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
|
|
87
|
+
environment: environmentFromEnv(),
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
</Update>
|
|
92
|
+
|
|
93
|
+
<Update label="v0.3.1" description="September 16, 2026" tags={["CLI"]}>
|
|
94
|
+
|
|
95
|
+
### Improvements
|
|
96
|
+
|
|
97
|
+
#### Cleaner `kelviq pull` output
|
|
98
|
+
|
|
99
|
+
A pulled `kelviq.config.ts` now writes charge prices the way you'd author them. A charge's `feature` is the feature's identifier:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
chargeCatalogPrice: [
|
|
103
|
+
{
|
|
104
|
+
feature: 'seats',
|
|
105
|
+
priceModel: 'FLAT',
|
|
106
|
+
...
|
|
107
|
+
},
|
|
108
|
+
]
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Previously that field held the whole feature object the API returns — its UUID, timestamps and Stripe ids — and each charge carried its own server-generated ids. Those fields are now left out, so a pulled catalog is around 20% smaller, holds no UUIDs or Stripe ids, and reads as something you can edit by hand and review in a pull request.
|
|
112
|
+
|
|
113
|
+
Existing pulled files keep working: `kelviq push` accepts the identifier, the UUID and the embedded object alike.
|
|
114
|
+
|
|
115
|
+
</Update>
|
|
116
|
+
|
|
9
117
|
<Update label="v1.1.0" description="September 16, 2026" tags={["MCP Server"]}>
|
|
10
118
|
|
|
11
119
|
### New Features
|
|
@@ -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
|
|