@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,771 @@
1
+ ---
2
+ title: "React UI"
3
+ slug: "frontend-integration/react-ui"
4
+ section: "frontend-integration"
5
+ description: "Documentation for the kelviq React UI SDK - A comprehensive pricing table and paywall solution"
6
+ ---
7
+ ## 1. Overview
8
+
9
+ The **kelviq React UI SDK** provides a complete React-based solution for integrating dynamic, customizable pricing tables and paywalls into web applications. It handles fetching offering data, displaying pricing plans with multiple billing periods, managing subscriptions, and processing checkouts with full localization support.
10
+
11
+ ---
12
+
13
+ ## 2. Installation
14
+
15
+ Install the SDK using npm or yarn:
16
+
17
+ ```bash
18
+ npm install @kelviq/react-ui
19
+ # or
20
+ yarn add @kelviq/react-ui
21
+ ```
22
+
23
+ ---
24
+
25
+ ## 3. Quick Start
26
+
27
+ ### Basic Setup
28
+
29
+ Note: You must import the CSS file for the components to be styled correctly.
30
+
31
+ ```tsx
32
+ import { KelviqProvider, KQPricingTable } from '@kelviq/react-ui';
33
+ import '@kelviq/react-ui/dist/kq-react-ui.css';
34
+
35
+ function App() {
36
+ return (
37
+ <KelviqProvider
38
+ accessToken="YOUR_ACCESS_TOKEN"
39
+ offeringId="YOUR_OFFERING_ID"
40
+ customerId="OPTIONAL_CUSTOMER_ID"
41
+ >
42
+
43
+ </KelviqProvider>
44
+ );
45
+ }
46
+ ```
47
+
48
+ ### With Custom Event Handling
49
+
50
+ ```tsx
51
+ import { KelviqProvider, KQPricingTable } from '@kelviq/react-ui';
52
+ import '@kelviq/react-ui/dist/kq-react-ui.css';
53
+
54
+ function App() {
55
+ const handleCustomPriceClick = (details) => {
56
+ console.log('Custom price plan clicked:', details);
57
+ // Handle custom pricing logic
58
+ };
59
+
60
+ return (
61
+ <KelviqProvider
62
+ accessToken="YOUR_ACCESS_TOKEN"
63
+ offeringId="YOUR_OFFERING_ID"
64
+ customerId="OPTIONAL_CUSTOMER_ID"
65
+ >
66
+
67
+ </KelviqProvider>
68
+ );
69
+ }
70
+ ```
71
+
72
+ ---
73
+
74
+ ## 4. Core Components
75
+
76
+ ### 4.1. `KelviqProvider`
77
+
78
+ The top-level provider component that initializes the SDK and manages the global state.
79
+
80
+ #### Required Props
81
+
82
+ | Prop | Type | Description |
83
+ |------|------|-------------|
84
+ | `accessToken` | `string` | Your kelviq client access token |
85
+ | `offeringId` | `string` | The unique identifier for your offering |
86
+
87
+ #### Optional Props
88
+
89
+ | Prop | Type | Default | Description |
90
+ |------|------|---------|-------------|
91
+ | `customerId` | `string` | `undefined` | Customer identifier for personalized pricing |
92
+ | `environment` | `sandbox\|production` | 'production' | The environment to use. If you want to use the sandbox, you must provide this. |
93
+ | `checkoutSuccessUrl` | `string` | `window.location.href` | URL to redirect after successful checkout |
94
+ | `apiConfig` | `KelviqAPIConfig` | `{}` | Advanced API configuration options |
95
+
96
+ #### API Configuration Options
97
+
98
+ ```tsx
99
+ interface KelviqAPIConfig {
100
+ onError?: (error: Error) => void;
101
+ maxRetries?: number; // Default: 3
102
+ timeout?: number; // Default: 5000ms
103
+ backoffBaseDelay?: number;
104
+ offeringApiUrl?: string;
105
+ subscriptionApiUrl?: string;
106
+ checkoutApiUrl?: string;
107
+ }
108
+ ```
109
+
110
+ ### 4.2. `KQPricingTable`
111
+
112
+ The main pricing table component that displays all plans and handles user interactions.
113
+
114
+ #### Props
115
+
116
+ | Prop | Type | Default | Description |
117
+ |------|------|---------|-------------|
118
+ | `customStyles` | `PricingTableStyle` | `{}` | Custom styling configuration |
119
+ | `customActionButton` | `CustomActionButton` | `undefined` | Custom button component |
120
+ | `customCheckIcon` | `React.ReactNode` | `undefined` | Custom check icon |
121
+ | `customUnCheckIcon` | `React.ReactNode` | `undefined` | Custom uncheck icon |
122
+ | `customTooltipIcon` | `React.ReactNode` | `undefined` | Custom tooltip icon |
123
+ | `onCustomPriceClick` | `(details: PlanClickDetails) => void` | `undefined` | Callback for custom price plans |
124
+ | `renderActionButtonAfter` | `features \| price` | `price` | Render the action button after the features or the price |
125
+ | `insertElements.*` | `InsertElements` | `{}` | Insert custom elements anywhere in the pricing table |
126
+ | `insertElements.beforePlanName` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the plan name |
127
+ | `insertElements.afterPlanName` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the plan name |
128
+ | `insertElements.beforePlanDescription` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the plan description |
129
+ | `insertElements.afterPlanDescription` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the plan description |
130
+ | `insertElements.beforePrice` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the price |
131
+ | `insertElements.afterPrice` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the price |
132
+ | `insertElements.beforeFeatures` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the features |
133
+ | `insertElements.afterFeatures` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the features |
134
+ | `insertElements.beforeActionButton` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the action button |
135
+ | `insertElements.afterActionButton` | `(plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the action button |
136
+ | `insertElements.beforeSwitch` | `(activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements before the switch |
137
+ | `insertElements.afterSwitch` | `(activePeriod: ChargePeriodEnum) => JSX.Element` | `undefined` | Insert custom elements after the switch |
138
+
139
+ #### Example Usage
140
+
141
+ ```tsx
142
+ <KQPricingTable
143
+ onCustomPriceClick={(details) => {
144
+ console.log('Custom plan selected:', details.plan.displayName);
145
+ // Handle custom pricing logic
146
+ }}
147
+ customStyles={{
148
+ style: {
149
+ cardBackgroundColor: '#f8f9fa',
150
+ buttonBackgroundColor: '#28a745',
151
+ buttonColor: '#ffffff',
152
+ titleColor: '#212529'
153
+ },
154
+ typography: {
155
+ titleFontSize: 24,
156
+ titleFontWeight: '600'
157
+ },
158
+ layout: {
159
+ gap: 20,
160
+ minWidth: 280,
161
+ maxWidth: 400
162
+ }
163
+ }}
164
+ insertElements={{
165
+ afterPrice: (plan) => {
166
+ if(plan.shouldHighlight) {
167
+ return <div>Most popular plan</div>;
168
+ }
169
+ return null;
170
+ }
171
+ }}
172
+ />
173
+ ```
174
+
175
+ ### 4.3. `KQPlan`
176
+
177
+ Renders a list of pricing plans with billing period switching.
178
+
179
+ #### Props
180
+
181
+ | Prop | Type | Required | Description |
182
+ |------|------|----------|-------------|
183
+ | `plans` | `OfferingPlan[]` | Yes | Array of plans to display |
184
+ | `pricingTable` | `PricingTable` | Yes | Pricing table configuration |
185
+ | `billingPeriods` | `BillingPeriod[]` | Yes | Available billing periods |
186
+ | `countryCode` | `string` | Yes | Country code for localization |
187
+ | `currencyCode` | `string` | Yes | Currency code (e.g., "USD") |
188
+ | `currencySymbol` | `string` | Yes | Currency symbol (e.g., "$") |
189
+ | `currencyConversionRate` | `number` | Yes | Currency conversion rate |
190
+ | `pricingLocale` | `string` | Yes | Locale for price formatting |
191
+ | `onPlanClick` | `(details: PlanClickDetails) => void` | Yes | Plan selection callback |
192
+ | `customStyles` | `PricingTableStyle` | No | Custom styling |
193
+ | `customActionButton` | `CustomActionButton` | No | Custom button component |
194
+ | `actionButtonLoadingPlanIdentifier` | `string` | No | Loading state for specific plan |
195
+ | `noStyles` | `boolean` | No | Disable default styling |
196
+
197
+ ### 4.4. `KQPlanItem`
198
+
199
+ Displays a single pricing plan card.
200
+
201
+ #### Props
202
+
203
+ | Prop | Type | Required | Description |
204
+ |------|------|----------|-------------|
205
+ | `plan` | `OfferingPlan` | Yes | Plan data to display |
206
+ | `pricingTable` | `PricingTable` | Yes | Pricing table configuration |
207
+ | `period` | `ChargePeriodEnum` | Yes | Current billing period |
208
+ | `countryCode` | `string` | Yes | Country code |
209
+ | `currencyCode` | `string` | Yes | Currency code |
210
+ | `currencySymbol` | `string` | Yes | Currency symbol |
211
+ | `currencyConversionRate` | `number` | Yes | Conversion rate |
212
+ | `pricingLocale` | `string` | Yes | Locale for formatting |
213
+ | `onKQPlanItemClick` | `(details: PlanClickDetails) => void` | Yes | Click handler |
214
+ | `customActionButton` | `CustomActionButton` | No | Custom button |
215
+ | `actionButtonText` | `string` | No | Button text |
216
+ | `actionButtonLoading` | `boolean` | No | Loading state |
217
+ | `actionButtonDisabled` | `boolean` | No | Disabled state |
218
+ | `isActive` | `boolean` | No | Active plan indicator |
219
+ | `successText` | `string` | No | Success message |
220
+ | `noStyles` | `boolean` | No | Disable styling |
221
+
222
+ ### 4.5. `KQPrice`
223
+
224
+ Renders formatted price display with currency and period information.
225
+
226
+ #### Props
227
+
228
+ | Prop | Type | Required | Description |
229
+ |------|------|----------|-------------|
230
+ | `price` | `number` | Yes | Price amount |
231
+ | `countryCode` | `string` | Yes | Country code |
232
+ | `currencyCode` | `string` | Yes | Currency code |
233
+ | `currencySymbol` | `string` | Yes | Currency symbol |
234
+ | `currencyConversionRate` | `number` | Yes | Conversion rate |
235
+ | `pricingLocale` | `string` | Yes | Locale for formatting |
236
+ | `period` | `ChargePeriodEnum` | Yes | Billing period |
237
+ | `showDecimal` | `boolean` | Yes | Show decimal places |
238
+ | `showCurrencySymbol` | `boolean` | Yes | Show currency symbol |
239
+ | `showCurrencyCode` | `boolean` | Yes | Show currency code |
240
+ | `minimumFractionDigits` | `number` | Yes | Minimum decimal places |
241
+ | `maximumFractionDigits` | `number` | Yes | Maximum decimal places |
242
+
243
+ ### 4.6. `KQFeatures`
244
+
245
+ Renders the features list for a plan.
246
+
247
+ #### Props
248
+
249
+ | Prop | Type | Required | Description |
250
+ |------|------|----------|-------------|
251
+ | `features` | `OfferingFeature[]` | Yes | Array of features |
252
+ | `period` | `ChargePeriodEnum` | Yes | Current billing period |
253
+ | `customCheckIcon` | `React.ReactNode` | No | Custom check icon |
254
+ | `customUnCheckIcon` | `React.ReactNode` | No | Custom uncheck icon |
255
+ | `customTooltipIcon` | `React.ReactNode` | No | Custom tooltip icon |
256
+ | `descriptionTooltipEnabled` | `boolean` | No | Enable tooltips |
257
+ | `onUsageChange` | `(featureId: string, quantity: number) => void` | No | Usage change handler |
258
+
259
+ ---
260
+
261
+ ## 5. Data Types
262
+
263
+ ### Core Types
264
+
265
+ ```tsx
266
+ // Billing periods
267
+ enum ChargePeriodEnum {
268
+ ONE_TIME = 'ONE_TIME',
269
+ MONTHLY = 'MONTHLY',
270
+ YEARLY = 'YEARLY',
271
+ WEEKLY = 'WEEKLY',
272
+ DAILY = 'DAILY',
273
+ THREE_MONTHS = 'THREE_MONTHS',
274
+ SIX_MONTHS = 'SIX_MONTHS'
275
+ }
276
+
277
+ // Price types
278
+ enum PriceTypeEnum {
279
+ FREE = 'FREE',
280
+ PAID = 'PAID',
281
+ CUSTOM = 'CUSTOM'
282
+ }
283
+
284
+ // Price models
285
+ enum PriceModelEnum {
286
+ FLAT = 'FLAT',
287
+ PACKAGE = 'PACKAGE',
288
+ TIERED = 'TIERED',
289
+ VOLUME = 'VOLUME'
290
+ }
291
+
292
+ // Plan structure
293
+ interface OfferingPlan {
294
+ id: string;
295
+ name: string;
296
+ displayName: string;
297
+ displayDescription: string;
298
+ identifier: string;
299
+ isArchived: boolean;
300
+ features: OfferingFeature[];
301
+ price: OfferingPlanPrice;
302
+ shouldHighlight: boolean;
303
+ enabled: boolean;
304
+ }
305
+
306
+ // Plan click details
307
+ interface PlanClickDetails {
308
+ plan: OfferingPlan;
309
+ chargePeriod: ChargePeriodEnum;
310
+ usageMap: Record<string, number>;
311
+ }
312
+
313
+ // Pricing table style
314
+ interface PricingTableStyle {
315
+ style: PricingTableColorConfig;
316
+ typography: PricingTableTypographyConfig;
317
+ layout: PricingTableLayoutConfig;
318
+ }
319
+ ```
320
+
321
+ ### Color Configuration
322
+
323
+ ```tsx
324
+ interface PricingTableColorConfig {
325
+ primaryColor: string;
326
+ primaryHoverColor: string;
327
+ onPrimaryColor: string;
328
+ secondaryColor: string;
329
+ cardBackgroundColor: string;
330
+ billingSwitchBackgroundColor: string;
331
+ billingSwitchColor: string;
332
+ billingSwitchSelectedColor: string;
333
+ titleColor: string;
334
+ descriptionColor: string;
335
+ priceColor: string;
336
+ priceUnitColor: string;
337
+ pricePeriodColor: string;
338
+ featureColor: string;
339
+ dividerColor: string;
340
+ buttonBackgroundColor: string;
341
+ buttonColor: string;
342
+ buttonHoverBackgroundColor: string;
343
+ advancedMode: boolean;
344
+ }
345
+ ```
346
+
347
+ ### Typography Configuration
348
+
349
+ ```tsx
350
+ interface PricingTableTypographyConfig {
351
+ titleFontSize: number;
352
+ titleFontWeight: string;
353
+ descriptionFontSize: number;
354
+ descriptionFontWeight: string;
355
+ priceFontSize: number;
356
+ priceFontWeight: string;
357
+ priceUnitFontSize: number;
358
+ priceUnitFontWeight: string;
359
+ featureFontSize: number;
360
+ featureFontWeight: string;
361
+ pricePeriodFontSize: number;
362
+ pricePeriodFontWeight: string;
363
+ }
364
+ ```
365
+
366
+ ### Layout Configuration
367
+
368
+ ```tsx
369
+ interface PricingTableLayoutConfig {
370
+ minWidth: number;
371
+ maxWidth: number;
372
+ gap: number;
373
+ align: 'start' | 'center' | 'end';
374
+ }
375
+ ```
376
+
377
+ ---
378
+
379
+ ## 6. Styling and Customization
380
+
381
+ ### 6.1. CSS Variables
382
+
383
+ The SDK uses CSS variables for styling. You can override these in your CSS:
384
+
385
+ ```css
386
+ :root {
387
+ /* Card & Background */
388
+ --kq-card-bg: #ffffff;
389
+ --kq-card-border-width: 1px solid;
390
+ --kq-card-border-color: 1px solid;
391
+
392
+ /* Text Colors */
393
+ --kq-title-color: #171923;
394
+ --kq-description-color: #718096;
395
+ --kq-feature-color: #171923;
396
+
397
+ /* Price Colors */
398
+ --kq-price-color: #171923;
399
+ --kq-price-unit-color: #171923;
400
+ --kq-price-period-color: #718096;
401
+
402
+ /* Button Colors */
403
+ --kq-button-bg: #1A202C;
404
+ --kq-button-hover-bg: #1A202C;
405
+ --kq-button-color: #F7FAFC;
406
+
407
+ /* Billing Switch Colors */
408
+ --kq-billing-switch-bg: #1A202C;
409
+ --kq-billing-switch-color: #F7FAFC;
410
+ --kq-billing-switch-selected-color: #F7FAFC;
411
+
412
+ /* UI Elements */
413
+ --kq-divider-color: #E2E8F0;
414
+ --kq-tooltip-bg: #2D3748;
415
+ --kq-tooltip-color: #ffffff;
416
+
417
+ /* Typography - Title */
418
+ --kq-title-size: 24px;
419
+ --kq-title-weight: 600;
420
+
421
+ /* Typography - Description */
422
+ --kq-description-size: 16px;
423
+ --kq-description-weight: 400;
424
+
425
+ /* Typography - Price */
426
+ --kq-price-size: 28px;
427
+ --kq-price-weight: 700;
428
+ --kq-price-unit-size: 32px;
429
+ --kq-price-unit-weight: 700;
430
+ --kq-price-period-size: 16px;
431
+ --kq-price-period-weight: 400;
432
+
433
+ /* Typography - Feature */
434
+ --kq-feature-size: 14px;
435
+ --kq-feature-weight: 400;
436
+
437
+ /* Layout */
438
+ --kq-min-width: 360px;
439
+ --kq-max-width: 400px;
440
+ --kq-gap: 24px;
441
+ --kq-align: center;
442
+ }
443
+ ```
444
+
445
+ ### 6.2. Custom Styles Object
446
+
447
+ ```tsx
448
+ const customStyles: PricingTableStyle = {
449
+ style: {
450
+ cardBackgroundColor: '#ffffff',
451
+ buttonBackgroundColor: '#28a745',
452
+ buttonColor: '#ffffff',
453
+ titleColor: '#212529',
454
+ descriptionColor: '#6c757d',
455
+ priceColor: '#000000',
456
+ featureColor: '#495057'
457
+ },
458
+ typography: {
459
+ titleFontSize: 24,
460
+ titleFontWeight: '600',
461
+ descriptionFontSize: 14,
462
+ descriptionFontWeight: '400',
463
+ priceFontSize: 32,
464
+ priceFontWeight: '700'
465
+ },
466
+ layout: {
467
+ gap: 24,
468
+ minWidth: 300,
469
+ maxWidth: 450,
470
+ align: 'center'
471
+ }
472
+ };
473
+ ```
474
+
475
+ ### 6.3. Custom Action Button
476
+
477
+ ```tsx
478
+ const CustomButton: CustomActionButton = ({ onClick, children, plan, disabled }) => (
479
+ <button
480
+ onClick={onClick}
481
+ disabled={disabled}
482
+ className="my-custom-button"
483
+ style={{
484
+ backgroundColor: plan.shouldHighlight ? '#ff6b35' : '#007bff',
485
+ color: '#ffffff',
486
+ padding: '12px 24px',
487
+ border: 'none',
488
+ borderRadius: '6px',
489
+ cursor: disabled ? 'not-allowed' : 'pointer'
490
+ }}
491
+ >
492
+ {children}
493
+ </button>
494
+ );
495
+
496
+ ```
497
+
498
+ ### 6.4. noStyles Mode
499
+
500
+ For complete styling control, use the `noStyles` prop:
501
+
502
+ ```tsx
503
+
504
+ ```
505
+
506
+ ### 6.5. CSS Class Reference
507
+
508
+ The kelviq React UI components use consistent CSS class names that you can target for custom styling. All classes are prefixed with `kq-` to avoid naming conflicts.
509
+
510
+ #### CSS Class Hierarchy
511
+
512
+ ```css
513
+ .kq-plan /* Root container */
514
+ ├── .kq-plan-switch /* Billing period switcher */
515
+ │ └── .kq-switch /* Switch wrapper */
516
+ │ └── .kq-switch-button /* Individual switch buttons */
517
+ │ └── .kq-promo-caption /* Discount badges (20%, etc.) */
518
+ ├── .kq-plan-items /* Plans container */
519
+ └── .kq-plan-item /* Individual plan card */
520
+ ├── .kq-plan-item-header /* Plan title section */
521
+ │ ├── .kq-plan-item-heading /* Plan name */
522
+ │ └── .kq-plan-item-subheading /* Plan description */
523
+ ├── .kq-plan-item-price /* Price section */
524
+ │ ├── .kq-price-container /* Price wrapper */
525
+ │ │ ├── .kq-price-currency /* Currency container */
526
+ │ │ │ ├── .kq-price-currency-symbol /* $ symbol */
527
+ │ │ │ └── .kq-price-currency-code /* USD text */
528
+ │ │ ├── .kq-price-integer /* Main price number */
529
+ │ │ ├── .kq-price-decimal-separator /* Decimal point */
530
+ │ │ └── .kq-price-decimal /* Decimal digits */
531
+ │ └── .kq-plan-item-price-period /* /month text */
532
+ ├── .kq-separator /* Divider line */
533
+ ├── .kq-plan-item-features /* Features section */
534
+ │ └── .kq-features-list /* Features list */
535
+ │ └── .kq-features-list-item /* Individual features */
536
+ │ ├── .kq-tooltip-wrapper /* Feature tooltips */
537
+ │ │ └── .kq-tooltip /* Tooltip content */
538
+ │ ├── .kq-feature-quantity-input /* Quantity number input */
539
+ │ ├── .kq-feature-quantity-input-unit /* Input unit label */
540
+ │ └── .kq-feature-quantity-select-container /* Quantity dropdown */
541
+ │ ├── .kq-feature-quantity-select /* Select element */
542
+ │ └── .kq-feature-quantity-select-arrow /* Dropdown arrow */
543
+ └── .kq-plan-item-button /* CTA button */
544
+ ```
545
+
546
+ ---
547
+
548
+ ## 7. Advanced Features
549
+
550
+ ### 7.1. Usage-Based Pricing
551
+
552
+ The SDK supports metered billing and tiered pricing:
553
+
554
+ ```tsx
555
+ // Features with usage tracking
556
+ const features = [
557
+ {
558
+ identifier: 'api_calls',
559
+ displayName: 'API Calls',
560
+ priceModel: PriceModelEnum.VOLUME,
561
+ charges: [
562
+ {
563
+ chargePeriod: ChargePeriodEnum.MONTHLY,
564
+ tiers: [
565
+ { flatAmount: 0, unitAmount: 0.01, upTo: 1000 },
566
+ { flatAmount: 10, unitAmount: 0.008, upTo: 10000 },
567
+ { flatAmount: 82, unitAmount: 0.005, upTo: null }
568
+ ]
569
+ }
570
+ ]
571
+ }
572
+ ];
573
+ ```
574
+
575
+ ### 7.2. Custom Price Plans
576
+
577
+ Handle custom pricing plans with the `onCustomPriceClick` callback:
578
+
579
+ ```tsx
580
+ <KQPricingTable
581
+ onCustomPriceClick={(details) => {
582
+ // Open contact form or custom pricing modal
583
+ openCustomPricingModal(details.plan);
584
+ }}
585
+ />
586
+ ```
587
+
588
+ ### 7.3. Subscription Management
589
+
590
+ The SDK automatically handles subscription updates:
591
+
592
+ - **New Subscriptions**: Redirects to checkout
593
+ - **Plan Upgrades/Downgrades**: Updates existing subscription
594
+ - **Free Plan Upgrades**: Handles free trial to paid conversion
595
+
596
+ ### 7.4. Error Handling
597
+
598
+ ```tsx
599
+ <KelviqProvider
600
+ accessToken="YOUR_TOKEN"
601
+ offeringId="YOUR_OFFERING"
602
+ apiConfig={{
603
+ onError: (error) => {
604
+ console.error('kelviq Error:', error);
605
+ // Show user-friendly error message
606
+ showErrorMessage('Unable to load pricing. Please try again later.');
607
+ },
608
+ maxRetries: 3,
609
+ timeout: 10000
610
+ }}
611
+ >
612
+
613
+ </KelviqProvider>
614
+ ```
615
+
616
+ ---
617
+
618
+ ## 8. Complete Example
619
+
620
+ ```tsx
621
+ import React from 'react';
622
+ import {
623
+ KelviqProvider,
624
+ KQPricingTable,
625
+ PricingTableStyle
626
+ } from '@kelviq/react-ui';
627
+
628
+ const App: React.FC = () => {
629
+ const customStyles: PricingTableStyle = {
630
+ style: {
631
+ cardBackgroundColor: '#ffffff',
632
+ buttonBackgroundColor: '#007bff',
633
+ buttonColor: '#ffffff',
634
+ buttonHoverBackgroundColor: '#0056b3',
635
+ titleColor: '#212529',
636
+ descriptionColor: '#6c757d',
637
+ priceColor: '#000000',
638
+ featureColor: '#495057',
639
+ dividerColor: '#dee2e6',
640
+ billingSwitchBackgroundColor: '#f8f9fa',
641
+ billingSwitchColor: '#6c757d',
642
+ billingSwitchSelectedColor: '#007bff'
643
+ },
644
+ typography: {
645
+ titleFontSize: 24,
646
+ titleFontWeight: '600',
647
+ descriptionFontSize: 14,
648
+ descriptionFontWeight: '400',
649
+ priceFontSize: 32,
650
+ priceFontWeight: '700',
651
+ priceUnitFontSize: 16,
652
+ priceUnitFontWeight: '400',
653
+ featureFontSize: 14,
654
+ featureFontWeight: '400',
655
+ pricePeriodFontSize: 14,
656
+ pricePeriodFontWeight: '400'
657
+ },
658
+ layout: {
659
+ gap: 24,
660
+ minWidth: 300,
661
+ maxWidth: 450,
662
+ align: 'center'
663
+ }
664
+ };
665
+
666
+ const handleCustomPriceClick = (details) => {
667
+ console.log('Custom plan selected:', details.plan.displayName);
668
+ // Open contact form or pricing calculator
669
+ window.open('/contact', '_blank');
670
+ };
671
+
672
+ return (
673
+ <div className="app">
674
+ <header>
675
+ <h1>Choose Your Plan</h1>
676
+ <p>Select the perfect plan for your needs</p>
677
+ </header>
678
+
679
+ <KelviqProvider
680
+ accessToken="your-access-token"
681
+ offeringId="your-offering-id"
682
+ customerId="optional-customer-id"
683
+ checkoutSuccessUrl="https://yourapp.com/success"
684
+ apiConfig={{
685
+ onError: (error) => {
686
+ console.error('Pricing Error:', error);
687
+ },
688
+ timeout: 10000
689
+ }}
690
+ >
691
+
692
+ </KelviqProvider>
693
+ </div>
694
+ );
695
+ };
696
+
697
+ export default App;
698
+ ```
699
+
700
+ ---
701
+
702
+ ## 9. API Endpoints
703
+
704
+ The SDK uses the following default API endpoints:
705
+
706
+ - **Checkout API**: `https://api.kelviq.com/api/v1/checkout/`
707
+ - **Subscription API**: `https://api.kelviq.com/api/v1/subscriptions`
708
+
709
+ You can override these in the `apiConfig`:
710
+
711
+ ```tsx
712
+ <KelviqProvider
713
+ apiConfig={{
714
+ offeringApiUrl: 'https://your-api.com/offerings',
715
+ checkoutApiUrl: 'https://your-api.com/checkout',
716
+ subscriptionApiUrl: 'https://your-api.com/subscriptions'
717
+ }}
718
+ >
719
+ ```
720
+
721
+ ---
722
+
723
+ ## 10. Troubleshooting
724
+
725
+ ### Common Issues
726
+
727
+ 1. **Loading State**: Ensure your `accessToken` and `offeringId` are correct
728
+ 2. **Styling Issues**: Check CSS variable overrides and custom styles
729
+ 3. **API Errors**: Verify API endpoints and network connectivity
730
+ 4. **TypeScript Errors**: Ensure all required props are provided
731
+
732
+ ### Debug Mode
733
+
734
+ Enable console logging for debugging:
735
+
736
+ ```tsx
737
+ <KelviqProvider
738
+ apiConfig={{
739
+ onError: (error) => {
740
+ console.log('kelviq Debug:', {
741
+ error: error.message,
742
+ offeringId: 'your-offering-id',
743
+ timestamp: new Date().toISOString()
744
+ });
745
+ }
746
+ }}
747
+ >
748
+ ```
749
+ ---
750
+
751
+ ## Using the Sandbox
752
+
753
+ If you want to use the sandbox, you need to set the `environment` option to `sandbox` in the `KelviqProvider`.
754
+
755
+ ```tsx
756
+ <KelviqProvider
757
+ accessToken="YOUR_ACCESS_TOKEN"
758
+ offeringId="YOUR_OFFERING_ID"
759
+ environment="sandbox">
760
+
761
+ </KelviqProvider>
762
+ ```
763
+
764
+ ## 12. Support
765
+
766
+ For technical support and questions:
767
+
768
+ - **Documentation**: [docs.kelviq.com](https://docs.kelviq.com)
769
+ - **Email**: support@kelviq.com
770
+
771
+ ---