Refly SDK

A TypeScript SDK for interacting with the Refly referral system API.

Installation

npm install refly-js

Usage

Initialize the SDK

import { Refly } from "refly-js";

const refly = new Refly(
  "your-api-key",
  "https://referral-saas-production.up.railway.app"
);

User Management

Create a User

import { CreateUserRequest } from "refly-js";

const userData: CreateUserRequest = {
  external_id: "user123",
  email: "[email protected]",
  name: "John Doe",
  referral_code: "ABC123", // optional: the referral code of the user who referred this new user
};

try {
  const user = await refly.createUser(userData);
  console.log("User created:", user);
} catch (error) {
  console.error("Error creating user:", error.message);
}

Note about referral_code: When creating a user, the referral_code parameter should be the referral code of the existing user who referred this new user. For example, if user "john" has referral code "JOHN123" and refers a new user, you would pass "JOHN123" as the referral_code when creating the new user. This establishes the referral relationship between the referrer and the new user.

Get User Information

try {
  const user = await refly.getUser("user123");
  console.log("User info:", user);
  console.log("Referral link:", user.referral_link);
} catch (error) {
  console.error("Error getting user:", error.message);
}

Referrals

Get User's Referrals

try {
  const referrals = await refly.getUserReferrals("user123");
  console.log("User referrals:", referrals);
} catch (error) {
  console.error("Error getting referrals:", error.message);
}

Rewards

Get User's Available Rewards

try {
  const rewards = await refly.getUserRewards("user123");
  console.log("Available rewards:", rewards);
} catch (error) {
  console.error("Error getting rewards:", error.message);
}

Get Specific Reward Status

try {
  const reward = await refly.getUserReward("user123", "reward456");
  console.log("Reward status:", reward);
} catch (error) {
  console.error("Error getting reward:", error.message);
}

Unlock a Reward

try {
  const result = await refly.unlockReward("user123", "reward456");
  console.log("Reward unlocked:", result.message);
} catch (error) {
  console.error("Error unlocking reward:", error.message);
}

Credits

Get User's Credits

try {
  const credits = await refly.getUserCredits("user123");
  console.log("Credits:", credits);
} catch (error) {
  console.error("Error getting credits:", error.message);
}

Spend Credits

try {
  const result = await refly.spendCredits("user123", 10);
  console.log("Credits spent:", result);
} catch (error) {
  console.error("Error spending credits:", error.message);
}

API Reference

Constructor

new Refly(apiKey: string, baseUrl?: string)

• apiKey: Your Refly API key
• baseUrl: API base URL (defaults to 'https://api.refly.com')

Methods

User Methods

• getUser(externalId: string): Promise<User>
• createUser(userData: CreateUserRequest): Promise<CreateUserResponse>

Referral Methods

• getUserReferrals(externalId: string): Promise<Referral[]>

Reward Methods

• getUserRewards(externalId: string): Promise<Reward[]>
• getUserReward(externalId: string, rewardId: string): Promise<RewardStatus>
• unlockReward(externalId: string, rewardId: string): Promise<{ message: string }>

Credit Methods

• getUserCredits(externalId: string): Promise<Credits>
• spendCredits(externalId: string, amount: number): Promise<SpendCreditsResponse>

Types

interface User {
  id: string;
  external_id: string;
  referral_code: string;
  referral_link: string;
  referred_by: string | null;
  referral_count: number;
  created_at: string;
}

interface Referral {
  id: string;
  referee_external_id: string;
  created_at: string;
}

interface Reward {
  id: string;
  name: string;
  count: number;
  available: boolean;
  unlocked: boolean;
}

interface Credits {
  total_credits: number;
  spent_credits: number;
  available_credits: number;
}

interface CreateUserRequest {
  external_id: string;
  email?: string;
  name?: string;
  referral_code?: string;
  user_agent?: string;
}

Error Handling

All methods throw an Error with a descriptive message when the API returns an error. Make sure to wrap your calls in try-catch blocks.

Development

# Build the SDK
npm run build

# Watch mode for development
npm run dev

License

ISC