@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
package/README.md
CHANGED
|
@@ -8,12 +8,12 @@ capabilities at once:
|
|
|
8
8
|
|
|
9
9
|
1. **Typed tools** for the full Kelviq REST API — manage products, plans,
|
|
10
10
|
features, entitlements, customers, subscriptions, checkout sessions, license
|
|
11
|
-
keys, usage, promotions, the customer portal
|
|
11
|
+
keys, usage, promotions, and the customer portal.
|
|
12
12
|
2. **Searchable documentation** — the entire Kelviq docs site is bundled
|
|
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
|
+
> **45 tools** across **9 domains**, **69 resources** including the full
|
|
17
17
|
> OpenAPI spec. Works offline for docs Q&A — only API tools require a key.
|
|
18
18
|
|
|
19
19
|
## Install
|
|
@@ -83,16 +83,27 @@ key). Docs tools (`docs_search`, `docs_read`) work with no keys at all.
|
|
|
83
83
|
|---|---|---|---|
|
|
84
84
|
| `KELVIQ_SERVER_API_KEY` | yes (for API tools) | — | Bearer token for `api.kelviq.com` |
|
|
85
85
|
| `KELVIQ_CLIENT_API_KEY` | only for `promotion_get` | — | Bearer token for the edge host |
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
86
|
+
| `KELVIQ_ENV` | no | `production` | `sandbox` switches both API hosts (base + edge) to their sandbox equivalents. Any other value fails fast at startup. |
|
|
87
|
+
| `KELVIQ_BASE_URL` | no | `https://api.kelviq.com/api/v1` | Override (self-host, custom routing). Wins over `KELVIQ_ENV`. |
|
|
88
|
+
| `KELVIQ_EDGE_URL` | no | `https://edge.api.kelviq.com/api/v1` | Override the edge host (entitlements + promotions). Wins over `KELVIQ_ENV`. |
|
|
88
89
|
|
|
89
|
-
|
|
90
|
+
> **Sandbox keys only work against the sandbox environment** — the API
|
|
91
|
+
> enforces key↔host binding server-side, so a sandbox key against the
|
|
92
|
+
> production host (or vice versa) returns 403s rather than routing you
|
|
93
|
+
> anywhere useful.
|
|
94
|
+
|
|
95
|
+
To point at Kelviq sandbox:
|
|
90
96
|
|
|
91
97
|
```
|
|
92
|
-
|
|
93
|
-
KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
|
|
98
|
+
KELVIQ_ENV=sandbox
|
|
94
99
|
```
|
|
95
100
|
|
|
101
|
+
This resolves `KELVIQ_BASE_URL` to `https://sandboxapi.kelviq.com/api/v1` and
|
|
102
|
+
`KELVIQ_EDGE_URL` to `https://edge.sandboxapi.kelviq.com/api/v1`. To point at
|
|
103
|
+
a self-hosted or otherwise custom deployment, set `KELVIQ_BASE_URL` /
|
|
104
|
+
`KELVIQ_EDGE_URL` explicitly instead — they always take precedence over
|
|
105
|
+
`KELVIQ_ENV`.
|
|
106
|
+
|
|
96
107
|
## Tools
|
|
97
108
|
|
|
98
109
|
### Customers
|
|
@@ -130,25 +141,18 @@ KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
|
|
|
130
141
|
- `plan_list` / `plan_create` / `plan_retrieve` / `plan_update` / `plan_archive`
|
|
131
142
|
- `plan_publish` — release the latest draft, optionally migrate existing customers
|
|
132
143
|
- `plan_discard_draft` — drop the current draft, keep the published version
|
|
133
|
-
- `plan_prices_list`
|
|
144
|
+
- `plan_prices_list` — per-currency pricing on a plan
|
|
134
145
|
- `plan_entitlements_list` / `plan_entitlements_add` / `plan_entitlement_update` / `plan_entitlement_delete`
|
|
135
146
|
- `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
|
|
136
147
|
|
|
137
|
-
### Media
|
|
138
|
-
- `media_presigned_upload` — get a presigned S3 POST policy for uploading product images or plan files (max 5 GB). Returns a `fileKey` you pass back into `product_create` / `product_update` / `plan_create` / `plan_update`.
|
|
139
|
-
|
|
140
|
-
### Partner
|
|
141
|
-
- `partner_org_provision` — provision a new Kelviq org under your partner account
|
|
142
|
-
- `partner_org_list` / `partner_org_retrieve` / `partner_org_retrieve_by_external_id`
|
|
143
|
-
|
|
144
148
|
### Docs (no API key required)
|
|
145
149
|
- `docs_search` — full-text search across the bundled docs; returns slugs
|
|
146
150
|
- `docs_read` — fetch a single doc page by slug
|
|
147
151
|
|
|
148
152
|
## Resources
|
|
149
153
|
|
|
150
|
-
- `kelviq://docs/{section}/{slug}` — every conceptual page in the Kelviq docs (
|
|
151
|
-
- `kelviq://openapi.json` — the full OpenAPI 3.0 spec (
|
|
154
|
+
- `kelviq://docs/{section}/{slug}` — every conceptual page in the Kelviq docs (67 pages)
|
|
155
|
+
- `kelviq://openapi.json` — the full OpenAPI 3.0 spec (55 operations, all schemas)
|
|
152
156
|
- `kelviq://README` — top-level Kelviq overview
|
|
153
157
|
|
|
154
158
|
The OpenAPI spec is the source of truth for request/response shapes — for any
|
|
@@ -163,7 +167,7 @@ Once wired into your MCP client, try prompts like:
|
|
|
163
167
|
- *"Create a plan named 'Pro Monthly' under product UUID `…`, then publish it"* → `plan_create` → `plan_publish`
|
|
164
168
|
- *"What entitlements does customer `acme-42` have for `seats`?"* → `entitlements_get`
|
|
165
169
|
- *"Create a checkout session for plan `pro-monthly`, success URL `https://example.com/ok`"* → `checkout_create_session`
|
|
166
|
-
- *"
|
|
170
|
+
- *"What prices are configured on plan `pro-monthly`?"* → `plan_prices_list`
|
|
167
171
|
|
|
168
172
|
The LLM picks the tool from the description — you don't need to say "use the
|
|
169
173
|
tool called X."
|
|
@@ -177,7 +181,7 @@ npx -y @modelcontextprotocol/inspector \
|
|
|
177
181
|
npx -y @kelviq/mcp-server
|
|
178
182
|
```
|
|
179
183
|
|
|
180
|
-
Opens a browser UI where you can browse all
|
|
184
|
+
Opens a browser UI where you can browse all 45 tools, fill in arguments, and
|
|
181
185
|
run them against the real Kelviq API. Pre-fill env vars by exporting them
|
|
182
186
|
before the command:
|
|
183
187
|
|
|
@@ -304,12 +308,11 @@ src/
|
|
|
304
308
|
└── docs/ # snapshot of ../docs + openapi.json (built at npm publish)
|
|
305
309
|
```
|
|
306
310
|
|
|
307
|
-
The HTTP client routes between
|
|
308
|
-
|
|
311
|
+
The HTTP client routes between two hosts based on each tool's `host` / `auth`
|
|
312
|
+
arguments:
|
|
309
313
|
|
|
310
314
|
- `api.kelviq.com` — main API (Server key)
|
|
311
|
-
- `edge.api.kelviq.com` — entitlements
|
|
312
|
-
- `edge.kelviq.com` — promotions only (Client key)
|
|
315
|
+
- `edge.api.kelviq.com` — entitlements (Server key) and promotions (Client key)
|
|
313
316
|
|
|
314
317
|
All API responses are passed through as JSON text content; errors are
|
|
315
318
|
returned as `{ error: { status, message } }` with `isError: true` rather than
|
package/dist/config.d.ts
CHANGED
|
@@ -1,15 +1,23 @@
|
|
|
1
1
|
export type AuthScope = 'server' | 'client';
|
|
2
|
+
export type KelviqEnv = 'production' | 'sandbox';
|
|
2
3
|
export interface KelviqConfig {
|
|
3
4
|
serverApiKey: string | undefined;
|
|
4
5
|
clientApiKey: string | undefined;
|
|
5
6
|
baseUrl: string;
|
|
6
7
|
edgeUrl: string;
|
|
7
8
|
userAgent: string;
|
|
9
|
+
env: KelviqEnv;
|
|
8
10
|
}
|
|
9
11
|
export declare function loadConfig(env?: NodeJS.ProcessEnv): KelviqConfig;
|
|
12
|
+
export declare function getPackageVersion(): string;
|
|
10
13
|
export declare function requireKey(config: KelviqConfig, scope: AuthScope): string;
|
|
11
14
|
export declare class MissingKeyError extends Error {
|
|
12
15
|
readonly envVar: string;
|
|
13
16
|
readonly scope: AuthScope;
|
|
14
|
-
|
|
17
|
+
readonly env: KelviqEnv;
|
|
18
|
+
constructor(envVar: string, scope: AuthScope, env?: KelviqEnv);
|
|
19
|
+
}
|
|
20
|
+
export declare class InvalidEnvError extends Error {
|
|
21
|
+
readonly value: string;
|
|
22
|
+
constructor(value: string);
|
|
15
23
|
}
|
package/dist/config.js
CHANGED
|
@@ -1,21 +1,35 @@
|
|
|
1
1
|
const DEFAULT_BASE_URL = 'https://api.kelviq.com/api/v1';
|
|
2
2
|
const DEFAULT_EDGE_URL = 'https://edge.api.kelviq.com/api/v1';
|
|
3
|
+
const SANDBOX_BASE_URL = 'https://sandboxapi.kelviq.com/api/v1';
|
|
4
|
+
const SANDBOX_EDGE_URL = 'https://edge.sandboxapi.kelviq.com/api/v1';
|
|
5
|
+
function resolveEnv(env) {
|
|
6
|
+
const raw = env.KELVIQ_ENV?.trim();
|
|
7
|
+
if (!raw)
|
|
8
|
+
return 'production';
|
|
9
|
+
if (raw === 'production' || raw === 'sandbox')
|
|
10
|
+
return raw;
|
|
11
|
+
throw new InvalidEnvError(raw);
|
|
12
|
+
}
|
|
3
13
|
export function loadConfig(env = process.env) {
|
|
4
14
|
const stripSlash = (u) => u.replace(/\/+$/, '');
|
|
15
|
+
const kelviqEnv = resolveEnv(env);
|
|
16
|
+
const defaultBaseUrl = kelviqEnv === 'sandbox' ? SANDBOX_BASE_URL : DEFAULT_BASE_URL;
|
|
17
|
+
const defaultEdgeUrl = kelviqEnv === 'sandbox' ? SANDBOX_EDGE_URL : DEFAULT_EDGE_URL;
|
|
5
18
|
// KELVIQ_ENTITLEMENTS_URL is honored as a legacy alias so existing configs
|
|
6
19
|
// don't break, but KELVIQ_EDGE_URL is the canonical name now that
|
|
7
20
|
// entitlements and promotions share a single edge host.
|
|
8
|
-
const edgeOverride = env.KELVIQ_EDGE_URL?.trim() || env.KELVIQ_ENTITLEMENTS_URL?.trim() ||
|
|
21
|
+
const edgeOverride = env.KELVIQ_EDGE_URL?.trim() || env.KELVIQ_ENTITLEMENTS_URL?.trim() || defaultEdgeUrl;
|
|
9
22
|
return {
|
|
10
23
|
serverApiKey: env.KELVIQ_SERVER_API_KEY?.trim() || undefined,
|
|
11
24
|
clientApiKey: env.KELVIQ_CLIENT_API_KEY?.trim() || undefined,
|
|
12
|
-
baseUrl: stripSlash(env.KELVIQ_BASE_URL?.trim() ||
|
|
25
|
+
baseUrl: stripSlash(env.KELVIQ_BASE_URL?.trim() || defaultBaseUrl),
|
|
13
26
|
edgeUrl: stripSlash(edgeOverride),
|
|
14
27
|
userAgent: `kelviq-mcp/${getPackageVersion()} (+https://kelviq.com)`,
|
|
28
|
+
env: kelviqEnv,
|
|
15
29
|
};
|
|
16
30
|
}
|
|
17
31
|
import { createRequire } from 'node:module';
|
|
18
|
-
function getPackageVersion() {
|
|
32
|
+
export function getPackageVersion() {
|
|
19
33
|
try {
|
|
20
34
|
const require = createRequire(import.meta.url);
|
|
21
35
|
const pkg = require('../package.json');
|
|
@@ -29,19 +43,36 @@ export function requireKey(config, scope) {
|
|
|
29
43
|
const key = scope === 'server' ? config.serverApiKey : config.clientApiKey;
|
|
30
44
|
if (!key) {
|
|
31
45
|
const envVar = scope === 'server' ? 'KELVIQ_SERVER_API_KEY' : 'KELVIQ_CLIENT_API_KEY';
|
|
32
|
-
throw new MissingKeyError(envVar, scope);
|
|
46
|
+
throw new MissingKeyError(envVar, scope, config.env);
|
|
33
47
|
}
|
|
34
48
|
return key;
|
|
35
49
|
}
|
|
50
|
+
// The dashboard's API-keys page reads `?mode=live|sandbox`; "live" is the
|
|
51
|
+
// dashboard's internal name for production and must never leak into
|
|
52
|
+
// user-facing prose (see wording rule in README).
|
|
53
|
+
function keyPageUrl(env) {
|
|
54
|
+
const mode = env === 'sandbox' ? 'sandbox' : 'live';
|
|
55
|
+
return `https://app.kelviq.com/settings/api-keys?mode=${mode}`;
|
|
56
|
+
}
|
|
36
57
|
export class MissingKeyError extends Error {
|
|
37
58
|
envVar;
|
|
38
59
|
scope;
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
60
|
+
env;
|
|
61
|
+
constructor(envVar, scope, env = 'production') {
|
|
62
|
+
super(`Missing ${envVar}. Set it in your MCP client config to enable ${scope}-scoped Kelviq API tools ` +
|
|
63
|
+
`against the ${env} environment. Get keys at ${keyPageUrl(env)}.`);
|
|
42
64
|
this.envVar = envVar;
|
|
43
65
|
this.scope = scope;
|
|
66
|
+
this.env = env;
|
|
44
67
|
this.name = 'MissingKeyError';
|
|
45
68
|
}
|
|
46
69
|
}
|
|
70
|
+
export class InvalidEnvError extends Error {
|
|
71
|
+
value;
|
|
72
|
+
constructor(value) {
|
|
73
|
+
super(`Invalid KELVIQ_ENV "${value}". Valid values are "production" or "sandbox".`);
|
|
74
|
+
this.value = value;
|
|
75
|
+
this.name = 'InvalidEnvError';
|
|
76
|
+
}
|
|
77
|
+
}
|
|
47
78
|
//# sourceMappingURL=config.js.map
|
package/dist/config.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
|
|
@@ -2,12 +2,13 @@
|
|
|
2
2
|
title: "Authentication"
|
|
3
3
|
slug: "api-reference/authentication"
|
|
4
4
|
section: "api-reference"
|
|
5
|
+
description: "Authenticate securely with environment-scoped Kelviq API keys"
|
|
5
6
|
---
|
|
6
|
-
|
|
7
|
+
Kelviq API uses API keys to authenticate requests. All API requests must be made over HTTPS; calls made over plain HTTP will fail. API requests without authentication will also fail.
|
|
7
8
|
|
|
8
9
|
## API Keys
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
Kelviq provides two types of API keys for different use cases.
|
|
11
12
|
|
|
12
13
|
|
|
13
14
|
|
|
@@ -21,11 +22,13 @@ kelviq provides two types of API keys for different use cases.
|
|
|
21
22
|
|
|
22
23
|
**Environment Scoping:** API keys are scoped per environment. This means your **production** and **sandbox** environments will have separate and distinct API keys.
|
|
23
24
|
|
|
25
|
+
[Learn how the sandbox works →](/guides/sandbox)
|
|
26
|
+
|
|
24
27
|
**Important Security Notice:** Do not share your **Server API Key** in any publicly accessible areas such as frontend code, client-side applications, or public repositories.
|
|
25
28
|
|
|
26
29
|
### Obtaining Your API Key
|
|
27
30
|
|
|
28
|
-
You can get your API key from the
|
|
31
|
+
You can get your API key from the Kelviq application dashboard.
|
|
29
32
|
|
|
30
33
|
1. Navigate to **Settings**.
|
|
31
34
|
2. Go to the [**API keys**](https://app.kelviq.com/settings/api-keys) section.
|
|
@@ -39,3 +42,4 @@ To authenticate your requests, pass your **Server API Key** as a Bearer token in
|
|
|
39
42
|
|
|
40
43
|
```bash
|
|
41
44
|
Authorization: Bearer YOUR_API_KEY
|
|
45
|
+
```
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Introduction"
|
|
3
|
+
slug: "api-reference/introduction"
|
|
4
|
+
section: "api-reference"
|
|
5
|
+
description: "Base URLs, environments, and authentication for the Kelviq API"
|
|
6
|
+
---
|
|
7
|
+
The Kelviq API is available in two environments. Use the sandbox while building and testing your integration, then switch to production when you are ready to accept live payments.
|
|
8
|
+
|
|
9
|
+
## Base URLs
|
|
10
|
+
|
|
11
|
+
### Production
|
|
12
|
+
|
|
13
|
+
Use for live customers, production data, and real payments.
|
|
14
|
+
|
|
15
|
+
| API | Base URL |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| Core API | `https://api.kelviq.com/api/v1` |
|
|
18
|
+
| Edge API | `https://edge.api.kelviq.com/api/v1` |
|
|
19
|
+
|
|
20
|
+
### Sandbox
|
|
21
|
+
|
|
22
|
+
Use for development, integration testing, and test payments.
|
|
23
|
+
|
|
24
|
+
| API | Base URL |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| Core API | `https://sandboxapi.kelviq.com/api/v1` |
|
|
27
|
+
| Edge API | `https://edge.sandboxapi.kelviq.com/api/v1` |
|
|
28
|
+
|
|
29
|
+
The Core API manages resources such as products, plans, customers, subscriptions, and checkout sessions. The Edge API serves latency-sensitive features such as entitlements and promotions.
|
|
30
|
+
|
|
31
|
+
Sandbox and production are isolated. API keys and data created in one environment do not work or appear in the other.
|
|
32
|
+
|
|
33
|
+
[Learn how the sandbox works →](/guides/sandbox)
|
|
34
|
+
|
|
35
|
+
## Authentication
|
|
36
|
+
|
|
37
|
+
Kelviq uses API keys. Send your Server API Key as a Bearer token when calling the API from your backend:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
curl https://sandboxapi.kelviq.com/api/v1/catalog/products/ \
|
|
41
|
+
--header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY" \
|
|
42
|
+
--header "Accept: application/json"
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Use a Client API Key for supported browser integrations. Never expose a Server API Key in client-side code.
|
|
46
|
+
|
|
47
|
+
[Read the authentication guide →](/api-reference/authentication)
|
|
48
|
+
|
|
49
|
+
## Switching environments
|
|
50
|
+
|
|
51
|
+
For direct API calls, change the base URL and use the matching environment's API key. Official Kelviq SDKs accept an `environment` option:
|
|
52
|
+
|
|
53
|
+
```typescript Node.js
|
|
54
|
+
import { Kelviq } from "@kelviq/node-sdk";
|
|
55
|
+
|
|
56
|
+
const client = new Kelviq({
|
|
57
|
+
accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY,
|
|
58
|
+
environment: "sandbox",
|
|
59
|
+
});
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```python Python
|
|
63
|
+
from kelviq_sdk import Kelviq
|
|
64
|
+
|
|
65
|
+
client = Kelviq.create_sync_client(
|
|
66
|
+
access_token=KELVIQ_SANDBOX_SERVER_API_KEY,
|
|
67
|
+
environment="sandbox",
|
|
68
|
+
)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Omit `environment` or set it to `production` for live traffic.
|
|
72
|
+
|
|
73
|
+
## Pagination
|
|
74
|
+
|
|
75
|
+
List endpoints that support pagination use the `page` and `page_size` query parameters.
|
|
76
|
+
|
|
77
|
+
| Parameter | Type | Description |
|
|
78
|
+
| --- | --- | --- |
|
|
79
|
+
| `page` | integer | Page number to return. |
|
|
80
|
+
| `page_size` | integer | Number of results to return per page. The maximum is `100`. |
|
|
81
|
+
|
|
82
|
+
Pagination defaults depend on the resource:
|
|
83
|
+
|
|
84
|
+
| Endpoints | Default `page_size` | Maximum `page_size` |
|
|
85
|
+
| --- | ---: | ---: |
|
|
86
|
+
| Products, Plans, Plan Versions, and Features | `100` | `100` |
|
|
87
|
+
| All other paginated APIs | `10` | `100` |
|
|
88
|
+
|
|
89
|
+
You can request fewer results by setting `page_size`. Values above `100` are capped at `100`.
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
curl "https://sandboxapi.kelviq.com/api/v1/customers/?page=2&page_size=10" \
|
|
93
|
+
--header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Paginated responses contain the total result count, links to adjacent pages, and the current page of results:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"count": 250,
|
|
101
|
+
"next": "https://sandboxapi.kelviq.com/api/v1/customers/?page=3&page_size=10",
|
|
102
|
+
"previous": "https://sandboxapi.kelviq.com/api/v1/customers/?page=1&page_size=10",
|
|
103
|
+
"results": []
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Filtering
|
|
108
|
+
|
|
109
|
+
Search and filter parameters vary by endpoint and can be combined with pagination when supported.
|
|
110
|
+
|
|
111
|
+
Use the `search` query parameter for free-text search and endpoint-specific query parameters for filtering.
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# Search customers
|
|
115
|
+
curl "https://sandboxapi.kelviq.com/api/v1/customers/?search=acme&page=1&page_size=10" \
|
|
116
|
+
--header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY"
|
|
117
|
+
|
|
118
|
+
# Filter subscriptions by customer
|
|
119
|
+
curl "https://sandboxapi.kelviq.com/api/v1/subscriptions/?customer_id=customer_123" \
|
|
120
|
+
--header "Authorization: Bearer $KELVIQ_SANDBOX_SERVER_API_KEY"
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Consult the endpoint reference before adding a query parameter; unsupported parameters may be ignored or rejected.
|
|
124
|
+
|
|
125
|
+
## Error handling
|
|
126
|
+
|
|
127
|
+
The API uses standard HTTP status codes and returns detailed error information in the response body.
|
|
128
|
+
|
|
129
|
+
| HTTP Status | Name | Description |
|
|
130
|
+
| --- | --- | --- |
|
|
131
|
+
| `400` | Bad Request | The request body or parameters are invalid, or a business rule prevented the operation. |
|
|
132
|
+
| `401` | Unauthorized | The API key is missing, invalid, or belongs to a different environment. |
|
|
133
|
+
| `403` | Forbidden | The credentials are valid, but the requested action is not allowed. |
|
|
134
|
+
| `404` | Not Found | The requested resource does not exist. |
|
|
135
|
+
| `405` | Method Not Allowed | The HTTP method is not supported for the requested endpoint. |
|
|
136
|
+
| `409` | Conflict | The request conflicts with an existing resource, such as a duplicate account. |
|
|
137
|
+
| `422` | Unprocessable Entity | The request is well-formed but contains invalid or unsupported values. |
|
|
138
|
+
| `428` | Precondition Required | A required account configuration, such as billing-provider authentication, is incomplete. |
|
|
139
|
+
| `429` | Too Many Requests | The request rate limit has been exceeded. |
|
|
140
|
+
| `500` | Internal Server Error | Kelviq could not complete the request because of an unexpected server error. |
|
|
141
|
+
| `502` | Bad Gateway | Kelviq received an invalid response from an upstream service. |
|
|
142
|
+
| `503` | Service Unavailable | The service is temporarily unavailable. |
|
|
143
|
+
| `504` | Gateway Timeout | An upstream service did not respond in time. |
|
|
@@ -264,6 +264,8 @@ const response = await client.checkout.createSession({
|
|
|
264
264
|
|
|
265
265
|
* `defaultBillingCountry` : ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`) used to pre-fill the billing address country on the checkout page.
|
|
266
266
|
|
|
267
|
+
* `metadata` : An object of arbitrary key-value pairs to attach to the checkout session. The keys are preserved exactly as supplied and the object is returned unchanged on the `checkout.completed` webhook's `metadata` field. Example: `{ "order_ref": "ABC-123", "source": "pricing_page" }`.
|
|
268
|
+
|
|
267
269
|
**Returns**:
|
|
268
270
|
|
|
269
271
|
An instance of CreateCheckoutSessionResponse (Object), which includes:
|
|
@@ -585,19 +587,154 @@ An instance of ReportUsageResponse (Object), which includes:
|
|
|
585
587
|
|
|
586
588
|
## Subscriptions
|
|
587
589
|
|
|
588
|
-
The subscriptions module allows you to
|
|
590
|
+
The subscriptions module allows you to list, retrieve, create, update, and cancel customer subscriptions. You can access these operations via the `subscriptions` attribute on an initialized Kelviq client instance.
|
|
589
591
|
|
|
590
|
-
###
|
|
592
|
+
### List subscriptions
|
|
593
|
+
|
|
594
|
+
Retrieves a paginated list of subscriptions for a customer.
|
|
595
|
+
|
|
596
|
+
```typescript
|
|
597
|
+
const page = await client.subscriptions.list({
|
|
598
|
+
customerId: "cust_789",
|
|
599
|
+
page: 1,
|
|
600
|
+
pageSize: 20,
|
|
601
|
+
});
|
|
602
|
+
|
|
603
|
+
for (const subscription of page.results) {
|
|
604
|
+
console.log(subscription.id, subscription.status);
|
|
605
|
+
}
|
|
606
|
+
```
|
|
607
|
+
|
|
608
|
+
```json
|
|
609
|
+
{
|
|
610
|
+
"count": 1,
|
|
611
|
+
"next": null,
|
|
612
|
+
"previous": null,
|
|
613
|
+
"results": [
|
|
614
|
+
{
|
|
615
|
+
"id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
|
|
616
|
+
"startDate": "2025-07-28",
|
|
617
|
+
"endDate": null,
|
|
618
|
+
"status": "active",
|
|
619
|
+
"trialDaysRemaining": 0,
|
|
620
|
+
"customerId": "cust_789",
|
|
621
|
+
"billingType": "SUBSCRIPTION",
|
|
622
|
+
"files": [],
|
|
623
|
+
"links": [],
|
|
624
|
+
"license": []
|
|
625
|
+
}
|
|
626
|
+
]
|
|
627
|
+
}
|
|
628
|
+
```
|
|
629
|
+
|
|
630
|
+
**Required Parameters:**
|
|
631
|
+
|
|
632
|
+
* `customerId` (string): The client-defined identifier of the customer whose subscriptions will be returned.
|
|
633
|
+
|
|
634
|
+
**Optional Parameters:**
|
|
635
|
+
|
|
636
|
+
* `page` (number): Page number to retrieve.
|
|
637
|
+
* `pageSize` (number): Number of subscriptions to return per page.
|
|
638
|
+
|
|
639
|
+
**Returns:**
|
|
640
|
+
|
|
641
|
+
A `PaginatedSubscriptionResponse` containing `count`, `next`, `previous`, and a `results` array of `SubscriptionData` objects.
|
|
642
|
+
|
|
643
|
+
### Retrieve a subscription
|
|
644
|
+
|
|
645
|
+
Retrieves one subscription using its Kelviq subscription ID.
|
|
646
|
+
|
|
647
|
+
```typescript
|
|
648
|
+
const subscription = await client.subscriptions.retrieve({
|
|
649
|
+
subscriptionId: "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
|
|
650
|
+
});
|
|
651
|
+
|
|
652
|
+
console.log(subscription.id, subscription.status);
|
|
653
|
+
subscription.files?.forEach((file) => console.log(file.name, file.downloadUrl));
|
|
654
|
+
subscription.links?.forEach((link) => console.log(link.name, link.url));
|
|
655
|
+
subscription.license?.forEach((license) =>
|
|
656
|
+
console.log(license.licenseKey, license.activationLimit),
|
|
657
|
+
);
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
```json
|
|
661
|
+
{
|
|
662
|
+
"id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
|
|
663
|
+
"externalSubscriptionId": "sub_1RpoZoSBstCzyocS7iPmith3",
|
|
664
|
+
"startDate": "2025-07-28",
|
|
665
|
+
"endDate": null,
|
|
666
|
+
"billingPeriodStartTime": "2025-07-28T10:46:34Z",
|
|
667
|
+
"billingPeriodEndTime": "2025-08-28T10:46:34Z",
|
|
668
|
+
"amount": "261.00",
|
|
669
|
+
"recurrence": "month",
|
|
670
|
+
"currency": "usd",
|
|
671
|
+
"status": "active",
|
|
672
|
+
"trialDaysRemaining": 0,
|
|
673
|
+
"customerId": "cust_789",
|
|
674
|
+
"billingType": "SUBSCRIPTION",
|
|
675
|
+
"recurrenceUnit": 1,
|
|
676
|
+
"recurrenceType": "MONTH",
|
|
677
|
+
"files": [],
|
|
678
|
+
"links": [],
|
|
679
|
+
"license": []
|
|
680
|
+
}
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
**Required Parameters:**
|
|
684
|
+
|
|
685
|
+
* `subscriptionId` (string): The Kelviq UUID of the subscription.
|
|
686
|
+
|
|
687
|
+
**Returns:**
|
|
688
|
+
|
|
689
|
+
A `SubscriptionData` object. A missing subscription throws `NotFoundError`.
|
|
690
|
+
|
|
691
|
+
### Create a subscription
|
|
692
|
+
|
|
693
|
+
Creates a subscription directly for a customer without requiring a checkout session.
|
|
591
694
|
|
|
592
695
|
```typescript
|
|
593
696
|
import { CHARGE_PERIOD_CHOICES } from '@kelviq/node-sdk';
|
|
594
697
|
|
|
698
|
+
const subscription = await client.subscriptions.create({
|
|
699
|
+
planIdentifier: "plan-pro-monthly",
|
|
700
|
+
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
701
|
+
customerId: "cust_789",
|
|
702
|
+
successUrl: "https://example.com/subscription/success",
|
|
703
|
+
features: [{ identifier: "seats", quantity: 5 }],
|
|
704
|
+
ipAddress: "103.154.35.20",
|
|
705
|
+
});
|
|
706
|
+
|
|
707
|
+
console.log(subscription.id, subscription.status);
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
**Required Parameters:**
|
|
711
|
+
|
|
712
|
+
* `planIdentifier` (string): Identifier of the plan to subscribe to.
|
|
713
|
+
* `chargePeriod` (`ChargePeriod`): Billing period such as `MONTHLY`, `YEARLY`, `WEEKLY`, or `DAILY`.
|
|
714
|
+
* `customerId` (string): Client-defined identifier of the customer.
|
|
715
|
+
|
|
716
|
+
**Optional Parameters:**
|
|
717
|
+
|
|
718
|
+
* `successUrl` (string): URL to redirect to after successful subscription creation.
|
|
719
|
+
* `features` (`FeatureListItem[]`): Feature identifiers and requested quantities.
|
|
720
|
+
* `ipAddress` (string): Customer IP address used for location-based pricing.
|
|
721
|
+
|
|
722
|
+
**Returns:**
|
|
723
|
+
|
|
724
|
+
A `CreateSubscriptionResponse` containing the created subscription, including its plan files, links, and issued licenses when available.
|
|
725
|
+
|
|
726
|
+
### Updates an existing subscription to a new plan
|
|
727
|
+
|
|
728
|
+
```typescript
|
|
729
|
+
import { CHARGE_PERIOD_CHOICES, PAYMENT_BEHAVIORS } from '@kelviq/node-sdk';
|
|
730
|
+
|
|
595
731
|
try {
|
|
596
732
|
const response = await client.subscriptions.update({
|
|
597
733
|
subscriptionId: "sub_node_78058918",
|
|
598
734
|
planIdentifier: "premium-plan-node",
|
|
599
735
|
chargePeriod: CHARGE_PERIOD_CHOICES.MONTHLY,
|
|
600
|
-
trialEnd: "
|
|
736
|
+
trialEnd: "2027-12-31T23:59:59Z", // or "now" to end the trial immediately
|
|
737
|
+
paymentBehavior: PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT
|
|
601
738
|
});
|
|
602
739
|
} catch (e) {
|
|
603
740
|
console.error(`Error updating subscription: ${e}`);
|
|
@@ -635,8 +772,9 @@ try {
|
|
|
635
772
|
* Example: `[{"identifier": "seats", "quantity": 10}, {"identifier": "projects", "quantity": 5}]`
|
|
636
773
|
* `trialEnd` (string): Controls the trial period for the updated subscription. Accepts either:
|
|
637
774
|
* The literal string `"now"` to end any active trial immediately.
|
|
638
|
-
* An ISO 8601 datetime string (e.g. `"
|
|
775
|
+
* An ISO 8601 datetime string (e.g. `"2027-12-31T23:59:59Z"`) to set a new trial end date. The datetime must be in the future. Naive datetimes (no timezone designator) are interpreted as UTC.
|
|
639
776
|
* If omitted, the existing trial behavior on the subscription is preserved.
|
|
777
|
+
* `paymentBehavior` (`PaymentBehavior`): Set to `PAYMENT_BEHAVIORS.ACTIVATE_ON_PAYMENT` (the value `"activate_on_payment"`) to keep the current subscription active while payment is pending. The new plan and features are applied only after payment succeeds. If the pending update expires, the current subscription remains unchanged. Omit this field to use the default immediate-update behavior.
|
|
640
778
|
|
|
641
779
|
The SDK validates `trialEnd` client-side — invalid datetime strings or past datetimes throw `InvalidRequestError` before the request is sent.
|
|
642
780
|
|
|
@@ -927,8 +1065,12 @@ const session = await client.portal.createSession({
|
|
|
927
1065
|
customerId: "cust_789",
|
|
928
1066
|
});
|
|
929
1067
|
|
|
1068
|
+
// Build the signed portal link — customerPortalUrl alone does not
|
|
1069
|
+
// authenticate; the token must be appended as a query parameter.
|
|
1070
|
+
const portalLink = `${session.customerPortalUrl}?token=${session.token}`;
|
|
1071
|
+
|
|
930
1072
|
// Redirect your customer to the portal
|
|
931
|
-
res.redirect(
|
|
1073
|
+
res.redirect(portalLink);
|
|
932
1074
|
```
|
|
933
1075
|
|
|
934
1076
|
```json
|
|
@@ -949,7 +1091,7 @@ An instance of `CreatePortalSessionResponse` (TypeScript Interface), which inclu
|
|
|
949
1091
|
|
|
950
1092
|
* `token` : The session token that authenticates the customer portal session.
|
|
951
1093
|
* `email` : The email address of the customer.
|
|
952
|
-
* `customerPortalUrl` : The URL
|
|
1094
|
+
* `customerPortalUrl` : The customer's billing portal base URL. **This URL alone does not authenticate the session** — append the `token` as a query parameter (`${customerPortalUrl}?token=${token}`) to produce the signed link you share with the customer. The token expires, so create a fresh session per visit.
|
|
953
1095
|
|
|
954
1096
|
---
|
|
955
1097
|
## Webhooks
|