Configuration

/**
 * The widget's public configuration, in the shape an integrator writes.
 *
 * Modelled on the LI.FI widget: one object, drop it on `<MavnaWidget>`, and the
 * widget quotes, routes and (by default) manages wallets itself. Every field maps
 * to a real capability of the engine or the flow underneath, so nothing here
 * promises something the code cannot honour.
 *
 * Kept JSON-serialisable except the event and wallet hooks, so a future iframe
 * build can pass the rest of the config over postMessage without a rewrite.
 */
export type Variant = "compact" | "wide" | "drawer";

export type Appearance = "light" | "dark" | "system";

/** UI the integrator can remove. Each maps to a real control in the flow. */
export type HiddenUIElement =
  | "activity"
  | "settings"
  | "networkToggle"
  | "railToggles"
  | "poweredBy";

/** UI the integrator can lock. `destination` fixes the recipient to `toAddress`. */
export type RequiredUIElement = "destination";

/**
 * What the widget reports back to the host. Every event is backed by a real signal
 * in the flow: a completed quote, a route the user picked, a wallet that connected,
 * a transfer moving through its steps, or one that finished or failed.
 */
export type MavnaWidgetEvent =
  | { readonly type: "routesAvailable"; readonly count: number; readonly declined: number }
  | { readonly type: "routeSelected"; readonly source: string; readonly receives: number }
  | {
      readonly type: "walletConnected";
      readonly ecosystem: "evm" | "stellar";
      readonly address: string;
    }
  | { readonly type: "transferStarted" }
  | { readonly type: "transferStepUpdated"; readonly id: string; readonly phase: string }
  | { readonly type: "transferCompleted" }
  | { readonly type: "transferFailed"; readonly reason: string }
  /**
   * The transfer is on its way and the widget stopped watching it: it outlived
   * the widget's patience, or the widget went away. Not a failure; the money is
   * in flight and can be checked on or finished from Activity.
   */
  | { readonly type: "transferStillMoving"; readonly reason: string }
  /**
   * A conversion on arrival could not meet the minimum, so what was sent
   * arrived as it came: not a success, but the money is in the account.
   */
  | {
      readonly type: "transferDeliveredAsCame";
      readonly reason: string;
      readonly asset: string;
      readonly baseUnits: string;
    }
  /**
   * The rail says the transfer executed on Stellar but can no longer prove what
   * arrived. It has ended: not a failure, and not still moving. The Stellar
   * transaction is given for checking it.
   */
  | {
      readonly type: "transferDeliveredUnverified";
      readonly reason: string;
      /** The Stellar transaction the rail reported. */
      readonly stellarTxHash: string;
      readonly explorerUrl: string;
    };

/**
 * Opt out of the widget's own wallet management. Provide an already-connected EVM
 * `Connection` and/or a Stellar signer, and the widget uses them instead of
 * discovering wallets itself; `onConnect` replaces the built-in connect UI with
 * the host's own.
 */
export interface WalletConfig {
  readonly onConnect?: () => void;
  readonly evm?: Connection;
  readonly stellar?: StellarWalletApi;
}

/** Colour and type overrides, applied as CSS custom properties on the root. */
export interface WidgetTheme {
  readonly tokens?: Readonly<Record<string, string>>;
  readonly font?: string;
  readonly fontMono?: string;
  readonly radius?: string;
  readonly radiusLg?: string;
}

export interface MavnaWidgetConfig {
  /** Required. Identifies the integrator, and attributes an integrator fee. */
  readonly integrator: string;
  /**
   * The network the widget starts on. Default testnet. Mainnet's default node
   * is a public third-party one; set `rpcUrl` to your own provider.
   */
  readonly network?: NetworkId;
  /**
   * The networks the network toggle switches between, `network` among them.
   * Default only `network`. Every network besides `network` needs its own
   * `sponsorUrl` in `endpoints`, since a sponsor serves one network.
   */
  readonly networks?: readonly NetworkId[];
  /**
   * Endpoints per network. For `network` itself, `rpcUrl` and `sponsorUrl`
   * below work too; a value here wins.
   */
  readonly endpoints?: Partial<Record<NetworkId, NetworkEndpoints>>;
  readonly variant?: Variant;
  readonly appearance?: Appearance;
  readonly theme?: WidgetTheme;
  /** Stellar RPC endpoint. EVM reads go through the connected wallet, never here. */
  readonly rpcUrl?: string;
  /** A sponsor the integrator runs; defaults to Mavna's local dev sponsor. */
  readonly sponsorUrl?: string;
  /**
   * The Mavna Arrival Contract on `network`, which lets USDT0 routes convert on
   * arrival with one signature. Defaults to the deployed one (testnet only); a
   * network without one says so on its LayerZero routes. Other networks set
   * theirs in `endpoints`.
   */
  readonly arrivalContract?: string;
  /**
   * How routes are ranked when several arrive, and the flow's initial priority.
   * The two the flow exposes: most received, or fastest.
   */
  readonly routePriority?: "best-received" | "fastest";
  /**
   * An integrator fee, taken from what the user receives. bps is an integer in
   * [0, 1000]; recipient and recipientName are both required when set.
   */
  readonly fee?: IntegratorFeeConfig;
  /** Rails an operator has taken out of rotation (`parseDisabledSources` format). */
  readonly disabledSources?: string;

  // ---- form initialisation ----
  /** The chain the form starts on, by its Mavna slug (e.g. "ethereum"). */
  readonly fromChain?: string;
  /**
   * What the recipient arrives holding: USDC or XLM when sending USDC, and
   * USDT0, USDC or XLM when sending USDT0 (anything but USDT0 is converted).
   */
  readonly wanted?: Wanted;
  /** What the form starts out sending. Defaults to USDC. */
  readonly fromAsset?: SendAsset;
  /** The amount the form starts with. */
  readonly fromAmount?: string;
  /** The recipient's Stellar address, pre-filled (locked with requiredUI). */
  readonly toAddress?: string;

  // ---- narrowing what the widget offers ----
  /** Chains the picker offers, filtered over the network's real chain list. */
  readonly chains?: { readonly allow?: readonly string[]; readonly deny?: readonly string[] };
  /** The rails to race and toggle. Defaults to all four. */
  readonly rails?: readonly RailName[];
  readonly hiddenUI?: readonly HiddenUIElement[];
  readonly requiredUI?: readonly RequiredUIElement[];

  // ---- integration ----
  /** Links for the header overflow ("...") menu. Empty or absent hides the menu.
      The integrator's own destinations (its site, docs, socials), kept as plain
      data so the config stays serialisable. */
  readonly menuLinks?: readonly MavnaMenuLink[];
  /** Namespaces this widget's local transfer history, so two integrators on one
      origin do not share it. */
  readonly keyPrefix?: string;
  readonly walletConfig?: WalletConfig;
  readonly onEvent?: (event: MavnaWidgetEvent) => void;
}