@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.
- package/LICENSE +21 -0
- package/README.md +322 -0
- package/dist/config.d.ts +16 -0
- package/dist/config.js +45 -0
- package/dist/config.js.map +1 -0
- package/dist/docs/README.md +128 -0
- package/dist/docs/api-reference/authentication.md +41 -0
- package/dist/docs/backend-integration/node-sdk.md +1040 -0
- package/dist/docs/backend-integration/python-sdk.md +1198 -0
- package/dist/docs/changelog/app.md +80 -0
- package/dist/docs/changelog/checkout-api.md +59 -0
- package/dist/docs/changelog/js-promotions-ui.md +14 -0
- package/dist/docs/changelog/js-sdk.md +281 -0
- package/dist/docs/changelog/node-sdk.md +378 -0
- package/dist/docs/changelog/python-sdk.md +456 -0
- package/dist/docs/changelog/react-sdk.md +580 -0
- package/dist/docs/checkout/checkout-configuration.md +434 -0
- package/dist/docs/coustomers-management/overview.md +111 -0
- package/dist/docs/customer-portal/overview.md +81 -0
- package/dist/docs/frontend-integration/js-sdk.md +676 -0
- package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
- package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
- package/dist/docs/frontend-integration/react-sdk.md +1187 -0
- package/dist/docs/frontend-integration/react-ui.md +771 -0
- package/dist/docs/getstarted/fees.md +160 -0
- package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
- package/dist/docs/getstarted/merchant-of-record.md +64 -0
- package/dist/docs/getstarted/review-process.md +190 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
- package/dist/docs/guides/subscription-integration.md +291 -0
- package/dist/docs/guides/webhooks.md +963 -0
- package/dist/docs/legal/approved-prohibited-policy.md +252 -0
- package/dist/docs/legal/buyer-terms.md +177 -0
- package/dist/docs/legal/compliant-user-flow.md +216 -0
- package/dist/docs/legal/master-service-agreement.md +404 -0
- package/dist/docs/legal/payment-flow-diagram.md +188 -0
- package/dist/docs/legal/seller-terms.md +169 -0
- package/dist/docs/manifest.json +415 -0
- package/dist/docs/monetization/offerings.md +156 -0
- package/dist/docs/monetization/pricing-tables.md +226 -0
- package/dist/docs/monetization/targeting-rules.md +278 -0
- package/dist/docs/openapi.json +5479 -0
- package/dist/docs/payouts/overview.md +43 -0
- package/dist/docs/payouts/payout-account.md +12 -0
- package/dist/docs/payouts/transactions.md +23 -0
- package/dist/docs/product-catalog/digital-downloads.md +117 -0
- package/dist/docs/product-catalog/discounts.md +69 -0
- package/dist/docs/product-catalog/entitlements.md +428 -0
- package/dist/docs/product-catalog/free-and-trials.md +36 -0
- package/dist/docs/product-catalog/license-keys.md +324 -0
- package/dist/docs/product-catalog/links.md +92 -0
- package/dist/docs/product-catalog/location-based-pricing.md +41 -0
- package/dist/docs/product-catalog/one-time-payments.md +24 -0
- package/dist/docs/product-catalog/plans.md +199 -0
- package/dist/docs/product-catalog/products.md +60 -0
- package/dist/docs/product-catalog/subscriptions.md +29 -0
- package/dist/docs/product-catalog/tax-settings.md +37 -0
- package/dist/docs/product-catalog/usage-based-billing.md +119 -0
- package/dist/docs/promotions/create-a-promotion.md +75 -0
- package/dist/docs/promotions/customize-banner.md +41 -0
- package/dist/docs/promotions/integrate.md +38 -0
- package/dist/docs/promotions/overview.md +51 -0
- package/dist/docs/quickstart/core-concepts.md +146 -0
- package/dist/docs/quickstart/dashboard-setup.md +129 -0
- package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
- package/dist/docs/sales/checkout-sessions.md +58 -0
- package/dist/docs/sales/orders.md +76 -0
- package/dist/http/client.d.ts +28 -0
- package/dist/http/client.js +76 -0
- package/dist/http/client.js.map +1 -0
- package/dist/http/errors.d.ts +20 -0
- package/dist/http/errors.js +58 -0
- package/dist/http/errors.js.map +1 -0
- package/dist/resources/docs-index.d.ts +25 -0
- package/dist/resources/docs-index.js +109 -0
- package/dist/resources/docs-index.js.map +1 -0
- package/dist/resources/index.d.ts +2 -0
- package/dist/resources/index.js +73 -0
- package/dist/resources/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +1304 -0
- package/dist/schemas/kelviq.js +468 -0
- package/dist/schemas/kelviq.js.map +1 -0
- package/dist/server.d.ts +2 -0
- package/dist/server.js +41 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/_util.d.ts +15 -0
- package/dist/tools/_util.js +15 -0
- package/dist/tools/_util.js.map +1 -0
- package/dist/tools/checkout.d.ts +3 -0
- package/dist/tools/checkout.js +18 -0
- package/dist/tools/checkout.js.map +1 -0
- package/dist/tools/customers.d.ts +3 -0
- package/dist/tools/customers.js +32 -0
- package/dist/tools/customers.js.map +1 -0
- package/dist/tools/docs.d.ts +2 -0
- package/dist/tools/docs.js +43 -0
- package/dist/tools/docs.js.map +1 -0
- package/dist/tools/entitlements.d.ts +3 -0
- package/dist/tools/entitlements.js +22 -0
- package/dist/tools/entitlements.js.map +1 -0
- package/dist/tools/features.d.ts +3 -0
- package/dist/tools/features.js +55 -0
- package/dist/tools/features.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.js +44 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/licenses.d.ts +3 -0
- package/dist/tools/licenses.js +44 -0
- package/dist/tools/licenses.js.map +1 -0
- package/dist/tools/media.d.ts +3 -0
- package/dist/tools/media.js +18 -0
- package/dist/tools/media.js.map +1 -0
- package/dist/tools/offerings.d.ts +3 -0
- package/dist/tools/offerings.js +21 -0
- package/dist/tools/offerings.js.map +1 -0
- package/dist/tools/partner.d.ts +3 -0
- package/dist/tools/partner.js +55 -0
- package/dist/tools/partner.js.map +1 -0
- package/dist/tools/plan-entitlements.d.ts +3 -0
- package/dist/tools/plan-entitlements.js +56 -0
- package/dist/tools/plan-entitlements.js.map +1 -0
- package/dist/tools/plan-files.d.ts +3 -0
- package/dist/tools/plan-files.js +43 -0
- package/dist/tools/plan-files.js.map +1 -0
- package/dist/tools/plans.d.ts +3 -0
- package/dist/tools/plans.js +120 -0
- package/dist/tools/plans.js.map +1 -0
- package/dist/tools/portal.d.ts +3 -0
- package/dist/tools/portal.js +18 -0
- package/dist/tools/portal.js.map +1 -0
- package/dist/tools/product-files.d.ts +3 -0
- package/dist/tools/product-files.js +31 -0
- package/dist/tools/product-files.js.map +1 -0
- package/dist/tools/product-settings.d.ts +3 -0
- package/dist/tools/product-settings.js +31 -0
- package/dist/tools/product-settings.js.map +1 -0
- package/dist/tools/products.d.ts +3 -0
- package/dist/tools/products.js +69 -0
- package/dist/tools/products.js.map +1 -0
- package/dist/tools/promotions.d.ts +3 -0
- package/dist/tools/promotions.js +19 -0
- package/dist/tools/promotions.js.map +1 -0
- package/dist/tools/subscriptions.d.ts +3 -0
- package/dist/tools/subscriptions.js +63 -0
- package/dist/tools/subscriptions.js.map +1 -0
- package/dist/tools/usage.d.ts +3 -0
- package/dist/tools/usage.js +18 -0
- package/dist/tools/usage.js.map +1 -0
- 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).
|