@fireballgg/sdk

TypeScript SDK for building applications on Gigaverse and Fireball. Includes type-safe API clients, game data, and utilities for dungeons, fishing, and on-chain integrations.

Installation

npm install @fireballgg/sdk
# or
yarn add @fireballgg/sdk
# or
bun add @fireballgg/sdk

Features

• 🎮 Game APIs: Full TypeScript clients for Gigaverse and Fireball APIs
• 🔗 Blockchain Integration: Juiced subgraph and API clients
• 📊 Game Data: Comprehensive game data exports (items, enemies, gear, recipes)
• 🪵 Logging: Built-in structured logging with Pino
• 🔒 Type Safety: Full TypeScript support with auto-generated types
• 📦 Modular: Tree-shakeable exports for optimal bundle size

API Modules

Gigaverse API

Game API client for dungeon runs, fishing, and other Gigaverse features.

import { createGigaverseApi } from '@fireballgg/sdk/gigaverse-api';

const api = createGigaverseApi({
  authToken: 'your-jwt-token'
});

// Example: Fetch account data
const account = await api.getAccount();

Fireball API

GraphQL API client for Fireball backend services. All methods are auto-generated from GraphQL operations.

import { createFireballApi } from '@fireballgg/sdk/fireball-api';

const api = createFireballApi({
  endpoint: 'https://fireball.gg/graphql',
  jwt: 'your-jwt-token'
});

// Example: Fetch account by ID
const account = await api.GetAccountById({ id: '123' });

// Example: Fetch dungeons
const dungeons = await api.GetDungeons({ take: 10 });

Juiced Subgraph

GraphQL client for querying Juiced blockchain data (item listings, trade history).

import { createJuicedSubgraph } from '@fireballgg/sdk/juiced-subgraph';

const subgraph = createJuicedSubgraph();

// Example: Get items last sale data
const result = await subgraph.GetItemsLastSale({ first: 100 });

Juiced API

REST API client for Juiced marketplace at juiced.sh.

import { JuicedApi } from '@fireballgg/sdk/juiced-api';

const api = new JuicedApi();

// Example: Get latest trades
const trades = await api.getLatestTrades({ limit: 50 });

Logger

Structured logging with Pino (with console fallback for browser environments).

import { createLogger } from '@fireballgg/sdk/logger';

const logger = createLogger({ service: 'my-app' });
logger.info('Hello world');

Game Data

Import static game data as JSON:

// Core game data
import items from '@fireballgg/sdk/data/items.json';
import gear from '@fireballgg/sdk/data/gear.json';
import enemies from '@fireballgg/sdk/data/enemies.json';
import recipes from '@fireballgg/sdk/data/recipes.json';

// Fishing data
import fishingCards from '@fireballgg/sdk/data/fishing_cards.json';
import fishingRates from '@fireballgg/sdk/data/fishing_exchange_rates.json';

// Other game data
import constants from '@fireballgg/sdk/data/constants.json';
import checkpoints from '@fireballgg/sdk/data/checkpoints.json';
import hatchery from '@fireballgg/sdk/data/hatchery.json';

Utilities & Types

The main package export includes shared utilities, types, enums, and constants:

import {
  // Enums
  DungeonType,
  GameType,
  FishingAction,
  FishingType,
  ItemRarity,

  // Types
  Gear,
  Item,
  Enemy,
  Action,

  // Constants
  GIGAVERSE_ENDPOINT,
  ROMS_CONTRACT_ADDRESS,
  PETS_CONTRACT_ADDRESS,

  // Utilities
  // ... and more
} from '@fireballgg/sdk';

Development

# Install dependencies
bun install

# Build SDK
bun run build

# Build in watch mode
bun run build:watch

# Generate GraphQL types
bun run codegen

# Fetch external game data
bun run fetch

Package Structure

@fireballgg/sdk
├── /                      - Core utilities, types, enums, and constants
├── /gigaverse-api         - Gigaverse game API client
├── /fireball-api          - Fireball GraphQL API client (auto-generated)
├── /juiced-api            - Juiced REST API client
├── /juiced-subgraph       - Juiced GraphQL subgraph client
├── /logger                - Structured logging utilities
├── /data/*.json           - Game data exports
└── /abis/*.json           - Smart contract ABIs

License

MIT License - see LICENSE file for details.

Links

• npm package
• fireball client