RefKit SDK

RefKit SDK is the business-side ingestion client for referral and event tracking.

It is aligned to the current API contract:

• POST /track
• POST /sdk/referrals/apply
• GET /sdk/referrals

The SDK sends API-key authenticated requests and supports idempotent tracking payloads.

Install

npm install refkit-sdk

Quick Start (NPM)

import { RefKitClient } from "@repo/sdk";

const refkit = new RefKitClient({
  apiKey: "rk_live_xxx",
  apiUrl: "https://your-api-host",
  source: "my-app",
});

// Track a generic event
await refkit.trackEvent({
  eventName: "signup_complete",
  metadata: { plan: "starter" },
});

// Track a referral event
await refkit.trackReferralConversion({
  referrer: "alice-code",
  metadata: {
    referredUserEmail: "[email protected]",
  },
});

// Apply referral directly
await refkit.applyReferral({
  referralCode: "alice-code",
  referredUserEmail: "[email protected]",
});

// Read recent referrals linked to this API key
const recent = await refkit.listReferrals(25);

Request Behavior

The API can process synchronously or queue to worker depending on payload context.

Typical response envelope:

{
  "success": true,
  "queued": true,
  "jobId": "event:...",
  "jobType": "EVENT_PROCESS"
}

Or synchronous:

{
  "success": true,
  "processedSynchronously": true,
  "queued": false,
  "triggerId": "..."
}

React Package

The package also exports lightweight React helpers:

• RefKitProvider
• useTrackEvent
• useApplyReferral
• useRecentReferrals
• Leaderboard
• UserRewardsDashboard

Example:

import { RefKitProvider, useTrackEvent } from "@repo/sdk/react";

function TrackButton() {
  const { track, isLoading } = useTrackEvent();

  return (
    <button
      disabled={isLoading}
      onClick={() =>
        track({ eventName: "button_click", metadata: { section: "hero" } })
      }
    >
      Track
    </button>
  );
}

export function App() {
  return (
    <RefKitProvider
      config={{ apiKey: "rk_live_xxx", apiUrl: "https://your-api-host" }}
    >
      <TrackButton />
    </RefKitProvider>
  );
}

CDN Build

The SDK builds a browser bundle at dist/cdn/refkit.min.js. Build script also copies it to:

• apps/api/public/cdn/refkit.min.js
• apps/web/public/refkit.min.js

npm run build --workspace packages/sdk

Notes

• Keep API keys server-safe whenever possible.
• If used client-side, restrict origins in Business API Key settings.
• Use idempotency keys for repeated or retried event submissions.