@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

``bash
npm install @blossu/server
`

Quick Start

`typescript
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: "user@example.com",
});

// 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

$3

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

`typescript
// 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,
}),
});
`

`typescript
// 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 });
}
`

$3

`typescript
// 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

$3

`typescript
// Create a partner
const partner = await blossu.partners.create({
email: "partner@example.com",
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");
`

$3

`typescript
// 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");
`

$3

`typescript
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: "user@example.com",
});

// 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.

$3

`typescript
// 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");
`

$3

`typescript
// 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");
`

$3

`typescript
// 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",
});
`

$3

`typescript
// 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");
`

$3

`typescript
// 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

`typescript
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:

`typescript
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

`typescript
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:

`typescript
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