@kelviq/mcp-server 0.2.3 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -23
- package/dist/config.d.ts +9 -1
- package/dist/config.js +38 -7
- package/dist/config.js.map +1 -1
- package/dist/docs/api-reference/authentication.md +7 -3
- package/dist/docs/api-reference/introduction.md +143 -0
- package/dist/docs/backend-integration/node-sdk.md +148 -6
- package/dist/docs/backend-integration/python-sdk.md +195 -11
- package/dist/docs/changelog/api.md +119 -0
- package/dist/docs/changelog/app.md +693 -0
- package/dist/docs/changelog/mcp-server.md +61 -0
- package/dist/docs/changelog/node-sdk.md +153 -0
- package/dist/docs/changelog/python-sdk.md +182 -0
- package/dist/docs/cli/commands.md +225 -0
- package/dist/docs/cli/environments.md +95 -0
- package/dist/docs/cli/kelviq-config.md +141 -0
- package/dist/docs/cli/overview.md +223 -0
- package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
- package/dist/docs/guides/mcp-server.md +141 -194
- package/dist/docs/guides/sandbox.md +107 -0
- package/dist/docs/guides/webhooks.md +81 -0
- package/dist/docs/manifest.json +64 -8
- package/dist/docs/openapi.json +1206 -50
- package/dist/docs/product-catalog/one-time-payments.md +3 -1
- package/dist/docs/product-catalog/usage-based-billing.md +86 -7
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -128
- package/dist/schemas/kelviq.js +50 -63
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +5 -2
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/index.js +0 -4
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +4 -1
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +9 -15
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.d.ts +11 -1
- package/dist/tools/portal.js +28 -2
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +6 -1
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +6 -2
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- package/package.json +5 -2
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "MCP Server"
|
|
3
|
+
slug: "changelog/mcp-server"
|
|
4
|
+
section: "changelog"
|
|
5
|
+
description: "Changelog for @kelviq/mcp-server"
|
|
6
|
+
---
|
|
7
|
+
<Update label="v0.4.0" description="July 24, 2026">
|
|
8
|
+
|
|
9
|
+
### New Features
|
|
10
|
+
|
|
11
|
+
#### Full checkout surface
|
|
12
|
+
|
|
13
|
+
`checkout_create_session` now accepts every field the API supports — including `customAmount` (with `taxBehavior` and `currencyCode`) for custom-priced sessions, `discountCode` to pre-apply a coupon, `metadata` (returned verbatim on the `checkout.completed` webhook), `discountsEnabled`, `lockEmail`, and `defaultBillingCountry`. Previously these were silently dropped before the request was sent.
|
|
14
|
+
|
|
15
|
+
#### Subscription update options
|
|
16
|
+
|
|
17
|
+
`subscription_update` now supports `trialEnd` (`"now"` or an ISO 8601 datetime) and `paymentBehavior: "activate_on_payment"` to keep the current subscription active until payment for the update succeeds.
|
|
18
|
+
|
|
19
|
+
#### Safety annotations on every tool
|
|
20
|
+
|
|
21
|
+
All 45 tools now declare [MCP tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) — `readOnlyHint`, `destructiveHint`, `idempotentHint` — so MCP clients can auto-approve reads while asking for confirmation on destructive operations like `plan_archive` or `subscription_cancel`.
|
|
22
|
+
|
|
23
|
+
#### Guided prompts
|
|
24
|
+
|
|
25
|
+
Three built-in MCP prompts encode the golden-path workflows: `setup_product` (catalog bootstrap end-to-end), `launch_plan` (add a plan to an existing product), and `diagnose_customer` (entitlement/subscription cross-check). In Claude Code they appear as slash commands, e.g. `/kelviq:setup_product`.
|
|
26
|
+
|
|
27
|
+
### Fixes
|
|
28
|
+
|
|
29
|
+
- The server now reports its real version to MCP clients (it was pinned to an old value).
|
|
30
|
+
- An automated spec-conformance suite now guards every request schema against the OpenAPI spec, so new API fields can no longer be silently dropped.
|
|
31
|
+
|
|
32
|
+
</Update>
|
|
33
|
+
|
|
34
|
+
<Update label="v0.3.0" description="July 24, 2026">
|
|
35
|
+
|
|
36
|
+
### New Features
|
|
37
|
+
|
|
38
|
+
#### Sandbox environment support
|
|
39
|
+
|
|
40
|
+
Set `KELVIQ_ENV=sandbox` to target your sandbox environment — the server switches both API hosts (`sandboxapi.kelviq.com` and `edge.sandboxapi.kelviq.com`) automatically. Keys only work against their own environment, and an invalid `KELVIQ_ENV` value fails fast at startup instead of silently hitting production.
|
|
41
|
+
|
|
42
|
+
#### Signed portal links
|
|
43
|
+
|
|
44
|
+
`portal_session_create` now returns a ready-to-share `signedPortalUrl` — the portal URL with the session token already appended. The bare `customerPortalUrl` does not authenticate on its own; always share the signed link.
|
|
45
|
+
|
|
46
|
+
### Breaking Changes
|
|
47
|
+
|
|
48
|
+
Six tools were removed: `media_presigned_upload`, the four `partner_org_*` tools, and `plan_prices_bulk_set`. Plan pricing is managed in the dashboard or with the [Kelviq CLI](/cli/overview) (`kelviq push`), which previews and confirms every price change; `plan_prices_list` (read) remains available.
|
|
49
|
+
|
|
50
|
+
### Improvements
|
|
51
|
+
|
|
52
|
+
- `subscription_create` now documents that it requires off-session charging to be enabled for your organization, with `checkout_create_session` as the fallback.
|
|
53
|
+
- The missing-key error links directly to the API-keys page in the right dashboard mode for your environment.
|
|
54
|
+
|
|
55
|
+
</Update>
|
|
56
|
+
|
|
57
|
+
<Update label="v0.2.0 – v0.2.3" description="June 16–17, 2026">
|
|
58
|
+
|
|
59
|
+
Initial public release of `@kelviq/mcp-server`: the full Kelviq API as typed MCP tools plus the entire documentation as searchable resources, followed by packaging fixes and consolidation onto a single edge host.
|
|
60
|
+
|
|
61
|
+
</Update>
|
|
@@ -4,6 +4,159 @@ slug: "changelog/node-sdk"
|
|
|
4
4
|
section: "changelog"
|
|
5
5
|
description: "Changelog for @kelviq/node-sdk"
|
|
6
6
|
---
|
|
7
|
+
<Update label="v2.7.3" description="July 21, 2026">
|
|
8
|
+
|
|
9
|
+
### New Features
|
|
10
|
+
|
|
11
|
+
#### Activate Subscription Updates After Payment
|
|
12
|
+
|
|
13
|
+
`client.subscriptions.update()` now supports `paymentBehavior`. Use the exported `PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT` constant to keep the current subscription active until payment for the update succeeds.
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { CHARGE_PERIOD_CHOICES, PAYMENT_BEHAVIORS } from "@kelviq/node-sdk";
|
|
17
|
+
|
|
18
|
+
const subscription = await client.subscriptions.update({
|
|
19
|
+
subscriptionId: "78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
20
|
+
planIdentifier: "premium-plan",
|
|
21
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
22
|
+
paymentBehavior: PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT,
|
|
23
|
+
});
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The SDK serializes the option as `payment_behavior: "activate_on_payment"`. If payment is not completed and the pending update expires, the existing subscription remains active and unchanged.
|
|
27
|
+
|
|
28
|
+
</Update>
|
|
29
|
+
|
|
30
|
+
<Update label="v2.7.2" description="July 14, 2026">
|
|
31
|
+
|
|
32
|
+
### New Features
|
|
33
|
+
|
|
34
|
+
#### List, Retrieve, and Create Subscriptions
|
|
35
|
+
|
|
36
|
+
The subscriptions module now supports the complete read and create workflow:
|
|
37
|
+
|
|
38
|
+
- `client.subscriptions.list()` retrieves a customer's paginated subscription list with optional pagination controls.
|
|
39
|
+
- `client.subscriptions.retrieve()` retrieves a subscription by its Kelviq UUID.
|
|
40
|
+
- `client.subscriptions.create()` creates a subscription directly for a customer.
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
const page = await client.subscriptions.list({
|
|
44
|
+
customerId: "cust_789",
|
|
45
|
+
page: 1,
|
|
46
|
+
pageSize: 20,
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
const subscription = await client.subscriptions.retrieve({
|
|
50
|
+
subscriptionId: page.results[0].id,
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
const created = await client.subscriptions.create({
|
|
54
|
+
planIdentifier: "plan-pro-monthly",
|
|
55
|
+
chargePeriod: "MONTHLY",
|
|
56
|
+
customerId: "cust_789",
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
New TypeScript models cover paginated results, create payloads, product and plan details, features, files, links, and issued licenses.
|
|
61
|
+
|
|
62
|
+
</Update>
|
|
63
|
+
|
|
64
|
+
<Update label="v2.7.0-beta.2" description="July 10, 2026">
|
|
65
|
+
|
|
66
|
+
### New Features
|
|
67
|
+
|
|
68
|
+
#### Create One-Time Charges
|
|
69
|
+
|
|
70
|
+
A new `client.charges.create()` method can immediately charge a customer's saved payment method without creating a checkout session.
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
const charge = await client.charges.create({
|
|
74
|
+
planIdentifier: "lifetime-access",
|
|
75
|
+
chargePeriod: "ONE_TIME",
|
|
76
|
+
customerId: "cust_789",
|
|
77
|
+
currencyCode: "USD",
|
|
78
|
+
features: [{ identifier: "seats", quantity: 5 }],
|
|
79
|
+
ipAddress: "103.154.35.20",
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
console.log(charge.id, charge.status, charge.amount);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The customer must already have a usable payment method on file. `chargePeriod` is restricted to `"ONE_TIME"`; use the subscriptions API for recurring billing. The SDK includes typed request and response models for charge records.
|
|
86
|
+
|
|
87
|
+
</Update>
|
|
88
|
+
|
|
89
|
+
<Update label="v2.7.0" description="July 4, 2026">
|
|
90
|
+
|
|
91
|
+
### New Features
|
|
92
|
+
|
|
93
|
+
#### Caching & Offline Resilience
|
|
94
|
+
|
|
95
|
+
The SDK now includes a two-tier cache that keeps entitlement checks fast and lets your app keep working during transient network/API outages.
|
|
96
|
+
|
|
97
|
+
- **L1 — in-memory** (on by default): entitlements are cached per-process. Fresh entries (within the TTL) are served without a network call; if the API is unreachable or returns a 5xx, the last-known value is served as a fallback.
|
|
98
|
+
- **L2 — distributed** (optional): a shared store (e.g. Redis) so the cache and the offline usage queue are shared across processes and containers, and survive restarts.
|
|
99
|
+
|
|
100
|
+
Read-through order is **L1 → L2 → API**, with write-through to both on every successful fetch.
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
const client = new Kelviq({
|
|
104
|
+
accessToken: process.env.KELVIQ_API_KEY,
|
|
105
|
+
enableCache: true, // default true
|
|
106
|
+
cacheTtlMs: 60_000, // freshness window in ms (default 60000)
|
|
107
|
+
});
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Set `enableCache: false` to disable caching entirely.
|
|
111
|
+
|
|
112
|
+
#### Offline Usage Queue
|
|
113
|
+
|
|
114
|
+
Usage/event reports that fail due to a network error are automatically **queued** and replayed on the next report call (or via `client.reporting.flush()`), so measurements are not lost during brief outages. Cached entitlement usage is updated optimistically so access checks stay consistent while offline.
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
const remaining = await client.reporting.flush(); // returns count still queued
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
#### Distributed Cache — `RedisStore`
|
|
121
|
+
|
|
122
|
+
A ready-to-use `RedisStore` (backed by `ioredis`, an optional dependency) can be shared across multiple instances / containers so they use one cache and one durable usage queue.
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
import { Kelviq, RedisStore } from '@kelviq/node-sdk';
|
|
126
|
+
|
|
127
|
+
const store = new RedisStore({ url: 'redis://localhost:6379/0', prefix: 'kelviq:prod' });
|
|
128
|
+
const client = new Kelviq({ accessToken: process.env.KELVIQ_API_KEY, cacheStore: store });
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
You can also bring your own backend by implementing the public `CacheStore` interface and passing it as `cacheStore`. All instances that should share a cache must use the same `prefix`.
|
|
132
|
+
|
|
133
|
+
</Update>
|
|
134
|
+
|
|
135
|
+
<Update label="v2.6.0" description="June 5, 2026">
|
|
136
|
+
|
|
137
|
+
### New Features
|
|
138
|
+
|
|
139
|
+
#### Checkout Session — `metadata` Parameter
|
|
140
|
+
|
|
141
|
+
`CreateCheckoutSessionPayload` now accepts an optional `metadata` field for attaching arbitrary key-value pairs to a checkout session. The metadata is returned verbatim on the `checkout.completed` webhook payload's `metadata` field, letting you correlate a completed checkout back to your own records.
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
const response = await client.checkout.createSession({
|
|
145
|
+
planIdentifier: "plan-pro-monthly",
|
|
146
|
+
chargePeriod: "MONTHLY",
|
|
147
|
+
customerId: "cust_789",
|
|
148
|
+
successUrl: "https://example.com/success",
|
|
149
|
+
metadata: {
|
|
150
|
+
orderId: "order_12345",
|
|
151
|
+
referralCode: "SUMMER2026",
|
|
152
|
+
},
|
|
153
|
+
});
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Unlike other payload fields, the **keys inside `metadata` are preserved exactly as provided** — they are not converted to snake_case on the way to the API, so they survive the round-trip back through webhooks unchanged.
|
|
157
|
+
|
|
158
|
+
</Update>
|
|
159
|
+
|
|
7
160
|
<Update label="v2.5.0" description="May 10, 2026">
|
|
8
161
|
|
|
9
162
|
### New Features
|
|
@@ -4,6 +4,188 @@ slug: "changelog/python-sdk"
|
|
|
4
4
|
section: "changelog"
|
|
5
5
|
description: "Changelog for kelviq-sdk (Python)"
|
|
6
6
|
---
|
|
7
|
+
<Update label="v2.7.3" description="July 21, 2026">
|
|
8
|
+
|
|
9
|
+
### New Features
|
|
10
|
+
|
|
11
|
+
#### Activate Subscription Updates After Payment
|
|
12
|
+
|
|
13
|
+
The synchronous and asynchronous `client.subscriptions.update()` methods now support `paymentBehavior="activate_on_payment"`. This keeps the current subscription active while payment for the update is pending.
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
subscription = client.subscriptions.update(
|
|
17
|
+
subscriptionId="78058918-9746-4280-9b9b-1bd5115eec6e",
|
|
18
|
+
planIdentifier="premium-plan",
|
|
19
|
+
chargePeriod="MONTHLY",
|
|
20
|
+
paymentBehavior="activate_on_payment",
|
|
21
|
+
)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The SDK validates the option and serializes it as `payment_behavior`. The new plan and features are applied only after payment succeeds; if the pending update expires, the existing subscription remains active and unchanged.
|
|
25
|
+
|
|
26
|
+
</Update>
|
|
27
|
+
|
|
28
|
+
<Update label="v2.7.2" description="July 14, 2026">
|
|
29
|
+
|
|
30
|
+
### New Features
|
|
31
|
+
|
|
32
|
+
#### List, Retrieve, and Create Subscriptions
|
|
33
|
+
|
|
34
|
+
The synchronous and asynchronous subscription clients now support the complete read and create workflow:
|
|
35
|
+
|
|
36
|
+
- `client.subscriptions.list()` retrieves a customer's paginated subscription list with optional pagination controls.
|
|
37
|
+
- `client.subscriptions.retrieve()` retrieves a subscription by its Kelviq UUID.
|
|
38
|
+
- `client.subscriptions.create()` creates a subscription directly for a customer.
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
page = client.subscriptions.list(
|
|
42
|
+
customerId="cust_789",
|
|
43
|
+
page=1,
|
|
44
|
+
page_size=20,
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
subscription = client.subscriptions.retrieve(
|
|
48
|
+
subscriptionId=page.results[0].id,
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
created = client.subscriptions.create(
|
|
52
|
+
planIdentifier="plan-pro-monthly",
|
|
53
|
+
chargePeriod="MONTHLY",
|
|
54
|
+
customerId="cust_789",
|
|
55
|
+
)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
All three methods are also available on `async_client` and return validated Pydantic models. New models cover paginated results, create payloads, product and plan details, features, files, links, and issued licenses.
|
|
59
|
+
|
|
60
|
+
</Update>
|
|
61
|
+
|
|
62
|
+
<Update label="v2.7.1" description="July 10, 2026">
|
|
63
|
+
|
|
64
|
+
### New Features
|
|
65
|
+
|
|
66
|
+
#### Create One-Time Charges
|
|
67
|
+
|
|
68
|
+
The synchronous and asynchronous clients now provide `client.charges.create()` for immediately charging a customer's saved payment method without creating a checkout session.
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
charge = client.charges.create(
|
|
72
|
+
planIdentifier="lifetime-access",
|
|
73
|
+
chargePeriod="ONE_TIME",
|
|
74
|
+
customerId="cust_789",
|
|
75
|
+
currencyCode="USD",
|
|
76
|
+
features=[{"identifier": "seats", "quantity": 5}],
|
|
77
|
+
ipAddress="103.154.35.20",
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
print(charge.id, charge.status, charge.amount)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
**Async variant:**
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
charge = await async_client.charges.create(
|
|
87
|
+
planIdentifier="lifetime-access",
|
|
88
|
+
chargePeriod="ONE_TIME",
|
|
89
|
+
customerId="cust_789",
|
|
90
|
+
)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The customer must already have a usable payment method on file. `chargePeriod` is restricted to `"ONE_TIME"`; use the subscriptions API for recurring billing. Pydantic request and response models validate parameters and provide typed charge records.
|
|
94
|
+
|
|
95
|
+
</Update>
|
|
96
|
+
|
|
97
|
+
<Update label="v2.7.0" description="July 4, 2026">
|
|
98
|
+
|
|
99
|
+
### New Features
|
|
100
|
+
|
|
101
|
+
#### Caching & Offline Resilience
|
|
102
|
+
|
|
103
|
+
The SDK now includes a two-tier cache that keeps entitlement checks fast and lets your app keep working during transient network/API outages.
|
|
104
|
+
|
|
105
|
+
- **L1 — in-memory** (on by default): entitlements are cached per-process. Fresh entries (within the TTL) are served without a network call; if the API is unreachable or returns a 5xx, the last-known value is served as a fallback.
|
|
106
|
+
- **L2 — distributed** (optional): a shared store (e.g. Redis) so the cache and the offline usage queue are shared across processes / gunicorn workers / containers, and survive restarts.
|
|
107
|
+
|
|
108
|
+
Read-through order is **L1 → L2 → API**, with write-through to both on every successful fetch.
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
client = Kelviq.create_sync_client(
|
|
112
|
+
access_token=ACCESS_TOKEN,
|
|
113
|
+
enable_cache=True, # default True
|
|
114
|
+
cache_ttl=60.0, # freshness window in seconds (default 60)
|
|
115
|
+
)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Set `enable_cache=False` to disable caching entirely. Both the sync and async clients are supported.
|
|
119
|
+
|
|
120
|
+
#### Offline Usage Queue
|
|
121
|
+
|
|
122
|
+
Usage/event reports that fail due to a network error are automatically **queued** and replayed on the next report call (or via `client.reporting.flush()`), so measurements are not lost during brief outages. Cached entitlement usage is updated optimistically so access checks stay consistent while offline.
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
remaining = client.reporting.flush() # returns count still queued
|
|
126
|
+
# async: remaining = await async_client.reporting.flush()
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
#### Distributed Cache — `RedisStore` / `AsyncRedisStore`
|
|
130
|
+
|
|
131
|
+
Ready-to-use Redis-backed stores can be shared across multiple processes / gunicorn workers / containers so they use one cache and one durable usage queue. Redis is an optional extra (`pip install "kelviq-sdk[redis]"`).
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
from kelviq_sdk import Kelviq, RedisStore
|
|
135
|
+
|
|
136
|
+
store = RedisStore(url="redis://localhost:6379/0", prefix="kelviq:prod")
|
|
137
|
+
client = Kelviq.create_sync_client(access_token=ACCESS_TOKEN, cache_store=store)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
# Async
|
|
142
|
+
from kelviq_sdk import Kelviq, AsyncRedisStore
|
|
143
|
+
|
|
144
|
+
store = AsyncRedisStore(url="redis://localhost:6379/0", prefix="kelviq:prod")
|
|
145
|
+
async_client = Kelviq.create_async_client(access_token=ACCESS_TOKEN, cache_store=store)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
You can also bring your own backend by implementing the public `CacheStore` interface and passing it as `cache_store`. All workers/tasks that should share a cache must use the same `prefix`.
|
|
149
|
+
|
|
150
|
+
</Update>
|
|
151
|
+
|
|
152
|
+
<Update label="v2.6.0" description="June 5, 2026">
|
|
153
|
+
|
|
154
|
+
### New Features
|
|
155
|
+
|
|
156
|
+
#### Checkout Session — `metadata` Parameter
|
|
157
|
+
|
|
158
|
+
`checkout.create_session()` now accepts an optional `metadata` parameter for attaching arbitrary key-value pairs to a checkout session. The metadata is returned verbatim on the `checkout.completed` webhook payload's `metadata` field, letting you correlate a completed checkout back to your own records.
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
response = client.checkout.create_session(
|
|
162
|
+
planIdentifier="plan-pro-monthly",
|
|
163
|
+
chargePeriod="MONTHLY",
|
|
164
|
+
customerId="cust_789",
|
|
165
|
+
successUrl="https://example.com/success",
|
|
166
|
+
metadata={
|
|
167
|
+
"orderId": "order_12345",
|
|
168
|
+
"referralCode": "SUMMER2026",
|
|
169
|
+
},
|
|
170
|
+
)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
**Async variant:**
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
response = await async_client.checkout.create_session(
|
|
177
|
+
planIdentifier="plan-pro-monthly",
|
|
178
|
+
chargePeriod="MONTHLY",
|
|
179
|
+
customerId="cust_789",
|
|
180
|
+
successUrl="https://example.com/success",
|
|
181
|
+
metadata={"orderId": "order_12345"},
|
|
182
|
+
)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The keys inside `metadata` are preserved exactly as provided — they are not transformed on the way to the API, so they survive the round-trip back through webhooks unchanged.
|
|
186
|
+
|
|
187
|
+
</Update>
|
|
188
|
+
|
|
7
189
|
<Update label="v2.5.0" description="May 10, 2026">
|
|
8
190
|
|
|
9
191
|
### New Features
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Command reference"
|
|
3
|
+
slug: "cli/commands"
|
|
4
|
+
section: "cli"
|
|
5
|
+
description: "Every Kelviq CLI command, flag by flag."
|
|
6
|
+
---
|
|
7
|
+
All commands support `--help`. The CLI targets your **sandbox** environment unless you pass `--prod` — see [Environments & authentication](/cli/environments).
|
|
8
|
+
|
|
9
|
+
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
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## kelviq init
|
|
14
|
+
|
|
15
|
+
Writes a starter `kelviq.config.ts` to the current directory.
|
|
16
|
+
|
|
17
|
+
```shell
|
|
18
|
+
kelviq init
|
|
19
|
+
kelviq init -o pricing/kelviq.config.ts
|
|
20
|
+
kelviq init --force
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
| Flag | Description |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `-o, --output <path>` | Where to write the file. Defaults to `kelviq.config.ts` in the current directory. |
|
|
26
|
+
| `--force` | Overwrite the file if it already exists. Without it, `init` refuses rather than clobbering your edits. |
|
|
27
|
+
|
|
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).
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## kelviq login
|
|
33
|
+
|
|
34
|
+
Stores a Server API key for the CLI to use.
|
|
35
|
+
|
|
36
|
+
```shell
|
|
37
|
+
kelviq login # store a sandbox key (default)
|
|
38
|
+
kelviq login --prod # store a production key
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
| Flag | Description |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `--prod` | Store the key for the production environment instead of sandbox. |
|
|
44
|
+
|
|
45
|
+
What it does:
|
|
46
|
+
|
|
47
|
+
1. Prints the dashboard's [API keys page](https://app.kelviq.com/settings/api-keys) URL and tries to open it in your default browser — already switched to the environment you're logging into (sandbox by default, production with `--prod`), so the key on screen is the key the CLI expects.
|
|
48
|
+
2. Prompts you to paste the key. In an interactive terminal each pasted character shows as `*` — so you can see the paste landed — and a `Received a N-character key.` line confirms the length. The key itself is never echoed or logged.
|
|
49
|
+
3. Stores it in `~/.config/kelviq/config.json` with owner-only permissions (`0600`).
|
|
50
|
+
|
|
51
|
+
Paste a **Server API Key**, not a Client API Key. Server keys have full API access — treat the config file like any other credential store, and never commit it anywhere.
|
|
52
|
+
|
|
53
|
+
Kelviq has no key-introspection endpoint yet, so `login` cannot verify the key is valid or show which organization it belongs to — the first `pull` is where a bad key surfaces.
|
|
54
|
+
|
|
55
|
+
For CI and other non-interactive contexts, skip `login` entirely and set an environment variable instead — see [Environments & authentication](/cli/environments#environment-variables).
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## kelviq logout
|
|
60
|
+
|
|
61
|
+
Removes stored API keys.
|
|
62
|
+
|
|
63
|
+
```shell
|
|
64
|
+
kelviq logout # remove the stored sandbox key
|
|
65
|
+
kelviq logout --prod # remove the stored production key
|
|
66
|
+
kelviq logout --all # remove both
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
| Flag | Description |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `--prod` | Remove the production key instead of sandbox. |
|
|
72
|
+
| `--all` | Remove both sandbox and production keys. |
|
|
73
|
+
|
|
74
|
+
`logout` only touches the stored config file. Keys supplied via environment variables are unaffected — unset those in your shell or CI configuration.
|
|
75
|
+
|
|
76
|
+
Removing a key locally does not revoke it. To revoke a key, delete it from the [API keys page](https://app.kelviq.com/settings/api-keys) in the dashboard.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## kelviq env
|
|
81
|
+
|
|
82
|
+
Shows which environment and keys the CLI is configured with. Read-only — it never calls the API.
|
|
83
|
+
|
|
84
|
+
```shell
|
|
85
|
+
kelviq env
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
Environment : sandbox (default — use --prod to target production)
|
|
90
|
+
Sandbox URL : https://sandboxapi.kelviq.com/api/v1
|
|
91
|
+
Prod URL : https://api.kelviq.com/api/v1
|
|
92
|
+
Sandbox key : set
|
|
93
|
+
Prod key : missing
|
|
94
|
+
Org : unknown — Kelviq has no key-introspection endpoint yet
|
|
95
|
+
```
|
|
96
|
+
|
|
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).
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## kelviq pull
|
|
102
|
+
|
|
103
|
+
Fetches your remote catalog and writes it as a `kelviq.config.ts`.
|
|
104
|
+
|
|
105
|
+
```shell
|
|
106
|
+
kelviq pull # pull the sandbox catalog
|
|
107
|
+
kelviq pull --prod # pull the production catalog
|
|
108
|
+
kelviq pull -o pricing.config.ts
|
|
109
|
+
kelviq pull --force # overwrite an existing file
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
| Flag | Description |
|
|
113
|
+
|---|---|
|
|
114
|
+
| `--prod` | Pull from the production environment instead of sandbox. |
|
|
115
|
+
| `-o, --output <path>` | Where to write the config. Defaults to `kelviq.config.ts` in the current directory. |
|
|
116
|
+
| `--force` | Overwrite the output file if it already exists. Without it, `pull` refuses rather than overwriting local edits. |
|
|
117
|
+
|
|
118
|
+
What it fetches: all products, all features, the **latest version** of each plan, and each plan's prices and entitlements. Every cross-reference in the generated file uses `identifier` slugs, never UUIDs — the file is stable across environments that share identifiers.
|
|
119
|
+
|
|
120
|
+
On success, `pull` prints the path it wrote and a **warnings list** for anything it couldn't represent in the config format (for example, plan fields like `license`, `links`, `countries`, and `files` are dropped, with one warning each). Warnings are informational — the file it wrote is still valid.
|
|
121
|
+
|
|
122
|
+
On failure — missing key, network error, unexpected API response — `pull` writes `pull failed: <reason>` to stderr and exits non-zero without touching the output file.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## kelviq push
|
|
127
|
+
|
|
128
|
+
Deploys a `kelviq.config.ts` to a Kelviq environment: fetches the current remote catalog, computes exactly what would change, shows you the diff, and applies it only after confirmation.
|
|
129
|
+
|
|
130
|
+
```shell
|
|
131
|
+
kelviq push --dry-run # preview only — never writes anything
|
|
132
|
+
kelviq push # diff, confirm, apply to sandbox
|
|
133
|
+
kelviq push --prod # same, against production
|
|
134
|
+
kelviq push --publish # also publish the plans this run changed
|
|
135
|
+
kelviq push pricing.config.ts # explicit config path
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
| Flag | Description |
|
|
139
|
+
|---|---|
|
|
140
|
+
| `[config]` | Path to the config file. Defaults to `kelviq.config.ts`. |
|
|
141
|
+
| `--prod` | Target production instead of sandbox. |
|
|
142
|
+
| `--dry-run` | Print the diff and exit. Guaranteed zero writes. |
|
|
143
|
+
| `--yes` | Skip the confirmation prompts (required in non-interactive sessions, e.g. CI). |
|
|
144
|
+
| `--publish` | Publish the plans this run created, updated, or price-replaced — with its own confirmation. |
|
|
145
|
+
| `--migrate-features` | With `--publish`: migrate existing customers to the published plan's entitlements. |
|
|
146
|
+
| `--migrate-pricing` | With `--publish`: migrate existing customers to the published plan's pricing. |
|
|
147
|
+
| `--prune` | Archive remote-only plans/features that the CLI created (see below). |
|
|
148
|
+
| `--allow-prod-prune` | Required in place of the interactive typed confirmation to `--prune` production non-interactively. |
|
|
149
|
+
| `--verbose` | Expand aggregated warnings (e.g. list every stripped server-owned price field individually). |
|
|
150
|
+
| `--json` | With `--dry-run` only: emit the machine-readable plan-of-record as JSON on stdout. |
|
|
151
|
+
|
|
152
|
+
The diff shows **what actually changes**, value to value — `~ update plan "pro": name "Pro" → "Pro Plan"` — so the confirmation gate is reviewable at a glance.
|
|
153
|
+
|
|
154
|
+
### Scripting with `--json`
|
|
155
|
+
|
|
156
|
+
`kelviq push --dry-run --json` prints exactly one JSON document: `{environment, direction, changes, summary, operations, prune, publish, featureDrift, errors, warnings}`. The `changes` boolean makes drift checks a one-liner in CI:
|
|
157
|
+
|
|
158
|
+
```shell
|
|
159
|
+
kelviq push --dry-run --json | jq -e '.changes | not' || echo "catalog has drifted"
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`--json` is valid only with `--dry-run` (JSON mode never mixes with prompts or writes), always exits 0 on a successful render, and emits `{"error": …}` documents on failures. The shape is a documented, versioned contract — see the repo README.
|
|
163
|
+
|
|
164
|
+
### What push writes — and in what order
|
|
165
|
+
|
|
166
|
+
Push converges the environment toward your config in dependency order: products → features → plans → entitlements → prices → publish → prune. Cross-references you wrote as identifiers are resolved to UUIDs automatically, including references to resources created earlier in the same run.
|
|
167
|
+
|
|
168
|
+
**Everything push writes is a draft by default.** Plan creates land in draft; updating a published plan creates a new draft version. Nothing a customer sees changes until a plan is explicitly published. On a mid-run failure, push stops immediately, reports exactly what was applied and what wasn't, and exits non-zero — there's no rollback, but because the writes were drafts, a half-applied push has no customer impact.
|
|
169
|
+
|
|
170
|
+
Push stamps a `managed-by: kelviq-cli` entry into the `metadata` of every feature and plan it creates (merged with any metadata you declare). That marker is how `--prune` later distinguishes CLI-managed resources from everything else — you'll see it in the dashboard, and it's safe to leave alone.
|
|
171
|
+
|
|
172
|
+
### Prices are all-or-nothing per plan
|
|
173
|
+
|
|
174
|
+
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
|
+
|
|
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.
|
|
177
|
+
|
|
178
|
+
### Features can't be updated — by design
|
|
179
|
+
|
|
180
|
+
The Kelviq API deliberately treats feature attributes as immutable; renaming a feature is a dashboard operation. If a feature in your config differs from its remote counterpart, push stops **before writing anything** and lists the drifted fields — fix the feature in the [dashboard](https://app.kelviq.com), run `kelviq pull`, and push again.
|
|
181
|
+
|
|
182
|
+
### Publishing
|
|
183
|
+
|
|
184
|
+
`--publish` publishes the plans the run just changed, after a second, separate confirmation listing them. A bare `--publish` never migrates existing customers — they stay on their current entitlements and pricing until you deliberately pass `--migrate-features` and/or `--migrate-pricing`, each of which spells out its consequence before you confirm. `--yes` skips prompts; it never substitutes for passing a migration flag explicitly.
|
|
185
|
+
|
|
186
|
+
### Pruning
|
|
187
|
+
|
|
188
|
+
Remote-only resources — things that exist in the environment but not in your config — are normally just listed as warnings. `--prune` archives them, under strict conditions:
|
|
189
|
+
|
|
190
|
+
- Only plans and features **carrying the `managed-by: kelviq-cli` marker** are ever archived. Anything created in the dashboard, by another tool, or before marker support is listed as *skipped* with the reason — never touched.
|
|
191
|
+
- **Products are never pruned**, ever.
|
|
192
|
+
- Archiving is the platform's soft-delete — nothing is destroyed.
|
|
193
|
+
- Pruning production requires typing the environment name at a dedicated prompt (or `--allow-prod-prune` in CI). `--yes` alone never unlocks it.
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## kelviq promote
|
|
198
|
+
|
|
199
|
+
Moves your sandbox catalog to production in one command — the same engine and safety rails as `push`, with sandbox as the source instead of a local file.
|
|
200
|
+
|
|
201
|
+
```shell
|
|
202
|
+
kelviq promote --dry-run # preview what production would change — read-only
|
|
203
|
+
kelviq promote # diff, confirm, apply drafts to production
|
|
204
|
+
kelviq promote --publish # and publish the changed plans
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
| Flag | Description |
|
|
208
|
+
|---|---|
|
|
209
|
+
| `--dry-run` | Print the sandbox→production diff and exit. Guaranteed zero writes. |
|
|
210
|
+
| `--yes` | Skip the confirmation prompts. |
|
|
211
|
+
| `--publish` / `--migrate-features` / `--migrate-pricing` | Same semantics as `push`. |
|
|
212
|
+
| `--prune` | Archive marker-carrying production plans/features absent from sandbox. Always crosses the production-prune gate. |
|
|
213
|
+
| `--allow-prod-prune` | Non-interactive stand-in for the typed production confirmation. |
|
|
214
|
+
| `--verbose` / `--json` | Same semantics as `push` (`--json` requires `--dry-run`). |
|
|
215
|
+
|
|
216
|
+
Promote reads and writes **no local file** — it fetches the sandbox catalog in memory and reconciles production toward it, matching resources by identifier (which is why the config format bans per-environment UUIDs). It needs both keys configured: sandbox to read, production to write.
|
|
217
|
+
|
|
218
|
+
Everything you know about push applies: drafts by default, a confirmation showing the full diff first, feature drift between the environments stops the run with dashboard guidance, and prices replace whole-set per plan. The intended workflow is always `--dry-run` first:
|
|
219
|
+
|
|
220
|
+
```shell
|
|
221
|
+
kelviq promote --dry-run # read what would change
|
|
222
|
+
kelviq promote # then do it
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Promotion is one-way — sandbox to production. There is no reverse mode.
|