@kelviq/mcp-server 0.2.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 (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +322 -0
  3. package/dist/config.d.ts +16 -0
  4. package/dist/config.js +45 -0
  5. package/dist/config.js.map +1 -0
  6. package/dist/docs/README.md +128 -0
  7. package/dist/docs/api-reference/authentication.md +41 -0
  8. package/dist/docs/backend-integration/node-sdk.md +1040 -0
  9. package/dist/docs/backend-integration/python-sdk.md +1198 -0
  10. package/dist/docs/changelog/app.md +80 -0
  11. package/dist/docs/changelog/checkout-api.md +59 -0
  12. package/dist/docs/changelog/js-promotions-ui.md +14 -0
  13. package/dist/docs/changelog/js-sdk.md +281 -0
  14. package/dist/docs/changelog/node-sdk.md +378 -0
  15. package/dist/docs/changelog/python-sdk.md +456 -0
  16. package/dist/docs/changelog/react-sdk.md +580 -0
  17. package/dist/docs/checkout/checkout-configuration.md +434 -0
  18. package/dist/docs/coustomers-management/overview.md +111 -0
  19. package/dist/docs/customer-portal/overview.md +81 -0
  20. package/dist/docs/frontend-integration/js-sdk.md +676 -0
  21. package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
  22. package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
  23. package/dist/docs/frontend-integration/react-sdk.md +1187 -0
  24. package/dist/docs/frontend-integration/react-ui.md +771 -0
  25. package/dist/docs/getstarted/fees.md +160 -0
  26. package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
  27. package/dist/docs/getstarted/merchant-of-record.md +64 -0
  28. package/dist/docs/getstarted/review-process.md +190 -0
  29. package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
  30. package/dist/docs/guides/subscription-integration.md +291 -0
  31. package/dist/docs/guides/webhooks.md +963 -0
  32. package/dist/docs/legal/approved-prohibited-policy.md +252 -0
  33. package/dist/docs/legal/buyer-terms.md +177 -0
  34. package/dist/docs/legal/compliant-user-flow.md +216 -0
  35. package/dist/docs/legal/master-service-agreement.md +404 -0
  36. package/dist/docs/legal/payment-flow-diagram.md +188 -0
  37. package/dist/docs/legal/seller-terms.md +169 -0
  38. package/dist/docs/manifest.json +415 -0
  39. package/dist/docs/monetization/offerings.md +156 -0
  40. package/dist/docs/monetization/pricing-tables.md +226 -0
  41. package/dist/docs/monetization/targeting-rules.md +278 -0
  42. package/dist/docs/openapi.json +5479 -0
  43. package/dist/docs/payouts/overview.md +43 -0
  44. package/dist/docs/payouts/payout-account.md +12 -0
  45. package/dist/docs/payouts/transactions.md +23 -0
  46. package/dist/docs/product-catalog/digital-downloads.md +117 -0
  47. package/dist/docs/product-catalog/discounts.md +69 -0
  48. package/dist/docs/product-catalog/entitlements.md +428 -0
  49. package/dist/docs/product-catalog/free-and-trials.md +36 -0
  50. package/dist/docs/product-catalog/license-keys.md +324 -0
  51. package/dist/docs/product-catalog/links.md +92 -0
  52. package/dist/docs/product-catalog/location-based-pricing.md +41 -0
  53. package/dist/docs/product-catalog/one-time-payments.md +24 -0
  54. package/dist/docs/product-catalog/plans.md +199 -0
  55. package/dist/docs/product-catalog/products.md +60 -0
  56. package/dist/docs/product-catalog/subscriptions.md +29 -0
  57. package/dist/docs/product-catalog/tax-settings.md +37 -0
  58. package/dist/docs/product-catalog/usage-based-billing.md +119 -0
  59. package/dist/docs/promotions/create-a-promotion.md +75 -0
  60. package/dist/docs/promotions/customize-banner.md +41 -0
  61. package/dist/docs/promotions/integrate.md +38 -0
  62. package/dist/docs/promotions/overview.md +51 -0
  63. package/dist/docs/quickstart/core-concepts.md +146 -0
  64. package/dist/docs/quickstart/dashboard-setup.md +129 -0
  65. package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
  66. package/dist/docs/sales/checkout-sessions.md +58 -0
  67. package/dist/docs/sales/orders.md +76 -0
  68. package/dist/http/client.d.ts +28 -0
  69. package/dist/http/client.js +76 -0
  70. package/dist/http/client.js.map +1 -0
  71. package/dist/http/errors.d.ts +20 -0
  72. package/dist/http/errors.js +58 -0
  73. package/dist/http/errors.js.map +1 -0
  74. package/dist/resources/docs-index.d.ts +25 -0
  75. package/dist/resources/docs-index.js +109 -0
  76. package/dist/resources/docs-index.js.map +1 -0
  77. package/dist/resources/index.d.ts +2 -0
  78. package/dist/resources/index.js +73 -0
  79. package/dist/resources/index.js.map +1 -0
  80. package/dist/schemas/kelviq.d.ts +1304 -0
  81. package/dist/schemas/kelviq.js +468 -0
  82. package/dist/schemas/kelviq.js.map +1 -0
  83. package/dist/server.d.ts +2 -0
  84. package/dist/server.js +41 -0
  85. package/dist/server.js.map +1 -0
  86. package/dist/tools/_util.d.ts +15 -0
  87. package/dist/tools/_util.js +15 -0
  88. package/dist/tools/_util.js.map +1 -0
  89. package/dist/tools/checkout.d.ts +3 -0
  90. package/dist/tools/checkout.js +18 -0
  91. package/dist/tools/checkout.js.map +1 -0
  92. package/dist/tools/customers.d.ts +3 -0
  93. package/dist/tools/customers.js +32 -0
  94. package/dist/tools/customers.js.map +1 -0
  95. package/dist/tools/docs.d.ts +2 -0
  96. package/dist/tools/docs.js +43 -0
  97. package/dist/tools/docs.js.map +1 -0
  98. package/dist/tools/entitlements.d.ts +3 -0
  99. package/dist/tools/entitlements.js +22 -0
  100. package/dist/tools/entitlements.js.map +1 -0
  101. package/dist/tools/features.d.ts +3 -0
  102. package/dist/tools/features.js +55 -0
  103. package/dist/tools/features.js.map +1 -0
  104. package/dist/tools/index.d.ts +3 -0
  105. package/dist/tools/index.js +44 -0
  106. package/dist/tools/index.js.map +1 -0
  107. package/dist/tools/licenses.d.ts +3 -0
  108. package/dist/tools/licenses.js +44 -0
  109. package/dist/tools/licenses.js.map +1 -0
  110. package/dist/tools/media.d.ts +3 -0
  111. package/dist/tools/media.js +18 -0
  112. package/dist/tools/media.js.map +1 -0
  113. package/dist/tools/offerings.d.ts +3 -0
  114. package/dist/tools/offerings.js +21 -0
  115. package/dist/tools/offerings.js.map +1 -0
  116. package/dist/tools/partner.d.ts +3 -0
  117. package/dist/tools/partner.js +55 -0
  118. package/dist/tools/partner.js.map +1 -0
  119. package/dist/tools/plan-entitlements.d.ts +3 -0
  120. package/dist/tools/plan-entitlements.js +56 -0
  121. package/dist/tools/plan-entitlements.js.map +1 -0
  122. package/dist/tools/plan-files.d.ts +3 -0
  123. package/dist/tools/plan-files.js +43 -0
  124. package/dist/tools/plan-files.js.map +1 -0
  125. package/dist/tools/plans.d.ts +3 -0
  126. package/dist/tools/plans.js +120 -0
  127. package/dist/tools/plans.js.map +1 -0
  128. package/dist/tools/portal.d.ts +3 -0
  129. package/dist/tools/portal.js +18 -0
  130. package/dist/tools/portal.js.map +1 -0
  131. package/dist/tools/product-files.d.ts +3 -0
  132. package/dist/tools/product-files.js +31 -0
  133. package/dist/tools/product-files.js.map +1 -0
  134. package/dist/tools/product-settings.d.ts +3 -0
  135. package/dist/tools/product-settings.js +31 -0
  136. package/dist/tools/product-settings.js.map +1 -0
  137. package/dist/tools/products.d.ts +3 -0
  138. package/dist/tools/products.js +69 -0
  139. package/dist/tools/products.js.map +1 -0
  140. package/dist/tools/promotions.d.ts +3 -0
  141. package/dist/tools/promotions.js +19 -0
  142. package/dist/tools/promotions.js.map +1 -0
  143. package/dist/tools/subscriptions.d.ts +3 -0
  144. package/dist/tools/subscriptions.js +63 -0
  145. package/dist/tools/subscriptions.js.map +1 -0
  146. package/dist/tools/usage.d.ts +3 -0
  147. package/dist/tools/usage.js +18 -0
  148. package/dist/tools/usage.js.map +1 -0
  149. package/package.json +88 -0
@@ -0,0 +1,146 @@
1
+ ---
2
+ title: "Core concepts"
3
+ slug: "quickstart/core-concepts"
4
+ section: "quickstart"
5
+ ---
6
+ Understanding these core concepts will make it easier to design your pricing and integrate the SDK.
7
+
8
+ ---
9
+
10
+ ## Products
11
+
12
+ A product is the main thing you sell.
13
+ Examples: "Cursor", "TimeMaster Pro", or "API Service".
14
+
15
+ [Learn more about products →](/product-catalog/products)
16
+
17
+ ---
18
+
19
+ ## Plans
20
+
21
+ A plan is how you package and price your product. You attach features and prices to a plan.
22
+
23
+ Examples: Free, Starter, Pro, Enterprise.
24
+
25
+ [Learn more about plans →](/product-catalog/plans)
26
+
27
+ ---
28
+
29
+ ## Features & Entitlements
30
+
31
+ A feature is a capability a customer can access. Entitlements define how that feature gets used within a specific plan.
32
+
33
+ You define features once and reuse them across multiple plans. Entitlements control the access, limits, or configuration for those features.
34
+
35
+ Examples:
36
+ - API access with 1,000 requests per month
37
+ - AI tokens with a limit of 10,000 tokens per month
38
+ - Storage feature with 100 GB included
39
+ - Priority support enabled for Pro customers
40
+
41
+ Entitlements come in three types
42
+
43
+ * **Boolean** to toggle a feature on or off
44
+ * **Metered** to track usage like AI tokens, workflow runs, or compute time
45
+ * **Config** to pass custom values or settings to your application
46
+
47
+ [Learn more about features & entitlements →](/product-catalog/entitlements)
48
+
49
+ ---
50
+
51
+ ## Digital downloads
52
+
53
+ A digital download is a file that your customers can download after purchasing.
54
+
55
+ Examples: e-books, software, music, videos.
56
+
57
+ [Learn more about digital downloads →](/product-catalog/digital-downloads)
58
+
59
+ ---
60
+
61
+ ## License keys
62
+
63
+ A license key is a code that your customers can use to activate a digital download.
64
+
65
+ Examples: software activation, game keys, e-books.
66
+
67
+ [Learn more about license keys →](/product-catalog/license-keys)
68
+
69
+ ---
70
+
71
+ ## Links
72
+
73
+ Links allow you to share important URLs with customers after they purchase your plan.
74
+
75
+ Examples: Discord servers, Slack workspaces, Notion pages, member-only dashboards.
76
+
77
+ [Learn more about links →](/product-catalog/links)
78
+
79
+ ---
80
+
81
+ ## Customers
82
+
83
+ A customer is a person or company that purchases your product.
84
+
85
+ Typically, you create a customer record when someone signs up in your app.
86
+ When they complete a purchase, Kelviq maps the transaction to the customer record automatically.
87
+
88
+ [Learn more about customers →](/coustomers-management/overview)
89
+
90
+ ---
91
+
92
+ ## Typical workflows
93
+
94
+ ### AI and usage based products
95
+
96
+ Billing for actual work delivered rather than just seat access.
97
+
98
+ 1. Create features like AI tokens, API calls, or workflow runs
99
+ 2. Create a product
100
+ 3. Create plans with a flat base fee plus metered usage charges
101
+ 4. Add entitlements to set soft or hard caps on compute
102
+ 5. Integrate the SDK to report usage back to Kelviq as the AI performs work
103
+ 6. Customer subscribes and pays automatically based on their actual consumption
104
+
105
+ ### One-time products
106
+
107
+ Selling digital downloads, license keys, or access links:
108
+
109
+ 1. Create a **product**
110
+ 2. Create a **plan** with one-time pricing
111
+ 3. Add **digital downloads**, **license keys**, or **links** to the plan
112
+ 4. Share your checkout link or embed a pricing table
113
+ 5. Customer purchases → receives their files, keys, and links
114
+
115
+ ### SaaS subscriptions
116
+
117
+ Selling recurring access with feature limits:
118
+
119
+ 1. Create **features** (e.g., API calls, storage, AI tokens)
120
+ 2. Create a **product**
121
+ 3. Create **plans** with recurring pricing (monthly/yearly)
122
+ 4. Add **entitlements** to each plan (e.g., 1,000 API calls/month)
123
+ 5. Integrate the **SDK** to check feature access and enforce limits
124
+ 6. Customer subscribes → SDK controls what they can access
125
+
126
+ ---
127
+
128
+ ## Integrate with your app
129
+
130
+ To bring everything you set up in the dashboard into your app, use one of these options:
131
+
132
+ - **[SDKs](/frontend-integration/react-sdk)** — check feature access and enforce usage limits in code
133
+ - **[APIs](/api-reference/authentication)** — use for custom needs such as syncing usage or triggering upgrades
134
+
135
+ **No webhooks required.** Kelviq SDKs and UI widgets stay in sync automatically—no need to build webhook handlers or manage event processing.
136
+
137
+ [See the full integration guide →](/quickstart/integrate-with-your-app)
138
+
139
+ ---
140
+
141
+ ## Need help?
142
+
143
+ Have questions, need help with implementation, or want a walkthrough?
144
+ Email us at **hi@kelviq.com** or [book a demo](https://tidycal.com/neravath/15-minute-meeting).
145
+
146
+ ---
@@ -0,0 +1,129 @@
1
+ ---
2
+ title: "Dashboard setup"
3
+ slug: "quickstart/dashboard-setup"
4
+ section: "quickstart"
5
+ ---
6
+ Before you can integrate kelviq into your app, you need to configure your **products, plans, and features** in the dashboard.
7
+ This setup defines how your pricing and entitlements will work.
8
+
9
+ ---
10
+
11
+ ## Create a product
12
+
13
+ 1. In the sidebar, go to **Products → Create product**
14
+ 2. Enter a product name (e.g., "Design Course", "Pro Plan", "Premium Templates")
15
+ 3. Click **Save** — you'll be redirected to the product page
16
+
17
+ ---
18
+
19
+ ## Create a plan
20
+
21
+ From the product page:
22
+
23
+ 1. Click **Create plan**
24
+ 2. Enter a plan name (e.g., “Basic Plan”)
25
+ 3. Click **Save** — you’ll be redirected to the plan details page
26
+
27
+ ---
28
+
29
+ ## Add pricing to the plan
30
+
31
+ From the plan page, click the **Price** section to configure pricing:
32
+
33
+ 1. Select billing cycles: **Monthly**, **Yearly**, **3 Months**, or **One Time**
34
+ 2. Enter prices for each selected billing cycle
35
+ 3. (Optional) Enable **Free trial** and set the trial period in days
36
+ 4. Click **Save**
37
+
38
+ ### Usage based pricing
39
+
40
+ To charger your users based on cosnumption like copute or agent runs you can ad usage based pricing.
41
+
42
+ 1. In the Price section select the usage billing option
43
+ 2. Choose the specific feature you want to track like AI tokens or workflow executions
44
+ 3. Set your price per unit
45
+ 4. Combine this with a flat base fee if you want a hybrid pricing model
46
+
47
+ ### Regional pricing
48
+
49
+ To offer localized prices in different currencies:
50
+
51
+ 1. In the Price section, click **Add Region** under Regional Pricing
52
+ 2. Select a currency (e.g., Indian Rupee, Euro)
53
+ 3. Enter prices for each billing cycle in that currency
54
+ 4. Click **Add Currency**
55
+
56
+ This allows you to set specific prices for different markets rather than relying on automatic currency conversion.
57
+
58
+ ---
59
+
60
+ ## Add digital downloads
61
+
62
+ If your plan includes downloadable content (e-books, software, course materials):
63
+
64
+ 1. Click the **Digital downloads** section
65
+ 2. Upload files that customers will receive after purchase
66
+ 3. Files are securely delivered to customers upon successful payment
67
+
68
+ ---
69
+
70
+ ## Add license keys
71
+
72
+ To automatically generate unique license keys for each purchase:
73
+
74
+ 1. Click the **License keys** section
75
+ 2. Toggle license key generation **on**
76
+ 3. Keys are automatically created and delivered to customers after purchase
77
+
78
+ You can use these keys to validate customers in your application.
79
+
80
+ ---
81
+
82
+ ## Add features and limits
83
+
84
+ Click the **Features & limits** section to configure feature access and usage quotas for this plan.
85
+
86
+ 1. Click **Add feature**
87
+ 2. A modal will open where you can create or select features
88
+ 3. Configure the feature value for this plan
89
+
90
+ ### Feature types
91
+
92
+ Features are created independently and can be attached to multiple plans with different values:
93
+
94
+ - **Switch (Boolean)** — on or off
95
+ Examples: priority support, bonus content access, community access, custom branding
96
+
97
+ - **Customizable** — a fixed numeric limit, no usage reporting
98
+ Examples: number of downloads, max projects, storage limit (10 GB, 100 GB)
99
+
100
+ - **Metered** — tracked consumption, usage events sent to Kelviq, resets each billing cycle
101
+ Examples: API calls, AI generations, video renders, exports per month
102
+
103
+ Once added, features appear in the plan's feature list. You can reorder or remove them as needed.
104
+
105
+ ---
106
+
107
+ ## Publish the plan
108
+
109
+ The last step is to publish your plan, so customers can see it and purchase it.
110
+
111
+ ---
112
+
113
+ ## Next steps
114
+
115
+ Your plan is now set up and synced with Stripe.
116
+ Next, you can integrate Kelviq into your app:
117
+
118
+ - Use **checkout links** to let customers purchase your plans
119
+ - Create a customer in Kelviq when a user signs up in your app
120
+ - Use the Kelviq **SDK** to check feature access and track usage
121
+
122
+ ---
123
+
124
+ ## Need help?
125
+
126
+ Have questions, need help with implementation, or want a walkthrough?
127
+ Email us at **hi@kelviq.com** or [book a demo](https://tidycal.com/neravath/15-minute-meeting).
128
+
129
+ ---
@@ -0,0 +1,149 @@
1
+ ---
2
+ title: "Integrate with your app"
3
+ slug: "quickstart/integrate-with-your-app"
4
+ section: "quickstart"
5
+ ---
6
+ After setting up your product and plans in the dashboard, you can bring them into your app using the kelviq SDKs and UI components.
7
+
8
+ > Note: In this guide we use the **Node SDK** and **React SDK** as examples.
9
+ > Other SDKs like Python, JavaScript, are also available — the steps are the same.
10
+
11
+ ---
12
+
13
+ ## 1. Create a customer (optional)
14
+
15
+ Typically, you create a customer record when someone signs up in your app.
16
+ When they complete a purchase, Kelviq maps the transaction to the customer record automatically.
17
+
18
+ This is optional, but creating a customer in kelviq makes it easy to track subscriptions and usage in the dashboard.
19
+
20
+ ### Install the Node SDK
21
+
22
+ ```bash
23
+ npm install @kelviq/node-sdk
24
+ ````
25
+
26
+ ```ts
27
+ import { Kelviq } from "@kelviq/node-sdk";
28
+
29
+ // API keys are under Settings → API keys in the dashboard
30
+ const client = new Kelviq({
31
+ accessToken: process.env.KELVIQ_SERVER_API_KEY!,
32
+ });
33
+
34
+ // Create a customer on signup
35
+ const newCustomer = await client.customers.create({
36
+ customerId: "unique-customer-001",
37
+ email: "customer@example.com",
38
+ name: "Node SDK User",
39
+ });
40
+ ```
41
+
42
+ ---
43
+
44
+ ## 2. Checkout links
45
+
46
+ Every plan in Kelviq has a checkout link that you can use to send customers directly to checkout.
47
+
48
+ ### Get a checkout link
49
+
50
+ 1. In the dashboard, go to your **Product → Plan**
51
+ 2. Click **Get Link** in the top right
52
+ 3. Copy the checkout URL
53
+
54
+ ### Using checkout links
55
+
56
+ You can use checkout links in multiple ways:
57
+
58
+ - **Direct link** — Share the URL in emails, landing pages, or marketing campaigns
59
+ - **Button on your site** — Link your "Buy Now" or "Get Access" buttons to the checkout URL
60
+ - **With customer ID** — Append `?customer_id=unique-customer-001` to link the purchase to an existing customer
61
+
62
+ ```html
63
+ <a href="https://checkout.kelviq.com/your-plan-id?customer_id=unique-customer-001">
64
+ Buy Now
65
+ </a>
66
+ ```
67
+
68
+ When a customer completes checkout, their subscription and entitlements are automatically available in Kelviq.
69
+
70
+ ---
71
+
72
+ ## 3. Check feature access
73
+
74
+ Once a customer completes a purchase, their entitlements are available in the SDK.
75
+ You can check feature access in the frontend (React SDK) or backend (Node SDK).
76
+ In all examples we’ll keep using the same customer ID: `unique-customer-001`.
77
+
78
+ ### React: show or hide UI based on entitlements
79
+
80
+ ```tsx
81
+ import { ShowWhenBooleanEntitled } from '@kelviq/react-sdk';
82
+
83
+ <ShowWhenBooleanEntitled
84
+ featureId="enable-dark-mode"
85
+ loadingComponent={<p>Checking…</p>}
86
+ fallback={<p>Dark mode not available</p>}
87
+ >
88
+ <button>Toggle Dark Mode</button>
89
+ </ShowWhenBooleanEntitled>
90
+ ```
91
+
92
+ ### React: read all entitlements
93
+
94
+ ```tsx
95
+ import { useAllEntitlements } from '@kelviq/react-sdk';
96
+
97
+ function EntitlementsList() {
98
+ const { data: entitlements } = useAllEntitlements();
99
+
100
+ return (
101
+ <ul>
102
+ {Object.values(entitlements).map(ent => (
103
+ <li key={ent.featureId}>
104
+ {ent.featureId}: {ent.hasAccess ? 'Enabled' : 'Disabled'} ({ent.featureType})
105
+ </li>
106
+ ))}
107
+ </ul>
108
+ );
109
+ }
110
+ ```
111
+
112
+ ### Backend check with Node
113
+
114
+ ```ts
115
+ const ent = await client.entitlements.getEntitlement({
116
+ customerId: "unique-customer-001",
117
+ featureId: "max_upload_size_mb",
118
+ });
119
+
120
+ if (ent && file.sizeMB > (ent.usageLimit ?? Infinity)) {
121
+ throw new Error("Upgrade required");
122
+ }
123
+ ```
124
+
125
+ ---
126
+
127
+ ## 4. Report usage (metered features)
128
+
129
+ For metered features (like downloads, exports, AI generations, or API calls), send usage events from your backend.
130
+
131
+ ```ts
132
+ import { BEHAVIOUR_CHOICES } from '@kelviq/node-sdk';
133
+
134
+ await client.reporting.reportUsage({
135
+ customerId: "unique-customer-001",
136
+ featureId: "downloads",
137
+ value: 1,
138
+ behaviour: BEHAVIOUR_CHOICES.DELTA, // or SET
139
+ });
140
+ ```
141
+
142
+ ---
143
+
144
+ ## Need help?
145
+
146
+ Have questions, need help with implementation, or want a walkthrough?
147
+ Email us at **hi@kelviq.com** or [book a demo](https://tidycal.com/neravath/15-minute-meeting).
148
+
149
+ ---
@@ -0,0 +1,58 @@
1
+ ---
2
+ title: "Checkout Sessions"
3
+ slug: "sales/checkout-sessions"
4
+ section: "sales"
5
+ description: "Monitor live traffic and debug failed purchase attempts"
6
+ ---
7
+ While the **Orders** page tracks successful revenue, the **Checkout Sessions** page tracks every single attempt.
8
+
9
+ This is your granular, real-time log of what is happening on your payment page right now. It is essential for debugging failed transactions and recovering abandoned carts.
10
+
11
+ ## Accessing sessions
12
+
13
+
14
+
15
+ Go to **Sales > Checkout sessions** in the sidebar.
16
+
17
+
18
+
19
+
20
+ Use the status tabs to isolate specific types of traffic:
21
+ * **Open:** Customers currently on the payment page.
22
+ * **Succeeded:** Completed purchases.
23
+ * **Failed:** Declined cards or errors.
24
+ * **Expired:** Sessions where the customer left without paying.
25
+
26
+
27
+ <img height="200" src="/images/checkout-sessions-list.png" alt="List of checkout sessions showing status and customer emails" />
28
+
29
+ ## Session details
30
+
31
+ Click on any session to see the raw data. This is useful if you need to understand *why* a transaction failed (e.g. "Card expired" vs "Insufficient funds").
32
+
33
+ <img height="200" src="/images/checkout-session-detail.png" alt="Detailed view of a checkout session including timeline" />
34
+
35
+ ### Customer & context
36
+ See exactly who is attempting to buy and where they are coming from.
37
+ * **Customer info:** Email address, location, and IP address.
38
+ * **Product:** The specific item or license they are trying to purchase.
39
+ * **Device:** The payment method and device type used.
40
+
41
+ ### The timeline
42
+ The timeline allows you to reconstruct the customer's journey step-by-step.
43
+ 1. **Session created:** The moment they clicked your buy button.
44
+ 2. **Details provided:** When they filled in their email or card info.
45
+ 3. **Outcome:** The specific failure reason (e.g. `card_declined`) or success message.
46
+
47
+ ## Actions & recovery
48
+
49
+ This page gives you tools to assist customers who are stuck.
50
+
51
+ * **Recover sales**
52
+ If you see a **Failed** session, you can use the email address to reach out and offer support.
53
+ * **Share portal access**
54
+ For successful sessions, you can copy the **Portal Link** directly from the details view and send it to the customer manually.
55
+ * **Resend receipt**
56
+ Trigger a new email receipt if the customer missed the first one.
57
+ * **View order**
58
+ Click the **Order** button to jump straight to the official revenue record in the Orders page.
@@ -0,0 +1,76 @@
1
+ ---
2
+ title: "Orders"
3
+ slug: "sales/orders"
4
+ section: "sales"
5
+ description: "Track revenue and manage individual customer purchases"
6
+ ---
7
+ The **Orders** page is your central hub for transaction history. It shows a real-time list of every purchase made through your checkout.
8
+
9
+ Navigate to **Sales > Orders** in the sidebar to access it.
10
+
11
+ <img height="200" src="/images/orders-list-view.png" alt="Orders list view showing customer email, product, and status" />
12
+
13
+ ## The order list
14
+
15
+ The main view provides a high-level summary of your incoming revenue. You can see:
16
+ * **Customer:** Email address of the buyer.
17
+ * **Product:** What they purchased.
18
+ * **Status:** The current state (Paid, Refunded, Chargeback).
19
+ * **Date:** When the order was placed.
20
+ * **Revenue:** The total amount captured.
21
+
22
+ ### Filtering
23
+ You can filter the list to find specific transactions.
24
+ * **Date range:** Select specific days or months.
25
+ * **Status:** Filter by Paid, Refunded, or Chargeback.
26
+
27
+ ### Quick actions
28
+ Click the **three-dot menu (...)** on any row to perform quick actions without opening the full details.
29
+
30
+ <img height="200" src="/images/orders-quick-actions.png" alt="Meatball menu showing refund and receipt options" />
31
+
32
+ * **Refund payment:** Initiate a full or partial refund.
33
+ * **Send receipt:** Resend the email receipt to the customer.
34
+ * **Generate invoice:** Download the official invoice for the transaction.
35
+
36
+ ---
37
+
38
+ ## Order details
39
+
40
+ Click on any row to open the **Order Drawer**. This panel gives you complete control over that specific transaction.
41
+
42
+ <img height="200" src="/images/order-drawer-overview.png" alt="Side drawer showing customer details and order summary" />
43
+
44
+ ### Overview
45
+ The default view shows the core transaction data.
46
+ * **Customer details:** Name, email, and IP address.
47
+ * **Payment info:** Credit card last-4, banking details, and billing address.
48
+ * **Order summary:** Line items, taxes (VAT/GST), discounts applied, and the total charge.
49
+
50
+ ### Deliverables
51
+ Manage exactly what this specific customer received.
52
+
53
+ * **Licenses:**
54
+ View the generated license key. You can edit activation limits, change the expiry date, or deactivate the key entirely if you suspect abuse.
55
+ * **Downloads:**
56
+ See which files the customer has access to. You can remove or hide specific files for this order if you need to revoke access to a particular asset.
57
+ * **Links:**
58
+ View the external links shared with this customer.
59
+
60
+ ### Subscription
61
+ If the order is tied to a recurring plan, a **Subscription** tab will appear.
62
+ * Click the subscription ID to see the full billing history.
63
+ * Check upcoming renewal dates and past invoices.
64
+ * See if other products were bundled in the same plan.
65
+
66
+ ### Timeline
67
+ The timeline acts as an audit log for the order. It tracks every event chronologically.
68
+
69
+ <img height="200" src="/images/order-timeline.png" alt="Timeline view showing order creation, payment success, and email receipts" />
70
+
71
+ * Order created
72
+ * Receipts and invoices sent
73
+ * Payment success or failure
74
+ * Subscription creation
75
+
76
+ This is useful for debugging customer issues, such as verifying if they actually received their receipt email.
@@ -0,0 +1,28 @@
1
+ import { type AuthScope, type KelviqConfig } from '../config.js';
2
+ import { type KelviqAPIError } from './errors.js';
3
+ export type RequestInit = {
4
+ method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
5
+ /** Path beneath the host root, e.g. '/customers/'. */
6
+ path: string;
7
+ /** JSON body, if any. */
8
+ body?: unknown;
9
+ /** Query string params. Skipped when value is null/undefined. */
10
+ query?: Record<string, string | number | boolean | null | undefined>;
11
+ /** Which API host to call. Defaults to 'base'. */
12
+ host?: 'base' | 'edge' | 'entitlements';
13
+ /** Which API key to send. */
14
+ auth: AuthScope;
15
+ };
16
+ export type Result<T> = {
17
+ ok: true;
18
+ data: T;
19
+ } | {
20
+ ok: false;
21
+ } & KelviqAPIError;
22
+ export declare class KelviqHttpClient {
23
+ private readonly config;
24
+ constructor(config: KelviqConfig);
25
+ request<T = unknown>(init: RequestInit): Promise<Result<T>>;
26
+ private buildUrl;
27
+ private missingKeyError;
28
+ }
@@ -0,0 +1,76 @@
1
+ import { requireKey, MissingKeyError } from '../config.js';
2
+ import { fromException, fromHttpResponse } from './errors.js';
3
+ export class KelviqHttpClient {
4
+ config;
5
+ constructor(config) {
6
+ this.config = config;
7
+ }
8
+ async request(init) {
9
+ let key;
10
+ try {
11
+ key = requireKey(this.config, init.auth);
12
+ }
13
+ catch (err) {
14
+ if (err instanceof MissingKeyError) {
15
+ return { ok: false, ...this.missingKeyError(err) };
16
+ }
17
+ return { ok: false, ...fromException(err) };
18
+ }
19
+ const host = init.host === 'edge'
20
+ ? this.config.edgeUrl
21
+ : init.host === 'entitlements'
22
+ ? this.config.entitlementsUrl
23
+ : this.config.baseUrl;
24
+ const url = this.buildUrl(host, init.path, init.query);
25
+ let response;
26
+ try {
27
+ response = await fetch(url, {
28
+ method: init.method,
29
+ headers: {
30
+ Authorization: `Bearer ${key}`,
31
+ 'User-Agent': this.config.userAgent,
32
+ Accept: 'application/json',
33
+ ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
34
+ },
35
+ body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
36
+ });
37
+ }
38
+ catch (err) {
39
+ return { ok: false, ...fromException(err) };
40
+ }
41
+ const raw = await response.text();
42
+ let parsed = raw;
43
+ if (raw.length > 0) {
44
+ try {
45
+ parsed = JSON.parse(raw);
46
+ }
47
+ catch {
48
+ // leave as text
49
+ }
50
+ }
51
+ if (!response.ok) {
52
+ return { ok: false, ...fromHttpResponse(response.status, parsed) };
53
+ }
54
+ return { ok: true, data: parsed };
55
+ }
56
+ buildUrl(host, path, query) {
57
+ const url = new URL(host.replace(/\/+$/, '') + (path.startsWith('/') ? path : `/${path}`));
58
+ if (query) {
59
+ for (const [k, v] of Object.entries(query)) {
60
+ if (v === null || v === undefined)
61
+ continue;
62
+ url.searchParams.set(k, String(v));
63
+ }
64
+ }
65
+ return url.toString();
66
+ }
67
+ missingKeyError(err) {
68
+ return {
69
+ error: {
70
+ status: 'Configuration error',
71
+ message: err.message,
72
+ },
73
+ };
74
+ }
75
+ }
76
+ //# sourceMappingURL=client.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Normalized error shape returned to MCP tool callers as JSON content.
3
+ *
4
+ * Kelviq returns two error shapes in the wild:
5
+ * - { status, message } (ErrorResponse)
6
+ * - { detail } (DetailErrorResponse)
7
+ * Plus the usual network / serialization failures. We collapse all of these
8
+ * into KelviqAPIError so tool implementations don't have to branch.
9
+ */
10
+ export interface KelviqAPIError {
11
+ error: {
12
+ status: string;
13
+ message: string;
14
+ httpStatus?: number;
15
+ raw?: unknown;
16
+ };
17
+ }
18
+ export declare function isKelviqAPIError(value: unknown): value is KelviqAPIError;
19
+ export declare function fromHttpResponse(httpStatus: number, body: unknown): KelviqAPIError;
20
+ export declare function fromException(err: unknown): KelviqAPIError;