@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,265 @@
1
+ ---
2
+ title: "Promotions UI JS SDK"
3
+ slug: "frontend-integration/promotions-ui-js"
4
+ section: "frontend-integration"
5
+ description: "Add purchasing power parity discounts and a localised banner to any website"
6
+ ---
7
+ The Promotions UI JS SDK automatically applies location-based discounts to prices on your page and renders a customisable banner that tells visitors about their local deal. It works with plain HTML — no framework required.
8
+
9
+ This SDK is separate from the [entitlements JS SDK](/frontend-integration/js-sdk). Use this SDK when you need PPP / country-based discount banners and price display.
10
+
11
+ ---
12
+
13
+ ## Installation
14
+
15
+ ### 1. Add the Script
16
+
17
+ Paste this snippet just before the closing `<head>` tag on your pricing page:
18
+
19
+ ```html
20
+ <script type="text/javascript">
21
+ function resolvePdSDKFunction(n,...o){return new Promise((e,t)=>{!function i(){window.KQPromotionUISDK&&"function"==typeof window.KQPromotionUISDK[n]?window.KQPromotionUISDK[n](...o).then(e).catch(t):setTimeout(i,100)}()})}!function(n,o,e,t,i,r,c){n[t]=n[t]||function(){(n[t].q=n[t].q||[]).push(Array.prototype.slice.call(arguments))},r=o.createElement(e),c=o.getElementsByTagName(e)[0],r.id="kelviq-sdk",r.async=1,r.src="https://cdn.kelviq.com/js-promotions-ui/0.1/js-promotions-ui.umd.js",c.parentNode.insertBefore(r,c)}(window,document,"script","KQPromotionUISDK"),window.KQPromotionUI={init:function(n){KQPromotionUISDK("init",n)},getUpdatedPrice:function(n,o){return resolvePdSDKFunction("getUpdatedPrice",n,o)},updatePriceElement:function(n,o){return resolvePdSDKFunction("updatePriceElement",n,o)},updatePrice:function(n){return resolvePdSDKFunction("updatePrice",n)}};
22
+ </script>
23
+
24
+ ```
25
+
26
+ ### 2. Initialize the SDK
27
+
28
+ Copy your promotion ID from the promotion detail page and call `init()`:
29
+
30
+ <img src="/images/copy-promotion-id.png" alt="Copy promotion ID" />
31
+
32
+ ```javascript
33
+ KQPromotionUI.init({
34
+ // Replace with your promotion ID
35
+ promotionId: "YOUR_PROMOTION_ID",
36
+ // Access token can be found in the Settings -> API keys section
37
+ accessToken: "YOUR_CLIENT_ACCESS_TOKEN",
38
+ showBanner: true,
39
+ });
40
+ ```
41
+
42
+ This will automatically display a discount banner if the visitor is eligible for a discount.
43
+
44
+ **Never expose your Server API Key in the browser.** Use the **Client API Key**, which is safe for client-side code. You can find both keys under **Settings → API keys** in the [Kelviq dashboard](https://app.kelviq.com/settings/api-keys).
45
+
46
+ ---
47
+
48
+ ## `init()` options
49
+
50
+ | Option | Type | Default | Description |
51
+ |--------|------|---------|-------------|
52
+ | `promotionId` | `string` | — | Promotion ID from the Kelviq dashboard |
53
+ | `accessToken` | `string` | — | Client API Key (Settings → API keys) |
54
+ | `showBanner` | `boolean` | `true` | Render the localised discount banner automatically |
55
+ | `environment` | `"production" \| "sandbox"` | `"production"` | Target environment |
56
+ | `baseCurrencyCode` | `string` | `"USD"` | ISO 4217 code for prices displayed on the page |
57
+ | `baseCurrencySymbol` | `string` | `"$"` | Symbol written to `data-kq-currency-symbol` elements |
58
+ | `currencyDisplay` | `"symbol" \| "code" \| "name"` | `"symbol"` | How the currency is formatted via `Intl.NumberFormat` |
59
+ | `showDecimal` | `boolean` | `false` | Include the decimal portion in formatted prices |
60
+ | `minimumDecimalDigits` | `number` | `2` | Minimum fraction digits (0–2) |
61
+ | `maximumDecimalDigits` | `number` | `2` | Maximum fraction digits (0–2) |
62
+ | `banner.*` | object | — | Customization for the discount banner |
63
+ | `banner.unStyled` | boolean | false | if true, no styling will be applied to the banner |
64
+ | `banner.addCloseIcon`| boolean | true | Control close button visibility. This setting will work only if close button is enabled from the ParityDeals banner settings |
65
+ | `banner.placement` | `top\|bottom` | 'top' | The placement of the discount banner |
66
+ | `banner.container` | string | null | The container for the discount banner |
67
+ | `banner.backgroundColor`| string | '#f0f0f0' | The background color of the discount banner |
68
+ | `banner.fontColor` | string | '#333333' | The font color of the discount banner |
69
+ | `banner.borderRadius` | string | '0px' | The border radius of the discount banner |
70
+ | `banner.fontSize` | string | '14px' | The font size of the discount banner |
71
+
72
+ ---
73
+
74
+ ## Auto price update
75
+
76
+ After `init()` resolves, every element with `data-kq-price` on the page is automatically updated with the discounted price for the visitor's country.
77
+
78
+ ### Basic usage
79
+
80
+ ```html
81
+ <!-- Integer-only price -->
82
+ <div data-kq-price="49">
83
+ <sup data-kq-currency-symbol></sup>
84
+ <span data-kq-price-integer></span>
85
+ </div>
86
+
87
+ <!-- Price with decimal -->
88
+ <div data-kq-price="49" data-kq-show-decimal="true">
89
+ <sup data-kq-currency-symbol></sup>
90
+ <span data-kq-price-integer></span>
91
+ <span data-kq-price-decimal-separator></span>
92
+ <span data-kq-price-decimal></span>
93
+ </div>
94
+
95
+ <!-- Discounted price + original price (linked by data-kq-rel) -->
96
+ <div data-kq-price="79" data-kq-rel="pro-plan" data-kq-show-decimal="true">
97
+ <span data-kq-price-formatted></span>
98
+ </div>
99
+ <div data-kq-original-price-display="99" data-kq-rel="pro-plan" class="original-price">
100
+ <span data-kq-price-formatted></span>
101
+ </div>
102
+
103
+ <!-- Currency code instead of symbol -->
104
+ <div data-kq-price="99" data-kq-currency-display="code">
105
+ <span data-kq-price-formatted></span> <!-- renders e.g. "USD 99" -->
106
+ </div>
107
+ ```
108
+
109
+ The original-price element is hidden by default. The SDK shows it automatically when a discount is active and hides it when the visitor's country has no discount.
110
+
111
+ ### Price container attributes
112
+
113
+ | Attribute | Value | Description |
114
+ |-----------|-------|-------------|
115
+ | `data-kq-price` | `number` | Base price — the discounted value is computed and written to child elements |
116
+ | `data-kq-original-price-display` | `number` | Original (pre-discount) price; hidden when there is no active discount |
117
+ | `data-kq-rel` | `string` | Links a price element and its original-price element so they update together |
118
+ | `data-kq-show-decimal` | `"true" \| "false"` | Per-element decimal override (falls back to `showDecimal` from `init()`) |
119
+ | `data-kq-currency-display` | `"symbol" \| "code" \| "name"` | Per-element currency format |
120
+ | `data-kq-minimum-decimal-digits` | `number` | Per-element minimum fraction digits (0–2) |
121
+ | `data-kq-maximum-decimal-digits` | `number` | Per-element maximum fraction digits (0–2) |
122
+
123
+ ### Sub-element attributes
124
+
125
+ Place these inside a price container to receive individual parts of the formatted price:
126
+
127
+ | Attribute | Example output |
128
+ |-----------|----------------|
129
+ | `data-kq-currency-symbol` | `$` |
130
+ | `data-kq-price-integer` | `49` |
131
+ | `data-kq-price-decimal` | `99` |
132
+ | `data-kq-price-decimal-separator` | `.` |
133
+ | `data-kq-currency-code` | `USD` |
134
+ | `data-kq-price-formatted` | `$49.99` |
135
+
136
+ ---
137
+
138
+ ## JS API
139
+
140
+ All methods return Promises and require `init()` to have been called first.
141
+
142
+ ### `getUpdatedPrice(price, options?)`
143
+
144
+ Computes the discounted price and returns a `PriceObject` without touching the DOM.
145
+
146
+ ```javascript
147
+ const result = await KQPromotionUI.getUpdatedPrice(100, { showDecimal: true });
148
+ console.log(result.formattedPrice); // "$80.00"
149
+ console.log(result.price); // 80
150
+ ```
151
+
152
+ **Parameters**
153
+
154
+ | Parameter | Type | Description |
155
+ |-----------|------|-------------|
156
+ | `price` | `number` | Base price to apply the discount to |
157
+ | `options` | `Partial<Config>` | Optional overrides (same fields as `init()`) |
158
+
159
+ **Returns — `PriceObject`**
160
+
161
+ | Field | Type | Description |
162
+ |-------|------|-------------|
163
+ | `price` | `number` | Final price after discount |
164
+ | `formattedPrice` | `string` | Fully formatted string, e.g. `$80.00` |
165
+ | `integerPart` | `string` | Integer portion only, e.g. `80` |
166
+ | `decimalPart` | `string` | Decimal digits only, e.g. `00` |
167
+ | `decimalSeparator` | `string` | Locale-specific separator, e.g. `.` |
168
+ | `currencySymbol` | `string` | Currency symbol, e.g. `$` |
169
+ | `currencyCode` | `string` | ISO 4217 code, e.g. `USD` |
170
+ | `apiResponse` | `PricingData` | Full API response including country, percentage, and widgets |
171
+
172
+ ---
173
+
174
+ ### `updatePriceElement(element, options?)`
175
+
176
+ Updates a specific DOM element with the computed discounted price. The element **must** have a `data-kq-price` attribute. All elements linked to it via `data-kq-rel` are updated as well.
177
+
178
+ ```javascript
179
+ const el = document.getElementById("pro-price");
180
+ const result = await KQPromotionUI.updatePriceElement(el, { showDecimal: true });
181
+ console.log(result.formattedPrice);
182
+ ```
183
+
184
+ **Parameters**
185
+
186
+ | Parameter | Type | Description |
187
+ |-----------|------|-------------|
188
+ | `element` | `HTMLElement` | Must have `data-kq-price` attribute |
189
+ | `options` | `Partial<Config>` | Optional overrides |
190
+
191
+ Returns a `PriceObject` (same shape as `getUpdatedPrice`).
192
+
193
+ ---
194
+
195
+ ### `updatePrice(configs[])`
196
+
197
+ Batch-update multiple elements, optionally rendering each with an HTML template.
198
+
199
+ ```javascript
200
+ await KQPromotionUI.updatePrice([
201
+ {
202
+ element: document.getElementById("monthly"),
203
+ price: 29,
204
+ options: { showDecimal: false },
205
+ template: "<div class='price'>{{formattedPrice}} <small>/mo</small></div>",
206
+ },
207
+ {
208
+ element: document.getElementById("annual"),
209
+ price: 199,
210
+ options: { showDecimal: true },
211
+ template: "<div class='price'>{{formattedPrice}} <small>/yr</small></div>",
212
+ },
213
+ ]);
214
+ ```
215
+
216
+ **Config object fields**
217
+
218
+ | Field | Type | Description |
219
+ |-------|------|-------------|
220
+ | `element` | `HTMLElement` | Target element — its `innerHTML` is replaced with the rendered template |
221
+ | `price` | `number` | Base price |
222
+ | `options` | `Partial<Config>` | Optional overrides |
223
+ | `template` | `string` | HTML string with `{{key}}` placeholders |
224
+
225
+ **Available template variables** (any field from `PriceObject`):
226
+
227
+ `{{price}}` · `{{formattedPrice}}` · `{{integerPart}}` · `{{decimalPart}}` · `{{decimalSeparator}}` · `{{currencySymbol}}` · `{{currencyCode}}`
228
+
229
+ Returns `Promise<PriceObject[]>` — one entry per config.
230
+
231
+ ---
232
+
233
+ ## CSS hooks
234
+
235
+ The SDK adds classes to `document.body` that you can target in your stylesheets:
236
+
237
+ | Class | Added when |
238
+ |-------|------------|
239
+ | `kq-discount-applied` | An active discount > 0% exists for the visitor's country |
240
+ | `kq-has-parity-banner` | The discount banner has been injected into the page |
241
+
242
+ ```css
243
+ /* Show a sale badge only when a discount is active */
244
+ .sale-badge { display: none; }
245
+ body.kq-discount-applied .sale-badge { display: inline-block; }
246
+
247
+ /* Add top padding so content isn't hidden under the banner */
248
+ body.kq-has-parity-banner main { padding-top: 60px; }
249
+ ```
250
+
251
+ ---
252
+
253
+ ## Sandbox
254
+
255
+ Set `environment: "sandbox"` to test against the Kelviq sandbox environment.
256
+
257
+ ```javascript
258
+ KQPromotionUI.init({
259
+ promotionId: "YOUR_PROMOTION_ID",
260
+ accessToken: "YOUR_CLIENT_ACCESS_TOKEN",
261
+ environment: "sandbox",
262
+ });
263
+ ```
264
+
265
+ Use sandbox API keys (available under **Settings → API keys** with the Sandbox toggle enabled) so real visitor data is never affected during testing.
@@ -0,0 +1,361 @@
1
+ ---
2
+ title: "React Promotions UI"
3
+ slug: "frontend-integration/react-promotions-ui"
4
+ section: "frontend-integration"
5
+ description: "Add purchasing power parity discounts and a localised banner to your React app"
6
+ ---
7
+ The `@kelviq/react-promotions-ui` SDK provides React components for displaying location-based promotional banners and dynamically discounted prices. It handles API communication, discount calculation, and currency formatting out of the box.
8
+
9
+ - A **React Context Provider** (`KQProvider`) to fetch and share promotion data
10
+ - A **banner component** (`KQBanner`) with template variables and full styling control
11
+ - **Price components** for formatted display of discounted prices
12
+ - **Granular price components** for building fully custom price layouts
13
+
14
+ This SDK is separate from the [entitlements React SDK](/frontend-integration/react-sdk) and the [React UI SDK](/frontend-integration/react-ui). Use this SDK when you need PPP / country-based discount banners and price display in a React app.
15
+
16
+ ---
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ npm install @kelviq/react-promotions-ui
22
+ # or
23
+ yarn add @kelviq/react-promotions-ui
24
+ ```
25
+
26
+ Requires `react` and `react-dom` as peer dependencies (v17, v18, or v19).
27
+
28
+ ---
29
+
30
+ ## Quick start
31
+
32
+ Wrap your app with `KQProvider` and place `KQBanner` where you want the banner to appear.
33
+
34
+ ```tsx
35
+ import { KQProvider, KQBanner } from '@kelviq/react-promotions-ui';
36
+
37
+ function App() {
38
+ return (
39
+ <KQProvider
40
+ promotionId="YOUR_PROMOTION_ID"
41
+ accessToken="YOUR_ACCESS_TOKEN"
42
+ >
43
+
44
+
45
+ </KQProvider>
46
+ );
47
+ }
48
+ ```
49
+
50
+ **Never expose your Server API Key in the browser.** Use the **Client API Key**, which is safe for client-side code. You can find both keys under **Settings → API keys** in the [Kelviq dashboard](https://app.kelviq.com/settings/api-keys).
51
+
52
+ ---
53
+
54
+ ## `KQProvider`
55
+
56
+ The provider initializes the SDK, fetches promotion data from the Kelviq API, and makes it available to all child components via React Context.
57
+
58
+ ### Props
59
+
60
+ | Prop | Type | Default | Description |
61
+ |------|------|---------|-------------|
62
+ | `promotionId` | `string` | `''` | The promotion ID from the Kelviq dashboard |
63
+ | `accessToken` | `string` | `''` | Client API Key (Settings → API keys) |
64
+ | `kqIdentifier` | `string` | `''` | Optional Kelviq identifier for the request |
65
+ | `environment` | `'production' \| 'sandbox'` | `'production'` | Set to `'sandbox'` to use the sandbox API |
66
+ | `baseCurrencyCode` | `string` | `'USD'` | ISO 4217 currency code used for formatting |
67
+ | `baseCurrencySymbol` | `string` | `'$'` | Currency symbol for display |
68
+ | `config` | `object` | `{}` | Advanced configuration (see below) |
69
+
70
+ ### Advanced config
71
+
72
+ The optional `config` prop accepts:
73
+
74
+ | Field | Type | Default | Description |
75
+ |-------|------|---------|-------------|
76
+ | `apiUrl` | `string` | — | Override the default API endpoint |
77
+ | `onError` | `(error: Error) => void` | — | Error callback for API failures |
78
+ | `maxRetries` | `number` | `3` | Maximum retry attempts for failed requests |
79
+ | `timeout` | `number` | `5000` | Request timeout in milliseconds |
80
+
81
+ ### Sandbox
82
+
83
+ Set `environment` to `'sandbox'` to test against the Kelviq sandbox environment:
84
+
85
+ ```tsx
86
+ <KQProvider
87
+ promotionId="YOUR_PROMOTION_ID"
88
+ accessToken="YOUR_SANDBOX_ACCESS_TOKEN"
89
+ environment="sandbox"
90
+ >
91
+
92
+ </KQProvider>
93
+ ```
94
+
95
+ ---
96
+
97
+ ## `KQBanner`
98
+
99
+ Displays a location-aware promotional banner. The banner message is configured in the Kelviq dashboard and supports template variables that are automatically replaced with real data.
100
+
101
+ ```tsx
102
+ import { KQBanner } from '@kelviq/react-promotions-ui';
103
+
104
+ // Basic — uses styles from the dashboard
105
+
106
+ // With local style overrides
107
+ <KQBanner
108
+ backgroundColor="#1a1a2e"
109
+ fontColor="#eaeaea"
110
+ borderRadius="8px"
111
+ fontSize="14px"
112
+ addCloseIcon={true}
113
+ className="my-banner"
114
+ onClose={() => console.log('Banner closed')}
115
+ />
116
+ ```
117
+
118
+ ### Props
119
+
120
+ | Prop | Type | Default | Description |
121
+ |------|------|---------|-------------|
122
+ | `backgroundColor` | `string` | *(from API)* | Banner background color |
123
+ | `fontColor` | `string` | *(from API)* | Banner text color |
124
+ | `borderRadius` | `string` | *(from API)* | Banner border radius |
125
+ | `fontSize` | `string` | *(from API)* | Banner font size |
126
+ | `unStyled` | `boolean` | *(from API)* | If `true`, no default styles are injected |
127
+ | `addCloseIcon` | `boolean` | *(from API)* | Show a close button on the banner |
128
+ | `className` | `string` | `''` | Custom CSS class name |
129
+ | `onClose` | `() => void` | — | Callback fired when the banner is closed |
130
+
131
+ Props override the corresponding values returned by the API. If you don't pass a prop, the dashboard-configured value is used.
132
+
133
+ ### Template variables
134
+
135
+ The banner message (configured in the dashboard) supports these placeholders:
136
+
137
+ | Variable | Replaced with | Example |
138
+ |----------|---------------|---------|
139
+ | `{country}` | Visitor's country name | `United States` |
140
+ | `{country_flag}` | Country flag image (CDN-hosted SVG) | 🇺🇸 *(rendered as `<img>`)* |
141
+ | `{coupon_code}` | The discount coupon code | `SAVE20` |
142
+ | `{discount_percentage}` | The discount percentage | `20` |
143
+
144
+ **Example message:**
145
+
146
+ ```
147
+ Hello {country_flag} You're visiting from {country}! Use code "{coupon_code}" for {discount_percentage}% off.
148
+ ```
149
+
150
+ ### CSS hooks
151
+
152
+ The banner adds classes to `document.body` that you can target in your stylesheets:
153
+
154
+ | Class | Added when |
155
+ |-------|------------|
156
+ | `kq-has-banner` | The banner is visible on the page |
157
+
158
+ ```css
159
+ /* Add top padding so content isn't hidden behind the banner */
160
+ body.kq-has-banner main {
161
+ padding-top: 60px;
162
+ }
163
+ ```
164
+
165
+ ### Unstyled mode
166
+
167
+ Set `unStyled={true}` to remove all default styles and apply your own CSS from scratch. Target the banner using the `kq-banner` CSS class or the `data-testid="kq-banner"` attribute.
168
+
169
+ ```tsx
170
+
171
+ ```
172
+
173
+ ---
174
+
175
+ ## `KQPriceFormatted`
176
+
177
+ Displays a fully formatted discounted price based on the visitor's location.
178
+
179
+ ```tsx
180
+ import { KQPriceFormatted } from '@kelviq/react-promotions-ui';
181
+
182
+ // Discounted price
183
+
184
+ // With decimals
185
+
186
+ // Currency code instead of symbol
187
+
188
+ ```
189
+
190
+ ### Props
191
+
192
+ | Prop | Type | Default | Description |
193
+ |------|------|---------|-------------|
194
+ | `price` | `number` | — | **Required.** The product price |
195
+ | `displayPrice` | `number` | — | The price shown for original display (used with `isOriginalDisplay`) |
196
+ | `isOriginalDisplay` | `boolean` | `false` | Renders as strikethrough original price for comparison |
197
+ | `className` | `string` | `''` | Custom CSS class name |
198
+ | `currencyDisplay` | `'symbol' \| 'code' \| 'name'` | `'symbol'` | How the currency is displayed |
199
+ | `showDecimal` | `boolean` | `false` | Whether to show decimal digits |
200
+ | `minimumDecimalDigits` | `number` | `2` | Minimum decimal digits when `showDecimal` is `true` |
201
+ | `maximumDecimalDigits` | `number` | `2` | Maximum decimal digits (max 2) |
202
+
203
+ ### Original + discounted price
204
+
205
+ Show a strikethrough original price next to the discounted price:
206
+
207
+ ```tsx
208
+
209
+ ```
210
+
211
+ ---
212
+
213
+ ## Granular price components
214
+
215
+ Use these components individually to build custom price layouts with full styling control. All components must be rendered inside a `KQProvider`.
216
+
217
+ ### `KQPriceInteger`
218
+
219
+ Displays just the integer part of the discounted price.
220
+
221
+ ```tsx
222
+ import { KQPriceInteger } from '@kelviq/react-promotions-ui';
223
+
224
+ ```
225
+
226
+ | Prop | Type | Default | Description |
227
+ |------|------|---------|-------------|
228
+ | `price` | `number` | — | **Required.** The product price |
229
+ | `className` | `string` | `''` | Custom CSS class name |
230
+
231
+ ### `KQPriceDecimal`
232
+
233
+ Displays just the decimal portion of the discounted price.
234
+
235
+ ```tsx
236
+ import { KQPriceDecimal } from '@kelviq/react-promotions-ui';
237
+
238
+ ```
239
+
240
+ | Prop | Type | Default | Description |
241
+ |------|------|---------|-------------|
242
+ | `price` | `number` | — | **Required.** The product price |
243
+ | `className` | `string` | `''` | Custom CSS class name |
244
+ | `minimumDecimalDigits` | `number` | `2` | Minimum decimal digits |
245
+ | `maximumDecimalDigits` | `number` | `2` | Maximum decimal digits (max 2) |
246
+
247
+ ### `KQPriceDecimalSeparator`
248
+
249
+ Renders the locale-specific decimal separator (e.g. `.` or `,`).
250
+
251
+ ```tsx
252
+ import { KQPriceDecimalSeparator } from '@kelviq/react-promotions-ui';
253
+
254
+ ```
255
+
256
+ | Prop | Type | Default | Description |
257
+ |------|------|---------|-------------|
258
+ | `price` | `number` | — | **Required.** The product price |
259
+ | `className` | `string` | `''` | Custom CSS class name |
260
+
261
+ ### `KQPriceCurrencySymbol`
262
+
263
+ Renders the currency symbol (e.g. `$`, `€`, `₹`).
264
+
265
+ ```tsx
266
+ import { KQPriceCurrencySymbol } from '@kelviq/react-promotions-ui';
267
+
268
+ ```
269
+
270
+ | Prop | Type | Default | Description |
271
+ |------|------|---------|-------------|
272
+ | `className` | `string` | `''` | Custom CSS class name |
273
+
274
+ ### `KQPriceCurrencyCode`
275
+
276
+ Renders the currency code (e.g. `USD`, `EUR`, `INR`).
277
+
278
+ ```tsx
279
+ import { KQPriceCurrencyCode } from '@kelviq/react-promotions-ui';
280
+
281
+ ```
282
+
283
+ | Prop | Type | Default | Description |
284
+ |------|------|---------|-------------|
285
+ | `className` | `string` | `''` | Custom CSS class name |
286
+
287
+ ### Custom price layout example
288
+
289
+ Combine granular components to build a fully custom price display:
290
+
291
+ ```tsx
292
+ import {
293
+ KQPriceCurrencySymbol,
294
+ KQPriceInteger,
295
+ KQPriceDecimalSeparator,
296
+ KQPriceDecimal,
297
+ KQPriceCurrencyCode,
298
+ } from '@kelviq/react-promotions-ui';
299
+
300
+ <div className="custom-price">
301
+
302
+
303
+
304
+
305
+ <span className="currency-code">
306
+
307
+ </span>
308
+ </div>
309
+ ```
310
+
311
+ ---
312
+
313
+ ## Complete example
314
+
315
+ ```tsx
316
+ import {
317
+ KQProvider,
318
+ KQBanner,
319
+ KQPriceFormatted,
320
+ KQPriceCurrencySymbol,
321
+ KQPriceInteger,
322
+ KQPriceDecimalSeparator,
323
+ KQPriceDecimal,
324
+ } from '@kelviq/react-promotions-ui';
325
+
326
+ function PricingPage() {
327
+ return (
328
+ <KQProvider
329
+ promotionId="YOUR_PROMOTION_ID"
330
+ accessToken="YOUR_ACCESS_TOKEN"
331
+ >
332
+
333
+
334
+
335
+
336
+ <div className="pricing">
337
+ <span className="original">
338
+
339
+ </span>
340
+ <span className="discounted">
341
+
342
+ </span>
343
+ </div>
344
+
345
+
346
+ <div className="custom-price">
347
+
348
+
349
+
350
+
351
+ </div>
352
+ </KQProvider>
353
+ );
354
+ }
355
+ ```
356
+
357
+ ---
358
+
359
+ ## Support
360
+
361
+ For technical support and questions, reach out at [hi@kelviq.com](mailto:hi@kelviq.com).