JS/TS SDK Reference

The official JavaScript/TypeScript SDK (ffdata-client) is a lightweight, dependency-free, and production-ready library. Built with TypeScript types natively, it provides enterprise resilience features including jittered exponential backoffs, granular circuit breakers, global pauses, and a memory-safe Bounded LRU caching layer.

Installation

Install the package via npm inside your project root:

npm install ffdata-clientTerminal

Client Initialization

Initialize the FFClient instance by feeding your secret API credential.

javascript

import { FFClient } from 'ffdata-client';

// Initialize client using your secret API key
// Suitable for Node.js (18+), Edge environments, and Browser runtimes
const client = new FFClient('your_api_key', {
  timeout: 10,         // request timeout in seconds (default is 10)
  maxRetries: 3,       // automatic retries on network/server failures (default is 2)
  fallbackMode: true,  // returns stale cache during circuit breaker/rate-limit outages
  debug: 'basic'       // logging levels: 'off', 'basic', 'verbose' (default is 'off')
});
});

Querying Player Statistics

Call `getPlayer` to fetch player data. Specify region and detail filters directly:

javascript

// Fetch player details
try {
  const playerData = await client.getPlayer(
    1738283841,
    'ind',         // optional region code, defaults to "ind"
    'detailed'     // basic, detailed, or full
  );

  console.log(playerData.data.nickname);
  console.log(playerData.data.level);
  console.log(`Credits remaining: ${playerData.meta.credits_left}`);
} catch (error) {
  console.error('Failed to fetch player:', error);
}, error);
}

Querying Clan/Guild Data

Fetch detailed guild hierarchies and rosters using `getClan`:

javascript

// Fetch clan details (Guild info)
try {
  const clanData = await client.getClan(
    3022208474,
    'ind',
    'basic'
  );

  console.log(clanData.data.clan_name);
  console.log(clanData.data.member_num);
} catch (error) {
  console.error('Failed to fetch clan:', error);
}, error);
}

Querying Craftland Authors

Retrieve author profile stats and publishing map listings using `getWorkshopAuthor`:

javascript

// Fetch Craftland workshop author details
try {
  const authorData = await client.getWorkshopAuthor(
    1738283841,
    'full'
  );

  console.log(authorData.data.nickname);
  authorData.data.publish_maps.forEach((mapInfo: any) => {
    console.log(`Map: ${mapInfo.map_name} - Plays: ${mapInfo.plays}`);
  });
} catch (error) {
  console.error('Failed to fetch workshop author:', error);
}, error);
}

Exception Handling

The SDK maps status codes to structured exceptions to allow clean client-side exception routing:

javascript

import { FFClient } from 'ffdata-client';
import {
  AuthError,
  InsufficientCreditsError,
  RateLimitError,
  CircuitBreakerError
} from 'ffdata-client';

const client = new FFClient('your_api_key');

try {
  const player = await client.getPlayer(1738283841);
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Invalid API credentials. Review authorization tokens.');
  } else if (error instanceof InsufficientCreditsError) {
    console.error('Your account balance has run out. Refill credits to resume.');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry allowed after ${error.retryAfter} seconds.`);
  } else if (error instanceof CircuitBreakerError) {
    console.error('Local client circuit breaker opened due to high downstream failure rates.');
  } else {
    console.error('Unexpected client error:', error.message);
  }
}, error.message);
  }
}