@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.
Files changed (63) hide show
  1. package/README.md +34 -26
  2. package/dist/config.d.ts +4 -0
  3. package/dist/config.js +30 -9
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/backend-integration/better-auth.md +369 -0
  6. package/dist/docs/backend-integration/node-sdk.md +373 -5
  7. package/dist/docs/backend-integration/python-sdk.md +444 -6
  8. package/dist/docs/changelog/api.md +516 -5
  9. package/dist/docs/changelog/app.md +162 -0
  10. package/dist/docs/changelog/cli.md +33 -0
  11. package/dist/docs/changelog/mcp-server.md +23 -0
  12. package/dist/docs/changelog/node-sdk.md +124 -0
  13. package/dist/docs/changelog/python-sdk.md +135 -0
  14. package/dist/docs/checkout/apply-a-discount-code.md +150 -0
  15. package/dist/docs/checkout/checkout-configuration.md +88 -22
  16. package/dist/docs/checkout/checkout-metadata.md +219 -0
  17. package/dist/docs/checkout/static-checkout-url.md +201 -0
  18. package/dist/docs/cli/commands.md +1 -1
  19. package/dist/docs/cli/environments.md +17 -9
  20. package/dist/docs/cli/kelviq-config.md +35 -1
  21. package/dist/docs/cli/overview.md +2 -0
  22. package/dist/docs/coustomers-management/overview.md +15 -19
  23. package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
  24. package/dist/docs/frontend-integration/react-ui.md +51 -16
  25. package/dist/docs/getstarted/fees.md +45 -54
  26. package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
  27. package/dist/docs/getstarted/review-process.md +3 -3
  28. package/dist/docs/guides/agent-toolkit.md +143 -0
  29. package/dist/docs/guides/mcp-server.md +114 -34
  30. package/dist/docs/guides/migrate-from-cashfree.md +7 -0
  31. package/dist/docs/guides/sandbox.md +34 -0
  32. package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
  33. package/dist/docs/guides/subscription-integration.md +28 -4
  34. package/dist/docs/guides/webhooks.md +367 -6
  35. package/dist/docs/manifest.json +102 -4
  36. package/dist/docs/openapi.json +7411 -2648
  37. package/dist/docs/payouts/overview.md +30 -0
  38. package/dist/docs/payouts/transactions.md +50 -6
  39. package/dist/docs/product-catalog/create-a-feature.md +113 -0
  40. package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
  41. package/dist/docs/product-catalog/discounts.md +25 -12
  42. package/dist/docs/product-catalog/entitlements.md +53 -16
  43. package/dist/docs/product-catalog/free-and-trials.md +8 -4
  44. package/dist/docs/product-catalog/location-based-pricing.md +2 -0
  45. package/dist/docs/product-catalog/one-time-payments.md +4 -0
  46. package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
  47. package/dist/docs/product-catalog/plans.md +14 -0
  48. package/dist/docs/product-catalog/products.md +5 -13
  49. package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
  50. package/dist/docs/product-catalog/subscriptions.md +109 -12
  51. package/dist/docs/product-catalog/usage-alerts.md +257 -0
  52. package/dist/docs/product-catalog/usage-based-billing.md +49 -12
  53. package/dist/docs/quickstart/dashboard-setup.md +1 -1
  54. package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
  55. package/dist/docs/sales/create-a-one-time-charge.md +144 -0
  56. package/dist/http/client.js +9 -2
  57. package/dist/http/client.js.map +1 -1
  58. package/dist/http/errors.d.ts +8 -0
  59. package/dist/http/errors.js +20 -0
  60. package/dist/http/errors.js.map +1 -1
  61. package/dist/server.js +10 -1
  62. package/dist/server.js.map +1 -1
  63. 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**, **69 resources** including the full
17
- > OpenAPI spec. Works offline for docs Q&A — only API tools require a key.
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
- -- npx -y @kelviq/mcp-server
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 `api.kelviq.com` |
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 | `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`. |
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
- > **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.
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
- To point at Kelviq sandbox:
100
+ The server uses your **sandbox** environment unless you opt in to live data:
96
101
 
97
102
  ```
98
- KELVIQ_ENV=sandbox
103
+ KELVIQ_ENV=production
99
104
  ```
100
105
 
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
+ | `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 conceptual page in the Kelviq docs (67 pages)
155
- - `kelviq://openapi.json` — the full OpenAPI 3.0 spec (55 operations, all schemas)
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
- function resolveEnv(env) {
6
- const raw = env.KELVIQ_ENV?.trim();
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 'production';
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 kelviqEnv = resolveEnv(env);
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 = env.KELVIQ_EDGE_URL?.trim() || env.KELVIQ_ENTITLEMENTS_URL?.trim() || defaultEdgeUrl;
40
+ const edgeOverride = read('KELVIQ_EDGE_URL') || read('KELVIQ_ENTITLEMENTS_URL') || defaultEdgeUrl;
22
41
  return {
23
- serverApiKey: env.KELVIQ_SERVER_API_KEY?.trim() || undefined,
24
- clientApiKey: env.KELVIQ_CLIENT_API_KEY?.trim() || undefined,
25
- baseUrl: stripSlash(env.KELVIQ_BASE_URL?.trim() || defaultBaseUrl),
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 = 'production') {
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;
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
@@ -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.