Referral Rock plugin

• The credential is Basic with both keys. The public key is the username and the private key the password; a single key with an empty password answers 401. The plugin builds the Authorization header from the stored value.
• Two different 401 bodies. A request with no credential answers a JSON wrapper, { response: { status_code, status_message, body } }. A credential the host rejects answers HTML before the request reaches the API, so the status is all there is. The plugin reads both.
• Refused creates throw. A duplicate member email or an unknown referral code answers 400 with the reason in message, which the plugin raises as a ReferralrockAPIError. A refused reward answers 200 with resultInfo.Status: "Failed"; the plugin raises that too.
• Paging is offset and count. A collection answers offset, total and the rows; next_offset is null once the rows reach the total. Omitting count returns everything, because that is the documented default.
• Member sort values. sort takes one of Member_Views_Desc, Member_Views_Asc, Page_Views_Desc, Page_Views_Asc, Lead_Count_Desc, Lead_Count_Asc, Reward_Issued_Total_Desc, Reward_Issued_Total_Asc, Member_Full_Name_Desc, Member_Full_Name_Asc, Create_Dt_Desc or Create_Dt_Asc, and it defaults to Create_Dt_Desc.
• An unrecognised sort is silently ignored. Referral Rock says so explicitly and falls back to the default, so a typo would return correctly-shaped data in the wrong order. members.list pins the accepted values.
• A member needs a program, a first name and an email. Referral Rock validates all three, so the schema requires them.
• A reward is sent as an array. POST /api/rewards takes a list of reward infos, each with ONE of memberQuery or referralQuery and a newReward, and answers a list of results; the plugin wraps your input and unwraps the first result. Give member_id or referral_id, not both, and a payout_id: Referral Rock requires one, and a payout only exists once a reward rule in the program uses it.
• Retries. Referral Rock documents no throughput window and no Retry-After, so a 429 is retried three times with exponential backoff. A 5xx is retried only for a read.

• 7 typed API operations

​

Setup

npm install corsair @corsair-dev/referralrock better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/referralrock better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/referralrock better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/referralrock better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { referralrock } from '@corsair-dev/referralrock';

export const corsair = createCorsair({
	plugins: [
		referralrock(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

referralrock()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'referralrock',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.referralrock.api.members.list({ count: 50 });

const tenant = corsair.withTenant('acme');
await tenant.referralrock.api.referrals.create({
	referral_code: 'SAM123',
	first_name: 'Jordan',
	email: 'jordan@example.com',
	amount: 250,
});

​

What’s next