@kelviq/mcp-server 0.4.0 → 1.0.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 +34 -26
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- 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/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 +114 -34
- 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 +102 -4
- 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/server.js +10 -1
- package/dist/server.js.map +1 -1
- 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
|
-
> **45 tools** across **9 domains**,
|
|
17
|
-
> OpenAPI spec. Works offline for docs Q&A — only API tools require a
|
|
16
|
+
> **45 tools** across **9 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
|
|
|
@@ -151,8 +159,8 @@ a self-hosted or otherwise custom deployment, set `KELVIQ_BASE_URL` /
|
|
|
151
159
|
|
|
152
160
|
## Resources
|
|
153
161
|
|
|
154
|
-
- `kelviq://docs/{section}/{slug}` — every
|
|
155
|
-
- `kelviq://openapi.json` — the full OpenAPI 3.0 spec (
|
|
162
|
+
- `kelviq://docs/{section}/{slug}` — every page in the Kelviq docs
|
|
163
|
+
- `kelviq://openapi.json` — the full OpenAPI 3.0 spec (every operation and schema)
|
|
156
164
|
- `kelviq://README` — top-level Kelviq overview
|
|
157
165
|
|
|
158
166
|
The OpenAPI spec is the source of truth for request/response shapes — for any
|
|
@@ -178,7 +186,7 @@ Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
|
|
|
178
186
|
|
|
179
187
|
```bash
|
|
180
188
|
npx -y @modelcontextprotocol/inspector \
|
|
181
|
-
npx -y @kelviq/mcp-server
|
|
189
|
+
npx -y @kelviq/mcp-server@latest
|
|
182
190
|
```
|
|
183
191
|
|
|
184
192
|
Opens a browser UI where you can browse all 45 tools, fill in arguments, and
|
|
@@ -188,7 +196,7 @@ before the command:
|
|
|
188
196
|
```bash
|
|
189
197
|
KELVIQ_SERVER_API_KEY=<key> KELVIQ_CLIENT_API_KEY=<key> \
|
|
190
198
|
npx -y @modelcontextprotocol/inspector \
|
|
191
|
-
npx -y @kelviq/mcp-server
|
|
199
|
+
npx -y @kelviq/mcp-server@latest
|
|
192
200
|
```
|
|
193
201
|
|
|
194
202
|
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":"AAgBA,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AACzD,MAAM,gBAAgB,GAAG,oCAAoC,CAAC;AAC9D,MAAM,gBAAgB,GAAG,sCAAsC,CAAC;AAChE,MAAM,gBAAgB,GAAG,2CAA2C,CAAC;AAErE,4EAA4E;AAC5E,8EAA8E;AAC9E,0EAA0E;AAC1E,yEAAyE;AACzE,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAE/C,SAAS,OAAO,CAAC,GAAsB,EAAE,IAAY,EAAE,UAAoB;IACzE,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,GAAuB;IACzC,uEAAuE;IACvE,sEAAsE;IACtE,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAI,GAAG,KAAK,YAAY,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAC1D,MAAM,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,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,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,cAAc,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACrF,MAAM,cAAc,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACrF,2EAA2E;IAC3E,kEAAkE;IAClE,wDAAwD;IACxD,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,IAAI,CAAC,yBAAyB,CAAC,IAAI,cAAc,CAAC;IAClG,OAAO;QACL,YAAY,EAAE,IAAI,CAAC,uBAAuB,CAAC;QAC3C,YAAY,EAAE,IAAI,CAAC,uBAAuB,CAAC;QAC3C,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,cAAc,CAAC;QAC9D,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC;QACjC,SAAS,EAAE,cAAc,iBAAiB,EAAE,wBAAwB;QACpE,GAAG,EAAE,SAAS;QACd,WAAW,EAAE,MAAM,KAAK,SAAS;QACjC,cAAc;KACf,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,UAAU,iBAAiB;IAC/B,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,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0EAA0E;AAC1E,oEAAoE;AACpE,kDAAkD;AAClD,SAAS,UAAU,CAAC,GAAc;IAChC,MAAM,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IACpD,OAAO,iDAAiD,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEtB;IACA;IACA;IAHlB,YACkB,MAAc,EACd,KAAgB,EAChB,MAAiB,SAAS;QAE1C,KAAK,CACH,WAAW,MAAM,gDAAgD,KAAK,2BAA2B;YAC/F,eAAe,GAAG,6BAA6B,UAAU,CAAC,GAAG,CAAC,GAAG,CACpE,CAAC;QAPc,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAW;QAChB,QAAG,GAAH,GAAG,CAAuB;QAM1C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACZ;IAA5B,YAA4B,KAAa;QACvC,KAAK,CAAC,uBAAuB,KAAK,gDAAgD,CAAC,CAAC;QAD1D,UAAK,GAAL,KAAK,CAAQ;QAEvC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}
|
|
@@ -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.
|