@refkitnet/sdk

Browser and server helpers for RefKit affiliate click capture, customer identification, and API-reported payments.

Install

npm install @refkitnet/sdk

Consent (required where applicable)

Before recording RefKit tracking, you must obtain end-user consent where your jurisdiction or CMP requires it (e.g. GDPR/ePrivacy). Server-side capture does not remove that responsibility; only capture after any required consent is granted.

Browser fallback example:

if (userHasAnalyticsConsent()) {
  refkit.capture();
}

RefKit is a data processor; you (the app owner) are the data controller and are responsible for lawful basis, privacy notices, and consent UI.

Server capture (recommended)

Capture on the backend that receives the landing request so RefKit receives the original visitor metadata and the returned click id can live in secure first-party storage.

import { captureClick } from "@refkitnet/sdk";

const landingUrl = new URL(request.url);
const via = landingUrl.searchParams.get("via");

if (via) {
  const result = await captureClick({
    apiKey: process.env.REFKIT_API_KEY!,
    via,
    page: landingUrl.toString(),
    referrer: request.headers.get("referer") ?? undefined,
    visitorIp: trustedClientIp(request),
    visitorUserAgent: request.headers.get("user-agent") ?? undefined,
  });

  secureSession.refkitClickId = result.click_id;
}

The app API key is server-side only. Never expose it in browser code. When your app is behind a proxy, use your framework or platform's trusted-proxy client IP helper instead of accepting an arbitrary X-Forwarded-For value.

Browser fallback

import { init, capture, getClickId, getStripeMetadata } from "@refkitnet/sdk/browser";

init();

// After consent — reads ?via= from URL, records click, and persists click_id
await capture();

const clickId = getClickId();

// Stripe apps: pass to Stripe Checkout metadata on your server
const metadata = getStripeMetadata();

Browser capture uses the public capture mode without an API key. RefKit derives visitor metadata from the request and ignores body-supplied visitor metadata.

The unique via code identifies the affiliate link and its Program. Do not add a Program identifier to the public URL.

Customer identification and API revenue

import {
  identifyCustomer,
  reportPayment,
  reportRefund,
} from "@refkitnet/sdk";

const result = await identifyCustomer({
  apiKey: process.env.REFKIT_API_KEY!,
  baseUrl: "https://app.refkit.net",
  externalCustomerId: "user_123",
  email: "[email protected]",
  clickId: clickIdFromSecureSession,
});

// API-reported revenue apps only
await reportPayment({
  apiKey: process.env.REFKIT_API_KEY!,
  paymentId: invoice.id,
  customerId: result.customer_id,
  programId: result.program_id,
  amount: 2900,
  currency: "usd",
});

await reportRefund({
  apiKey: process.env.REFKIT_API_KEY!,
  refundId: refund.id,
  paymentId: invoice.id,
  amount: 2900,
});

If payment reporting happens after signup, persist result.customer_id and result.program_id with your customer or billing record.

Attribution window

Clicks are attributed for 30 days. Keep the server-captured click id in secure first-party storage and call identifyCustomer as soon as possible after signup. Browser storage limits are another reason to treat browser capture as the fallback.

License

MIT