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

``bash
npm install @flock/node-flock
`

---

Quick Start

#### Initialize the SDK:
`typescript
import { FlockSDK } from '@flock/node-flock';

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

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

#### Identify a customer:

`typescript
// Identify a customer
const customer = await sdk.customers.identify({
externalUserId: 'user_123',
email: 'user@example.com',
name: 'Jane Doe',
});
`

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

#### Create a referral:
`typescript
// 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):
`typescript
await sdk.rewards.trigger({
campaignId: campaign.id,
externalUserId: 'user_123',
environment: 'production', // Or 'test'
});
`

#### Validating Webhook Events:
`typescript
// 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