nothing-browser 0.0.21 → 0.1.0

package/piggy/iframe/index.ts

@@ -0,0 +1,79 @@
+// piggy/iframe/index.ts
+import { PiggyClient } from "../client";
+
+// ─── Descriptor types ─────────────────────────────────────────────────────────
+
+export interface IframeDescriptor {
+  index: number;
+  src:   string;
+  id:    string;
+  name:  string;
+}
+
+// ─── Option types ─────────────────────────────────────────────────────────────
+
+/** Target an iframe by its index or src. One must be provided. */
+export type IframeTarget =
+  | { index: number; src?: never }
+  | { src: string;  index?: never };
+
+export type IframeEvaluateOptions = IframeTarget & { js: string };
+export type IframeClickOptions    = IframeTarget & { sel: string };
+export type IframeTypeOptions     = IframeTarget & { sel: string; text: string };
+export type IframeTextOptions     = IframeTarget & { sel: string };
+export type IframeHtmlOptions     = IframeTarget;
+export type IframeWaitSelOptions  = IframeTarget & { sel: string; timeout?: number };
+
+// ─── IframeClient ─────────────────────────────────────────────────────────────
+
+export class IframeClient {
+  constructor(private client: PiggyClient) {}
+
+  /** List all iframes on the page: index, src, id, name. */
+  list(tabId = "default"): Promise<IframeDescriptor[]> {
+    return this.client.send("iframe.list", { tabId });
+  }
+
+  /** Run arbitrary JS inside the targeted iframe. Returns whatever the script returns. */
+  evaluate(opts: IframeEvaluateOptions, tabId = "default"): Promise<unknown> {
+    return this.client.send("iframe.evaluate", { ...opts, tabId });
+  }
+
+  /** Click a selector inside the targeted iframe. */
+  click(opts: IframeClickOptions, tabId = "default"): Promise<boolean> {
+    return this.client.send("iframe.click", { ...opts, tabId });
+  }
+
+  /** Type text into a selector inside the targeted iframe. */
+  type(opts: IframeTypeOptions, tabId = "default"): Promise<boolean> {
+    return this.client.send("iframe.type", { ...opts, tabId });
+  }
+
+  /** Get innerText of a selector inside the targeted iframe. */
+  text(opts: IframeTextOptions, tabId = "default"): Promise<string> {
+    return this.client.send("iframe.text", { ...opts, tabId });
+  }
+
+  /** Get the full HTML of the targeted iframe. */
+  html(opts: IframeHtmlOptions, tabId = "default"): Promise<string> {
+    return this.client.send("iframe.html", { ...opts, tabId });
+  }
+
+  /** Wait until a selector appears inside the targeted iframe. */
+  waitSel(opts: IframeWaitSelOptions, tabId = "default"): Promise<boolean> {
+    return this.client.send("iframe.waitSel", { ...opts, tabId });
+  }
+}
+
+// ─── Factory helper ───────────────────────────────────────────────────────────
+
+export function createIframeAPI(client: PiggyClient): IframeClient {
+  return new IframeClient(client);
+}
+// Done. One thing worth noting — `IframeTarget` is a discriminated union so TypeScript enforces you pass either `index` or `src`, never both. Usage looks like:
+
+// ```js
+// piggy.google.iframe.list()
+// piggy.google.iframe.click({ index: 0, sel: "#btn" })
+// piggy.google.iframe.evaluate({ src: "https://...", js: "document.title" })
+// ```

package/piggy/interactions/index.ts

@@ -0,0 +1,79 @@
+// piggy/interactions/index.ts
+import { PiggyClient } from "../client";
+
+export interface MousePosition {
+  x: number;
+  y: number;
+}
+
+export class InteractionsClient {
+  constructor(private client: PiggyClient) {}
+
+  // ── Click ─────────────────────────────────────────────────────────────────
+
+  click(selector: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("click", { selector, tabId });
+  }
+
+  dblclick(selector: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("dblclick", { selector, tabId });
+  }
+
+  hover(selector: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("hover", { selector, tabId });
+  }
+
+  // ── Input ─────────────────────────────────────────────────────────────────
+
+  type(selector: string, text: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("type", { selector, text, tabId });
+  }
+
+  typeClear(selector: string, text: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("type", { selector, text, clear: true, tabId });
+  }
+
+  select(selector: string, value: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("select", { selector, value, tabId });
+  }
+
+  // ── Scroll ────────────────────────────────────────────────────────────────
+
+  scrollTo(selector: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("scroll.to", { selector, tabId });
+  }
+
+  scrollBy(px: number, tabId = "default"): Promise<boolean> {
+    return this.client.send("scroll.by", { px, tabId });
+  }
+
+  // ── Keyboard ──────────────────────────────────────────────────────────────
+
+  keyPress(key: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("keyboard.press", { key, tabId });
+  }
+
+  keyCombo(combo: string, tabId = "default"): Promise<boolean> {
+    return this.client.send("keyboard.combo", { combo, tabId });
+  }
+
+  // ── Mouse ─────────────────────────────────────────────────────────────────
+
+  mouseMove(x: number, y: number, tabId = "default"): Promise<boolean> {
+    return this.client.send("mouse.move", { x, y, tabId });
+  }
+
+  mouseDrag(from: MousePosition, to: MousePosition, tabId = "default"): Promise<boolean> {
+    return this.client.send("mouse.drag", { from, to, tabId });
+  }
+
+  // ── Evaluate ──────────────────────────────────────────────────────────────
+
+  evaluate(js: string, tabId = "default"): Promise<unknown> {
+    return this.client.send("evaluate", { js, tabId });
+  }
+}
+
+export function createInteractionsAPI(client: PiggyClient): InteractionsClient {
+  return new InteractionsClient(client);
+}

package/piggy/media/index.ts

@@ -0,0 +1,46 @@
+// piggy/media/index.ts
+import { PiggyClient } from "../client";
+import { writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+export class MediaClient {
+  constructor(private client: PiggyClient) {}
+
+  // ── Screenshot ────────────────────────────────────────────────────────────
+
+  async screenshot(filePath?: string, tabId = "default"): Promise<string> {
+    const b64 = await this.client.send<string>("screenshot", { tabId });
+    if (filePath) {
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, Buffer.from(b64, "base64"));
+      return filePath;
+    }
+    return b64;
+  }
+
+  // ── PDF ───────────────────────────────────────────────────────────────────
+
+  async pdf(filePath?: string, tabId = "default"): Promise<string> {
+    const b64 = await this.client.send<string>("pdf", { tabId });
+    if (filePath) {
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, Buffer.from(b64, "base64"));
+      return filePath;
+    }
+    return b64;
+  }
+
+  // ── Image blocking ────────────────────────────────────────────────────────
+
+  blockImages(tabId = "default"): Promise<void> {
+    return this.client.send("intercept.block.images", { tabId });
+  }
+
+  unblockImages(tabId = "default"): Promise<void> {
+    return this.client.send("intercept.unblock.images", { tabId });
+  }
+}
+
+export function createMediaAPI(client: PiggyClient): MediaClient {
+  return new MediaClient(client);
+}

package/piggy/navigation/index.ts

@@ -0,0 +1,52 @@
+// piggy/navigation/index.ts
+import { PiggyClient } from "../client";
+
+export class NavigationClient {
+  constructor(private client: PiggyClient) {}
+
+  // ── Navigation ────────────────────────────────────────────────────────────
+
+  navigate(url: string, tabId = "default"): Promise<void> {
+    return this.client.send("navigate", { url, tabId });
+  }
+
+  reload(tabId = "default"): Promise<void> {
+    return this.client.send("reload", { tabId });
+  }
+
+  goBack(tabId = "default"): Promise<void> {
+    return this.client.send("go.back", { tabId });
+  }
+
+  goForward(tabId = "default"): Promise<void> {
+    return this.client.send("go.forward", { tabId });
+  }
+
+  // ── Page info ─────────────────────────────────────────────────────────────
+
+  url(tabId = "default"): Promise<string> {
+    return this.client.send("page.url", { tabId });
+  }
+
+  title(tabId = "default"): Promise<string> {
+    return this.client.send("page.title", { tabId });
+  }
+
+  content(tabId = "default"): Promise<string> {
+    return this.client.send("page.content", { tabId });
+  }
+
+  // ── Wait ──────────────────────────────────────────────────────────────────
+
+  waitForNavigation(tabId = "default"): Promise<void> {
+    return this.client.send("wait.navigation", { tabId });
+  }
+
+  waitForSelector(selector: string, timeout = 10000, tabId = "default"): Promise<void> {
+    return this.client.send("wait.selector", { selector, timeout, tabId });
+  }
+}
+
+export function createNavigationAPI(client: PiggyClient): NavigationClient {
+  return new NavigationClient(client);
+}

package/piggy/provide/index.ts

@@ -0,0 +1,144 @@
+// piggy/provide/index.ts
+import { PiggyClient } from "../client";
+
+// ─── Return types ─────────────────────────────────────────────────────────────
+
+export interface ProvideTable {
+  headers: string[];
+  rows:    string[][];
+}
+
+export interface ProvideLink {
+  text: string;
+  href: string;
+}
+
+export interface ProvideImage {
+  alt: string;
+  src: string;
+}
+
+export interface ProvideForm {
+  [name: string]: string;
+}
+
+export interface ProvidePage {
+  title: string;
+  url:   string;
+  html:  string;
+  text:  string;
+}
+
+export interface ProvideDiv {
+  tag:      string;
+  id:       string;
+  cls:      string;
+  text:     string;
+  html:     string;
+  children: ProvideDiv[];
+}
+
+export interface ProvideMeta {
+  [name: string]: string;
+}
+
+export interface ProvideSelectOption {
+  text:     string;
+  value:    string;
+  selected: boolean;
+}
+
+export interface ProvideSelect {
+  value:   string;
+  options: ProvideSelectOption[];
+}
+
+// ─── ProvideClient ────────────────────────────────────────────────────────────
+
+export class ProvideClient {
+  constructor(private client: PiggyClient) {}
+
+  /** innerText of the first matched element. */
+  text(selector: string, tabId = "default"): Promise<string> {
+    return this.client.send("provide.text", { selector, tabId });
+  }
+
+  /** innerText of all matched elements. */
+  textAll(selector: string, tabId = "default"): Promise<string[]> {
+    return this.client.send("provide.textAll", { selector, tabId });
+  }
+
+  /** Single attribute value from the first matched element. */
+  attr(selector: string, attr: string, tabId = "default"): Promise<string> {
+    return this.client.send("provide.attr", { selector, attr, tabId });
+  }
+
+  /** Attribute value from all matched elements. */
+  attrAll(selector: string, attr: string, tabId = "default"): Promise<string[]> {
+    return this.client.send("provide.attrAll", { selector, attr, tabId });
+  }
+
+  /** innerHTML of the first matched element. */
+  html(selector: string, tabId = "default"): Promise<string> {
+    return this.client.send("provide.html", { selector, tabId });
+  }
+
+  /** Extract a table into headers + rows. */
+  table(selector: string, tabId = "default"): Promise<ProvideTable> {
+    return this.client.send("provide.table", { selector, tabId });
+  }
+
+  /** Extract a list of text items. Optionally scope items with itemSel. */
+  list(selector: string, itemSel?: string, tabId = "default"): Promise<string[]> {
+    return this.client.send("provide.list", { selector, itemSel, tabId });
+  }
+
+  /** All links inside an optional selector. */
+  links(selector?: string, tabId = "default"): Promise<ProvideLink[]> {
+    return this.client.send("provide.links", { selector, tabId });
+  }
+
+  /** All images inside an optional selector. */
+  images(selector?: string, tabId = "default"): Promise<ProvideImage[]> {
+    return this.client.send("provide.images", { selector, tabId });
+  }
+
+  /** Form field name→value map. */
+  form(selector: string, tabId = "default"): Promise<ProvideForm> {
+    return this.client.send("provide.form", { selector, tabId });
+  }
+
+  /** Full page info: title, url, html, text. */
+  page(tabId = "default"): Promise<ProvidePage> {
+    return this.client.send("provide.page", { tabId });
+  }
+
+  /** Structured div: tag, id, cls, text, html, children[]. */
+  div(selector: string, tabId = "default"): Promise<ProvideDiv> {
+    return this.client.send("provide.div", { selector, tabId });
+  }
+
+  /** All <meta> name→content pairs. */
+  meta(tabId = "default"): Promise<ProvideMeta> {
+    return this.client.send("provide.meta", { tabId });
+  }
+
+  /** <select> current value + all options. */
+  select(selector: string, tabId = "default"): Promise<ProvideSelect> {
+    return this.client.send("provide.select", { selector, tabId });
+  }
+
+  /**
+   * Parse JSON from element innerText or script[type=application/json].
+   * selector is optional — defaults to the first matching JSON script tag.
+   */
+  json(selector?: string, tabId = "default"): Promise<unknown> {
+    return this.client.send("provide.json", { selector, tabId });
+  }
+}
+
+// ─── Factory helper ───────────────────────────────────────────────────────────
+
+export function createProvideAPI(client: PiggyClient): ProvideClient {
+  return new ProvideClient(client);
+}

package/piggy/proxy/index.ts

@@ -0,0 +1,154 @@
+// piggy/proxy/index.ts
+import { PiggyClient } from "../client";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type ProxyType    = "http" | "https" | "socks5";
+export type ProxyHealth  = "alive" | "dead" | "checking" | "unchecked";
+export type RotationMode = "none" | "timed" | "perrequest";
+
+export interface ProxyEntry {
+  index:   number;
+  host:    string;
+  port:    number;
+  type:    ProxyType;
+  user:    string;
+  proxy:   string;   // full string e.g. "socks5://user:pass@host:port"
+  latency: number;
+  health:  ProxyHealth;
+  current: boolean;
+}
+
+export interface ProxyStats {
+  total:     number;
+  alive:     number;
+  dead:      number;
+  index:     number;
+  active:    boolean;
+  checking:  boolean;
+  skipDead:  boolean;
+  autoCheck: boolean;
+}
+
+export interface ProxyListResult {
+  proxies: ProxyEntry[];
+  total:   number;
+  shown:   number;
+}
+
+export interface ProxyCurrent {
+  active:  boolean;
+  host?:   string;
+  port?:   number;
+  type?:   ProxyType;
+  user?:   string;
+  proxy?:  string;
+  latency?: number;
+  health?: ProxyHealth;
+}
+
+export interface ProxyConfig {
+  skipDead:  boolean;
+  autoCheck: boolean;
+}
+
+// ─── Inline set options ───────────────────────────────────────────────────────
+
+export type ProxySetOptions =
+  | { proxy: string }
+  | { host: string; port: number; type?: ProxyType; user?: string; pass?: string };
+
+// ─── ProxyClient ──────────────────────────────────────────────────────────────
+
+export class ProxyClient {
+  constructor(private client: PiggyClient) {}
+
+  /** Load proxies from a local file path. */
+  load(path: string): Promise<void> {
+    return this.client.send("proxy.load", { path });
+  }
+
+  /** Fetch proxies from a URL. Result comes via proxy:loaded / proxy:fetch:failed events. */
+  fetch(url: string): Promise<void> {
+    return this.client.send("proxy.fetch", { url });
+  }
+
+  /** Load an .ovpn config file. */
+  ovpn(path: string): Promise<void> {
+    return this.client.send("proxy.ovpn", { path });
+  }
+
+  /** Set a single proxy inline. */
+  set(opts: ProxySetOptions): Promise<void> {
+    return this.client.send("proxy.set", opts);
+  }
+
+  /** Health-check all loaded proxies. Results come via events. */
+  test(): Promise<void> {
+    return this.client.send("proxy.test", {});
+  }
+
+  /** Abort an in-progress health check. */
+  testStop(): Promise<void> {
+    return this.client.send("proxy.test.stop", {});
+  }
+
+  /** Rotate to the next proxy in the pool. */
+  next(): Promise<string> {
+    return this.client.send("proxy.next", {});
+  }
+
+  /** Alias for next(). */
+  rotate(): Promise<string> {
+    return this.client.send("proxy.rotate", {});
+  }
+
+  /** Disable the proxy — use the real IP. */
+  disable(): Promise<void> {
+    return this.client.send("proxy.disable", {});
+  }
+
+  /** Re-enable the current proxy. */
+  enable(): Promise<void> {
+    return this.client.send("proxy.enable", {});
+  }
+
+  /** Get the current active proxy details. */
+  current(): Promise<ProxyCurrent> {
+    return this.client.send("proxy.current", {});
+  }
+
+  /** Get pool stats: total, alive, dead, index, active, checking. */
+  stats(): Promise<ProxyStats> {
+    return this.client.send("proxy.stats", {});
+  }
+
+  /** List all proxies with health info. limit defaults to 500. */
+  list(limit?: number): Promise<ProxyListResult> {
+    return this.client.send("proxy.list", { limit });
+  }
+
+  /** Set rotation mode and interval (seconds, only used for "timed"). */
+  rotation(mode: RotationMode, interval?: number): Promise<void> {
+    return this.client.send("proxy.rotation", { mode, interval });
+  }
+
+  /** Set skipDead / autoCheck flags. */
+  config(opts: Partial<ProxyConfig>): Promise<ProxyConfig> {
+    return this.client.send("proxy.config", opts);
+  }
+
+  /**
+   * Save the current proxy list to a file.
+   * filter: "all" | "alive" | "dead" — defaults to "all".
+   */
+  save(path: string, filter?: "all" | "alive" | "dead"): Promise<void> {
+    return this.client.send("proxy.save", { path, filter });
+  }
+}
+
+// ─── Factory helper ───────────────────────────────────────────────────────────
+
+export function createProxyAPI(client: PiggyClient): ProxyClient {
+  return new ProxyClient(client);
+}