Node.js (Server)

The refport server SDK provides track.lead(), track.sale(), and embedTokens.create() for server-side conversion reporting.

The refport package is the server-side SDK for Node.js. Use it to report lead and sale conversion events, generate embed tokens for the referral portal, and read click IDs from incoming HTTP requests.

Installation

npm install refport
# or
pnpm add refport
# or
yarn add refport

Initialising the client

Create a single Refport instance and reuse it across your application. Store your API key in an environment variable — never commit it to source control.

import { Refport } from 'refport';

export const refport = new Refport({
  apiKey: process.env.REFPORT_API_KEY!,
});

Constructor options

Option	Type	Required	Description
`apiKey`	`string`	Yes	Your Refport API key
`baseUrl`	`string`	No	Override the API base URL (default: `https://app.refport.co`)

`track.lead(params)`

Report a lead event when a user signs up or creates an account.

await refport.track.lead({
  clickId: 'abc123',
  eventName: 'Sign Up',
  customerExternalId: user.id,
  customerEmail: user.email,
  customerName: user.name,
});

Parameters

Parameter	Type	Required	Description
`clickId`	`string`	Yes	The `refp_id` click ID from the user's cookie
`eventName`	`string`	Yes	Descriptive name for the lead event (e.g. `"Sign Up"`)
`customerExternalId`	`string`	Yes	Your internal user ID
`customerEmail`	`string`	No	User's email address
`customerName`	`string`	No	User's display name
`customerAvatar`	`string`	No	URL to the user's avatar image
`metadata`	`Record<string, unknown>`	No	Arbitrary metadata attached to the event

Response

{
  eventName: string;
  click: { id: string };
  link: {
    id: string;
    domain: string;
    key: string;
    url: string;
    programId: string | null;
  };
  customer: {
    externalId: string;
    email: string;
    name: string | null;
  };
}

`track.sale(params)`

Report a sale event when a customer makes a purchase.

await refport.track.sale({
  clickId: 'abc123',
  customerExternalId: user.id,
  amount: 4900,        // in smallest currency unit (cents for USD)
  currency: 'usd',
  eventName: 'Purchase',
  invoiceId: 'inv_001',
  paymentProcessor: 'stripe',
});

Parameters

Parameter	Type	Required	Description
`clickId`	`string`	Yes	The `refp_id` click ID from the user's cookie
`customerExternalId`	`string`	Yes	Your internal user ID
`amount`	`number`	Yes	Sale amount in the smallest currency unit (e.g. cents)
`currency`	`string`	No	ISO 4217 currency code (default: `"usd"`)
`eventName`	`string`	No	Descriptive name for the event (default: `"Purchase"`)
`invoiceId`	`string`	No	Your invoice or order ID for deduplication
`paymentProcessor`	`"stripe" \| "shopify" \| "polar" \| "paddle" \| "revenuecat" \| "custom"`	No	The payment processor used
`customerEmail`	`string`	No	Customer's email
`customerName`	`string`	No	Customer's display name
`customerAvatar`	`string`	No	URL to the customer's avatar
`metadata`	`Record<string, unknown>`	No	Arbitrary metadata

Response

{
  eventName: string;
  customer: {
    externalId: string;
    email: string;
    name: string | null;
  };
  sale: {
    id: string;
    amount: number;
    currency: string;
    commissionAmount: number;
    status: string;
    invoiceId: string | null;
    paymentProcessor: string;
  };
}

`embedTokens.create(params)`

Generate a short-lived public token for rendering the embedded referral portal. See Embedded Portal for full usage.

const token = await refport.embedTokens.create({
  tenantId: user.id,
  partner: {
    email: user.email,
    name: user.name,
  },
});
// token.publicToken — pass to <RefportEmbed>
// token.expires — Date object

Parameters

At least one of tenantId, enrollmentId, or partner must be provided.

Parameter	Type	Required	Description
`tenantId`	`string`	No	Your internal tenant/customer ID
`enrollmentId`	`string`	No	Existing enrollment ID to bind to
`partner.email`	`string`	Yes (in partner)	Partner's email address
`partner.name`	`string`	No	Partner's display name

Two helpers are exported for reading the refp_id click ID from server-side requests, without depending on any specific framework.

`getClickIdFromRequest(req, cookieName?)`

Works with standard Request objects (Fetch API), Next.js / Express / Nitro request objects, and anything with a cookies map or headers object.

import { getClickIdFromRequest } from 'refport';

const clickId = getClickIdFromRequest(req);

`getClickIdFromCookie(cookieHeader, cookieName?)`

Parses a raw Cookie header string directly.

import { getClickIdFromCookie } from 'refport';

const clickId = getClickIdFromCookie(req.headers.get('cookie'));

Error handling

All SDK methods throw typed errors. Catch them to handle specific failure modes gracefully.

import {
  RefportAuthError,
  RefportNotFoundError,
  RefportRateLimitError,
  RefportValidationError,
  RefportError,
} from 'refport';

try {
  await refport.track.lead({ ... });
} catch (err) {
  if (err instanceof RefportAuthError) {
    // Invalid or missing API key
  } else if (err instanceof RefportValidationError) {
    // Bad request parameters
  } else if (err instanceof RefportRateLimitError) {
    // Too many requests — back off and retry
  } else if (err instanceof RefportError) {
    // Generic error: err.status, err.code, err.message
  }
}

Error class	HTTP status	When thrown
`RefportAuthError`	401	Invalid or missing API key
`RefportValidationError`	400 / 422	Invalid request parameters
`RefportNotFoundError`	404	Resource not found
`RefportRateLimitError`	429	Rate limit exceeded
`RefportError`	any	Base class for all errors

Node.js (Server)

On this page