vipros-sdk
Version:
VIPros SDK - Universal Web Components for cashback & VIPoints. Works with any framework!
310 lines (218 loc) • 6.75 kB
Markdown
# VIPros SDK
Universal JavaScript SDK for integrating VIPros cashback and VIPoints offers into e-commerce websites. Compatible with all major JavaScript frameworks.
[](https://www.npmjs.com/package/vipros-sdk)
[](https://opensource.org/licenses/MIT)
## Installation
```bash
npm install vipros-sdk
```
## Quick Start
### Vanilla JavaScript
```javascript
import ViprosSDK from "vipros-sdk";
ViprosSDK.init({
apiKey: "your-api-key",
apiBaseUrl: "https://your-domain.com/api",
});
```
```html
<vipros-offer-card ean="4059952613239" price="89.99"></vipros-offer-card>
```
### React
```jsx
import { ViprosProvider, ViprosOfferCard } from "vipros-sdk/react";
function App() {
return (
<ViprosProvider config={{ apiKey: "your-api-key" }}>
<ViprosOfferCard ean="4059952613239" price={89.99} />
</ViprosProvider>
);
}
```
### Vue 3
```javascript
import { ViprosPlugin } from "vipros-sdk/vue";
import { createApp } from "vue";
const app = createApp(App);
app.use(ViprosPlugin, { apiKey: "your-api-key" });
```
```vue
<template>
<vipros-offer-card ean="4059952613239" price="89.99" />
</template>
```
### Angular / Svelte
Web Components work natively in any framework:
```typescript
import "vipros-sdk";
```
```html
<vipros-offer-card ean="4059952613239" price="89.99"></vipros-offer-card>
```
## API Reference
### Configuration
#### `ViprosSDK.init(config)`
Initialize the SDK with your API credentials.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | -------------------------- |
| `apiKey` | string | Yes | Your VIPros API key |
| `apiBaseUrl` | string | No | Custom API base URL |
| `debug` | boolean | No | Enable debug logging |
| `primaryColor` | string | No | Default theme color (hex) |
| `onReady` | function | No | Callback when SDK is ready |
| `onOfferLoaded` | function | No | Callback when offer loads |
| `onError` | function | No | Callback on errors |
**Example:**
```javascript
ViprosSDK.init({
apiKey: "your-api-key",
apiBaseUrl: "https://api.vipros.fr",
debug: false,
});
```
### Methods
#### `getProductData(ean)`
Fetch product data by EAN code.
**Parameters:**
- `ean` (string): Product EAN code
**Returns:** Promise<Product|null>
**Example:**
```javascript
const product = await ViprosSDK.getProductData("4059952613239");
if (product) {
console.log(product.name);
console.log(product.cashback);
}
```
#### `clearCache()`
Clear the internal product cache.
**Example:**
```javascript
ViprosSDK.clearCache();
```
### React Components
#### `<ViprosProvider>`
Provider component that makes the SDK available to child components.
**Props:**
| Prop | Type | Required | Description |
| ---------- | --------- | -------- | ----------------- |
| `config` | object | Yes | SDK configuration |
| `fallback` | ReactNode | No | Loading fallback |
**Example:**
```jsx
<ViprosProvider
config={{ apiKey: "your-api-key" }}
fallback={<div>Loading...</div>}
>
{children}
</ViprosProvider>
```
#### `<ViprosOfferCard>`
Display a cashback offer card for a product.
**Props:**
| Prop | Type | Required | Description |
| --------------- | --------- | -------- | -------------------- |
| `ean` | string | Yes | Product EAN code |
| `price` | number | Yes | Product price |
| `primaryColor` | string | No | Theme color (hex) |
| `onOfferLoaded` | function | No | Callback when loaded |
| `onOfferClick` | function | No | Callback on click |
| `onError` | function | No | Callback on error |
| `fallback` | ReactNode | No | Loading fallback |
**Example:**
```jsx
<ViprosOfferCard
ean="4059952613239"
price={89.99}
primaryColor="#7e87ed"
onOfferLoaded={(product) => console.log(product)}
/>
```
#### `useViprosSDK()` Hook
Access SDK methods in React components.
**Returns:**
```typescript
{
isReady: boolean;
error: Error | null;
getProductData: (ean: string) => Promise<Product | null>;
clearCache: () => void;
}
```
**Example:**
```jsx
import { useViprosSDK } from "vipros-sdk/react";
function MyComponent() {
const { isReady, getProductData } = useViprosSDK();
const handleLoad = async () => {
const product = await getProductData("4059952613239");
console.log(product);
};
return <button onClick={handleLoad}>Load Product</button>;
}
```
### Vue Plugin
#### Installation
```javascript
import { ViprosPlugin } from "vipros-sdk/vue";
import { createApp } from "vue";
const app = createApp(App);
app.use(ViprosPlugin, {
apiKey: "your-api-key",
apiBaseUrl: "https://api.vipros.fr",
});
```
#### Using in Components
The plugin provides the SDK instance via Vue's provide/inject:
```vue
<script setup>
import { inject } from "vue";
const vipros = inject("vipros");
const loadProduct = async () => {
const product = await vipros.getProductData("4059952613239");
console.log(product);
};
</script>
```
### Web Component
#### `<vipros-offer-card>`
Custom element for displaying cashback offers.
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | ------ | -------- | ----------------- |
| `ean` | string | Yes | Product EAN code |
| `price` | string | Yes | Product price |
| `primary-color` | string | No | Theme color (hex) |
**Example:**
```html
<vipros-offer-card ean="4059952613239" price="89.99" primary-color="#7e87ed">
</vipros-offer-card>
```
## TypeScript Support
The SDK includes TypeScript definitions for all APIs.
```typescript
import ViprosSDK from "vipros-sdk";
import type { ViprosConfig, ViprosProduct } from "vipros-sdk";
const config: ViprosConfig = {
apiKey: "your-api-key",
};
ViprosSDK.init(config);
const product: ViprosProduct | null = await ViprosSDK.getProductData("123");
```
## Debugging
For development and troubleshooting, enable debug mode:
```javascript
ViprosSDK.init({
apiKey: "your-api-key",
debug: true,
});
```
The SDK will log detailed information to the console.
### getStats()
Returns internal SDK statistics (cache hits, request counts). Primarily useful for debugging and monitoring.
```javascript
const stats = ViprosSDK.getStats();
console.log(stats.cacheHits);
console.log(stats.totalRequests);
```