Skip to content

Core SDK: Getting Started

Beta SDK

These SDKs are currently in beta. APIs may change before stable release.

The @rebuy/core-sdk is a framework-agnostic SDK for integrating Rebuy's personalization and recommendation engine into any JavaScript application.

Installation

npm install @rebuy/core-sdk

Quick Start

import { RebuySDK } from '@rebuy/core-sdk';

// Initialize the SDK
const sdk = new RebuySDK({
    apiKey: 'your-api-key',
});

// Fetch top seller recommendations
const topSellers = await sdk.products.getTopSellers({ limit: 5 });
console.log('Top Sellers:', topSellers);

// Fetch recommendations from a custom Data Source
const dataSourceProducts = await sdk.products.fetchFromDataSource(1234, {
    shopify_product_ids: ['product-123'],
    limit: 6,
});
console.log('Products from Data Source:', dataSourceProducts);

Core Features

Product Recommendations

Fetch product recommendations from any of Rebuy's standard endpoints or from a custom Data Source.

Standard Recommendations:

// Get top sellers
const topSellers = await sdk.products.getTopSellers({ limit: 10 });

// Get similar products
const similarProducts = await sdk.products.getSimilar({ limit: 5 });

Custom Data Sources:

Leverage the full power of the Rebuy rules engine by fetching from a specific Data Source.

const products = await sdk.products.fetchFromDataSource(1234, {
    cart: currentCartObject,
    limit: 4,
});

Context Builder

The RebuyContextBuilder class provides a fluent API for creating rich context objects for Data Sources. This reduces errors and improves discoverability of context parameters.

import { RebuyContextBuilder } from '@rebuy/core-sdk';

// Create a context with the builder
const context = new RebuyContextBuilder(sdk)
    .withCart(cartObject)
    .withProduct({ id: 'gid://shopify/Product/123' })
    .withCustomer({ id: 456, tags: ['vip', 'wholesale'] })
    .withUrl('https://shop.com/products?sort=price')
    .withLocation('US')
    .withLanguage('en')
    .build();

// Use the context with a Data Source
const products = await sdk.products.fetchFromDataSource('pdp-recommendations', context);

Builder Methods:

Method Description
merge(context) Merge an existing context object
withCart(cart) Add cart data using the SDK's internal transformer
withProduct(product) Add a product's ID (can be chained for multiple products)
withCustomer(customer) Add customer ID and tags
withUrl(url) Extract path and query parameters from a URL
withLocation(countryCode) Add the user's country code (ISO 3166-1 alpha-2)
withLanguage(language) Add the user's language code (ISO 639-1)
build() Return the final context object

Viewed Products

Track and retrieve products that users have viewed.

// Track a product view
await sdk.tracking.productView('product-123');

// Get recently viewed products
const viewedProducts = await sdk.products.getRecentlyViewed({ limit: 10 });

Framework Integration

While this is a framework-agnostic SDK, Rebuy provides first-party integrations for popular frameworks:

For React and Shopify Hydrogen projects, the dedicated @rebuy/hydrogen-sdk wrapper is recommended as it provides React components, hooks, and Remix integration.

Next Steps

See something that needs updating? Suggest an edit