@chiraitori/hoyolab-core/index.d.ts

Core utilities for HoYoLab automation - daily check-ins and code redemption with smart rate limiting

// Type definitions for hoyolab-core

export interface HoyoLabClientOptions {
  cookie: string;
  userAgent?: string;
}

export interface CheckInResult {
  success: boolean;
  alreadyCheckedIn: boolean;
  totalSignDays: number;
  award?: {
    name: string;
    count: number;
    icon: string;
  };
  account: {
    uid: string;
    nickname: string;
    region: string;
  };
}

export interface RedeemResult {
  success: boolean;
  code: string;
  account: {
    uid: string;
    nickname: string;
    region: string;
  };
}

export interface BulkRedeemResult {
  code: string;
  success: boolean;
  account?: {
    uid: string;
    nickname: string;
    region: string;
  };
  error?: string;
  errorCode?: string;
}

export interface CodeInfo {
  code: string;
  rewards: string[];
  source: string;
}

export interface FetchCodesOptions {
  source?: string;
}

export interface RedeemMultipleOptions {
  delay?: number;
  stopOnError?: boolean;
}

export interface AccountInfo {
  uid: string;
  nickname: string;
  region: string;
  level?: number;
  game: string;
}

export class HoyoLabError extends Error {
  code: string;
  details: any;
  
  constructor(message: string, code: string, details?: any);
}

export class HoyoLabClient {
  constructor(options: HoyoLabClientOptions);
  
  dailyCheckIn(game: string, uid?: string): Promise<CheckInResult>;
  redeemCode(game: string, code: string, uid?: string): Promise<RedeemResult>;
  fetchAvailableCodes(game: string, options?: FetchCodesOptions): Promise<CodeInfo[]>;
  redeemMultipleCodes(game: string, codes: string[], uid?: string, options?: RedeemMultipleOptions): Promise<BulkRedeemResult[]>;
  redeemCodeOnly(game: string, code: string, uid?: string): Promise<RedeemResult>;
  getAccounts(game?: string): Promise<AccountInfo[]>;
}

export const Games: {
  readonly GENSHIN_IMPACT: 'genshin';
  readonly HONKAI_STAR_RAIL: 'starrail';
  readonly ZENLESS_ZONE_ZERO: 'zenless';
};

export const Regions: {
  readonly NORTH_AMERICA: 'NA';
  readonly EUROPE: 'EU';
  readonly ASIA: 'SEA';
  readonly TAIWAN_HK_MO: 'TW/HK/MO';
};

export const ErrorCodes: {
  readonly INVALID_COOKIE: 'INVALID_COOKIE';
  readonly ALREADY_CHECKED_IN: 'ALREADY_CHECKED_IN';
  readonly INVALID_CODE: 'INVALID_CODE';
  readonly CODE_EXPIRED: 'CODE_EXPIRED';
  readonly CODE_ALREADY_USED: 'CODE_ALREADY_USED';
  readonly RATE_LIMITED: 'RATE_LIMITED';
  readonly NETWORK_ERROR: 'NETWORK_ERROR';
  readonly API_ERROR: 'API_ERROR';
  readonly INVALID_UID: 'INVALID_UID';
  readonly ACCOUNT_NOT_FOUND: 'ACCOUNT_NOT_FOUND';
};

export function getRegionName(game: string, regionCode: string): string;

export interface CookieValidation {
  valid: boolean;
  error?: string;
  hasRedeemTokens?: boolean;
  tokens?: Record<string, string>;
}

export interface RetryOptions {
  maxRetries?: number;
  baseDelay?: number;
  maxDelay?: number;
}

export class RateLimiter {
  constructor(maxCalls?: number, windowMs?: number);
  waitIfNeeded(): Promise<void>;
}

export class SimpleCache {
  constructor(ttlMs?: number);
  set(key: string, value: any): void;
  get(key: string): any | null;
  clear(): void;
}

export const utils: {
  sleep(ms: number): Promise<void>;
  retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
  validateCookie(cookie: string): CookieValidation;
  formatCheckInResult(result: CheckInResult): string;
  formatRedeemResult(result: RedeemResult): string;
  getTimezoneOffset(region: string): number;
  isNewDay(region: string, lastCheck?: Date): boolean;
  RateLimiter: typeof RateLimiter;
  SimpleCache: typeof SimpleCache;
};

declare const _default: {
  HoyoLabClient: typeof HoyoLabClient;
  Games: typeof Games;
  Regions: typeof Regions;
  getRegionName: typeof getRegionName;
  ErrorCodes: typeof ErrorCodes;
  HoyoLabError: typeof HoyoLabError;
  utils: typeof utils;
};

export default _default;