TypeScript API Reference

Complete API reference for the Vidya TypeScript SDK.

Core Classes

VidyaSDK

The main entry point for interacting with the Vidya ecosystem.

class VidyaSDK {
  constructor(config: VidyaConfig)
  
  // Properties
  auth: AuthModule
  inventory: InventoryModule
  marketplace: MarketplaceModule
  crafting: CraftingModule
  gacha: GachaModule
  leaderboard: LeaderboardModule
  social: SocialModule
  npc: NPCModule
  currency: CurrencyModule
  quest: QuestModule
  stats: StatsModule
  
  // Methods
  getProject(): Promise<Project>
  getSession(): Session | null
  setSession(session: Session): void
  clearSession(): void
}

Player

The central object representing a player in the game.

class Player {
  // Static factory methods
  static fromSession(session: Session): Player
  static fromWallet(wallet: string): Player
  
  // Properties
  readonly id: string
  readonly wallet: string
  readonly canWrite: boolean
  
  // Methods
  requireWrite(): void
  getProfile(): Promise<PlayerProfile>
  getStats(): Promise<PlayerStats>
  getAchievements(): Promise<Achievement[]>
}

Item

Represents an in-game item with built-in methods.

class Item {
  // Properties
  readonly id: number
  readonly name: string
  readonly description: string
  readonly image: string
  readonly attributes: ItemAttribute[]
  readonly owner: string
  readonly balance: number
  readonly equipped: boolean
  readonly tradeable: boolean
  readonly consumable: boolean
  readonly stackable: boolean
  readonly maxStack: number
  readonly characterSlot: CharacterSlot
  
  // Methods
  transfer(to: Player, quantity?: number): Promise<void>
  equip(): Promise<void>
  unequip(): Promise<void>
  consume(quantity?: number): Promise<void>
  list(price: bigint, quantity?: number): Promise<Listing>
  getListings(): Promise<Listing[]>
  burn(quantity?: number): Promise<void>
}

Modules

AuthModule

Handles authentication and session management.

interface AuthModule {
  // Methods
  login(options: LoginOptions): Promise<Session>
  logout(): Promise<void>
  refreshSession(): Promise<Session>
  getSession(): Session | null
  onSessionChange(callback: (session: Session | null) => void): () => void
  
  // OAuth providers
  loginWithGoogle(): Promise<Session>
  loginWithDiscord(): Promise<Session>
  loginWithTwitter(): Promise<Session>
  
  // Wallet authentication
  loginWithWallet(options: WalletLoginOptions): Promise<Session>
  connectWallet(type: WalletType): Promise<string>
}

InventoryModule

Manages player inventory and items.

interface InventoryModule {
  // Item retrieval
  getItems(player: Player): Promise<Item[]>
  getItem(player: Player, predicate: ItemPredicate): Promise<Item | null>
  getItem(player: Player, id: number): Promise<Item | null>
  getEquippedItems(player: Player): Promise<Item[]>
  
  // Item operations
  equipItem(params: EquipParams): Promise<void>
  unequipItem(params: UnequipParams): Promise<void>
  transferItem(params: TransferParams): Promise<void>
  consumeItem(params: ConsumeParams): Promise<void>
  
  // Batch operations
  transferBatch(params: BatchTransferParams): Promise<void>
  equipBatch(params: BatchEquipParams): Promise<void>
  
  // Events
  onItemsChange(player: Player, callback: (items: Item[]) => void): () => void
  onItemEquipped(player: Player, callback: (item: Item) => void): () => void
  onItemConsumed(player: Player, callback: (item: Item, quantity: number) => void): () => void
}

MarketplaceModule

Handles marketplace operations.

interface MarketplaceModule {
  // Listing management
  createListing(params: CreateListingParams): Promise<Listing>
  cancelListing(listingId: string): Promise<void>
  getListings(filter?: ListingFilter): Promise<Listing[]>
  getPlayerListings(player: Player): Promise<Listing[]>
  
  // Trading
  buyListing(listingId: string, quantity?: number): Promise<void>
  makeOffer(params: OfferParams): Promise<Offer>
  acceptOffer(offerId: string): Promise<void>
  rejectOffer(offerId: string): Promise<void>
  getOffers(player: Player): Promise<Offer[]>
  
  // Price data
  getItemPriceHistory(itemId: number): Promise<PricePoint[]>
  getFloorPrice(itemId: number): Promise<bigint>
  getMarketStats(itemId: number): Promise<MarketStats>
  
  // Events
  onListingCreated(callback: (listing: Listing) => void): () => void
  onListingSold(callback: (sale: Sale) => void): () => void
}

CraftingModule

Manages item crafting and recipes.

interface CraftingModule {
  // Recipe management
  getRecipes(): Promise<Recipe[]>
  getRecipe(recipeId: number): Promise<Recipe>
  getAvailableRecipes(player: Player): Promise<Recipe[]>
  
  // Crafting
  craft(player: Player, recipeId: number, quantity?: number): Promise<Item[]>
  getCraftingCost(recipeId: number, quantity?: number): Promise<CraftingCost>
  canCraft(player: Player, recipeId: number, quantity?: number): Promise<boolean>
  
  // Batch crafting
  craftBatch(player: Player, recipes: CraftBatchParams[]): Promise<Item[]>
  
  // Events
  onItemCrafted(callback: (result: CraftResult) => void): () => void
}

GachaModule

Handles loot box and gacha mechanics.

interface GachaModule {
  // Gacha pools
  getPools(): Promise<GachaPool[]>
  getPool(poolId: string): Promise<GachaPool>
  
  // Rolling
  roll(player: Player, poolId: string, count?: number): Promise<GachaResult>
  getRollCost(poolId: string, count?: number): Promise<RollCost>
  getPityStatus(player: Player, poolId: string): Promise<PityStatus>
  
  // History
  getRollHistory(player: Player, poolId?: string): Promise<RollHistory[]>
  getDropRates(poolId: string): Promise<DropRate[]>
  
  // Events
  onRoll(callback: (result: GachaResult) => void): () => void
  onPityTriggered(callback: (pity: PityTrigger) => void): () => void
}

LeaderboardModule

Manages game leaderboards and rankings.

interface LeaderboardModule {
  // Leaderboard access
  getLeaderboards(): Promise<Leaderboard[]>
  getLeaderboard(leaderboardId: string): Promise<LeaderboardData>
  getPlayerRank(player: Player, leaderboardId: string): Promise<RankData>
  
  // Rankings
  getTopPlayers(leaderboardId: string, limit?: number): Promise<LeaderboardEntry[]>
  getNearbyPlayers(player: Player, leaderboardId: string, range?: number): Promise<LeaderboardEntry[]>
  getFriendRankings(player: Player, leaderboardId: string): Promise<LeaderboardEntry[]>
  
  // Score submission
  submitScore(player: Player, leaderboardId: string, score: number): Promise<void>
  
  // Events
  onRankChange(player: Player, callback: (change: RankChange) => void): () => void
  onLeaderboardUpdate(leaderboardId: string, callback: (data: LeaderboardData) => void): () => void
}

SocialModule

Handles social features like friends and guilds.

interface SocialModule {
  // Friends
  getFriends(player: Player): Promise<Friend[]>
  sendFriendRequest(from: Player, to: Player): Promise<void>
  acceptFriendRequest(player: Player, requestId: string): Promise<void>
  removeFriend(player: Player, friendId: string): Promise<void>
  blockPlayer(player: Player, targetId: string): Promise<void>
  
  // Guilds
  createGuild(player: Player, params: CreateGuildParams): Promise<Guild>
  joinGuild(player: Player, guildId: string): Promise<void>
  leaveGuild(player: Player): Promise<void>
  getGuild(guildId: string): Promise<Guild>
  getGuildMembers(guildId: string): Promise<GuildMember[]>
  
  // Messaging
  sendMessage(from: Player, to: Player, message: string): Promise<void>
  getMessages(player: Player): Promise<Message[]>
  
  // Events
  onFriendRequest(player: Player, callback: (request: FriendRequest) => void): () => void
  onMessage(player: Player, callback: (message: Message) => void): () => void
  onGuildInvite(player: Player, callback: (invite: GuildInvite) => void): () => void
}

NPCModule

Manages AI-powered NPCs.

interface NPCModule {
  // NPC interactions
  getNPCs(): Promise<NPC[]>
  getNPC(npcId: string): Promise<NPC>
  talkToNPC(player: Player, npcId: string, message: string): Promise<NPCResponse>
  
  // NPC state
  getNPCRelationship(player: Player, npcId: string): Promise<Relationship>
  getNPCInventory(npcId: string): Promise<Item[]>
  
  // Trading with NPCs
  tradeWithNPC(player: Player, npcId: string, params: NPCTradeParams): Promise<void>
  getNPCShop(npcId: string): Promise<NPCShop>
  
  // Events
  onNPCInteraction(callback: (interaction: NPCInteraction) => void): () => void
  onRelationshipChange(player: Player, callback: (change: RelationshipChange) => void): () => void
}

Types and Interfaces

Configuration

interface VidyaConfig {
  projectId: string
  environment?: 'development' | 'staging' | 'production'
  apiUrl?: string
  wsUrl?: string
  debug?: boolean
}

Authentication Types

interface Session {
  id: string
  player: PlayerInfo
  wallet: string
  expiresAt: Date
  refreshToken: string
}

interface LoginOptions {
  provider: 'google' | 'discord' | 'twitter' | 'wallet'
  redirectUrl?: string
}

interface WalletLoginOptions {
  wallet: WalletType
  message?: string
  signature?: string
}

type WalletType = 'metamask' | 'walletconnect' | 'phantom' | 'coinbase'

Item Types

interface ItemAttribute {
  id: number
  name: string
  value: number | string
  displayValue?: string
}

type ItemPredicate = (item: Item) => boolean

enum CharacterSlot {
  None = 0,
  Head = 1,
  Body = 2,
  Legs = 3,
  Feet = 4,
  Hands = 5,
  Weapon = 6,
  Shield = 7,
  Accessory = 8
}

Marketplace Types

interface Listing {
  id: string
  seller: string
  item: Item
  price: bigint
  quantity: number
  createdAt: Date
  expiresAt?: Date
}

interface ListingFilter {
  itemId?: number
  seller?: string
  minPrice?: bigint
  maxPrice?: bigint
  characterSlot?: CharacterSlot
  attributes?: AttributeFilter[]
}

interface Offer {
  id: string
  buyer: string
  listing: Listing
  price: bigint
  quantity: number
  status: 'pending' | 'accepted' | 'rejected' | 'expired'
  createdAt: Date
}

Crafting Types

interface Recipe {
  id: number
  name: string
  description: string
  requirements: RecipeRequirement[]
  outputs: RecipeOutput[]
  craftingTime?: number
  cooldown?: number
}

interface RecipeRequirement {
  type: 'item' | 'currency'
  id: number
  quantity: number
}

interface RecipeOutput {
  itemId: number
  quantity: number
  chance?: number
}

Gacha Types

interface GachaPool {
  id: string
  name: string
  description: string
  items: GachaItem[]
  cost: Cost
  pitySystem?: PitySystem
}

interface GachaItem {
  itemId: number
  weight: number
  rarity: Rarity
}

interface GachaResult {
  items: Item[]
  animations?: Animation[]
  pityProgress?: number
}

enum Rarity {
  Common = 1,
  Uncommon = 2,
  Rare = 3,
  Epic = 4,
  Legendary = 5
}

Social Types

interface Friend {
  player: PlayerInfo
  status: 'online' | 'offline' | 'away'
  friendsSince: Date
}

interface Guild {
  id: string
  name: string
  description: string
  leader: string
  members: number
  level: number
  experience: number
  perks: GuildPerk[]
}

interface Message {
  id: string
  from: PlayerInfo
  to: PlayerInfo
  content: string
  timestamp: Date
  read: boolean
}

Error Handling

class VidyaError extends Error {
  code: ErrorCode
  details?: any
}

enum ErrorCode {
  // Authentication
  UNAUTHENTICATED = 'UNAUTHENTICATED',
  UNAUTHORIZED = 'UNAUTHORIZED',
  SESSION_EXPIRED = 'SESSION_EXPIRED',
  
  // Validation
  INVALID_PARAMETER = 'INVALID_PARAMETER',
  INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
  ITEM_NOT_FOUND = 'ITEM_NOT_FOUND',
  
  // Operations
  OPERATION_FAILED = 'OPERATION_FAILED',
  TRANSACTION_FAILED = 'TRANSACTION_FAILED',
  RATE_LIMITED = 'RATE_LIMITED',
  
  // Network
  NETWORK_ERROR = 'NETWORK_ERROR',
  TIMEOUT = 'TIMEOUT'
}

React Hooks

// Authentication
function useAuth(): AuthState
function useSession(): Session | null
function usePlayer(): Player | null

// Inventory
function useItems(player: Player): { items: Item[], loading: boolean, error: Error | null }
function useEquippedItems(player: Player): { items: Item[], loading: boolean, error: Error | null }

// Marketplace
function useListings(filter?: ListingFilter): { listings: Listing[], loading: boolean, error: Error | null }
function usePlayerListings(player: Player): { listings: Listing[], loading: boolean, error: Error | null }

// Social
function useFriends(player: Player): { friends: Friend[], loading: boolean, error: Error | null }
function useGuild(guildId: string): { guild: Guild | null, loading: boolean, error: Error | null }

// Real-time
function useRealtimeUpdates(events: string[]): void
function useNotifications(): Notification[]

Utilities

// Currency formatting
function formatCurrency(amount: bigint, decimals?: number): string
function parseCurrency(value: string, decimals?: number): bigint

// Item utilities
function sortItems(items: Item[], sortBy: 'name' | 'rarity' | 'value'): Item[]
function filterItems(items: Item[], filter: ItemFilter): Item[]
function groupItems(items: Item[]): Map<number, Item[]>

// Validation
function isValidWalletAddress(address: string): boolean
function isValidPlayerId(id: string): boolean
function isValidItemId(id: number): boolean