@loyali/sdk

Embeddable loyalty widgets for your application. Display customer points, tiers, achievements, and rewards.

Installation

npm install @loyali/sdk
# or
yarn add @loyali/sdk
# or
pnpm add @loyali/sdk

Quick Start

Vanilla JavaScript

<script type="module">
  import { Loyali } from '@loyali/sdk';

  const loyali = new Loyali({
    apiUrl: 'https://api.loyali.io/api/v1',
    publicKey: 'pk_live_your_key_here'
  });

  // Identify customer (use your user ID, not email for security)
  const customer = await loyali.identify({ 
    external_reference: 'your-user-id-123' 
  });

  console.log(`${customer.first_name} has ${customer.points_balance} points`);

  // Get rewards
  const rewards = await loyali.getRewards();
  console.log(`${rewards.affordable_count} rewards available`);

  // Get points history
  const activity = await loyali.getActivity();
  console.log('Recent activity:', activity.activities);

  // Link to portal for redemptions
  const portalUrl = loyali.getPortalUrl();
  // Redirect user to portal to redeem rewards
</script>

React

import { LoyaliProvider, useLoyali, usePoints, useRewards } from '@loyali/sdk/react';

function App() {
  return (
    <LoyaliProvider 
      config={{ 
        apiUrl: 'https://api.loyali.io/api/v1',
        publicKey: 'pk_live_your_key_here' 
      }}
    >
      <LoyaltyDashboard />
    </LoyaliProvider>
  );
}

function LoyaltyDashboard() {
  const { identify, customer, isIdentified } = useLoyali();
  const { data: rewards } = useRewards();

  useEffect(() => {
    // Identify with your system's user ID
    identify({ external_reference: 'your-user-id-123' });
  }, []);

  if (!isIdentified) return <div>Loading...</div>;

  return (
    <div>
      <h2>Welcome {customer.first_name}!</h2>
      <p>{customer.points_balance.toLocaleString()} points</p>
      <p>{customer.tier?.name} tier ({customer.tier?.multiplier}x multiplier)</p>
      <p>{rewards?.affordable_count} rewards you can redeem</p>
    </div>
  );
}

Security Model

The SDK uses public API keys (pk_live_xxx) which are safe to expose in client-side code.

Public keys can:

• ✅ Identify customers (by your user ID or Loyali UUID)
• ✅ Read points balance and history
• ✅ Read tier information
• ✅ Read achievements
• ✅ Read available rewards
• ✅ Get portal URL for redemptions

Public keys cannot:

• ❌ Award points (use server-side private key)
• ❌ Redeem rewards (use server-side private key)
• ❌ Identify by email (prevents enumeration)

For awarding points and processing redemptions, use private API keys (sk_live_xxx) server-side only.

API Methods

identify(params)

Identify a customer to load their loyalty data.

// Using your system's user ID (recommended)
await loyali.identify({ external_reference: 'user_12345' });

// Or using Loyali's customer UUID
await loyali.identify({ customer_id: 'uuid-here' });

getCustomer()

Get current customer data.

const customer = await loyali.getCustomer();
// Returns: { id, email, first_name, last_name, points_balance, tier, next_tier, ... }

getRewards()

Get available rewards the customer can redeem.

const { rewards, total, affordable_count } = await loyali.getRewards();
// rewards: [{ id, title, description, cost_points, image_url, can_afford, in_stock }]

getAchievements()

Get all achievements with earned status.

const { achievements, total_earned, total_available } = await loyali.getAchievements();
// achievements: [{ id, name, description, icon, badge_color, earned, earned_at }]

getActivity(limit?)

Get customer's points history.

const { activities, total, has_more } = await loyali.getActivity(20);
// activities: [{ type, source, delta, description, created_at }]

getOrgConfig()

Get organization branding and portal URL.

const config = await loyali.getOrgConfig();
// { name, slug, logo_url, primary_color, portal_url }

getPortalUrl()

Get the URL to redirect customers for redemptions.

const portalUrl = loyali.getPortalUrl();
window.location.href = portalUrl; // Redirect to redemption portal

Theming

The SDK respects your organization's branding colors configured in the Loyali dashboard.

const config = await loyali.getOrgConfig();
// config.primary_color = '#0d9488'
// config.secondary_color = '#ffb82b'
// config.logo_url = 'https://...'

TypeScript Support

Full TypeScript definitions are included:

import { Loyali, Customer, Reward, Achievement } from '@loyali/sdk';

const loyali = new Loyali({
  apiUrl: 'https://api.loyali.io/api/v1',
  publicKey: 'pk_live_xxx'
});

const customer: Customer = await loyali.identify({ 
  external_reference: 'user_123' 
});

Server-Side Integration

To award points and process redemptions, use private API keys server-side:

// YOUR SERVER CODE (Node.js example)
const response = await fetch('https://api.loyali.io/api/v1/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sk_live_your_private_key' // Private key!
  },
  body: JSON.stringify({
    customer_id: 'customer-uuid',
    event_type: 'purchase',
    properties: { amount: 99.99, order_id: 'order_123' }
  })
});

Browser Support

• Chrome (last 2 versions)
• Firefox (last 2 versions)
• Safari (last 2 versions)
• Edge (last 2 versions)

License

MIT