npm package: @fireballgg/sdk
Description: 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.
Latest version: 0.0.8

# @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

```bash
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.

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

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

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

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

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

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

## Game Data

Import static game data as JSON:

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

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

```bash
# 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](./LICENSE) file for details.

## Links

- [npm package](https://www.npmjs.com/package/@fireballgg/sdk)
- [fireball client](https://fireball.gg)