@kelviq/mcp-server 1.0.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.
@@ -6,7 +6,7 @@ description: "Install Kelviq into Claude Code with one plugin — or add the Kel
6
6
  ---
7
7
  The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus five **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
8
8
 
9
- Skills are the missing half of tool access. The MCP server gives your agent 45 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
9
+ Skills are the missing half of tool access. The MCP server gives your agent 56 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
10
10
 
11
11
  **The Agent Toolkit is new.** The skills and their names are stable, but content will keep improving alongside the platform. The bundled MCP server is always the latest published `@kelviq/mcp-server` — no toolkit update needed when the server improves.
12
12
 
@@ -32,7 +32,7 @@ export KELVIQ_CLIENT_API_KEY="<your-sandbox-client-key>" # only needed for pro
32
32
 
33
33
  Get keys at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
34
34
 
35
- **Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 45 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
35
+ **Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 56 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
36
36
 
37
37
  No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work without any credentials, so your agent can answer Kelviq questions from the documentation immediately. API tools return a clear `Configuration error` until a key is set.
38
38
 
@@ -98,7 +98,7 @@ Wraps the [Kelviq CLI](/cli/overview) loop for agents: `kelviq pull` → edit `k
98
98
 
99
99
  The toolkit layers three things, each doing what it's best at:
100
100
 
101
- 1. **Tools** (from the MCP server) do the work — 45 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
101
+ 1. **Tools** (from the MCP server) do the work — 56 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
102
102
  2. **Skills** (from this toolkit) supply the judgment — which tool, in what order, with which confirmations. They activate automatically based on what you ask.
103
103
  3. **Prompts** (from the MCP server) are guided, step-by-step flows you invoke explicitly — `setup_product`, `launch_plan`, and `diagnose_customer`. The skills route to them rather than duplicating them.
104
104
 
@@ -10,7 +10,7 @@ Instead of asking your assistant to "write me a curl command," you describe the
10
10
 
11
11
  **Using Claude Code?** The fastest install is the [Agent Toolkit](/guides/agent-toolkit) plugin — two commands set up this MCP server *and* five Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.
12
12
 
13
- **45 tools** spanning customers, checkout, subscriptions, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and the full OpenAPI spec, and **3 guided prompts** for the most common workflows. Every tool carries [MCP safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
13
+ **56 tools** spanning customers, checkout, subscriptions, discounts, webhooks, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and the full OpenAPI spec, and **3 guided prompts** for the most common workflows. Every tool carries [MCP safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
14
14
 
15
15
  ---
16
16
 
@@ -56,7 +56,7 @@ claude mcp add kelviq \
56
56
 
57
57
  The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
58
58
 
59
- Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 45 tools`.
59
+ Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 56 tools`.
60
60
 
61
61
  Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
62
62
 
@@ -251,6 +251,29 @@ Tools are grouped by domain. Each tool name uses `domain_action` form (`customer
251
251
  | `offering_get_product` | Fetch public pricing scoped to a product UUID. Includes localized prices + customer subscription state. |
252
252
  | `promotion_get` | Resolve the active promotion for the caller's location. Uses Client API key. |
253
253
 
254
+ ### Discounts
255
+
256
+ | Tool | Description |
257
+ |------|-------------|
258
+ | `discount_list` | List discount codes. Optional `search` across name and code, paginated. |
259
+ | `discount_create` | Create a percentage or fixed-amount code, optionally limited to products or plans with `appliesTo`. Merchant of Record organizations only. |
260
+ | `discount_retrieve` | Fetch one discount, including how often it's been redeemed and whether it's active. |
261
+ | `discount_update` | Enable or disable a code with `isActive`. Nothing else can change after creation. |
262
+ | `discount_archive` | Archive a code so it can no longer be used. |
263
+
264
+ ### Webhooks
265
+
266
+ | Tool | Description |
267
+ |------|-------------|
268
+ | `webhook_endpoint_list` | List endpoints with their URLs, events and enabled state. |
269
+ | `webhook_endpoint_create` | Register a public URL for the events you choose. Localhost and private addresses are rejected. |
270
+ | `webhook_endpoint_retrieve` | Fetch one endpoint. |
271
+ | `webhook_endpoint_update` | Change an endpoint's URL, events or enabled state. |
272
+ | `webhook_endpoint_delete` | Delete an endpoint. Deliveries stop immediately. |
273
+ | `webhook_log_list` | Delivery attempts from the last 30 days, with status codes and retries. |
274
+
275
+ Signing secrets are hidden in webhook tool results. Pass `revealSecret: true` only when you need the value — your app reads the secret from its env file, so it rarely needs to appear in a conversation.
276
+
254
277
  ### Catalog: Products
255
278
 
256
279
  | Tool | Description |
@@ -28,67 +28,11 @@
28
28
  "path": "backend-integration/python-sdk.md"
29
29
  },
30
30
  {
31
- "slug": "changelog/api",
32
- "section": "changelog",
33
- "title": "API",
34
- "description": "Changelog for the Kelviq API",
35
- "path": "changelog/api.md"
36
- },
37
- {
38
- "slug": "changelog/app",
39
- "section": "changelog",
40
- "title": "App",
41
- "description": "Changelog for the Kelviq Dashboard",
42
- "path": "changelog/app.md"
43
- },
44
- {
45
- "slug": "changelog/cli",
46
- "section": "changelog",
47
- "title": "CLI",
48
- "description": "Changelog for @kelviq/cli",
49
- "path": "changelog/cli.md"
50
- },
51
- {
52
- "slug": "changelog/js-promotions-ui",
53
- "section": "changelog",
54
- "title": "JS Promotions UI",
55
- "description": "Changelog for @kelviq/js-promotions-ui",
56
- "path": "changelog/js-promotions-ui.md"
57
- },
58
- {
59
- "slug": "changelog/js-sdk",
60
- "section": "changelog",
61
- "title": "JS SDK",
62
- "description": "Changelog for @kelviq/js-sdk",
63
- "path": "changelog/js-sdk.md"
64
- },
65
- {
66
- "slug": "changelog/mcp-server",
67
- "section": "changelog",
68
- "title": "MCP Server",
69
- "description": "Changelog for @kelviq/mcp-server",
70
- "path": "changelog/mcp-server.md"
71
- },
72
- {
73
- "slug": "changelog/node-sdk",
74
- "section": "changelog",
75
- "title": "Node SDK",
76
- "description": "Changelog for @kelviq/node-sdk",
77
- "path": "changelog/node-sdk.md"
78
- },
79
- {
80
- "slug": "changelog/python-sdk",
81
- "section": "changelog",
82
- "title": "Python SDK",
83
- "description": "Changelog for kelviq-sdk (Python)",
84
- "path": "changelog/python-sdk.md"
85
- },
86
- {
87
- "slug": "changelog/react-sdk",
88
- "section": "changelog",
89
- "title": "React SDK",
90
- "description": "Changelog for @kelviq/react-sdk",
91
- "path": "changelog/react-sdk.md"
31
+ "slug": "changelog",
32
+ "section": "root",
33
+ "title": "Changelog",
34
+ "description": "Every Kelviq release across the dashboard, API, SDKs, and developer tools",
35
+ "path": "changelog.md"
92
36
  },
93
37
  {
94
38
  "slug": "checkout/apply-a-discount-code",
@@ -175,12 +175,16 @@ export declare const CreateCheckoutSession: z.ZodObject<{
175
175
  lockEmail: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
176
176
  defaultBillingCountry: z.ZodOptional<z.ZodNullable<z.ZodString>>;
177
177
  discountCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
178
+ trialPeriod: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
179
+ billingPeriodsEnabled: z.ZodOptional<z.ZodNullable<z.ZodString>>;
180
+ email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
178
181
  metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
179
182
  }, "strip", z.ZodTypeAny, {
180
183
  planIdentifier: string;
181
184
  successUrl: string;
182
185
  chargePeriod: "ONE_TIME" | "MONTHLY" | "YEARLY" | "WEEKLY" | "DAILY" | "THREE_MONTHS" | "SIX_MONTHS";
183
186
  customerId?: string | null | undefined;
187
+ email?: string | null | undefined;
184
188
  metadata?: Record<string, unknown> | null | undefined;
185
189
  features?: {
186
190
  identifier: string;
@@ -196,11 +200,14 @@ export declare const CreateCheckoutSession: z.ZodObject<{
196
200
  lockEmail?: boolean | null | undefined;
197
201
  defaultBillingCountry?: string | null | undefined;
198
202
  discountCode?: string | null | undefined;
203
+ trialPeriod?: number | null | undefined;
204
+ billingPeriodsEnabled?: string | null | undefined;
199
205
  }, {
200
206
  planIdentifier: string;
201
207
  successUrl: string;
202
208
  chargePeriod: "ONE_TIME" | "MONTHLY" | "YEARLY" | "WEEKLY" | "DAILY" | "THREE_MONTHS" | "SIX_MONTHS";
203
209
  customerId?: string | null | undefined;
210
+ email?: string | null | undefined;
204
211
  metadata?: Record<string, unknown> | null | undefined;
205
212
  features?: {
206
213
  identifier: string;
@@ -216,6 +223,8 @@ export declare const CreateCheckoutSession: z.ZodObject<{
216
223
  lockEmail?: boolean | null | undefined;
217
224
  defaultBillingCountry?: string | null | undefined;
218
225
  discountCode?: string | null | undefined;
226
+ trialPeriod?: number | null | undefined;
227
+ billingPeriodsEnabled?: string | null | undefined;
219
228
  }>;
220
229
  export declare const GetEntitlements: z.ZodObject<{
221
230
  customerId: z.ZodString;
@@ -346,6 +355,7 @@ export declare const UpdateSubscription: z.ZodObject<{
346
355
  ipAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
347
356
  trialEnd: z.ZodOptional<z.ZodNullable<z.ZodString>>;
348
357
  paymentBehavior: z.ZodOptional<z.ZodNullable<z.ZodEnum<["activate_on_payment"]>>>;
358
+ prorationBehavior: z.ZodOptional<z.ZodNullable<z.ZodEnum<["IMMEDIATE_CHARGE", "PRORATE_NEXT_INVOICE", "NO_PRORATION"]>>>;
349
359
  }, "strip", z.ZodTypeAny, {
350
360
  planIdentifier: string;
351
361
  chargePeriod: "ONE_TIME" | "MONTHLY" | "YEARLY" | "WEEKLY" | "DAILY" | "THREE_MONTHS" | "SIX_MONTHS";
@@ -357,6 +367,7 @@ export declare const UpdateSubscription: z.ZodObject<{
357
367
  ipAddress?: string | null | undefined;
358
368
  trialEnd?: string | null | undefined;
359
369
  paymentBehavior?: "activate_on_payment" | null | undefined;
370
+ prorationBehavior?: "IMMEDIATE_CHARGE" | "PRORATE_NEXT_INVOICE" | "NO_PRORATION" | null | undefined;
360
371
  }, {
361
372
  planIdentifier: string;
362
373
  chargePeriod: "ONE_TIME" | "MONTHLY" | "YEARLY" | "WEEKLY" | "DAILY" | "THREE_MONTHS" | "SIX_MONTHS";
@@ -368,19 +379,26 @@ export declare const UpdateSubscription: z.ZodObject<{
368
379
  ipAddress?: string | null | undefined;
369
380
  trialEnd?: string | null | undefined;
370
381
  paymentBehavior?: "activate_on_payment" | null | undefined;
382
+ prorationBehavior?: "IMMEDIATE_CHARGE" | "PRORATE_NEXT_INVOICE" | "NO_PRORATION" | null | undefined;
371
383
  }>;
372
384
  export declare const CancelSubscription: z.ZodObject<{
373
385
  subscriptionId: z.ZodString;
374
386
  cancellationType: z.ZodEnum<["IMMEDIATE", "CURRENT_PERIOD_ENDS", "SPECIFIC_DATE"]>;
375
387
  cancellationDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
388
+ cancellationFeedback: z.ZodOptional<z.ZodNullable<z.ZodEnum<["TOO_EXPENSIVE", "MISSING_FEATURES", "SWITCHED_SERVICE", "UNUSED", "CUSTOMER_SERVICE", "LOW_QUALITY", "TOO_COMPLEX", "OTHER"]>>>;
389
+ cancellationComment: z.ZodOptional<z.ZodNullable<z.ZodString>>;
376
390
  }, "strip", z.ZodTypeAny, {
377
391
  subscriptionId: string;
378
392
  cancellationType: "IMMEDIATE" | "CURRENT_PERIOD_ENDS" | "SPECIFIC_DATE";
379
393
  cancellationDate?: string | null | undefined;
394
+ cancellationFeedback?: "TOO_EXPENSIVE" | "MISSING_FEATURES" | "SWITCHED_SERVICE" | "UNUSED" | "CUSTOMER_SERVICE" | "LOW_QUALITY" | "TOO_COMPLEX" | "OTHER" | null | undefined;
395
+ cancellationComment?: string | null | undefined;
380
396
  }, {
381
397
  subscriptionId: string;
382
398
  cancellationType: "IMMEDIATE" | "CURRENT_PERIOD_ENDS" | "SPECIFIC_DATE";
383
399
  cancellationDate?: string | null | undefined;
400
+ cancellationFeedback?: "TOO_EXPENSIVE" | "MISSING_FEATURES" | "SWITCHED_SERVICE" | "UNUSED" | "CUSTOMER_SERVICE" | "LOW_QUALITY" | "TOO_COMPLEX" | "OTHER" | null | undefined;
401
+ cancellationComment?: string | null | undefined;
384
402
  }>;
385
403
  export declare const GetProductOffering: z.ZodObject<{
386
404
  productId: z.ZodString;
@@ -1204,3 +1222,184 @@ export declare const PlanFileDownload: z.ZodObject<{
1204
1222
  planIdentifier: string;
1205
1223
  fileId: string;
1206
1224
  }>;
1225
+ export declare const ListDiscounts: z.ZodObject<{
1226
+ search: z.ZodOptional<z.ZodString>;
1227
+ page: z.ZodOptional<z.ZodNumber>;
1228
+ pageSize: z.ZodOptional<z.ZodNumber>;
1229
+ }, "strip", z.ZodTypeAny, {
1230
+ page?: number | undefined;
1231
+ pageSize?: number | undefined;
1232
+ search?: string | undefined;
1233
+ }, {
1234
+ page?: number | undefined;
1235
+ pageSize?: number | undefined;
1236
+ search?: string | undefined;
1237
+ }>;
1238
+ export declare const DiscountAppliesToItem: z.ZodObject<{
1239
+ product: z.ZodString;
1240
+ plans: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
1241
+ }, "strip", z.ZodTypeAny, {
1242
+ product: string;
1243
+ plans?: string[] | undefined;
1244
+ }, {
1245
+ product: string;
1246
+ plans?: string[] | undefined;
1247
+ }>;
1248
+ export declare const DiscountCreate: z.ZodObject<{
1249
+ discountType: z.ZodEnum<["PERCENTAGE", "FIXED_AMOUNT"]>;
1250
+ percentageOff: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
1251
+ amountOff: z.ZodOptional<z.ZodNullable<z.ZodString>>;
1252
+ currency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
1253
+ name: z.ZodString;
1254
+ code: z.ZodString;
1255
+ duration: z.ZodOptional<z.ZodEnum<["ONCE", "REPEATING", "FOREVER"]>>;
1256
+ durationInMonths: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
1257
+ redeemBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
1258
+ maxRedemptions: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
1259
+ appliesTo: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
1260
+ product: z.ZodString;
1261
+ plans: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
1262
+ }, "strip", z.ZodTypeAny, {
1263
+ product: string;
1264
+ plans?: string[] | undefined;
1265
+ }, {
1266
+ product: string;
1267
+ plans?: string[] | undefined;
1268
+ }>, "many">>>;
1269
+ }, "strip", z.ZodTypeAny, {
1270
+ code: string;
1271
+ name: string;
1272
+ discountType: "PERCENTAGE" | "FIXED_AMOUNT";
1273
+ currency?: string | null | undefined;
1274
+ percentageOff?: number | null | undefined;
1275
+ amountOff?: string | null | undefined;
1276
+ duration?: "ONCE" | "REPEATING" | "FOREVER" | undefined;
1277
+ durationInMonths?: number | null | undefined;
1278
+ redeemBy?: string | null | undefined;
1279
+ maxRedemptions?: number | null | undefined;
1280
+ appliesTo?: {
1281
+ product: string;
1282
+ plans?: string[] | undefined;
1283
+ }[] | null | undefined;
1284
+ }, {
1285
+ code: string;
1286
+ name: string;
1287
+ discountType: "PERCENTAGE" | "FIXED_AMOUNT";
1288
+ currency?: string | null | undefined;
1289
+ percentageOff?: number | null | undefined;
1290
+ amountOff?: string | null | undefined;
1291
+ duration?: "ONCE" | "REPEATING" | "FOREVER" | undefined;
1292
+ durationInMonths?: number | null | undefined;
1293
+ redeemBy?: string | null | undefined;
1294
+ maxRedemptions?: number | null | undefined;
1295
+ appliesTo?: {
1296
+ product: string;
1297
+ plans?: string[] | undefined;
1298
+ }[] | null | undefined;
1299
+ }>;
1300
+ export declare const DiscountRetrieve: z.ZodObject<{
1301
+ discountId: z.ZodString;
1302
+ }, "strip", z.ZodTypeAny, {
1303
+ discountId: string;
1304
+ }, {
1305
+ discountId: string;
1306
+ }>;
1307
+ export declare const DiscountUpdate: z.ZodObject<{
1308
+ discountId: z.ZodString;
1309
+ isActive: z.ZodBoolean;
1310
+ }, "strip", z.ZodTypeAny, {
1311
+ discountId: string;
1312
+ isActive: boolean;
1313
+ }, {
1314
+ discountId: string;
1315
+ isActive: boolean;
1316
+ }>;
1317
+ export declare const DiscountArchive: z.ZodObject<{
1318
+ discountId: z.ZodString;
1319
+ }, "strip", z.ZodTypeAny, {
1320
+ discountId: string;
1321
+ }, {
1322
+ discountId: string;
1323
+ }>;
1324
+ export declare const WebhookEventType: z.ZodEnum<["checkout.completed", "customer.created", "customer.updated", "order.created", "order.updated", "order.refunded", "subscription.created", "subscription.updated", "subscription.cancelled", "subscription.plan_changed", "subscription.trial_will_end", "invoice.created", "invoice.paid", "invoice.payment_failed", "refund.created", "refund.updated", "feature.usage_alert", "payment_method.created", "payment_method.updated", "payment_method.deleted"]>;
1325
+ export declare const ListWebhookEndpoints: z.ZodObject<{
1326
+ page: z.ZodOptional<z.ZodNumber>;
1327
+ pageSize: z.ZodOptional<z.ZodNumber>;
1328
+ revealSecret: z.ZodOptional<z.ZodBoolean>;
1329
+ }, "strip", z.ZodTypeAny, {
1330
+ page?: number | undefined;
1331
+ pageSize?: number | undefined;
1332
+ revealSecret?: boolean | undefined;
1333
+ }, {
1334
+ page?: number | undefined;
1335
+ pageSize?: number | undefined;
1336
+ revealSecret?: boolean | undefined;
1337
+ }>;
1338
+ export declare const WebhookEndpointCreate: z.ZodObject<{
1339
+ url: z.ZodString;
1340
+ events: z.ZodArray<z.ZodEnum<["checkout.completed", "customer.created", "customer.updated", "order.created", "order.updated", "order.refunded", "subscription.created", "subscription.updated", "subscription.cancelled", "subscription.plan_changed", "subscription.trial_will_end", "invoice.created", "invoice.paid", "invoice.payment_failed", "refund.created", "refund.updated", "feature.usage_alert", "payment_method.created", "payment_method.updated", "payment_method.deleted"]>, "many">;
1341
+ enabled: z.ZodOptional<z.ZodBoolean>;
1342
+ revealSecret: z.ZodOptional<z.ZodBoolean>;
1343
+ }, "strip", z.ZodTypeAny, {
1344
+ url: string;
1345
+ events: ("checkout.completed" | "customer.created" | "customer.updated" | "order.created" | "order.updated" | "order.refunded" | "subscription.created" | "subscription.updated" | "subscription.cancelled" | "subscription.plan_changed" | "subscription.trial_will_end" | "invoice.created" | "invoice.paid" | "invoice.payment_failed" | "refund.created" | "refund.updated" | "feature.usage_alert" | "payment_method.created" | "payment_method.updated" | "payment_method.deleted")[];
1346
+ enabled?: boolean | undefined;
1347
+ revealSecret?: boolean | undefined;
1348
+ }, {
1349
+ url: string;
1350
+ events: ("checkout.completed" | "customer.created" | "customer.updated" | "order.created" | "order.updated" | "order.refunded" | "subscription.created" | "subscription.updated" | "subscription.cancelled" | "subscription.plan_changed" | "subscription.trial_will_end" | "invoice.created" | "invoice.paid" | "invoice.payment_failed" | "refund.created" | "refund.updated" | "feature.usage_alert" | "payment_method.created" | "payment_method.updated" | "payment_method.deleted")[];
1351
+ enabled?: boolean | undefined;
1352
+ revealSecret?: boolean | undefined;
1353
+ }>;
1354
+ export declare const WebhookEndpointRetrieve: z.ZodObject<{
1355
+ endpointId: z.ZodString;
1356
+ revealSecret: z.ZodOptional<z.ZodBoolean>;
1357
+ }, "strip", z.ZodTypeAny, {
1358
+ endpointId: string;
1359
+ revealSecret?: boolean | undefined;
1360
+ }, {
1361
+ endpointId: string;
1362
+ revealSecret?: boolean | undefined;
1363
+ }>;
1364
+ export declare const WebhookEndpointUpdate: z.ZodObject<{
1365
+ endpointId: z.ZodString;
1366
+ url: z.ZodOptional<z.ZodString>;
1367
+ events: z.ZodOptional<z.ZodArray<z.ZodEnum<["checkout.completed", "customer.created", "customer.updated", "order.created", "order.updated", "order.refunded", "subscription.created", "subscription.updated", "subscription.cancelled", "subscription.plan_changed", "subscription.trial_will_end", "invoice.created", "invoice.paid", "invoice.payment_failed", "refund.created", "refund.updated", "feature.usage_alert", "payment_method.created", "payment_method.updated", "payment_method.deleted"]>, "many">>;
1368
+ enabled: z.ZodOptional<z.ZodBoolean>;
1369
+ revealSecret: z.ZodOptional<z.ZodBoolean>;
1370
+ }, "strip", z.ZodTypeAny, {
1371
+ endpointId: string;
1372
+ enabled?: boolean | undefined;
1373
+ url?: string | undefined;
1374
+ revealSecret?: boolean | undefined;
1375
+ events?: ("checkout.completed" | "customer.created" | "customer.updated" | "order.created" | "order.updated" | "order.refunded" | "subscription.created" | "subscription.updated" | "subscription.cancelled" | "subscription.plan_changed" | "subscription.trial_will_end" | "invoice.created" | "invoice.paid" | "invoice.payment_failed" | "refund.created" | "refund.updated" | "feature.usage_alert" | "payment_method.created" | "payment_method.updated" | "payment_method.deleted")[] | undefined;
1376
+ }, {
1377
+ endpointId: string;
1378
+ enabled?: boolean | undefined;
1379
+ url?: string | undefined;
1380
+ revealSecret?: boolean | undefined;
1381
+ events?: ("checkout.completed" | "customer.created" | "customer.updated" | "order.created" | "order.updated" | "order.refunded" | "subscription.created" | "subscription.updated" | "subscription.cancelled" | "subscription.plan_changed" | "subscription.trial_will_end" | "invoice.created" | "invoice.paid" | "invoice.payment_failed" | "refund.created" | "refund.updated" | "feature.usage_alert" | "payment_method.created" | "payment_method.updated" | "payment_method.deleted")[] | undefined;
1382
+ }>;
1383
+ export declare const WebhookEndpointDelete: z.ZodObject<{
1384
+ endpointId: z.ZodString;
1385
+ }, "strip", z.ZodTypeAny, {
1386
+ endpointId: string;
1387
+ }, {
1388
+ endpointId: string;
1389
+ }>;
1390
+ export declare const ListWebhookLogs: z.ZodObject<{
1391
+ startDate: z.ZodOptional<z.ZodString>;
1392
+ endDate: z.ZodOptional<z.ZodString>;
1393
+ page: z.ZodOptional<z.ZodNumber>;
1394
+ pageSize: z.ZodOptional<z.ZodNumber>;
1395
+ }, "strip", z.ZodTypeAny, {
1396
+ page?: number | undefined;
1397
+ pageSize?: number | undefined;
1398
+ startDate?: string | undefined;
1399
+ endDate?: string | undefined;
1400
+ }, {
1401
+ page?: number | undefined;
1402
+ pageSize?: number | undefined;
1403
+ startDate?: string | undefined;
1404
+ endDate?: string | undefined;
1405
+ }>;
@@ -112,6 +112,24 @@ export const CreateCheckoutSession = z.object({
112
112
  .nullable()
113
113
  .optional()
114
114
  .describe('Discount/coupon code to pre-apply to the checkout session. Applied only if active, unexpired, and valid for the selected plan; otherwise the request fails.'),
115
+ trialPeriod: z
116
+ .number()
117
+ .int()
118
+ .min(1)
119
+ .nullable()
120
+ .optional()
121
+ .describe('Trial days for the subscription this checkout creates. Overrides the trial configured on the plan.'),
122
+ billingPeriodsEnabled: z
123
+ .string()
124
+ .nullable()
125
+ .optional()
126
+ .describe('Comma-separated billing periods to show and allow on the checkout page, e.g. "MONTHLY,YEARLY".'),
127
+ email: z
128
+ .string()
129
+ .email()
130
+ .nullable()
131
+ .optional()
132
+ .describe('Email to pre-fill on the checkout page. Combine with lockEmail to stop the customer changing it.'),
115
133
  metadata: z
116
134
  .record(z.unknown())
117
135
  .nullable()
@@ -184,6 +202,11 @@ export const UpdateSubscription = z.object({
184
202
  .nullable()
185
203
  .optional()
186
204
  .describe('Set to "activate_on_payment" to keep the current subscription active while payment is pending and apply the new plan/charge period/features only after payment succeeds.'),
205
+ prorationBehavior: z
206
+ .enum(['IMMEDIATE_CHARGE', 'PRORATE_NEXT_INVOICE', 'NO_PRORATION'])
207
+ .nullable()
208
+ .optional()
209
+ .describe('When the customer is billed for the change: IMMEDIATE_CHARGE prorates and invoices the difference now; PRORATE_NEXT_INVOICE prorates now but bills on the next invoice; NO_PRORATION changes the plan without crediting or charging the partial period.'),
187
210
  });
188
211
  export const CancelSubscription = z.object({
189
212
  subscriptionId: z.string().uuid().describe('UUID of the subscription to cancel (path parameter).'),
@@ -194,6 +217,12 @@ export const CancelSubscription = z.object({
194
217
  .nullable()
195
218
  .optional()
196
219
  .describe('Required when cancellationType is SPECIFIC_DATE. Format: YYYY-MM-DD.'),
220
+ cancellationFeedback: z
221
+ .enum(['TOO_EXPENSIVE', 'MISSING_FEATURES', 'SWITCHED_SERVICE', 'UNUSED', 'CUSTOMER_SERVICE', 'LOW_QUALITY', 'TOO_COMPLEX', 'OTHER'])
222
+ .nullable()
223
+ .optional()
224
+ .describe('Optional structured reason for the cancellation.'),
225
+ cancellationComment: z.string().nullable().optional().describe('Optional free-form cancellation comment.'),
197
226
  });
198
227
  // -- Offerings ------------------------------------------------------------
199
228
  export const GetProductOffering = z.object({
@@ -452,4 +481,148 @@ export const PlanFileDownload = z.object({
452
481
  planIdentifier: z.string().describe('Plan identifier.'),
453
482
  fileId: z.string().describe('File UUID.'),
454
483
  });
484
+ // =========================================================================
485
+ // Discounts
486
+ // =========================================================================
487
+ const PageSize = z.number().int().min(1).max(100).optional().describe('Results per page (default 10, max 100).');
488
+ export const ListDiscounts = z.object({
489
+ search: z.string().optional().describe("Free-text search across the discount's name and code."),
490
+ page: z.number().int().positive().optional(),
491
+ pageSize: PageSize,
492
+ });
493
+ export const DiscountAppliesToItem = z.object({
494
+ product: z.string().uuid().describe('UUID of the product this discount applies to.'),
495
+ plans: z
496
+ .array(z.string())
497
+ .optional()
498
+ .describe('Plan identifiers within the product. Omit or leave empty to apply to every plan of the product.'),
499
+ });
500
+ export const DiscountCreate = z.object({
501
+ discountType: z.enum(['PERCENTAGE', 'FIXED_AMOUNT']),
502
+ percentageOff: z
503
+ .number()
504
+ .int()
505
+ .nullable()
506
+ .optional()
507
+ .describe('Required (and only used) when discountType is PERCENTAGE, e.g. 20.'),
508
+ amountOff: z
509
+ .string()
510
+ .nullable()
511
+ .optional()
512
+ .describe('Required (and only used) when discountType is FIXED_AMOUNT, as a decimal string, e.g. "10.00".'),
513
+ currency: z
514
+ .string()
515
+ .nullable()
516
+ .optional()
517
+ .describe('3-letter ISO currency code. Required when discountType is FIXED_AMOUNT.'),
518
+ name: z.string().describe("Shown on the customer's invoice."),
519
+ code: z
520
+ .string()
521
+ .describe('The code customers enter at checkout. Uppercase letters and numbers only; must be unique among active discounts.'),
522
+ duration: z
523
+ .enum(['ONCE', 'REPEATING', 'FOREVER'])
524
+ .optional()
525
+ .describe('ONCE applies to the first payment; REPEATING applies for durationInMonths billing periods; FOREVER applies to every payment.'),
526
+ durationInMonths: z
527
+ .number()
528
+ .int()
529
+ .positive()
530
+ .nullable()
531
+ .optional()
532
+ .describe('With duration REPEATING: how many billing periods the discount applies for (billing cycles, not calendar months).'),
533
+ redeemBy: z
534
+ .string()
535
+ .nullable()
536
+ .optional()
537
+ .describe('UTC datetime after which the code can no longer be redeemed. Must be in the future.'),
538
+ maxRedemptions: z
539
+ .number()
540
+ .int()
541
+ .positive()
542
+ .nullable()
543
+ .optional()
544
+ .describe('Total number of times the code can be redeemed across all customers.'),
545
+ appliesTo: z
546
+ .array(DiscountAppliesToItem)
547
+ .nullable()
548
+ .optional()
549
+ .describe('Restrict the discount to specific products and plans. Omit to apply to all products.'),
550
+ });
551
+ export const DiscountRetrieve = z.object({
552
+ discountId: z.string().describe('Discount ID (path param `pk`).'),
553
+ });
554
+ export const DiscountUpdate = z.object({
555
+ discountId: z.string().describe('Discount ID (path param `pk`).'),
556
+ isActive: z.boolean().describe('true enables the code, false disables it. No other field can change after creation.'),
557
+ });
558
+ export const DiscountArchive = z.object({
559
+ discountId: z.string().describe('Discount ID to archive.'),
560
+ });
561
+ // =========================================================================
562
+ // Webhooks
563
+ // =========================================================================
564
+ export const WebhookEventType = z.enum([
565
+ 'checkout.completed',
566
+ 'customer.created',
567
+ 'customer.updated',
568
+ 'order.created',
569
+ 'order.updated',
570
+ 'order.refunded',
571
+ 'subscription.created',
572
+ 'subscription.updated',
573
+ 'subscription.cancelled',
574
+ 'subscription.plan_changed',
575
+ 'subscription.trial_will_end',
576
+ 'invoice.created',
577
+ 'invoice.paid',
578
+ 'invoice.payment_failed',
579
+ 'refund.created',
580
+ 'refund.updated',
581
+ 'feature.usage_alert',
582
+ 'payment_method.created',
583
+ 'payment_method.updated',
584
+ 'payment_method.deleted',
585
+ ]);
586
+ const RevealSecret = z
587
+ .boolean()
588
+ .optional()
589
+ .describe('Include the signing secret in the result. Default false: the secret is hidden so it never enters the conversation. Prefer writing it straight to the app env file with a command.');
590
+ export const ListWebhookEndpoints = z.object({
591
+ page: z.number().int().positive().optional(),
592
+ pageSize: PageSize,
593
+ revealSecret: RevealSecret,
594
+ });
595
+ export const WebhookEndpointCreate = z.object({
596
+ url: z
597
+ .string()
598
+ .url()
599
+ .describe('Public URL that receives events. Private, loopback and internal addresses (such as localhost) are rejected.'),
600
+ events: z.array(WebhookEventType).min(1).describe('Event types to deliver to this endpoint.'),
601
+ enabled: z.boolean().optional().describe('Whether the endpoint receives deliveries.'),
602
+ revealSecret: RevealSecret,
603
+ });
604
+ export const WebhookEndpointRetrieve = z.object({
605
+ endpointId: z.string().describe('Webhook endpoint ID (path param `pk`).'),
606
+ revealSecret: RevealSecret,
607
+ });
608
+ export const WebhookEndpointUpdate = z.object({
609
+ endpointId: z.string().describe('Webhook endpoint ID (path param `pk`).'),
610
+ url: z.string().url().optional(),
611
+ events: z.array(WebhookEventType).min(1).optional(),
612
+ enabled: z.boolean().optional(),
613
+ revealSecret: RevealSecret,
614
+ });
615
+ export const WebhookEndpointDelete = z.object({
616
+ endpointId: z.string().describe('Webhook endpoint ID to delete.'),
617
+ });
618
+ export const ListWebhookLogs = z.object({
619
+ startDate: z
620
+ .string()
621
+ .regex(/^\d{4}-\d{2}-\d{2}$/)
622
+ .optional()
623
+ .describe('YYYY-MM-DD. Results never go back more than 30 days.'),
624
+ endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD.'),
625
+ page: z.number().int().positive().optional(),
626
+ pageSize: PageSize,
627
+ });
455
628
  //# sourceMappingURL=kelviq.js.map