@kelviq/mcp-server 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +22 -20
  2. package/dist/config.d.ts +8 -2
  3. package/dist/config.js +42 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/api-reference/authentication.md +7 -3
  6. package/dist/docs/api-reference/introduction.md +143 -0
  7. package/dist/docs/backend-integration/node-sdk.md +148 -6
  8. package/dist/docs/backend-integration/python-sdk.md +195 -11
  9. package/dist/docs/changelog/api.md +119 -0
  10. package/dist/docs/changelog/app.md +693 -0
  11. package/dist/docs/changelog/node-sdk.md +153 -0
  12. package/dist/docs/changelog/python-sdk.md +182 -0
  13. package/dist/docs/cli/commands.md +225 -0
  14. package/dist/docs/cli/environments.md +95 -0
  15. package/dist/docs/cli/kelviq-config.md +141 -0
  16. package/dist/docs/cli/overview.md +223 -0
  17. package/dist/docs/customer-portal/managing-payment-methods.md +72 -0
  18. package/dist/docs/guides/mcp-server.md +374 -0
  19. package/dist/docs/guides/sandbox.md +107 -0
  20. package/dist/docs/guides/webhooks.md +81 -0
  21. package/dist/docs/manifest.json +64 -8
  22. package/dist/docs/openapi.json +1208 -52
  23. package/dist/docs/product-catalog/one-time-payments.md +3 -1
  24. package/dist/docs/product-catalog/usage-based-billing.md +86 -7
  25. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  26. package/dist/http/client.d.ts +1 -1
  27. package/dist/http/client.js +1 -5
  28. package/dist/http/client.js.map +1 -1
  29. package/dist/schemas/kelviq.d.ts +0 -128
  30. package/dist/schemas/kelviq.js +0 -63
  31. package/dist/schemas/kelviq.js.map +1 -1
  32. package/dist/server.js +2 -2
  33. package/dist/server.js.map +1 -1
  34. package/dist/tools/entitlements.js +1 -1
  35. package/dist/tools/entitlements.js.map +1 -1
  36. package/dist/tools/index.js +0 -4
  37. package/dist/tools/index.js.map +1 -1
  38. package/dist/tools/plan-files.js +1 -1
  39. package/dist/tools/plan-files.js.map +1 -1
  40. package/dist/tools/plans.js +1 -15
  41. package/dist/tools/plans.js.map +1 -1
  42. package/dist/tools/portal.d.ts +11 -1
  43. package/dist/tools/portal.js +27 -2
  44. package/dist/tools/portal.js.map +1 -1
  45. package/dist/tools/products.js +1 -1
  46. package/dist/tools/products.js.map +1 -1
  47. package/dist/tools/subscriptions.js +1 -1
  48. package/dist/tools/subscriptions.js.map +1 -1
  49. 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, and partner organizations.
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
- > **51 tools** across **13 domains**, **61 resources** including the full
16
+ > **45 tools** across **9 domains**, **61 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
@@ -82,19 +82,28 @@ key). Docs tools (`docs_search`, `docs_read`) work with no keys at all.
82
82
  | Variable | Required | Default | Purpose |
83
83
  |---|---|---|---|
84
84
  | `KELVIQ_SERVER_API_KEY` | yes (for API tools) | — | Bearer token for `api.kelviq.com` |
85
- | `KELVIQ_CLIENT_API_KEY` | only for `promotion_get` | — | Bearer token for `edge.kelviq.com` |
86
- | `KELVIQ_BASE_URL` | no | `https://api.kelviq.com/api/v1` | Override (sandbox, self-host) |
87
- | `KELVIQ_ENTITLEMENTS_URL` | no | `https://edge.api.kelviq.com` | Override entitlements host |
88
- | `KELVIQ_EDGE_URL` | no | `https://edge.kelviq.com/api/v1` | Override promotions edge host |
85
+ | `KELVIQ_CLIENT_API_KEY` | only for `promotion_get` | — | Bearer token for the edge host |
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`. |
89
89
 
90
- To point at Kelviq staging:
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:
91
96
 
92
97
  ```
93
- KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
94
- KELVIQ_ENTITLEMENTS_URL=https://edge.stagingapi.kelviq.com
95
- KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
98
+ KELVIQ_ENV=sandbox
96
99
  ```
97
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
+
98
107
  ## Tools
99
108
 
100
109
  ### Customers
@@ -132,17 +141,10 @@ KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
132
141
  - `plan_list` / `plan_create` / `plan_retrieve` / `plan_update` / `plan_archive`
133
142
  - `plan_publish` — release the latest draft, optionally migrate existing customers
134
143
  - `plan_discard_draft` — drop the current draft, keep the published version
135
- - `plan_prices_list` / `plan_prices_bulk_set` — atomic per-currency pricing updates
144
+ - `plan_prices_list` — per-currency pricing on a plan
136
145
  - `plan_entitlements_list` / `plan_entitlements_add` / `plan_entitlement_update` / `plan_entitlement_delete`
137
146
  - `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
138
147
 
139
- ### Media
140
- - `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`.
141
-
142
- ### Partner
143
- - `partner_org_provision` — provision a new Kelviq org under your partner account
144
- - `partner_org_list` / `partner_org_retrieve` / `partner_org_retrieve_by_external_id`
145
-
146
148
  ### Docs (no API key required)
147
149
  - `docs_search` — full-text search across the bundled docs; returns slugs
148
150
  - `docs_read` — fetch a single doc page by slug
@@ -165,7 +167,7 @@ Once wired into your MCP client, try prompts like:
165
167
  - *"Create a plan named 'Pro Monthly' under product UUID `…`, then publish it"* → `plan_create` → `plan_publish`
166
168
  - *"What entitlements does customer `acme-42` have for `seats`?"* → `entitlements_get`
167
169
  - *"Create a checkout session for plan `pro-monthly`, success URL `https://example.com/ok`"* → `checkout_create_session`
168
- - *"Provision a partner org with external ID `acme-99` and email `ops@acme.com`"* → `partner_org_provision`
170
+ - *"What prices are configured on plan `pro-monthly`?"* → `plan_prices_list`
169
171
 
170
172
  The LLM picks the tool from the description — you don't need to say "use the
171
173
  tool called X."
@@ -179,7 +181,7 @@ npx -y @modelcontextprotocol/inspector \
179
181
  npx -y @kelviq/mcp-server
180
182
  ```
181
183
 
182
- Opens a browser UI where you can browse all 51 tools, fill in arguments, and
184
+ Opens a browser UI where you can browse all 45 tools, fill in arguments, and
183
185
  run them against the real Kelviq API. Pre-fill env vars by exporting them
184
186
  before the command:
185
187
 
package/dist/config.d.ts CHANGED
@@ -1,16 +1,22 @@
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
- entitlementsUrl: string;
8
8
  userAgent: string;
9
+ env: KelviqEnv;
9
10
  }
10
11
  export declare function loadConfig(env?: NodeJS.ProcessEnv): KelviqConfig;
11
12
  export declare function requireKey(config: KelviqConfig, scope: AuthScope): string;
12
13
  export declare class MissingKeyError extends Error {
13
14
  readonly envVar: string;
14
15
  readonly scope: AuthScope;
15
- constructor(envVar: string, scope: AuthScope);
16
+ readonly env: KelviqEnv;
17
+ constructor(envVar: string, scope: AuthScope, env?: KelviqEnv);
18
+ }
19
+ export declare class InvalidEnvError extends Error {
20
+ readonly value: string;
21
+ constructor(value: string);
16
22
  }
package/dist/config.js CHANGED
@@ -1,15 +1,31 @@
1
1
  const DEFAULT_BASE_URL = 'https://api.kelviq.com/api/v1';
2
- const DEFAULT_EDGE_URL = 'https://edge.kelviq.com/api/v1';
3
- const DEFAULT_ENTITLEMENTS_URL = 'https://edge.api.kelviq.com';
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
+ }
4
13
  export function loadConfig(env = process.env) {
5
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;
18
+ // KELVIQ_ENTITLEMENTS_URL is honored as a legacy alias so existing configs
19
+ // don't break, but KELVIQ_EDGE_URL is the canonical name now that
20
+ // entitlements and promotions share a single edge host.
21
+ const edgeOverride = env.KELVIQ_EDGE_URL?.trim() || env.KELVIQ_ENTITLEMENTS_URL?.trim() || defaultEdgeUrl;
6
22
  return {
7
23
  serverApiKey: env.KELVIQ_SERVER_API_KEY?.trim() || undefined,
8
24
  clientApiKey: env.KELVIQ_CLIENT_API_KEY?.trim() || undefined,
9
- baseUrl: stripSlash(env.KELVIQ_BASE_URL?.trim() || DEFAULT_BASE_URL),
10
- edgeUrl: stripSlash(env.KELVIQ_EDGE_URL?.trim() || DEFAULT_EDGE_URL),
11
- entitlementsUrl: stripSlash(env.KELVIQ_ENTITLEMENTS_URL?.trim() || DEFAULT_ENTITLEMENTS_URL),
25
+ baseUrl: stripSlash(env.KELVIQ_BASE_URL?.trim() || defaultBaseUrl),
26
+ edgeUrl: stripSlash(edgeOverride),
12
27
  userAgent: `kelviq-mcp/${getPackageVersion()} (+https://kelviq.com)`,
28
+ env: kelviqEnv,
13
29
  };
14
30
  }
15
31
  import { createRequire } from 'node:module';
@@ -27,19 +43,36 @@ export function requireKey(config, scope) {
27
43
  const key = scope === 'server' ? config.serverApiKey : config.clientApiKey;
28
44
  if (!key) {
29
45
  const envVar = scope === 'server' ? 'KELVIQ_SERVER_API_KEY' : 'KELVIQ_CLIENT_API_KEY';
30
- throw new MissingKeyError(envVar, scope);
46
+ throw new MissingKeyError(envVar, scope, config.env);
31
47
  }
32
48
  return key;
33
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
+ }
34
57
  export class MissingKeyError extends Error {
35
58
  envVar;
36
59
  scope;
37
- constructor(envVar, scope) {
38
- super(`Missing ${envVar}. Set it in your MCP client config to enable ${scope}-scoped Kelviq API tools. ` +
39
- `Get keys at https://app.kelviq.com/settings/api-keys.`);
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)}.`);
40
64
  this.envVar = envVar;
41
65
  this.scope = scope;
66
+ this.env = env;
42
67
  this.name = 'MissingKeyError';
43
68
  }
44
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
+ }
45
78
  //# sourceMappingURL=config.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAWA,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AACzD,MAAM,gBAAgB,GAAG,gCAAgC,CAAC;AAC1D,MAAM,wBAAwB,GAAG,6BAA6B,CAAC;AAE/D,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO;QACL,YAAY,EAAE,GAAG,CAAC,qBAAqB,EAAE,IAAI,EAAE,IAAI,SAAS;QAC5D,YAAY,EAAE,GAAG,CAAC,qBAAqB,EAAE,IAAI,EAAE,IAAI,SAAS;QAC5D,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,gBAAgB,CAAC;QACpE,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,gBAAgB,CAAC;QACpE,eAAe,EAAE,UAAU,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,wBAAwB,CAAC;QAC5F,SAAS,EAAE,cAAc,iBAAiB,EAAE,wBAAwB;KACrE,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAyB,CAAC;QAC/D,OAAO,GAAG,CAAC,OAAO,IAAI,KAAK,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAoB,EAAE,KAAgB;IAC/D,MAAM,GAAG,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;IAC3E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,uBAAuB,CAAC;QACtF,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACZ;IAAgC;IAA5D,YAA4B,MAAc,EAAkB,KAAgB;QAC1E,KAAK,CACH,WAAW,MAAM,gDAAgD,KAAK,4BAA4B;YAChG,uDAAuD,CAC1D,CAAC;QAJwB,WAAM,GAAN,MAAM,CAAQ;QAAkB,UAAK,GAAL,KAAK,CAAW;QAK1E,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}
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
- 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
+ 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
- kelviq provides two types of API keys for different use cases.
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 kelviq application dashboard.
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 manage customer subscriptions, including updates and cancellation. You can access these operations via the `subscriptions` attribute on an initialized Kelviq client instance.
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
- ### Updates an existing subscription to a new plan
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: "2025-12-31T23:59:59Z" // or "now" to end the trial immediately
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. `"2025-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.
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(session.customerPortalUrl);
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 to redirect the customer to their customer portal. This link is pre-authenticated — no login required.
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