/**
 * Additional settings forwarded to the underlying CustomModule runner.
 */
export interface GameMethodSettings {
  timeout?: number;
  activeTimeout?: boolean;
  persistent?: boolean;
  [key: string]: unknown;
}

export type GameMethodParams = Record<string, unknown>;

/**
 * Allowed ShowAd placement values. The host derives the AdMob ad type
 * (rewarded / interstitial) from this field; banner is reserved for
 * future use and currently rejected by the mobile bridge.
 */
export type ShowAdPlacement = "rewarded" | "interstitial" | "banner";

/**
 * Lifecycle status returned by `gameTegra.showAd`. Mirrors the host's
 * `AdsStatus` enum.
 *
 * - `completed`: rewarded ad watched to completion; `reward` is set.
 * - `closed`: interstitial or rewarded dismissed without reward.
 * - `shown`: ad was shown (no explicit close/complete signal).
 * - `noFill`: AdMob returned no fill.
 * - `cooldownBlocked`: placement still in cooldown window.
 * - `queued`: another ad is already showing; this one was enqueued.
 * - `error`: validation or runtime error; see `errorCode`.
 */
export type ShowAdStatus =
  | "shown"
  | "completed"
  | "closed"
  | "noFill"
  | "cooldownBlocked"
  | "error"
  | "queued";

/**
 * Public params for `gameTegra.showAd`. See BackOffice
 * `docs/ad-revenue-miniapp-ledger-plan.md` §13.2 for the full contract.
 *
 * `adKey` is required and identifies the developer-defined slot inside
 * the miniapp (one of the primary reporting dimensions on BackOffice).
 * `metadata` is schemaless miniapp context that the host serializes into
 * the BFF register call; the host enforces a 4096-character cap on the
 * serialized payload.
 */
export interface ShowAdParams {
  adKey: string;
  placement?: ShowAdPlacement;
  metadata?: Record<string, unknown>;
  /**
   * Whether the host should show its ad-loading overlay.
   * Defaults to false.
   */
  showLoading?: boolean;
}

/**
 * Result returned by `gameTegra.showAd`. The promise resolves with this
 * shape on every terminal status (including `error`); inspect `status`
 * before treating `reward`. `eventId` correlates with the BackOffice ad
 * revenue ledger (set as soon as the ad reaches load).
 */
export interface ShowAdResult {
  status: ShowAdStatus;
  adRequestId: string;
  eventId?: string;
  reward?: number;
  viewDurationSeconds?: number;
  errorCode?: string;
  debugInfo?: Record<string, unknown> | null;
}

export interface SuperAppResponse<TData = unknown> {
  onClientSuccess: boolean;
  onHostSuccess: boolean;
  data: TData;
  errorMessage: string | null;
}

export interface PurchaseParams {
  /**
   * Payment package code configured on the MiniApp version in DevPortal.
   * This is the authoritative payment input forwarded by Engine.
   */
  code: string;
  /**
   * Legacy amount value. Engine keeps it only as metadata for older callers.
   */
  amount?: number;
  currency?: string;
  quantity?: number;
  metadata?: Record<string, unknown>;
  [key: string]: unknown;
}

export interface UserInfo {
  name: string;
  email: string;
  age: number | null;
}

export interface CaptureScreenshotOptions {
  /** Image format requested from the native host. Defaults to `png`. */
  format?: "png" | "jpeg";
  /** Encoding quality from 0 through 1. The host may ignore this for PNG. */
  quality?: number;
}

export interface CaptureScreenshotResult {
  /** Screenshot encoded as a data URL, for example `data:image/png;base64,...`. */
  dataUrl: string;
  mimeType: "image/png" | "image/jpeg";
  width: number;
  height: number;
}

export type ShareGameMomentResult =
  | { status: "published"; postId: string }
  | { status: "cancelled" }
  | { status: "failed"; errorCode: string };

/**
 * Payload shared through the `gameTegraReady` CustomEvent detail.
 */
export interface ReadyDetail {
  ready: boolean;
  superapp: unknown;
  gameTegra: GameTegraSDK;
  /** @deprecated Use gameTegra instead */
  supergame: GameTegraSDK;
}

/** Options for `onReady` listeners. */
export interface ReadyListenerOptions {
  once?: boolean;
  immediate?: boolean;
}

export type ReadyCallback = (detail: ReadyDetail) => void;

export interface StreamOptions {
  [key: string]: unknown;
}

export interface StreamEmitter {
  id: string;
  stream: string;
  on(eventName: string, handler: (payload: unknown) => void): () => void;
  off(eventName: string, handler: (payload: unknown) => void): void;
  stop(payload?: GameMethodParams): void;
  clearListeners(): void;
}

export interface NativeStreamController {
  id: string;
  stream: string;
  on(eventName: string, handler: (payload: unknown) => void): () => void;
  off(eventName: string, handler: (payload: unknown) => void): void;
  push(payload?: GameMethodParams): Promise<void>;
  error?(payload?: GameMethodParams): Promise<void>;
  stop(payload?: GameMethodParams): Promise<void>;
  isActive?(): boolean;
}

export interface BaseStreamParams {
  stream?: string;
  channel?: string;
  name?: string;
  topic?: string;
  options?: StreamOptions;
}

export interface ListenDataParams extends BaseStreamParams { }

export interface SendDataParams extends BaseStreamParams {
  key?: string;
  payload?: GameMethodParams | GameMethodParams[];
  data?: GameMethodParams | GameMethodParams[];
  message?: GameMethodParams;
  messages?: GameMethodParams[];
  autoStop?: boolean;
  reason?: string;
}

/**
 * Tuning knobs for the GameTegra SDK wrapper and its readiness behavior.
 */
export interface GameTegraSDKOptions {
  superapp?: unknown;
  methodMap?: Record<string, string>;
  superappReadyEventName?: string;
  readyEventName?: string;
  globalName?: string;
}

/** @deprecated Use GameTegraSDKOptions instead */
export type SuperGameSDKOptions = GameTegraSDKOptions;

/** Preconfigured mapping between friendly helpers and CustomModule names. */
export declare const DEFAULT_METHOD_MAP: Readonly<Record<string, string>>;
export declare const SUPERAPP_READY_EVENT: string;
export declare const GAMETEGRA_READY_EVENT: string;
/** @deprecated Use GAMETEGRA_READY_EVENT instead */
export declare const SUPERGAME_READY_EVENT: string;

/**
 * High-level helper that wraps the SuperApp JS SDK for common game scenarios.
 */
export declare class GameTegraSDK {
  constructor(options?: GameTegraSDKOptions);

  readonly ready: boolean;
  readonly superapp: unknown;
  methodMap: Record<string, string>;

  getReadyDetail(): ReadyDetail;
  waitUntilReady(): Promise<ReadyDetail>;
  onReady(callback: ReadyCallback, options?: ReadyListenerOptions): () => void;

  /**
   * Calls a mapped custom module method. The call is queued until the SDK is ready.
   */
  callGameMethod<TResult = unknown>(
    methodKeyOrName: string,
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  createRoom<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  joinRoom<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  leaveRoom<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  getScore<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  quickMatch<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  loadData<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  saveData<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  showAd(
    params: ShowAdParams,
    settings?: GameMethodSettings
  ): Promise<ShowAdResult>;

  createLeaderboard<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  getLeaderboard<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  updateLeaderboard<TResult = unknown>(
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  /**
   * Opens a group chat screen for the current match.
   * If `roomName` is provided, the host prefixes it with the miniAppId.
   * If omitted, the host auto-derives it from the active match.
   */
  openMatchChat<TResult = unknown>(
    params?: { roomName?: string } & GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  stopStream(channelKey: string): Promise<void>;

  stopListeningStream(keyOrEmitter: string | StreamEmitter): Promise<void>;

  sendData(
    params?: SendDataParams,
    options?: StreamOptions
  ): Promise<NativeStreamController>;

  listenData(
    params?: ListenDataParams,
    options?: StreamOptions
  ): Promise<StreamEmitter>;

  connectGame(
    streamName: string,
    options?: StreamOptions
  ): Promise<StreamEmitter>;

  custom<TResult = unknown>(
    functionName: string,
    params?: GameMethodParams,
    settings?: GameMethodSettings
  ): Promise<TResult>;

  setMethodMap(map: Record<string, string>): Record<string, string>;
  refresh(superappInstance?: unknown): unknown;

  /** Room chat namespace for joining/managing room-based chat channels. */
  readonly roomChat: RoomChat;

  /** Debug console overlay for in-WebView log inspection. */
  readonly devConsole: DevConsole;

  /** Virtual gamepad / touch controls. */
  readonly controls: Controls;

  // SuperApp Proxy Methods
  requestLocation<TResult = unknown>(): Promise<TResult>;
  readGyroscope(options?: { normalize?: boolean }): Promise<StreamEmitter>;
  readAccelerometer(options?: Record<string, unknown>): Promise<StreamEmitter>;
  vibrate(): Promise<void>;
  startPurchase<TResult = unknown>(params: PurchaseParams): Promise<TResult>;
  /** Backward-compatible alias for startPurchase. */
  pay<TResult = unknown>(params: PurchaseParams): Promise<TResult>;
  openMiniApp<TResult = unknown>(params?: unknown): Promise<TResult>;
  showLoading(): Promise<void>;
  hideLoading(): Promise<void>;
  capturePhoto<TResult = unknown>(): Promise<TResult>;
  pickImage<TResult = unknown>(): Promise<TResult>;
  /** Captures the currently visible MiniApp/MiniGame WebView content. */
  captureScreenshot(
    options?: CaptureScreenshotOptions
  ): Promise<CaptureScreenshotResult>;
  /** Captures the visible game, asks for user confirmation, and publishes a social moment. */
  shareGameMoment(): Promise<ShareGameMomentResult>;
  getParams<TResult = unknown>(): Promise<TResult>;
  getEnv(): Promise<Record<string, string>>;
  getEnv(key: string): Promise<string | undefined>;
  getLanguage<TResult = unknown>(): Promise<TResult>;
  reportEvent<TResult = unknown>(params?: unknown, settings?: unknown): Promise<TResult>;
  requestOrientation<TResult = unknown>(params?: { mode?: 'portrait' | 'landscape' | 'auto' }): Promise<TResult>;
  getUserInfo<TResult = SuperAppResponse<UserInfo>>(): Promise<TResult>;

  /**
   * Completely closes and destroys the current MiniApp session.
   * The app is removed from memory; state is not preserved.
   *
   * @example
   * await gameTegra.close();
   */
  close(): Promise<void>;

  /**
   * Sends the current MiniApp to the background.
   * The session is hidden but kept alive; state is fully preserved.
   * The user can resume the app later without a reload.
   *
   * @example
   * await gameTegra.sendToBackground();
   */
  sendToBackground(): Promise<void>;

  /**
   * Opens the native MiniApp menu overlay.
   * The overlay shows "Re-open MiniApp" (reload) and "Force Close" options,
   * identical to the one triggered by the built-in 3-dot menu button.
   *
   * @example
   * await gameTegra.showMenu();
   */
  showMenu(): Promise<void>;
}

/** @deprecated Use GameTegraSDK instead */
export declare const SuperGameSDK: typeof GameTegraSDK;

export interface RoomChatJoinOptions {
  persistence?: boolean;
  hidden?: boolean;
}

export interface RoomChatHandle {
  roomName: string;
  channelId: string;
  streamKey: string;
  on(eventName: 'message', handler: (msg: unknown) => void): () => void;
  on(eventName: 'presence', handler: (evt: unknown) => void): () => void;
  on(eventName: string, handler: (payload: unknown) => void): () => void;
  off(eventName: string, handler: (payload: unknown) => void): void;
  send(content: Record<string, unknown>): Promise<unknown>;
  getHistory(opts?: { limit?: number; cursor?: string; forward?: boolean }): Promise<unknown>;
  leave(): Promise<void>;
}

export interface RoomChat {
  /**
   * Join a room chat channel.
   * If roomName is omitted, the host auto-derives it from the active match.
   */
  join(roomName?: string, options?: RoomChatJoinOptions): Promise<RoomChatHandle>;
}

export interface DevConsoleShowOptions {
  interceptConsole?: boolean;
}

export interface DevConsole {
  show(opts?: DevConsoleShowOptions): void;
  hide(): void;
  toggle(): void;
  log(msg: string): void;
  warn(msg: string): void;
  error(msg: string): void;
  success(msg: string): void;
  clear(): void;
}

// -- Virtual Gamepad / Touch Controls --

export type ControlEventType = 'press' | 'release' | 'move';

export type JoystickDirection =
  | 'up' | 'down' | 'left' | 'right'
  | 'up_left' | 'up_right' | 'down_left' | 'down_right'
  | 'idle';

export interface ControlEvent {
  code: string;
  type: ControlEventType;
  timestamp: number;
}

export interface JoystickConfig {
  type?: 'analog' | 'dpad';
  size?: number;
  deadZone?: number;
  diagonals?: boolean;
}

export type BuiltinIcon =
  | 'circle' | 'cross' | 'crosshair' | 'arrow_up'
  | 'lightning' | 'stop' | 'shield' | 'sword';

export interface ButtonConfig {
  code: string;
  label?: string;
  icon?: BuiltinIcon | string | null;
}

export interface ControlsConfig {
  target?: string;
  joystick?: boolean | JoystickConfig;
  buttons?: ButtonConfig[] | false;
  opacity?: number;
  theme?: 'dark' | 'light';
}

export interface Controls {
  readonly visible: boolean;
  show(config?: ControlsConfig): void;
  hide(): void;
  destroy(): void;
  on(code: string, handler: (event: ControlEvent) => void): () => void;
  onAny(handler: (event: ControlEvent) => void): () => void;
}

declare global {
  interface HTMLElementTagNameMap {
    'gametegra-joystick': HTMLElement;
    'gametegra-buttons': HTMLElement;
  }
}

/** Instantiates a brand-new, unshared GameTegra SDK wrapper. */
export declare function createGameTegraSDK(
  options?: GameTegraSDKOptions
): GameTegraSDK;

/** @deprecated Use createGameTegraSDK instead */
export declare function createSuperGameSDK(
  options?: GameTegraSDKOptions
): GameTegraSDK;

/** Shared singleton instance that is also attached to `window.gameTegra`. */
export declare const gameTegra: GameTegraSDK;

/** @deprecated Use gameTegra instead */
export declare const supergame: GameTegraSDK;

/** Default export that references the shared singleton instance. */
export default gameTegra;