@usebadger/sdk

Official SDK for UseBadger - Gamify your app with badges and rewards.

Installation

npm install @usebadger/sdk
# or
yarn add @usebadger/sdk

Quick Start

import { BadgerClient } from "@usebadger/sdk";

const client = new BadgerClient({
  appId: "your-app-id",
  appSecret: "your-app-secret",
});

// Track an event
await client.events.sendEvent({
  userId: "user123",
  event: "purchase_completed",
  metadata: { amount: "99.99", product: "premium_plan" },
});

// Manually award a badge to a user
await client.badges.awardBadge("user123", "badge-id");

// Get user information
const user = await client.users.getUser("user123");
const badges = await user.getBadges();

API Reference

Configuration

interface SDKConfig {
  appId: string; // Your UseBadger app ID (required)
  appSecret?: string; // Your app secret for authenticated operations (optional)
}

Authentication

• appId: Your unique app identifier. Found in your app settings dashboard. This is public and safe to expose in client-side code.
• appSecret: Your app's secret key for authenticated operations like sending events and awarding badges. Generate this in your app settings dashboard. Keep this secret - never expose it in client-side code, public repositories, or browser environments.

Badges

// Get all badges with optional filtering
const { cursor, badges } = await client.badges.getBadges({
  cursor: "next-page-token",
  category: "onboarding",
  parentBadgeId: "parent-badge-id",
  userId: "user123",
});

// Get a specific badge
const badge = await client.badges.getBadge("badge-id");

// Award a badge to a user
const awardedBadge = await client.badges.awardBadge("user123", "badge-id");

// Get badge conditions
const conditions = await client.badges.getConditions("badge-id");

// Get badge rewards
const rewards = await client.badges.getRewards("badge-id");

// Badge object with convenience methods
const badge = await client.badges.getBadge("badge-id");
const conditions = await badge.getConditions();
const rewards = await badge.getRewards();
const users = await badge.getUsers();
const children = await badge.getChildren();
await badge.award("user123");

Events

// Send an event
const event = await client.events.sendEvent({
  userId: "user123",
  event: "page_view",
  metadata: { page: "/dashboard", referrer: "google.com" },
});

Users

// Get users with optional filtering
const { cursor, users } = await client.users.getUsers({
  cursor: "next-page-token",
  badgeId: "badge-id",
  badgeIds: ["badge1", "badge2"],
});

// Get a specific user
const user = await client.users.getUser("user123");

// Get user badges with filtering
const badges = await client.users.getUserBadges("user123", {
  cursor: "next-page-token",
  status: "all",
  statuses: [
    BadgeStatus.COMPLETE,
    BadgeStatus.INCOMPLETE,
    BadgeStatus.NOT_STARTED,
  ],
  category: "onboarding",
});

// Get a specific user badge
const userBadge = await client.users.getUserBadge("user123", "badge-id");

// Award a badge to a user
const awardedBadge = await client.users.awardUserBadge("user123", "badge-id");

// Get user rewards
const rewards = await client.users.getUserRewards("user123");

// User object with convenience methods
const user = await client.users.getUser("user123");
const userBadges = await user.getBadges({ status: "COMPLETE" });
const rewards = await user.getRewards();

Badge Relationships

// Get all children of a parent badge
const parentBadge = await client.badges.getBadge("sequence-start");
const children = await parentBadge.getChildren();
// You can also recursively get all descendants of a badge
const allChildren = await parentBadge.getChildren({ depth: Infinity });
// You can also get the parent of any badge in a sequence
const parent = await children[0].getParent();

// Track user progress through a badge sequence
const userBadge = await client.users.getUserBadge("user123", "sequence-start");
if (userBadge.current) {
  console.log(`User is at: ${userBadge.current.badgeId}`);
  if (userBadge.next) {
    console.log(`Next target: ${userBadge.next.badgeId} - ${userBadge.next.progress}%`);
  } else {
    console.log("User has completed the entire sequence!");
  }
}

### Webhook Verification

```typescript
app.post("/webhooks", (req, res) => {
  // Verify webhook signature
  const isValid = await client.verifySignature(
    req.body,
    webhookSecret,
    req.headers
  );
});

Types

The SDK provides comprehensive TypeScript types:

import type {
  Badge,
  BadgeCondition,
  BadgeReward,
  Event,
  User,
  UserBadge,
  UserBadgeCondition,
  BadgeVisibility,
  BadgeStatus,
  BadgeConditionType,
  StreakInterval,
} from "@usebadger/sdk";