@offcoin/sdk

@offcoin/sdk

TypeScript/JavaScript SDK for the Offcoin API. Manage members, tokens, XP, achievements, and leaderboards.

Installation

npm install @offcoin/sdk
# or
pnpm add @offcoin/sdk
# or
yarn add @offcoin/sdk

Quick Start

import { OffcoinClient } from '@offcoin/sdk';

const offcoin = new OffcoinClient({
  baseUrl: 'https://your-offcoin-instance.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret'
});

// List all members
const members = await offcoin.members.list();

// Create a member
const newMember = await offcoin.members.create({
  name: 'John Doe',
  aliases: ['discord:123456', 'github:johndoe']
});

// Add tokens
const result = await offcoin.members.addTokens('discord:123456', 100, 'Welcome bonus');
console.log(`New balance: ${result.newBalance}`);

API Reference

Members

// List all members
const members = await offcoin.members.list();

// Create a member
const member = await offcoin.members.create({
  name: 'John Doe',
  avatarUrl: 'https://example.com/avatar.png', // optional
  aliases: ['discord:123456', 'github:johndoe'] // optional
});

// Get a member by alias
const member = await offcoin.members.get('discord:123456');

// Update a member
const updated = await offcoin.members.update('discord:123456', {
  name: 'Jane Doe',
  avatarUrl: null // remove avatar
});

// Get token balance
const balance = await offcoin.members.getBalance('discord:123456');
console.log(`Balance: ${balance.balance}`);

// Get XP and level
const xp = await offcoin.members.getXp('discord:123456');
console.log(`XP: ${xp.xp}, Level: ${xp.level}`);

// Add tokens
const result = await offcoin.members.addTokens('discord:123456', 100, 'Purchase reward');

// Subtract tokens
const result = await offcoin.members.subtractTokens('discord:123456', 50, 'Item purchase');

// Add XP
const result = await offcoin.members.addXp('discord:123456', 25);

Achievements

// List all achievements
const achievements = await offcoin.achievements.list();

// Unlock an achievement for a member
const result = await offcoin.achievements.unlock('achievement-id', 'discord:123456');
console.log(`Unlocked: ${result.achievementName}`);
console.log(`Cascading achievements: ${result.cascadingAchievementsGranted}`);

Leaderboard

// Get leaderboard (default: sorted by XP, limit 50)
const leaderboard = await offcoin.leaderboard.get();

// Get top 10 by tokens
const tokenLeaderboard = await offcoin.leaderboard.get({
  sort: 'tokens',
  limit: 10
});

// Get top 25 by level
const levelLeaderboard = await offcoin.leaderboard.get({
  sort: 'level',
  limit: 25
});

Permissions

// List all purchasable permissions
const permissions = await offcoin.permissions.list();

// List permissions with ownership info for a specific member
const permissions = await offcoin.permissions.list({ alias: 'discord:123456' });
// Returns permissions with `owned` and `canPurchase` fields

// Purchase a permission for a member
const result = await offcoin.permissions.purchase('discord:123456', 'vip_access');
console.log(`Purchased ${result.permissionName} for ${result.tokenPrice} tokens`);
console.log(`New balance: ${result.newBalance}`);

Error Handling

The SDK throws typed errors for different scenarios:

import {
  OffcoinClient,
  AuthenticationError,
  NotFoundError,
  ValidationError
} from '@offcoin/sdk';

try {
  await offcoin.members.get('unknown-alias');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid credentials');
  } else if (error instanceof NotFoundError) {
    console.error('Member not found');
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  }
}

Error Types

Error Class	Code	Description
AuthenticationError	UNAUTHORIZED	Invalid client_id or client_secret
ForbiddenError	FORBIDDEN	Not authorized for this action
NotFoundError	NOT_FOUND	Resource not found
ValidationError	VALIDATION_ERROR	Invalid input data
BadRequestError	BAD_REQUEST	Malformed request
InternalError	INTERNAL_ERROR	Server error
OffcoinError	Various	Base error class

TypeScript Types

All types are exported for use in your application:

import type {
  Member,
  MemberBalance,
  MemberXp,
  Achievement,
  LeaderboardEntry,
  TokenOperationResult,
  XpOperationResult,
  UnlockResult,
  Permission,
  PurchasePermissionResult
} from '@offcoin/sdk';

Authentication

The SDK uses Basic Authentication with your API credentials. You can find your clientId and clientSecret in the Offcoin admin dashboard under Settings > API Access.

const offcoin = new OffcoinClient({
  baseUrl: 'https://your-offcoin-instance.com',
  clientId: process.env.OFFCOIN_CLIENT_ID!,
  clientSecret: process.env.OFFCOIN_CLIENT_SECRET!
});

Requirements

• Node.js 18+ (for native fetch support) or a browser environment
• TypeScript 5.0+ (for type definitions)

License

MIT