@mobula_labs/types

Centralized TypeScript types and Zod schemas for Mobula SDK and applications.

Overview

This package provides a comprehensive set of TypeScript types and Zod schemas for the Mobula API ecosystem. It serves as the single source of truth for type definitions across all Mobula packages and applications, ensuring type safety and consistency.

Features

• ✅ Type Safety: Full TypeScript support with strict typing
• ✅ Runtime Validation: Zod schemas for runtime type validation
• ✅ Dual Format Support: Available in both ESM and CommonJS formats
• ✅ API Versioning: Supports both v1 and v2 API schemas
• ✅ WebSocket Types: Complete type definitions for WebSocket payloads
• ✅ Utility Functions: Helper functions and constants for common operations
• ✅ Tree-shakeable: Only bundle what you use
• ✅ Zero Runtime Dependencies: Only peer dependency is Zod

Installation

npm install @mobula_labs/types zod
# or
bun add @mobula_labs/types zod
# or
pnpm add @mobula_labs/types zod

Note: zod (^3.0.0) is a required peer dependency for runtime validation.

Quick Start

import { MarketDataResponseSchema, TokenDetailsResponseSchema } from '@mobula_labs/types';
import type { z } from 'zod';

// Fetch and validate market data
const response = await fetch('https://api.mobula.io/api/1/market/data?asset=bitcoin');
const data = await response.json();

// Runtime validation
const validated = MarketDataResponseSchema.parse(data);
console.log(validated.data.price);

// Type inference
type MarketData = z.infer<typeof MarketDataResponseSchema>;

Usage

Basic Import

import { 
  AssetDetailsSchema, 
  MarketDataResponseSchema,
  TokenDetailsResponseSchema 
} from '@mobula_labs/types';

Type Inference from Schemas

import { AssetDetailsSchema } from '@mobula_labs/types';
import type { z } from 'zod';

// Infer TypeScript type from Zod schema
type AssetDetails = z.infer<typeof AssetDetailsSchema>;

// Use for validation
const result = AssetDetailsSchema.parse(apiResponse);

// Safe parsing (doesn't throw)
const safeResult = AssetDetailsSchema.safeParse(apiResponse);
if (safeResult.success) {
  console.log(safeResult.data);
} else {
  console.error(safeResult.error);
}

API Version Schemas

The package exports schemas organized by API version:

V1 API Schemas

import {
  // Market data
  MarketDataSchema,
  MarketHistorySchema,
  MarketPairsSchema,
  MarketSparklineSchema,
  
  // Wallet data
  WalletPortfolioSchema,
  WalletTransactionSchema,
  WalletBalanceUSDParamsSchema,
  WalletBalanceUSDResponseSchema,
  
  // Metadata
  MetadataSchema,
  MetadataTrendingsSchema,
  MetadataNewsSchema,
} from '@mobula_labs/types';

V2 API Schemas

import {
  // Assets
  AssetDetailsSchema,
  AssetPriceHistorySchema,
  
  // Markets
  MarketDetailsSchema,
  MarketOHLCVHistorySchema,
  
  // Tokens
  TokenDetailsSchema,
  TokenSecuritySchema,
  TokenTradesSchema,
  
  // Swaps
  SwapQuotingSchema,
  SwapSendSchema,
  
  // Wallets
  WalletPositionsSchema,
  WalletTokenBalancesSchema,
} from '@mobula_labs/types';

WebSocket Types

import {
  MarketPayloadSchema,
  TokenDetailsPayloadSchema,
  BalancePayloadSchema,
  OhlcvPayloadSchema,
  PositionPayloadSchema,
  FeedSchema,
} from '@mobula_labs/types';

// Example: Validate WebSocket message
const message = await ws.receive();
const validated = MarketPayloadSchema.parse(message);

Utility Functions & Constants

import {
  bigintAbs,
  period,
  BigIntLax,
  zodUtils,
  extractZodSchemaKeys,
  extractAllZodKeys,
} from '@mobula_labs/types';

// Use bigint utilities
const absoluteValue = bigintAbs(-100n); // 100n

// Use period helpers
const timeframe = period('1d');

// Use Zod utilities
const keys = extractZodSchemaKeys(MySchema);

Available Schema Categories

Market Schemas

• MarketDataSchema - Current market data
• MarketHistorySchema - Historical market data
• MarketPairsSchema - Trading pairs
• MarketSparklineSchema - Price sparklines
• MarketOHLCVHistorySchema - OHLCV candle data
• FundingRateSchema - Perpetual funding rates

Token Schemas

• TokenDetailsSchema - Token metadata and details
• TokenSecuritySchema - Token security analysis
• TokenTradesSchema - Recent trades
• TokenMarketsSchema - Markets listing the token
• TokenPositionsSchema - Token holder positions

Wallet Schemas

• WalletPortfolioSchema - Portfolio overview
• WalletBalanceUSDParamsSchema - USD balance query parameters
• WalletBalanceUSDResponseSchema - USD balance response
• WalletTransactionSchema - Transaction history
• WalletPositionsSchema - Open positions
• WalletTokenBalancesSchema - Token balances

Swap Schemas

• SwapQuotingSchema - Get swap quotes
• SwapQuotingBatchSchema - Batch quote requests
• SwapSendSchema - Execute swaps

Metadata Schemas

• MetadataSchema - Asset metadata
• MetadataCategoriesSchema - Token categories
• MetadataNewsSchema - Latest news
• MetadataTrendingsSchema - Trending tokens

Package Structure

packages/types/
├── src/
│   ├── v1/          # V1 API schemas
│   │   ├── market/
│   │   ├── metadata/
│   │   ├── wallet/
│   │   ├── token/
│   │   └── ...
│   ├── v2/          # V2 API schemas
│   │   ├── asset/
│   │   ├── market/
│   │   ├── swap/
│   │   ├── token/
│   │   └── wallet/
│   ├── wss/         # WebSocket schemas
│   │   ├── aggregated-feed/
│   │   ├── pulse/
│   │   └── stream/
│   └── utils/       # Utility functions and constants
│       ├── functions/
│       └── schemas/
├── dist/            # Built output
│   ├── esm/        # ES modules
│   ├── cjs/        # CommonJS
│   └── *.d.ts      # TypeScript declarations
└── package.json

Module Formats

The package supports multiple module formats with proper exports configuration:

// ESM (Recommended)
import { MarketDataSchema } from '@mobula_labs/types';

// CommonJS
const { MarketDataSchema } = require('@mobula_labs/types');

// TypeScript
import type { z } from 'zod';
type MarketData = z.infer<typeof MarketDataSchema>;

Real-World Example

import { 
  MarketDataResponseSchema, 
  TokenDetailsResponseSchema,
  WalletPortfolioSchema 
} from '@mobula_labs/types';
import type { z } from 'zod';

// Define types
type MarketData = z.infer<typeof MarketDataResponseSchema>;
type TokenDetails = z.infer<typeof TokenDetailsResponseSchema>;

async function getTokenInfo(address: string): Promise<TokenDetails> {
  const response = await fetch(
    `https://api.mobula.io/api/v2/token/details?address=${address}`
  );
  
  const data = await response.json();
  
  // Validate response with Zod - throws if invalid
  return TokenDetailsResponseSchema.parse(data);
}

async function getMarketPrice(asset: string): Promise<number | null> {
  const response = await fetch(
    `https://api.mobula.io/api/1/market/data?asset=${asset}`
  );
  
  const data = await response.json();
  const validated = MarketDataResponseSchema.parse(data);
  
  return validated.data.price;
}

// Error handling example
async function safeGetMarketData(asset: string) {
  try {
    const response = await fetch(
      `https://api.mobula.io/api/1/market/data?asset=${asset}`
    );
    const data = await response.json();
    
    const result = MarketDataResponseSchema.safeParse(data);
    
    if (result.success) {
      return { data: result.data, error: null };
    } else {
      return { data: null, error: result.error.errors };
    }
  } catch (error) {
    return { data: null, error: String(error) };
  }
}

Development

Build

bun run build

This will:

1. Clean the dist folder
2. Build ESM format to dist/esm/
3. Build CommonJS format to dist/cjs/
4. Generate TypeScript declaration files to dist/

Type Checking

bun run typecheck

Testing Exports

# Quick verification
bun -e "import('./dist/esm/index.js').then(m => console.log('Exports:', Object.keys(m).length))"

Contributing

When adding new schemas:

1. Place them in the appropriate version directory (v1/ or v2/)
2. Follow existing naming conventions (e.g., *Schema.ts)
3. Export them from src/index.ts
4. Ensure they use Zod for validation
5. Add JSDoc comments for better IDE support
6. Run bun run build and bun run typecheck before committing

Schema Naming Convention

• Schemas: *Schema.ts (e.g., MarketDataSchema.ts)
• Outputs: *Output.ts (e.g., SwapQuotingOutput.ts)
• Queries: *Query.ts (e.g., TokenSecurityQuery.ts)
• Payloads: *PayloadSchema.ts (e.g., MarketPayloadSchema.ts)

Version History

See CHANGELOG.md for release notes and migration guides.

Links

• Mobula API Documentation: https://docs.mobula.io
• Mobula Website: https://mobula.io
• Repository: https://github.com/MobulaFi/mobula-api
• Issues: https://github.com/MobulaFi/mobula-api/issues

License

MIT © Mobula