js-bindings.d.ts

/* auto-generated by NAPI-RS */
/* eslint-disable */
export declare class Application {
  constructor(options?: ApplicationOptions | undefined | null);
  onEvent(handler?: ((arg: ApplicationEvent) => void) | undefined | null): void;
  bind(handler?: ((arg: ApplicationEvent) => void) | undefined | null): void;
  isReady(): boolean;
  exit(): void;
  /** Creates a new WebContext with the given options. */
  createWebContext(options?: WebContextOptions | undefined | null): JsWebContext;
  createTrayIcon(options: TrayIconOptions): JsTrayIcon;
  createBrowserWindow(options?: BrowserWindowOptions | undefined | null): BrowserWindow;
  createChildBrowserWindow(options?: BrowserWindowOptions | undefined | null): BrowserWindow;
  setMenu(menuOptions?: MenuOptions | undefined | null): void;
  /**
   * Pump the tao event loop once without blocking. Returns `true` while
   * the app is alive, `false` when it should stop. Drive this from a JS
   * `setInterval` via the `run()` wrapper in `index.js`.
   */
  pumpEvents(): boolean;
  /**
   * Run Tao's native event loop continuously on the current thread.
   *
   * This blocks JavaScript until the application exits. Use `run()` when the
   * Node.js event loop must remain available.
   */
  runSync(): void;
  /** Run the application event loop. */
  run(options?: ApplicationRunOptions | undefined | null): void;
}

export declare class BrowserWindow {
  _registerProtocol(name: string, handler: (arg: string) => void): void;
  _completeProtocol(id: number, response: CustomProtocolResponse): void;
  createWebview(options?: WebviewOptions | undefined | null, webContext?: JsWebContext | undefined | null): JsWebview;
  _setPendingWebviewEventCallback(handler: (err: Error | null, arg: WebviewEventPayload) => any): void;
  _setPendingWebviewNavigationHandler(handler: (arg: string) => boolean): void;
  _clearPendingWebviewHandlers(): void;
  get isChild(): boolean;
  getNativeHandle(): bigint;
  isFocused(): boolean;
  isVisible(): boolean;
  isDecorated(): boolean;
  isClosable(): boolean;
  isMaximizable(): boolean;
  isMinimizable(): boolean;
  isMaximized(): boolean;
  isMinimized(): boolean;
  isResizable(): boolean;
  setTitle(title: string): void;
  get title(): string;
  setClosable(closable: boolean): void;
  setMaximizable(maximizable: boolean): void;
  setMinimizable(minimizable: boolean): void;
  setResizable(resizable: boolean): void;
  setSize(width: number, height: number, logical?: boolean | undefined | null): Dimensions | null;
  setMinSize(width: number, height: number, logical?: boolean | undefined | null): void;
  getInnerSize(logical?: boolean | undefined | null): Dimensions;
  setMaxSize(width: number, height: number, logical?: boolean | undefined | null): void;
  getOuterSize(logical?: boolean | undefined | null): Dimensions;
  openFileDialog(options?: FileDialogOptions | undefined | null): Array<string>;
  id(): number;
  hasMenu(): boolean;
  dispose(): void;
  isDisposed(): boolean;
  _onWindowEvent(handler?: ((arg: WindowEventPayload) => void) | undefined | null): void;
  get theme(): Theme;
  setTheme(theme: Theme): void;
  setWindowIcon(
    icon: Uint8Array | Array<number>,
    width?: number | undefined | null,
    height?: number | undefined | null,
  ): void;
  removeWindowIcon(): void;
  setEnable(enabled: boolean): void;
  setTaskbarIcon(
    icon: Uint8Array | Array<number>,
    width?: number | undefined | null,
    height?: number | undefined | null,
  ): void;
  removeTaskbarIcon(): void;
  setUndecoratedShadow(shadow: boolean): void;
  getNativeHandleAnyThread(): bigint;
  simpleFullscreen(): boolean;
  setSimpleFullscreen(fullscreen: boolean): boolean;
  hasShadow(): boolean;
  setHasShadow(value: boolean): void;
  setTabbingIdentifier(identifier: string): void;
  tabbingIdentifier(): string;
  isDocumentEdited(): boolean;
  setDocumentEdited(edited: boolean): void;
  getWaylandSurface(): bigint;
  setIosScaleFactor(value: number): void;
  setValidOrientations(value: IosValidOrientations): void;
  setPrefersHomeIndicatorHidden(value: boolean): void;
  setPreferredScreenEdgesDeferringSystemGestures(edges: number): void;
  setPrefersStatusBarHidden(value: boolean): void;
  androidContentRect(): AndroidContentRect;
  androidConfig(): string;
  setVisible(visible: boolean): void;
  setProgressBar(state: JsProgressBar): void;
  setMaximized(value: boolean): void;
  setMinimized(value: boolean): void;
  focus(): void;
  getAvailableMonitors(): Array<Monitor>;
  getCurrentMonitor(): Monitor | null;
  getPrimaryMonitor(): Monitor | null;
  getMonitorFromPoint(x: number, y: number): Monitor | null;
  setContentProtection(enabled: boolean): void;
  setAlwaysOnTop(enabled: boolean): void;
  setAlwaysOnBottom(enabled: boolean): void;
  setDecorations(enabled: boolean): void;
  get fullscreen(): FullscreenType | null;
  setFullscreen(fullscreenType?: FullscreenType | undefined | null): void;
  close(): void;
  hide(): void;
  show(): void;
  setPosition(x: number, y: number, logical?: boolean | undefined | null): void;
  getPosition(logical?: boolean | undefined | null): Position;
  center(): void;
  get width(): number;
  get height(): number;
  get x(): number;
  get y(): number;
  scaleFactor(): number;
  setCursor(cursor: CursorType): void;
  setCursorVisible(visible: boolean): void;
  setCursorPosition(x: number, y: number): void;
  setIgnoreCursorEvents(ignore: boolean): void;
  setSkipTaskbar(skip: boolean): void;
  requestRedraw(): void;
}

export declare class NativeNotification {
  constructor(options: NativeNotificationOptions, callback: (err: Error | null, arg: NotificationEventPayload) => any);
  close(): void;
}
export type JsNotification = NativeNotification;

export declare class TrayIcon {
  constructor();
  get id(): string;
  _onTrayEvent(handler?: ((arg: TrayEventPayload) => void) | undefined | null): void;
  setIcon(
    icon: Uint8Array | Array<number>,
    width?: number | undefined | null,
    height?: number | undefined | null,
  ): void;
  removeIcon(): void;
  setMenu(menu?: MenuOptions | undefined | null): void;
  setTooltip(tooltip?: string | undefined | null): void;
  setTitle(title?: string | undefined | null): void;
  setVisible(visible: boolean): void;
  setIconAsTemplate(value: boolean): void;
  setShowMenuOnLeftClick(value: boolean): void;
  setShowMenuOnRightClick(value: boolean): void;
  showMenu(): void;
  rect(): TrayRect | null;
  dispose(): void;
  isDisposed(): boolean;
}
export type JsTrayIcon = TrayIcon;

export declare class WebContext {
  /** Not supported. Use `app.createWebContext(options)` instead. */
  constructor();
  /** A reference to the data directory the context was created with. */
  get dataDirectory(): string | null;
  /** Check if a custom protocol has been registered on this context. */
  isCustomProtocolRegistered(scheme: string): boolean;
  /**
   * Set if this context allows automation.
   * Note: this is currently only enforced on Linux, and has the stipulation that only 1 context allows automation at a time.
   */
  setAllowsAutomation(flag: boolean): void;
  dispose(): void;
  isDisposed(): boolean;
}
export type JsWebContext = WebContext;

export declare class Webview {
  constructor();
  onIpcMessage(handler?: ((arg: IpcMessage) => void) | undefined | null): void;
  dispose(): void;
  isDisposed(): boolean;
  /**
   * Low-level method used by the JS `expose()` wrapper.
   *
   * Injects a page script that creates `window[name]` as an object with:
   * - static values from `statics_json` (a JSON object string)
   * - async function stubs for each name in `func_names`
   *
   * When the page calls one of the stubs the call is routed back here via
   * the internal IPC channel and dispatched to `handler`.  `handler` is
   * responsible for calling `evaluateScript` to send the response.
   */
  _exposeInternal(
    name: string,
    staticsJson: string,
    funcNames: Array<string>,
    handler: (arg: ExposeCallData) => void,
  ): void;
  print(): void;
  zoom(scaleFactor: number): void;
  setWebviewVisibility(visible: boolean): void;
  isDevtoolsOpen(): boolean;
  openDevtools(): void;
  closeDevtools(): void;
  loadUrl(url: string): void;
  loadHtml(html: string): void;
  evaluateScript(js: string): void;
  evaluateScriptWithCallback(js: string, callback: (err: Error | null, arg: string) => any): void;
  reload(): void;
  /** The URL the webview is currently showing. */
  url(): string | null;
  /** Webview width in logical pixels (same coordinate space as `set_bounds`). */
  get width(): number | null;
  /** Webview height in logical pixels (same coordinate space as `set_bounds`). */
  get height(): number | null;
  /** Webview x offset from the window's top-left corner, in logical pixels. */
  get x(): number | null;
  /** Webview y offset from the window's top-left corner, in logical pixels. */
  get y(): number | null;
  /** Load `url` with additional HTTP request headers. */
  loadUrlWithHeaders(url: string, headers: Array<HeaderData>): void;
  /**
   * Return all cookies currently stored for `url`, or every cookie if `url`
   * is `null` / `undefined`.
   */
  getCookies(url?: string | undefined | null): Array<WebviewCookie>;
  /** Store a cookie in the webview's session. */
  setCookie(cookie: WebviewCookie): void;
  /**
   * Delete a cookie by name.  `domain` and `path` narrow the match;
   * omit them to delete across all domains/paths.
   */
  deleteCookie(name: string, domain?: string | undefined | null, path?: string | undefined | null): void;
  /** Erase all cookies, cache, local storage, and IndexedDB data. */
  clearAllBrowsingData(): void;
  /**
   * Set the background colour shown before (or behind) page content.
   * Values are 0-255.
   */
  setBackgroundColor(r: number, g: number, b: number, a: number): void;
  /**
   * Return the webview's current bounds relative to the window, in logical
   * pixels.
   */
  getBounds(): WebviewBounds | null;
  /** Reposition and resize the webview within its window. */
  setBounds(bounds: WebviewBounds): void;
  /** Give keyboard focus to the webview content area. */
  focus(): void;
  /** Return focus to the parent/host window. */
  focusParent(): void;
}
export type JsWebview = Webview;

export interface AndroidContentRect {
  left: number;
  top: number;
  right: number;
  bottom: number;
}

export interface ApplicationEvent {
  event: WebviewApplicationEvent;
  customMenuEvent?: CustomMenuEvent;
}

export interface ApplicationOptions {
  controlFlow?: ControlFlow;
  waitTime?: number;
  exitCode?: number;
}

export interface ApplicationRunOptions {
  /** The interval in milliseconds to pump events. Defaults to 16 (60 FPS).  */
  interval?: number;
  /** Whether to keep the event loop alive. Defaults to true.  */
  ref?: boolean;
}

/** Converting `{protocol}://localhost/abc` to `{http_or_https}://{protocol}.localhost/abc` */
export declare function applyUriWorkAround(uri: string, httpOrHttps: string, protocol: string): string;

export interface BrowserWindowOptions {
  menu?: MenuOptions;
  showMenu?: boolean;
  resizable?: boolean;
  title?: string;
  logical?: boolean;
  width?: number;
  height?: number;
  x?: number;
  y?: number;
  contentProtection?: boolean;
  alwaysOnTop?: boolean;
  alwaysOnBottom?: boolean;
  visible?: boolean;
  decorations?: boolean;
  visibleOnAllWorkspaces?: boolean;
  maximized?: boolean;
  maximizable?: boolean;
  minimizable?: boolean;
  focused?: boolean;
  transparent?: boolean;
  fullscreen?: FullscreenType;
  windowsOwnerWindow?: bigint;
  windowsTaskbarIcon?: TrayIconImage;
  windowsNoRedirectionBitmap?: boolean;
  windowsDragAndDrop?: boolean;
  windowsSkipTaskbar?: boolean;
  windowsClassName?: string;
  windowsUndecoratedShadow?: boolean;
  macosMovableByWindowBackground?: boolean;
  macosTitlebarTransparent?: boolean;
  macosTitleHidden?: boolean;
  macosTitlebarHidden?: boolean;
  macosTitlebarButtonsHidden?: boolean;
  macosFullsizeContentView?: boolean;
  macosDisallowHidpi?: boolean;
  macosHasShadow?: boolean;
  macosTabbingIdentifier?: string;
  iosScaleFactor?: number;
  iosValidOrientations?: IosValidOrientations;
  iosPrefersHomeIndicatorHidden?: boolean;
  iosDeferredSystemGestureEdges?: number;
  iosPrefersStatusBarHidden?: boolean;
}

/** Kept for backward compat; no longer used internally. */
export declare enum ControlFlow {
  Poll = 0,
  Wait = 1,
  WaitUntil = 2,
  Exit = 3,
  ExitWithCode = 4,
}

/** Cursor shape passed to [`BrowserWindow::set_cursor`]. */
export declare enum CursorType {
  Default = 0,
  Crosshair = 1,
  Hand = 2,
  Arrow = 3,
  Move = 4,
  Text = 5,
  Wait = 6,
  Help = 7,
  Progress = 8,
  NotAllowed = 9,
  ContextMenu = 10,
  Cell = 11,
  VerticalText = 12,
  Alias = 13,
  Copy = 14,
  NoDrop = 15,
  Grab = 16,
  Grabbing = 17,
  ZoomIn = 18,
  ZoomOut = 19,
  ResizeEast = 20,
  ResizeNorth = 21,
  ResizeNorthEast = 22,
  ResizeNorthWest = 23,
  ResizeSouth = 24,
  ResizeSouthEast = 25,
  ResizeSouthWest = 26,
  ResizeWest = 27,
  ResizeEastWest = 28,
  ResizeNorthSouth = 29,
  ResizeNorthEastSouthWest = 30,
  ResizeNorthWestSouthEast = 31,
  ResizeColumn = 32,
  ResizeRow = 33,
  AllScroll = 34,
}

export interface CustomMenuEvent {
  id: string;
  windowId: number;
}

/** Incoming request delivered to a custom-protocol handler. */
export interface CustomProtocolRequest {
  url: string;
  method: string;
  headers: Array<HeaderData>;
  body?: Buffer;
}

/** Response returned by a custom-protocol handler. */
export interface CustomProtocolResponse {
  /** HTTP status code.  Defaults to 200. */
  statusCode?: number;
  /** Extra response headers (e.g. `[{ key: "Cache-Control", value: "no-store" }]`). */
  headers?: Array<HeaderData>;
  /** Response body bytes. */
  body: Buffer;
  /** MIME type (e.g. `"text/html"`, `"application/javascript"`). */
  mimeType?: string;
}

export interface Dimensions {
  width: number;
  height: number;
}

/** Data sent to the expose handler when the page calls a proxied function. */
export interface ExposeCallData {
  ns: string;
  method: string;
  id: number;
  argsJson: string;
}

export interface FileDialogOptions {
  multiple?: boolean;
  title?: string;
  defaultPath?: string;
  filters?: Array<FileFilter>;
}

export interface FileFilter {
  name: string;
  extensions: Array<string>;
}

export declare enum FullscreenType {
  Exclusive = 0,
  Borderless = 1,
}

export declare function getWebviewVersion(): string;

export interface HeaderData {
  key: string;
  value?: string;
}

export declare enum IosValidOrientations {
  LandscapeAndPortrait = 0,
  Landscape = 1,
  Portrait = 2,
}

export interface IpcMessage {
  body: Buffer;
  method: string;
  headers: Array<HeaderData>;
  uri: string;
}

/** If the URI is a work around URI for this protocol which starts with `{http_or_https}://{protocol}.` */
export declare function isWorkAroundUri(uri: string, httpOrHttps: string, protocol: string): boolean;

export interface JsProgressBar {
  state?: ProgressBarState;
  progress?: number;
}

export interface MenuItemOptions {
  id?: string;
  label?: string;
  enabled?: boolean;
  accelerator?: string;
  submenu?: MenuOptions;
  role?: string;
}

export interface MenuOptions {
  items: Array<MenuItemOptions>;
}

export interface Monitor {
  name?: string;
  scaleFactor: number;
  size: Dimensions;
  position: Position;
  videoModes: Array<VideoMode>;
}

export interface NativeNotificationAction {
  action: string;
  title: string;
  icon?: string;
}

export interface NativeNotificationOptions {
  title: string;
  body?: string;
  icon?: string;
  imagePath?: string;
  imageData?: Buffer;
  requireInteraction?: boolean;
  persistent: boolean;
  actions: Array<NativeNotificationAction>;
}

export interface NotificationEventPayload {
  event: string;
  action?: string;
  error?: string;
}

/** Returns `{protocol}://` */
export declare function originalUriPrefix(protocol: string): string;

export interface Position {
  x: number;
  y: number;
}

export declare enum ProgressBarState {
  None = 0,
  Normal = 1,
  Indeterminate = 2,
  Paused = 3,
  Error = 4,
}

/** Converting `{http_or_https}://{protocol}.localhost/abc` back to `{protocol}://localhost/abc` */
export declare function revertUriWorkAround(uri: string, httpOrHttps: string, protocol: string): string;

export declare enum Theme {
  Light = 0,
  Dark = 1,
  System = 2,
}

export interface TrayEventPayload {
  event: string;
  id: string;
  x: number;
  y: number;
  rect: TrayRect;
  button?: string;
  buttonState?: string;
}

export interface TrayIconImage {
  data: Buffer;
  width?: number;
  height?: number;
}

export interface TrayIconOptions {
  id?: string;
  icon?: TrayIconImage;
  tooltip?: string;
  title?: string;
  menu?: MenuOptions;
  iconIsTemplate?: boolean;
  menuOnLeftClick?: boolean;
  menuOnRightClick?: boolean;
}

export interface TrayRect {
  x: number;
  y: number;
  width: number;
  height: number;
}

/** The current version of the `@webviewjs/webview` package */
export const VERSION: string;

export interface VideoMode {
  size: Dimensions;
  bitDepth: number;
  refreshRate: number;
}

export interface WebContextOptions {
  /**
   * Whether the WebView window should have a custom user data path.
   * This is useful in Windows when a bundled application can’t have the webview data inside Program Files.
   */
  dataDirectory?: string;
  /**
   * Whether the WebView window should allow automation (e.g. for testing).
   * Note: this is currently only enforced on Linux, and has the stipulation that only 1 context allows automation at a time.
   */
  allowsAutomation?: boolean;
}

export declare enum WebviewApplicationEvent {
  WindowCloseRequested = 0,
  ApplicationCloseRequested = 1,
  CustomMenuClick = 2,
  Ready = 3,
}

export interface WebviewBounds {
  x: number;
  y: number;
  width: number;
  height: number;
}

export interface WebviewCookie {
  name: string;
  value: string;
  domain?: string;
  path?: string;
  httpOnly?: boolean;
  secure?: boolean;
  /** `"strict"`, `"lax"`, or `"none"`. */
  sameSite?: string;
}

/** Payload delivered to the webview event dispatch callback. */
export interface WebviewEventPayload {
  event: WebviewEventType;
  /** URL associated with the event (navigation, page load, download). */
  url?: string;
  /** Document title for `TitleChanged` events. */
  title?: string;
  /** Download success flag for `DownloadCompleted` events. */
  success?: boolean;
}

/** Event types fired by a Webview and surfaced as EventEmitter events in JS. */
export declare enum WebviewEventType {
  PageLoadStarted = 0,
  PageLoadFinished = 1,
  TitleChanged = 2,
  DownloadStarted = 3,
  DownloadCompleted = 4,
  NavigationStarted = 5,
  /**
   * Fired when a page attempts to open a new browser window
   * (`window.open`, `target="_blank"`, etc.).
   */
  NewWindowRequested = 6,
}

export interface WebviewOptions {
  url?: string;
  html?: string;
  width?: number;
  height?: number;
  x?: number;
  y?: number;
  enableDevtools?: boolean;
  incognito?: boolean;
  userAgent?: string;
  child?: boolean;
  preload?: string;
  transparent?: boolean;
  theme?: Theme;
  hotkeysZoom?: boolean;
  clipboard?: boolean;
  autoplay?: boolean;
  backForwardNavigationGestures?: boolean;
  /** Custom name for the IPC global injected by wry (default: `"ipc"`). */
  ipcName?: string;
  /** Whether to automatically normalize URL passed to `loadUrl` or `loadUrlWithHeaders` on windows (default: true). */
  autoNormalizeLoadUrl?: boolean;
  /**
   * Determines whether the custom protocols should use `https://<scheme>.path/to/page` instead of the default `http://<scheme>.path/to/page`.
   * Using a http scheme will allow mixed content when trying to fetch http endpoints and is therefore less secure but will match the behavior
   * of the `<scheme>://path/to/page` protocols used on macOS and Linux.
   */
  useHttpsScheme?: boolean;
}

export declare enum WindowCommand {
  Close = 0,
  Show = 1,
  Hide = 2,
}

export interface WindowEventPayload {
  event: WindowEventType;
  /** Physical x position (cursor or window). */
  x?: number;
  /** Physical y position (cursor or window). */
  y?: number;
  /** Physical width (resize event). */
  width?: number;
  /** Physical height (resize event). */
  height?: number;
  /** Mouse button index: 0=left, 1=middle, 2=right. */
  button?: number;
  /** Horizontal scroll delta (pixels). */
  deltaX?: number;
  /** Vertical scroll delta (pixels). */
  deltaY?: number;
  /** Logical key name (DOM KeyboardEvent.key, e.g. "a", "Enter", "ArrowLeft"). */
  key?: string;
  /** Physical key code (DOM KeyboardEvent.code, e.g. "KeyA", "ArrowLeft"). */
  code?: string;
  /** Modifier bitmask: 1=Shift, 2=Ctrl, 4=Alt, 8=Meta/Super/Command. */
  modifiers?: number;
  /** Whether this key event is a repeat from holding the key down. */
  isRepeat?: boolean;
  /** File paths for FileDrop / FileHover events. */
  files?: Array<string>;
  /** DPI scale factor for ScaleFactorChanged events. */
  scaleFactor?: number;
  /**
   * Text for Ime events (preedit string or committed text);
   * "light" or "dark" for ThemeChanged events.
   */
  text?: string;
  /** Touch point identifier (cast from u64) for Touch events. */
  touchId?: number;
  /**
   * Phase string: "started"/"moved"/"ended"/"cancelled" for Touch;
   * "enabled"/"preedit"/"commit"/"disabled" for Ime events.
   */
  phase?: string;
}

export declare enum WindowEventType {
  Moved = 0,
  Resized = 1,
  CloseRequested = 2,
  Focused = 3,
  Blurred = 4,
  MouseEnter = 5,
  MouseLeave = 6,
  MouseMove = 7,
  MouseDown = 8,
  MouseUp = 9,
  Scroll = 10,
  KeyDown = 11,
  KeyUp = 12,
  FileDrop = 13,
  FileHover = 14,
  FileHoverCancelled = 15,
  ScaleFactorChanged = 16,
  ThemeChanged = 17,
  Ime = 18,
  Touch = 19,
}

/** Returns `{http_or_https}://{protocol}.` */
export declare function workAroundUriPrefix(httpOrHttps: string, protocol: string): string;