Flock Node SDK

The official Node.js SDK for the Flock Referral & Rewards API.

Easily integrate referral, rewards, and customer management features into your Node.js applications.

Features

• Identify and manage customers
• Fetch live campaigns
• Create and manage referrals
• Trigger and manage rewards
• Ingest checkpoints
• Validate webhook event signatures

Installation

npm install @flock/node-flock

Quick Start

Initialize the SDK:

import { FlockSDK } from '@flock/node-flock';

const sdk = new FlockSDK({
  accessKey: 'your-service-access-key',
});

Ingest a checkpoint:

const checkpointResult = await sdk.checkpoints.ingest('purchase_completed', {
  externalUserId: 'user_123',
  environment: 'production', // Or 'test'
});

Identify a customer:

// Identify a customer
const customer = await sdk.customers.identify({
  externalUserId: 'user_123',
  email: '[email protected]',
  name: 'Jane Doe',
});

Get live campaign:

const campaign = await sdk.campaigns.getLive({ environment: 'production' }); // Or 'test'

Create a referral:

// Create a referral
const referral = await sdk.referrals.create({
  campaignId: campaign.id,
  referralCode: customer.referralCode,
  refereeExternalUserId: 'user_123',
});

Or you can trigger rewards directly (not recommended):

await sdk.rewards.trigger({
  campaignId: campaign.id,
  externalUserId: 'user_123',
  environment: 'production', // Or 'test'
});

Validating Webhook Events:

// Express.js route handler example
app.post('/webhooks/flock', (req, res) => {
  try {
    // Get the signature from the headers
    const signature = req.headers['x-flock-signature'];
    
    if (!signature) {
      return res.status(401).json({ error: 'Missing signature header' });
    }
    
    // Validate and construct the webhook event
    const event = sdk.webhooks.constructEvent({
      secret: 'your_webhook_secret',
      signature,
      payload: req.body,
      maxAge: 5 * 60 * 1000, // Optional: 5 minutes in milliseconds
    });
    
    // Handle the event based on its type
    switch (event.name) {
      case 'invitee.accepted':
        console.log(`Invitee ${event.data.invitee.id} accepted an invitation`);
        // Process the event...
        break;
      
      // Handle other event types...
      default:
        console.log(`Received unknown event type: ${event.name}`);
    }
    
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error.message);
    return res.status(400).json({ error: error.message });
  }
});

Links

• Flock Documentation
• Flock Dashboard