@kelviq/mcp-server 0.4.0 → 1.1.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 +43 -27
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/README.md +16 -0
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/changelog.md +3968 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +138 -35
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +98 -56
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +199 -0
- package/dist/schemas/kelviq.js +173 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +11 -1
- package/dist/server.js.map +1 -1
- package/dist/tools/discounts.d.ts +3 -0
- package/dist/tools/discounts.js +74 -0
- package/dist/tools/discounts.js.map +1 -0
- package/dist/tools/index.js +4 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/webhooks.d.ts +10 -0
- package/dist/tools/webhooks.js +114 -0
- package/dist/tools/webhooks.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,15 +13,16 @@ capabilities at once:
|
|
|
13
13
|
inside the package and exposed as MCP resources plus `docs_search` /
|
|
14
14
|
`docs_read` tools, so the LLM can ground its answers in the canonical docs.
|
|
15
15
|
|
|
16
|
-
> **
|
|
17
|
-
> OpenAPI spec. Works offline for docs Q&A — only API tools require a
|
|
16
|
+
> **56 tools** across **11 domains**, plus a resource for every docs page and
|
|
17
|
+
> the full OpenAPI spec. Works offline for docs Q&A — only API tools require a
|
|
18
|
+
> key.
|
|
18
19
|
|
|
19
20
|
## Install
|
|
20
21
|
|
|
21
22
|
```bash
|
|
22
23
|
npm install -g @kelviq/mcp-server
|
|
23
24
|
# or, no install needed:
|
|
24
|
-
npx -y @kelviq/mcp-server
|
|
25
|
+
npx -y @kelviq/mcp-server@latest
|
|
25
26
|
```
|
|
26
27
|
|
|
27
28
|
## Configure your MCP client
|
|
@@ -32,7 +33,8 @@ npx -y @kelviq/mcp-server
|
|
|
32
33
|
claude mcp add kelviq \
|
|
33
34
|
--env KELVIQ_SERVER_API_KEY=<your-server-key> \
|
|
34
35
|
--env KELVIQ_CLIENT_API_KEY=<your-client-key> \
|
|
35
|
-
--
|
|
36
|
+
--env KELVIQ_ENV=sandbox \
|
|
37
|
+
-- npx -y @kelviq/mcp-server@latest
|
|
36
38
|
```
|
|
37
39
|
|
|
38
40
|
> The `--` separator is required: it tells `claude` that everything after
|
|
@@ -41,6 +43,9 @@ claude mcp add kelviq \
|
|
|
41
43
|
|
|
42
44
|
Then `/mcp` in a new Claude Code session shows `kelviq` connected.
|
|
43
45
|
|
|
46
|
+
> Use keys from the environment `KELVIQ_ENV` names. `sandbox` is the
|
|
47
|
+
> default; for live data, use production keys with `KELVIQ_ENV=production`.
|
|
48
|
+
|
|
44
49
|
### Claude Desktop
|
|
45
50
|
|
|
46
51
|
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
|
|
@@ -50,10 +55,11 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
|
|
|
50
55
|
"mcpServers": {
|
|
51
56
|
"kelviq": {
|
|
52
57
|
"command": "npx",
|
|
53
|
-
"args": ["-y", "@kelviq/mcp-server"],
|
|
58
|
+
"args": ["-y", "@kelviq/mcp-server@latest"],
|
|
54
59
|
"env": {
|
|
55
60
|
"KELVIQ_SERVER_API_KEY": "server-...",
|
|
56
|
-
"KELVIQ_CLIENT_API_KEY": "client-..."
|
|
61
|
+
"KELVIQ_CLIENT_API_KEY": "client-...",
|
|
62
|
+
"KELVIQ_ENV": "sandbox"
|
|
57
63
|
}
|
|
58
64
|
}
|
|
59
65
|
}
|
|
@@ -65,7 +71,7 @@ Restart Claude Desktop. The hammer icon shows `kelviq` with all tools.
|
|
|
65
71
|
### Cursor / Zed / other MCP clients
|
|
66
72
|
|
|
67
73
|
Any client that supports stdio MCP servers — point it at
|
|
68
|
-
`npx -y @kelviq/mcp-server` with the env vars above.
|
|
74
|
+
`npx -y @kelviq/mcp-server@latest` with the env vars above.
|
|
69
75
|
|
|
70
76
|
### Get your API keys
|
|
71
77
|
|
|
@@ -81,28 +87,30 @@ key). Docs tools (`docs_search`, `docs_read`) work with no keys at all.
|
|
|
81
87
|
|
|
82
88
|
| Variable | Required | Default | Purpose |
|
|
83
89
|
|---|---|---|---|
|
|
84
|
-
| `KELVIQ_SERVER_API_KEY` | yes (for API tools) | — | Bearer token for
|
|
90
|
+
| `KELVIQ_SERVER_API_KEY` | yes (for API tools) | — | Bearer token for the core API |
|
|
85
91
|
| `KELVIQ_CLIENT_API_KEY` | only for `promotion_get` | — | Bearer token for the edge host |
|
|
86
|
-
| `KELVIQ_ENV` | no | `
|
|
87
|
-
| `KELVIQ_BASE_URL` | no | `
|
|
88
|
-
| `KELVIQ_EDGE_URL` | no | `
|
|
92
|
+
| `KELVIQ_ENV` | no | `sandbox` | `sandbox` or `production`; switches both API hosts (base + edge). Any other value fails fast at startup. |
|
|
93
|
+
| `KELVIQ_BASE_URL` | no | per `KELVIQ_ENV` | Override (self-host, custom routing). Wins over `KELVIQ_ENV`. |
|
|
94
|
+
| `KELVIQ_EDGE_URL` | no | per `KELVIQ_ENV` | Override the edge host (entitlements + promotions). Wins over `KELVIQ_ENV`. |
|
|
89
95
|
|
|
90
|
-
> **
|
|
91
|
-
>
|
|
92
|
-
>
|
|
93
|
-
> anywhere useful.
|
|
96
|
+
> **Keys only work against their own environment** — the API enforces
|
|
97
|
+
> key↔host binding server-side, so a sandbox key against the production host
|
|
98
|
+
> (or vice versa) returns 403s rather than routing you anywhere useful.
|
|
94
99
|
|
|
95
|
-
|
|
100
|
+
The server uses your **sandbox** environment unless you opt in to live data:
|
|
96
101
|
|
|
97
102
|
```
|
|
98
|
-
KELVIQ_ENV=
|
|
103
|
+
KELVIQ_ENV=production
|
|
99
104
|
```
|
|
100
105
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
`
|
|
105
|
-
|
|
106
|
+
| `KELVIQ_ENV` | Core API | Edge |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `sandbox` (default) | `https://sandboxapi.kelviq.com/api/v1` | `https://edge.sandboxapi.kelviq.com/api/v1` |
|
|
109
|
+
| `production` | `https://api.kelviq.com/api/v1` | `https://edge.api.kelviq.com/api/v1` |
|
|
110
|
+
|
|
111
|
+
To point at a self-hosted or otherwise custom deployment, set
|
|
112
|
+
`KELVIQ_BASE_URL` / `KELVIQ_EDGE_URL` explicitly instead — they always take
|
|
113
|
+
precedence over `KELVIQ_ENV`.
|
|
106
114
|
|
|
107
115
|
## Tools
|
|
108
116
|
|
|
@@ -129,6 +137,14 @@ a self-hosted or otherwise custom deployment, set `KELVIQ_BASE_URL` /
|
|
|
129
137
|
- `offering_get_product` — public pricing scoped to a product UUID
|
|
130
138
|
- `promotion_get` — resolve the active promotion for the caller's location *(uses Client API key, edge host)*
|
|
131
139
|
|
|
140
|
+
### Discounts
|
|
141
|
+
- `discount_list` / `discount_create` / `discount_retrieve` / `discount_archive`
|
|
142
|
+
- `discount_update` — enable or disable a code (nothing else can change after creation)
|
|
143
|
+
|
|
144
|
+
### Webhooks
|
|
145
|
+
- `webhook_endpoint_list` / `webhook_endpoint_create` / `webhook_endpoint_retrieve` / `webhook_endpoint_update` / `webhook_endpoint_delete` — signing secrets are hidden unless `revealSecret: true`
|
|
146
|
+
- `webhook_log_list` — delivery attempts from the last 30 days
|
|
147
|
+
|
|
132
148
|
### Catalog: Products
|
|
133
149
|
- `product_list` / `product_create` / `product_retrieve` / `product_update` / `product_archive`
|
|
134
150
|
- `product_settings_get` / `product_settings_update` — VPN/Tor/proxy policy, default currency, product URL
|
|
@@ -151,8 +167,8 @@ a self-hosted or otherwise custom deployment, set `KELVIQ_BASE_URL` /
|
|
|
151
167
|
|
|
152
168
|
## Resources
|
|
153
169
|
|
|
154
|
-
- `kelviq://docs/{section}/{slug}` — every
|
|
155
|
-
- `kelviq://openapi.json` — the full OpenAPI 3.0 spec (
|
|
170
|
+
- `kelviq://docs/{section}/{slug}` — every page in the Kelviq docs
|
|
171
|
+
- `kelviq://openapi.json` — the full OpenAPI 3.0 spec (every operation and schema)
|
|
156
172
|
- `kelviq://README` — top-level Kelviq overview
|
|
157
173
|
|
|
158
174
|
The OpenAPI spec is the source of truth for request/response shapes — for any
|
|
@@ -178,17 +194,17 @@ Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
|
|
|
178
194
|
|
|
179
195
|
```bash
|
|
180
196
|
npx -y @modelcontextprotocol/inspector \
|
|
181
|
-
npx -y @kelviq/mcp-server
|
|
197
|
+
npx -y @kelviq/mcp-server@latest
|
|
182
198
|
```
|
|
183
199
|
|
|
184
|
-
Opens a browser UI where you can browse all
|
|
200
|
+
Opens a browser UI where you can browse all 56 tools, fill in arguments, and
|
|
185
201
|
run them against the real Kelviq API. Pre-fill env vars by exporting them
|
|
186
202
|
before the command:
|
|
187
203
|
|
|
188
204
|
```bash
|
|
189
205
|
KELVIQ_SERVER_API_KEY=<key> KELVIQ_CLIENT_API_KEY=<key> \
|
|
190
206
|
npx -y @modelcontextprotocol/inspector \
|
|
191
|
-
npx -y @kelviq/mcp-server
|
|
207
|
+
npx -y @kelviq/mcp-server@latest
|
|
192
208
|
```
|
|
193
209
|
|
|
194
210
|
If the Inspector opens but the Command field shows the default placeholder
|
package/dist/config.d.ts
CHANGED
|
@@ -7,6 +7,10 @@ export interface KelviqConfig {
|
|
|
7
7
|
edgeUrl: string;
|
|
8
8
|
userAgent: string;
|
|
9
9
|
env: KelviqEnv;
|
|
10
|
+
/** False when KELVIQ_ENV was unset and `env` fell back to the sandbox default — lets auth errors explain that default. */
|
|
11
|
+
envExplicit?: boolean;
|
|
12
|
+
/** Variables whose value was an unexpanded `${...}` placeholder and were treated as unset. */
|
|
13
|
+
unexpandedVars?: string[];
|
|
10
14
|
}
|
|
11
15
|
export declare function loadConfig(env?: NodeJS.ProcessEnv): KelviqConfig;
|
|
12
16
|
export declare function getPackageVersion(): string;
|
package/dist/config.js
CHANGED
|
@@ -2,30 +2,51 @@ const DEFAULT_BASE_URL = 'https://api.kelviq.com/api/v1';
|
|
|
2
2
|
const DEFAULT_EDGE_URL = 'https://edge.api.kelviq.com/api/v1';
|
|
3
3
|
const SANDBOX_BASE_URL = 'https://sandboxapi.kelviq.com/api/v1';
|
|
4
4
|
const SANDBOX_EDGE_URL = 'https://edge.sandboxapi.kelviq.com/api/v1';
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
// A client that doesn't expand env references (Claude Desktop), or a config
|
|
6
|
+
// referencing a variable that isn't set (Claude Code passes "${NAME}" through
|
|
7
|
+
// as-is), hands us the literal placeholder. Treat it as unset rather than
|
|
8
|
+
// crashing on KELVIQ_ENV or sending "${KELVIQ_SERVER_API_KEY}" as a key.
|
|
9
|
+
const UNEXPANDED_PLACEHOLDER = /^\$\{[^}]*\}$/;
|
|
10
|
+
function readVar(env, name, unexpanded) {
|
|
11
|
+
const value = env[name]?.trim();
|
|
12
|
+
if (!value)
|
|
13
|
+
return undefined;
|
|
14
|
+
if (UNEXPANDED_PLACEHOLDER.test(value)) {
|
|
15
|
+
unexpanded.push(name);
|
|
16
|
+
return undefined;
|
|
17
|
+
}
|
|
18
|
+
return value;
|
|
19
|
+
}
|
|
20
|
+
function resolveEnv(raw) {
|
|
21
|
+
// Sandbox by default since 1.0.0: touching live data takes an explicit
|
|
22
|
+
// KELVIQ_ENV=production, so an agent that forgets the variable can't.
|
|
7
23
|
if (!raw)
|
|
8
|
-
return '
|
|
24
|
+
return 'sandbox';
|
|
9
25
|
if (raw === 'production' || raw === 'sandbox')
|
|
10
26
|
return raw;
|
|
11
27
|
throw new InvalidEnvError(raw);
|
|
12
28
|
}
|
|
13
29
|
export function loadConfig(env = process.env) {
|
|
14
30
|
const stripSlash = (u) => u.replace(/\/+$/, '');
|
|
15
|
-
const
|
|
31
|
+
const unexpandedVars = [];
|
|
32
|
+
const read = (name) => readVar(env, name, unexpandedVars);
|
|
33
|
+
const rawEnv = read('KELVIQ_ENV');
|
|
34
|
+
const kelviqEnv = resolveEnv(rawEnv);
|
|
16
35
|
const defaultBaseUrl = kelviqEnv === 'sandbox' ? SANDBOX_BASE_URL : DEFAULT_BASE_URL;
|
|
17
36
|
const defaultEdgeUrl = kelviqEnv === 'sandbox' ? SANDBOX_EDGE_URL : DEFAULT_EDGE_URL;
|
|
18
37
|
// KELVIQ_ENTITLEMENTS_URL is honored as a legacy alias so existing configs
|
|
19
38
|
// don't break, but KELVIQ_EDGE_URL is the canonical name now that
|
|
20
39
|
// entitlements and promotions share a single edge host.
|
|
21
|
-
const edgeOverride =
|
|
40
|
+
const edgeOverride = read('KELVIQ_EDGE_URL') || read('KELVIQ_ENTITLEMENTS_URL') || defaultEdgeUrl;
|
|
22
41
|
return {
|
|
23
|
-
serverApiKey:
|
|
24
|
-
clientApiKey:
|
|
25
|
-
baseUrl: stripSlash(
|
|
42
|
+
serverApiKey: read('KELVIQ_SERVER_API_KEY'),
|
|
43
|
+
clientApiKey: read('KELVIQ_CLIENT_API_KEY'),
|
|
44
|
+
baseUrl: stripSlash(read('KELVIQ_BASE_URL') || defaultBaseUrl),
|
|
26
45
|
edgeUrl: stripSlash(edgeOverride),
|
|
27
46
|
userAgent: `kelviq-mcp/${getPackageVersion()} (+https://kelviq.com)`,
|
|
28
47
|
env: kelviqEnv,
|
|
48
|
+
envExplicit: rawEnv !== undefined,
|
|
49
|
+
unexpandedVars,
|
|
29
50
|
};
|
|
30
51
|
}
|
|
31
52
|
import { createRequire } from 'node:module';
|
|
@@ -58,7 +79,7 @@ export class MissingKeyError extends Error {
|
|
|
58
79
|
envVar;
|
|
59
80
|
scope;
|
|
60
81
|
env;
|
|
61
|
-
constructor(envVar, scope, env = '
|
|
82
|
+
constructor(envVar, scope, env = 'sandbox') {
|
|
62
83
|
super(`Missing ${envVar}. Set it in your MCP client config to enable ${scope}-scoped Kelviq API tools ` +
|
|
63
84
|
`against the ${env} environment. Get keys at ${keyPageUrl(env)}.`);
|
|
64
85
|
this.envVar = envVar;
|
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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"}
|
package/dist/docs/README.md
CHANGED
|
@@ -120,6 +120,22 @@ To contribute to Kelviq docs:
|
|
|
120
120
|
- Link to related documentation
|
|
121
121
|
- Keep sections concise and focused
|
|
122
122
|
|
|
123
|
+
### Changelog
|
|
124
|
+
|
|
125
|
+
All release notes live in one page, `changelog.mdx`, newest first. Add each release as an `<Update>` at the top of the page, tagged with the product exactly as it appears in the filter. The product filter above the entries matches on that tag, and so does the sidebar:
|
|
126
|
+
|
|
127
|
+
```mdx
|
|
128
|
+
<Update label="v2.9.0" description="October 1, 2026" tags={["Node SDK"]}>
|
|
129
|
+
...
|
|
130
|
+
</Update>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Keep the label a plain string; an expression label loses its anchor link. Products are `App`, `JS SDK`, `React SDK`, `Node SDK`, `Python SDK`, `JS Promotions UI`, `MCP Server`, `CLI`, and `API`.
|
|
134
|
+
|
|
135
|
+
The sidebar lists the same products, as anchors under the Changelog tab in `docs.json`. They must be written as absolute URLs (`https://docs.kelviq.com/changelog#node-sdk`): Mintlify rewrites a relative href containing a hash to `/`. Absolute URLs would open in a new tab, so `ChangelogFilter` rewrites them back to same-page links once the page loads. To add a product, add it in three places: the `products` list passed to `<ChangelogFilter>`, the anchors in `docs.json`, and the redirect if the product had its own page before.
|
|
136
|
+
|
|
137
|
+
Those anchors would otherwise carry an icon and no group title, so `custom.css` hides the icon, heads the list with "Changelog", and highlights whichever product is selected. Those rules only apply while `ChangelogFilter` is on screen, which it marks with `data-changelog-page` on the body.
|
|
138
|
+
|
|
123
139
|
## Need Help?
|
|
124
140
|
|
|
125
141
|
- **Can't find something?** - Use the search feature (top of page)
|
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Better Auth"
|
|
3
|
+
slug: "backend-integration/better-auth"
|
|
4
|
+
section: "backend-integration"
|
|
5
|
+
description: "Wire Kelviq billing into your Better Auth server with @kelviq/better-auth"
|
|
6
|
+
---
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
`@kelviq/better-auth` is a
|
|
10
|
+
[Better Auth](https://better-auth.com) plugin that puts billing directly on
|
|
11
|
+
your auth server: it creates a Kelviq customer automatically on signup and
|
|
12
|
+
exposes checkout, customer portal, entitlement, and usage-reporting endpoints
|
|
13
|
+
from the same server that already handles your sessions.
|
|
14
|
+
|
|
15
|
+
Kelviq's `customerId` is caller-defined, so the plugin uses Better Auth's
|
|
16
|
+
`user.id` as the Kelviq customer id directly — there is no external-id
|
|
17
|
+
mapping to maintain. Entitlement checks are then available straight off your
|
|
18
|
+
auth client (`authClient.kelviq.hasAccess(...)`), without a separate billing
|
|
19
|
+
SDK call from the frontend.
|
|
20
|
+
|
|
21
|
+
## Install
|
|
22
|
+
|
|
23
|
+
```shell
|
|
24
|
+
npm install @kelviq/better-auth @kelviq/node-sdk better-auth
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`better-auth` (`>=1.6.0`) and `@kelviq/node-sdk` (`>=2.0.0`) are peer
|
|
28
|
+
dependencies — bring your own versions.
|
|
29
|
+
|
|
30
|
+
The package is not yet published to npm — the plugin API documented on this
|
|
31
|
+
page is final, but the install command above will not resolve until the
|
|
32
|
+
first release ships.
|
|
33
|
+
|
|
34
|
+
## Server setup
|
|
35
|
+
|
|
36
|
+
Construct an `@kelviq/node-sdk` client with your **Server API Key** and pass
|
|
37
|
+
it into `kelviq()`, then add whichever sub-plugins you need via `use`:
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { betterAuth } from 'better-auth';
|
|
41
|
+
import { Kelviq } from '@kelviq/node-sdk';
|
|
42
|
+
import { kelviq, portal, checkout, entitlements, usage, webhooks } from '@kelviq/better-auth';
|
|
43
|
+
|
|
44
|
+
const kelviqClient = new Kelviq({ accessToken: process.env.KELVIQ_SERVER_API_KEY! });
|
|
45
|
+
|
|
46
|
+
export const auth = betterAuth({
|
|
47
|
+
// ...your existing config
|
|
48
|
+
plugins: [
|
|
49
|
+
kelviq({
|
|
50
|
+
client: kelviqClient,
|
|
51
|
+
createCustomerOnSignUp: true,
|
|
52
|
+
getCustomerCreateParams: ({ user }) => ({
|
|
53
|
+
metadata: { source: 'better-auth' },
|
|
54
|
+
}),
|
|
55
|
+
use: [
|
|
56
|
+
portal(),
|
|
57
|
+
checkout({
|
|
58
|
+
plans: [
|
|
59
|
+
{ slug: 'pro', planIdentifier: 'plan-pro', chargePeriod: 'MONTHLY' },
|
|
60
|
+
{ slug: 'free', planIdentifier: 'plan-free', chargePeriod: 'ONE_TIME' },
|
|
61
|
+
],
|
|
62
|
+
successUrl: '/success?checkout_id={CHECKOUT_ID}',
|
|
63
|
+
}),
|
|
64
|
+
entitlements(),
|
|
65
|
+
usage(),
|
|
66
|
+
webhooks({
|
|
67
|
+
secret: process.env.KELVIQ_WEBHOOK_SECRET!,
|
|
68
|
+
}),
|
|
69
|
+
],
|
|
70
|
+
}),
|
|
71
|
+
],
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**Security warning:** the `Kelviq` client instance carries your Server API
|
|
76
|
+
Key. Construct it only in server-side code and pass it into `kelviq()` —
|
|
77
|
+
never import `@kelviq/node-sdk` or this client into anything that ships to
|
|
78
|
+
the browser. `@kelviq/better-auth/client` (used below) never imports the
|
|
79
|
+
server package, by design.
|
|
80
|
+
|
|
81
|
+
## Customer lifecycle
|
|
82
|
+
|
|
83
|
+
Set `createCustomerOnSignUp: true` to create a Kelviq customer after every
|
|
84
|
+
new Better Auth signup, with `customerId` set to `user.id`. The customer's
|
|
85
|
+
email and name are kept in sync automatically whenever the Better Auth user
|
|
86
|
+
record changes.
|
|
87
|
+
|
|
88
|
+
Use `getCustomerCreateParams` to attach extra data at creation time. It only
|
|
89
|
+
accepts `metadata` — the Kelviq customer-create call this plugin makes does
|
|
90
|
+
not carry a `billingAddress` field:
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
getCustomerCreateParams: ({ user }) => ({
|
|
94
|
+
metadata: { plan: 'trial', source: 'better-auth' },
|
|
95
|
+
}),
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
A Kelviq outage never blocks registration. If customer creation or the
|
|
99
|
+
sync-on-update call fails, the error is caught and logged through Better
|
|
100
|
+
Auth's logger — signup and profile updates always succeed regardless of
|
|
101
|
+
Kelviq's availability.
|
|
102
|
+
|
|
103
|
+
## Client setup
|
|
104
|
+
|
|
105
|
+
Add `kelviqClient()` to your Better Auth client to get typed
|
|
106
|
+
`authClient.kelviq.*` methods:
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
import { createAuthClient } from 'better-auth/client';
|
|
110
|
+
import { kelviqClient } from '@kelviq/better-auth/client';
|
|
111
|
+
|
|
112
|
+
export const authClient = createAuthClient({
|
|
113
|
+
plugins: [kelviqClient()],
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Portal
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
const { data } = await authClient.kelviq.portal();
|
|
121
|
+
window.location.href = data.url;
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`POST /kelviq/portal` resolves the authenticated session, creates a fresh
|
|
125
|
+
Kelviq customer portal session for `customerId === session.user.id`, and
|
|
126
|
+
returns the already-signed portal URL. The underlying token is short-lived
|
|
127
|
+
and single-use — create a new session (call `portal()` again) per visit
|
|
128
|
+
rather than caching the URL. An unauthenticated request gets a `401`.
|
|
129
|
+
|
|
130
|
+
## Checkout
|
|
131
|
+
|
|
132
|
+
Configure `checkout()` with a `plans` map from a stable `slug` to the actual
|
|
133
|
+
Kelviq `planIdentifier` and `chargePeriod`:
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
checkout({
|
|
137
|
+
plans: [
|
|
138
|
+
{ slug: 'pro', planIdentifier: 'plan-pro', chargePeriod: 'MONTHLY' },
|
|
139
|
+
{ slug: 'free', planIdentifier: 'plan-free', chargePeriod: 'ONE_TIME' },
|
|
140
|
+
],
|
|
141
|
+
successUrl: '/success?checkout_id={CHECKOUT_ID}', // relative paths resolve against baseURL
|
|
142
|
+
authenticatedUsersOnly: true, // default
|
|
143
|
+
}),
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
const { data } = await authClient.kelviq.checkout({ slug: 'pro' });
|
|
148
|
+
window.location.href = data.url; // hosted checkout page
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`POST /kelviq/checkout` resolves a plan either by `{ slug }` (looked up in
|
|
152
|
+
`plans` — slug wins if both are given) or directly by `{ planIdentifier,
|
|
153
|
+
chargePeriod }`. An unknown slug returns `400` listing the known slugs.
|
|
154
|
+
`customerId` is never accepted from the request — it is always the session
|
|
155
|
+
user's id.
|
|
156
|
+
|
|
157
|
+
`chargePeriod` accepts any Kelviq charge period, including `ONE_TIME` — use
|
|
158
|
+
it for free or one-off plans that don't recur.
|
|
159
|
+
|
|
160
|
+
`authenticatedUsersOnly` defaults to `true`, in which case an unauthenticated
|
|
161
|
+
request gets a `401`. Set it to `false` to allow anonymous checkout:
|
|
162
|
+
`customerId` is then omitted from the checkout session, and Kelviq
|
|
163
|
+
creates or reuses a customer by the email entered on the hosted checkout
|
|
164
|
+
page.
|
|
165
|
+
|
|
166
|
+
## Entitlements
|
|
167
|
+
|
|
168
|
+
This is the differentiator over wiring a separate billing SDK into your
|
|
169
|
+
frontend: entitlement checks are available directly on the same auth client
|
|
170
|
+
your app already uses for sessions.
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
entitlements(),
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
const { data } = await authClient.kelviq.entitlements(); // every entitlement for the signed-in user
|
|
178
|
+
const { data } = await authClient.kelviq.entitlement({ query: { featureId: 'seats' } });
|
|
179
|
+
const { data } = await authClient.kelviq.hasAccess({ query: { featureId: 'seats' } }); // { hasAccess: boolean }
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Three authenticated `GET` endpoints, all scoped to the session user:
|
|
183
|
+
`/kelviq/entitlements` (all entitlements), `/kelviq/entitlement?featureId=...`
|
|
184
|
+
(one entitlement), and `/kelviq/has-access?featureId=...`
|
|
185
|
+
(`{ hasAccess: boolean }`). `customerId` is never accepted from the request —
|
|
186
|
+
one signed-in user can never read another user's entitlements by supplying a
|
|
187
|
+
different id.
|
|
188
|
+
|
|
189
|
+
These endpoints are for **frontend** gating (show/hide UI) only. Backend code
|
|
190
|
+
should call the `@kelviq/node-sdk` client's `entitlements` module directly —
|
|
191
|
+
routing a server-side gating check back through the auth server would be an
|
|
192
|
+
unnecessary extra hop.
|
|
193
|
+
|
|
194
|
+
## Usage reporting
|
|
195
|
+
|
|
196
|
+
```typescript
|
|
197
|
+
usage({ allowClientReporting: true }), // default: false — the endpoint 403s
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
```typescript
|
|
201
|
+
await authClient.kelviq.usage({ featureId: 'api-calls', value: 1, behaviour: 'DELTA' });
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`POST /kelviq/usage` reports usage for the *signed-in* user's Kelviq
|
|
205
|
+
customer — `customerId` is never accepted from the request.
|
|
206
|
+
|
|
207
|
+
`allowClientReporting` defaults to `false` and the endpoint returns `403`
|
|
208
|
+
until you opt in. Client-originated usage reporting is spoofable by whoever
|
|
209
|
+
is logged in, and a `DELTA` report replayed by a flaky client double-counts
|
|
210
|
+
usage. Prefer reporting usage from your backend via the `@kelviq/node-sdk`
|
|
211
|
+
client's `reporting.reportUsage(...)` directly, where you control exactly
|
|
212
|
+
when and how often a report fires. Only enable client reporting for trusted
|
|
213
|
+
client-side metering, such as a `SET` report of a value the client can
|
|
214
|
+
reliably observe once.
|
|
215
|
+
|
|
216
|
+
## Webhooks
|
|
217
|
+
|
|
218
|
+
Register an endpoint in the Kelviq dashboard (**Settings → Webhooks**) using
|
|
219
|
+
your app's own domain and Better Auth's `basePath` (`/api/auth` by default):
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
https://<your-app>/api/auth/kelviq/webhooks
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The dashboard generates a signing secret in the format `kq_whsec_<random>`,
|
|
226
|
+
shown once — store it as `KELVIQ_WEBHOOK_SECRET` and pass it to `webhooks()`:
|
|
227
|
+
|
|
228
|
+
```typescript
|
|
229
|
+
import { webhooks } from '@kelviq/better-auth';
|
|
230
|
+
|
|
231
|
+
kelviq({
|
|
232
|
+
client: kelviqClient,
|
|
233
|
+
use: [
|
|
234
|
+
webhooks({
|
|
235
|
+
secret: process.env.KELVIQ_WEBHOOK_SECRET!,
|
|
236
|
+
onCheckoutCompleted: async ({ data }) => {
|
|
237
|
+
// grant access, e.g. mark the order's customer as entitled
|
|
238
|
+
},
|
|
239
|
+
onSubscriptionCancelled: async ({ data }) => {
|
|
240
|
+
// revoke access
|
|
241
|
+
},
|
|
242
|
+
onPayload: async (event) => {
|
|
243
|
+
// catch-all: called for every verified event, including ones this
|
|
244
|
+
// package doesn't have a named handler for yet
|
|
245
|
+
},
|
|
246
|
+
}),
|
|
247
|
+
],
|
|
248
|
+
});
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
This endpoint is unauthenticated by design — there is no
|
|
252
|
+
`authClient.kelviq.webhooks()`, and none is intended. Kelviq's servers are
|
|
253
|
+
the caller, not your frontend, so it's deliberately excluded from the typed
|
|
254
|
+
client. The `webhook-signature` header (verified with
|
|
255
|
+
`crypto.timingSafeEqual` against an HMAC-SHA256 of the raw request body) is
|
|
256
|
+
the only authentication.
|
|
257
|
+
|
|
258
|
+
All 15 event types have a named handler option:
|
|
259
|
+
|
|
260
|
+
| Handler | Event |
|
|
261
|
+
|---|---|
|
|
262
|
+
| `onCheckoutCompleted` | `checkout.completed` |
|
|
263
|
+
| `onCustomerCreated` | `customer.created` |
|
|
264
|
+
| `onCustomerUpdated` | `customer.updated` |
|
|
265
|
+
| `onOrderCreated` | `order.created` |
|
|
266
|
+
| `onOrderUpdated` | `order.updated` |
|
|
267
|
+
| `onOrderRefunded` | `order.refunded` |
|
|
268
|
+
| `onSubscriptionCreated` | `subscription.created` |
|
|
269
|
+
| `onSubscriptionUpdated` | `subscription.updated` |
|
|
270
|
+
| `onSubscriptionCancelled` | `subscription.cancelled` |
|
|
271
|
+
| `onSubscriptionPlanChanged` | `subscription.plan_changed` |
|
|
272
|
+
| `onFeatureUsageAlert` | `feature.usage_alert` |
|
|
273
|
+
| `onInvoiceCreated` | `invoice.created` |
|
|
274
|
+
| `onInvoicePaid` | `invoice.paid` |
|
|
275
|
+
| `onRefundCreated` | `refund.created` |
|
|
276
|
+
| `onRefundUpdated` | `refund.updated` |
|
|
277
|
+
|
|
278
|
+
A handler for a specific event runs first (if configured), then `onPayload`
|
|
279
|
+
(if configured) — every verified event reaches `onPayload`, including event
|
|
280
|
+
types this package doesn't have a named option for yet.
|
|
281
|
+
|
|
282
|
+
**If a handler throws, the endpoint returns `500`.** This is intentional:
|
|
283
|
+
Kelviq [retries](/guides/webhooks#how-it-works) non-`2xx` deliveries up to 3
|
|
284
|
+
times, 60 seconds apart, so a handler that throws on a transient failure (a
|
|
285
|
+
DB blip, a downstream API outage) gets a free retry. This means **handlers
|
|
286
|
+
must be idempotent** — the same event can be delivered more than once. Use
|
|
287
|
+
the event's `id` (which matches the `webhook-id` header) as a deduplication
|
|
288
|
+
key; this package does not persist or deduplicate events itself.
|
|
289
|
+
|
|
290
|
+
### Verifying webhooks outside Better Auth
|
|
291
|
+
|
|
292
|
+
If you need to verify a Kelviq webhook from a server that isn't running this
|
|
293
|
+
plugin (or Better Auth at all), the signature verifier is exported
|
|
294
|
+
standalone:
|
|
295
|
+
|
|
296
|
+
```typescript
|
|
297
|
+
import { verifyWebhookSignature } from '@kelviq/better-auth';
|
|
298
|
+
|
|
299
|
+
const result = verifyWebhookSignature({
|
|
300
|
+
secret: process.env.KELVIQ_WEBHOOK_SECRET!,
|
|
301
|
+
id: request.headers.get('webhook-id')!,
|
|
302
|
+
timestamp: request.headers.get('webhook-timestamp')!,
|
|
303
|
+
signature: request.headers.get('webhook-signature')!,
|
|
304
|
+
rawBody: await request.text(), // must be the exact wire bytes, not re-serialized JSON
|
|
305
|
+
});
|
|
306
|
+
// result: { valid: boolean, reason?: 'signature' | 'timestamp' | 'format' }
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
The algorithm matches the [webhooks guide](/guides/webhooks#verifying-signatures):
|
|
310
|
+
the signed string is `{webhook-id}.{webhook-timestamp}.{raw-request-body}`,
|
|
311
|
+
HMAC-SHA256 keyed with your signing secret used verbatim, hex digest, `v1,`
|
|
312
|
+
prefix stripped from the header before a constant-time comparison.
|
|
313
|
+
|
|
314
|
+
## Test your integration
|
|
315
|
+
|
|
316
|
+
### Sandbox checkout and webhooks
|
|
317
|
+
|
|
318
|
+
Point your `Kelviq` client at the [sandbox environment](/guides/sandbox) with
|
|
319
|
+
a sandbox Server API Key so signups, checkouts, and portal sessions created
|
|
320
|
+
while testing never touch production data:
|
|
321
|
+
|
|
322
|
+
```typescript
|
|
323
|
+
const kelviqClient = new Kelviq({
|
|
324
|
+
accessToken: process.env.KELVIQ_SANDBOX_SERVER_API_KEY!,
|
|
325
|
+
environment: 'sandbox',
|
|
326
|
+
});
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Run a checkout through `authClient.kelviq.checkout(...)` and complete payment
|
|
330
|
+
with the Stripe test card `4242 4242 4242 4242` (any future expiration date,
|
|
331
|
+
any valid CVC). See the [sandbox guide](/guides/sandbox) for the full set of
|
|
332
|
+
test card numbers and isolation details.
|
|
333
|
+
|
|
334
|
+
### Local webhook testing
|
|
335
|
+
|
|
336
|
+
The Kelviq dashboard needs a public HTTPS URL to deliver webhooks to, so
|
|
337
|
+
local development requires either:
|
|
338
|
+
|
|
339
|
+
- A tunnel (e.g. `ngrok http 3000`) pointed at your dev server, with the
|
|
340
|
+
tunnel's HTTPS URL plus `/api/auth/kelviq/webhooks` registered as the
|
|
341
|
+
endpoint in the dashboard, or
|
|
342
|
+
- Self-signed test events posted directly to your endpoint, computing the
|
|
343
|
+
signature yourself with the same algorithm `verifyWebhookSignature` checks:
|
|
344
|
+
|
|
345
|
+
```javascript
|
|
346
|
+
const crypto = require('crypto');
|
|
347
|
+
|
|
348
|
+
const secret = 'kq_whsec_test_secret';
|
|
349
|
+
const id = 'wh_test_1';
|
|
350
|
+
const timestamp = Math.floor(Date.now() / 1000).toString();
|
|
351
|
+
const body = JSON.stringify({
|
|
352
|
+
id,
|
|
353
|
+
type: 'subscription.created',
|
|
354
|
+
created_at: new Date().toISOString(),
|
|
355
|
+
data: { object: { id: 'sub_test_1', status: 'active' } },
|
|
356
|
+
});
|
|
357
|
+
|
|
358
|
+
const signedPayload = `${id}.${timestamp}.${body}`;
|
|
359
|
+
const signature = crypto.createHmac('sha256', secret).update(signedPayload, 'utf8').digest('hex');
|
|
360
|
+
|
|
361
|
+
// POST `body` to your endpoint with headers:
|
|
362
|
+
// webhook-id: id
|
|
363
|
+
// webhook-timestamp: timestamp
|
|
364
|
+
// webhook-signature: `v1,${signature}`
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
Never reuse a real signing secret in a test script or commit it to source
|
|
368
|
+
control — use a placeholder secret for local self-signed testing, and only
|
|
369
|
+
the dashboard-issued secret for actual Kelviq deliveries.
|