npm package: @gethelium/personalise
Description: Helium Personalisation Client for rendering product lists and features
Author: Helium
Latest version: 1.0.2

# @gethelium/personalise

The Helium Personalisation Platform SDK makes it easy to integrate intelligent product lists, dynamic merchandising, and personalized content into your website.

## Features

- **AI-Powered Recommendations**: Leverage machine learning to show the most relevant products to each customer
- **Dynamic Product Lists**: Create personalized product collections that adapt to user behavior and preferences
- **Easy Integration**: Simple JavaScript SDK that works with any e-commerce platform
- **Shopify Native**: Seamless integration with Shopify stores
- **Preview Mode**: Test and preview your personalization features before going live
- **TypeScript Support**: Full type definitions for better development experience

## Quick Start

### Installation

```bash
npm install @gethelium/personalise
```

### Basic Usage

```typescript
import { PersonalisationClient } from "@gethelium/personalise";

// Initialize the client (auto-detects Shopify store)
const client = new PersonalisationClient();

// Render personalized product recommendations
await client.render({
  featureHandles: ["trending", "recommended-for-you"],
  position: ".product-recommendations",
  type: "product-list",
});
```

That's it! Your personalized product recommendations will now appear on your website.

## Detailed Usage

### For Shopify Stores

The SDK automatically detects your Shopify store configuration:

```typescript
import { PersonalisationClient } from "@gethelium/personalise";

const client = new PersonalisationClient();

await client.render({
  featureHandles: ["trending", "you-might-like", "frequently-bought"],
  position: ".product-recommendations",
  type: "product-list",
});
```

### For Custom E-commerce Platforms

```typescript
import { PersonalisationClient } from "@gethelium/personalise";

const client = new PersonalisationClient("your-store-id", {
  apiBaseUrl: "https://api.heliumpersonalisation.com",
  shopifyConfig: {
    storefrontAccessToken: "your-storefront-token",
    shop: "your-store.myshopify.com",
  },
});

await client.render({
  featureHandles: ["featured", "on-sale", "new-arrivals"],
  position: "#recommendations-container",
  type: "product-list",
});
```

### Preview Your Features

Test your personalization features before going live:

```typescript
const client = new PersonalisationClient();

await client.render({
  featureHandles: ["test-feature"],
  position: ".preview-area",
  type: "product-list",
  isPreview: true,
  previewFeatureHandle: "test-feature",
  productHandle: "current-product",
});
```

## Use Cases

- **Product Detail Pages**: Show "Customers also viewed" and "Frequently bought together"
- **Homepage**: Display trending products and personalized recommendations
- **Category Pages**: Enhance category listings with AI-powered sorting
- **Cart Page**: Suggest complementary products to increase average order value
- **Email Campaigns**: Generate personalized product recommendations for email content

## ⚙️ Configuration

### PersonalisationClient Options

```typescript
interface PersonalisationConfig {
  apiBaseUrl: string; // Your Helium API endpoint
  shopifyConfig?: {
    // Required for Shopify integration
    storefrontAccessToken: string;
    shop: string;
  };
  websiteUrl?: string; // Custom website URL for config loading
}
```

### Render Options

```typescript
interface RenderOptions {
  featureHandles: string[]; // Array of feature identifiers
  position: string; // CSS selector where to render
  type: "product-list"; // Currently supports product lists
  productHandle?: string; // Current product handle (optional)
  isPreview?: boolean; // Enable preview mode
  previewFeatureHandle?: string; // Specific feature to preview
}
```

## Advanced Configuration

### Custom Styling

The SDK renders product cards with default styling that you can customize:

```css
/* Customize product card appearance */
.feature-container {
  margin: 2rem 0;
}

.product-card {
  /* Your custom product card styles */
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

Need help? Contact our support team or check out our [website](https://gethelium.co).

---

**Made with ❤️ by the Helium team**