@blossu/server

Official server-side SDK for Blossu - the affiliate and referral tracking platform.

When to Use This SDK

| Use Case | SDK | |----------|-----| | Frontend (React, Next.js, Vue) | Use @blossu/ui - handles click tracking automatically | | Backend (API routes, webhooks) | Use this SDK (@blossu/server) |

Typical flow:

1. @blossu/ui automatically tracks clicks when users arrive via ?ref=CODE
2. Your backend uses this SDK to track signups and sales

Installation

npm install @blossu/server

Quick Start

import { Blossu } from "@blossu/server";

const blossu = new Blossu(process.env.BLOSSU_API_KEY!);

// Track a signup (when user creates an account)
await blossu.track.signup({
  code: "PARTNER123",            // Required: the referral code
  customerExternalId: "usr_123", // Your user ID (used to link sales later)
  customerEmail: "[email protected]",
});

// Track a sale (when user makes a purchase)
await blossu.track.sale({
  customerExternalId: "usr_123", // Same ID from signup
  amount: 9900,                  // $99.00 in cents
});

Usage with Next.js

With @blossu/ui (Recommended)

If you're using @blossu/ui on the frontend, it stores the referral code in cookies. Pass it to your signup API:

// Frontend: Get referral info from @blossu/ui
import { getReferralInfo } from "@blossu/ui";

const referralInfo = getReferralInfo();
// { code: "PARTNER123", refId: "bls_abc123..." }

// Pass to your signup API
await fetch("/api/signup", {
  method: "POST",
  body: JSON.stringify({
    email,
    password,
    referralCode: referralInfo?.code,
  }),
});

// Backend: Track the signup
import { Blossu } from "@blossu/server";

const blossu = new Blossu(process.env.BLOSSU_API_KEY!);

export async function POST(request: NextRequest) {
  const { email, password, referralCode } = await request.json();
  
  // Create user in your system
  const user = await createUser({ email, password });
  
  // Track signup if referred
  if (referralCode) {
    await blossu.track.signup({
      code: referralCode,
      customerExternalId: user.id,
      customerEmail: email,
    });
  }
  
  return NextResponse.json({ success: true });
}

Server Actions

// app/actions.ts
"use server";

import { Blossu } from "@blossu/server";

const blossu = new Blossu(process.env.BLOSSU_API_KEY!);

export async function trackSignup(
  userId: string,
  email: string,
  referralCode: string | null
) {
  if (!referralCode) return;
  
  await blossu.track.signup({
    code: referralCode,
    customerExternalId: userId,
    customerEmail: email,
  });
}

API Reference

Partners

// Create a partner
const partner = await blossu.partners.create({
  email: "[email protected]",
  displayName: "John Doe",
  firstName: "John",
  lastName: "Doe",
});

// Get a partner
const partner = await blossu.partners.get("partner-id");

// Update a partner
const updated = await blossu.partners.update("partner-id", {
  displayName: "Jane Doe",
});

// List partners
const { items, cursor, hasMore } = await blossu.partners.list({
  limit: 20,
  status: "ACTIVE",
});

// Ban a partner
await blossu.partners.ban("partner-id", "Violation of terms");

Referral Codes

// Create a referral code
const code = await blossu.codes.create({
  partnerId: "partner-id",
  code: "JOHNREFERRAL",
  displayName: "John's Referral Link",
});

// Look up a code
const code = await blossu.codes.getByCode("JOHNREFERRAL");

// List codes for a partner
const codes = await blossu.codes.listByPartner("partner-id");

Tracking

import { Currency, SaleProvider } from "@blossu/server";

// Track a signup (when user creates account)
await blossu.track.signup({
  code: "PARTNER123",                // Required: referral code
  customerExternalId: "usr_123",     // Your user ID
  customerEmail: "[email protected]",
});

// Track a sale (when user makes a purchase)
await blossu.track.sale({
  customerExternalId: "usr_123",     // Same ID from signup
  amount: 9900,                      // Amount in cents
  currency: Currency.USD,
  provider: SaleProvider.STRIPE,
});

Note: Click tracking is handled automatically by @blossu/ui on the frontend. You typically don't need track.click() unless doing server-side click tracking.

Conversions

// List conversions
const conversions = await blossu.conversions.list({
  status: "PENDING",
});

// Approve a conversion
await blossu.conversions.approve("conversion-id");

// Reject a conversion
await blossu.conversions.reject("conversion-id", "Fraudulent activity");

Payouts

// Create a payout
const payout = await blossu.payouts.create({
  partnerId: "partner-id",
  amount: 5000, // $50.00
  currency: "USD",
  method: "MANUAL",
});

// Mark payout as paid
await blossu.payouts.markAsPaid("payout-id");

// Get pending balance for a partner
const balance = await blossu.payouts.getPendingBalance("partner-id");

Rewards

// Create a reward
const reward = await blossu.rewards.create({
  displayName: "20% Commission",
  triggerType: "PURCHASE",
  rewardType: "COMMISSION",
  reward: {
    type: "PERCENTAGE",
    value: 20,
  },
});

// List reward claims
const claims = await blossu.rewards.listClaims({
  status: "PENDING",
});

Analytics

// Get overview stats
const overview = await blossu.analytics.getOverview({
  startDate: "2024-01-01",
  endDate: "2024-01-31",
});

// Get clicks by code
const clicksByCode = await blossu.analytics.getClicksByCode({
  limit: 10,
});

// Get clicks timeseries
const timeseries = await blossu.analytics.getClicksTimeseries({
  interval: "day",
});

// Get partner stats
const partnerStats = await blossu.analytics.getPartnerStats("partner-id");

Program Settings

// Get program settings
const program = await blossu.program.get();

// Update program settings
await blossu.program.update({
  displayName: "My Affiliate Program",
  defaultCommission: {
    type: "PERCENTAGE",
    value: 20,
  },
});

Configuration

const blossu = new Blossu("your-api-key", {
  baseUrl: "https://api.blossu.com", // default
  timeout: 30000, // 30 seconds
  maxRetries: 3,
  apiVersion: "v1",
});

// Enable debug mode
blossu.setDebugMode(true);

// Set custom headers
blossu.setHeader("X-Custom-Header", "value");

Partner Widget Authentication

When embedding the partner widget in your app, you need to sign partner tokens server-side to prevent spoofing. The SDK provides a helper function for this:

import { signPartnerToken } from "@blossu/server";

// In your API route (e.g., Next.js)
export async function GET() {
  const session = await getServerSession();
  if (!session?.user?.email) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const token = signPartnerToken({ email: session.user.email });

  return Response.json(token); // { email, signature }
}

The function uses HMAC-SHA256 to sign the email. Set your secret key via:

• Environment variable: BLOSSU_SECRET_KEY
• Or pass it directly: signPartnerToken({ email, secretKey: "your-secret" })

Error Handling

import {
  Blossu,
  BlossuError,
  AuthenticationError,
  RateLimitError,
} from "@blossu/server";

try {
  await blossu.partners.create({ email: "invalid" });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof BlossuError) {
    console.error("API error:", error.message, error.code);
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions:

import type {
  Partner,
  PartnerCreateOptions,
  ReferralCode,
  Conversion,
  Payout,
  Reward,
  TrackSignupOptions,
  TrackSaleOptions,
  SignPartnerTokenOptions,
  PartnerToken,
} from "@blossu/server";

import {
  Currency,
  SaleProvider,
  PartnerStatus,
  ConversionStatus,
  PayoutStatus,
} from "@blossu/server";

License

MIT