@grabbit-labs/dynafetch 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+export type DynafetchThirdPartyPolicy = "skip-noncritical" | "execute-all";
+
+export type DynafetchFramework =
+  | "nextjs"
+  | "nuxt"
+  | "remix"
+  | "inertia"
+  | "astro"
+  | "sveltekit"
+  | "htmx"
+  | "generic-spa"
+  | "static";
+
+export type DynafetchStrategy =
+  | "static-html"
+  | "framework-probe"
+  | "jsdom-fallback";
+
+export type DynafetchProxyScope = "page" | "api" | "assets";
+
+export type DynafetchProxyConfig = string | {
+  url: string;
+  only?: DynafetchProxyScope[];
+};
+
+export type DynafetchOptions = {
+  /** Target URL to fetch and render. */
+  url: string;
+
+  /**
+   * Extra request headers merged on top of the default Chrome 146 headers.
+   * Any header you set here overrides the built-in default for that key.
+   * Headers you don't set keep their Chrome-like defaults (User-Agent,
+   * Accept, Sec-Fetch-*, etc.).
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Cookies to include. Accepts:
+   * - `string` — raw `Cookie` header value (`"k1=v1; k2=v2"`)
+   * - `string[]` — individual `name=value` pairs
+   * - `Record<string, string>` — key/value map
+   */
+  cookies?: Record<string, string> | string | string[];
+
+  /**
+   * Proxy configuration. Routes requests through an HTTP/HTTPS proxy with
+   * TLS fingerprint preservation.
+   *
+   * ```ts
+   * // Proxy all requests
+   * proxy: "http://user:pass@ip:port"
+   *
+   * // Only proxy the page fetch and API calls (skip static assets)
+   * proxy: { url: "http://user:pass@ip:port", only: ["page", "api"] }
+   * ```
+   */
+  proxy?: DynafetchProxyConfig;
+
+  /** Overall timeout for the entire operation in milliseconds. */
+  timeoutMs?: number;
+
+  /** TLS client profile to impersonate. @default `"chrome_146"` */
+  browserProfile?: string;
+
+  /** Advisory limit on sub-requests the executor may issue. */
+  maxSubrequests?: number;
+
+  /** Allow JSDOM-based script execution for dynamic pages. @default `true` */
+  allowJsdomFallback?: boolean;
+
+  /** Pre-fetch external `<script src>` tags during harvest. @default `true` */
+  prefetchExternalScripts?: boolean;
+
+  /** Pre-fetch `<link rel="modulepreload">` assets during harvest. @default `true` */
+  prefetchModulePreloads?: boolean;
+
+  /**
+   * Controls whether non-critical third-party scripts (analytics, ads, chat
+   * widgets) are executed.
+   * @default `"skip-noncritical"`
+   */
+  thirdPartyPolicy?: DynafetchThirdPartyPolicy;
+
+  /**
+   * Minimum time (ms) to wait before checking if the page is idle.
+   * @default 75
+   */
+  minWaitMs?: number;
+
+  /**
+   * How long (ms) the page must be completely idle (zero pending requests)
+   * before we consider it settled.
+   * @default 100
+   */
+  idleWaitMs?: number;
+
+  /**
+   * Hard upper bound (ms) on how long to wait for the page to settle.
+   * @default 2000
+   */
+  maxWaitMs?: number;
+
+  /**
+   * Maximum time (ms) to wait for ES module bundling (esbuild) to complete.
+   * @default 6000
+   */
+  moduleWaitMs?: number;
+};
+
+export type DynafetchResult = {
+  url: string;
+  finalUrl: string;
+  status: number;
+  html: string;
+  framework: DynafetchFramework;
+  strategy: DynafetchStrategy;
+  confidence: number;
+  warnings: string[];
+  timings: {
+    total: number;
+    harvest: number;
+    execute: number;
+    quiescence: number;
+    scriptsTransformed: number;
+  };
+  requestCount: number;
+};
+
+export type DynafetchPlan = {
+  framework: DynafetchFramework;
+  strategy: DynafetchStrategy;
+  reason: string;
+};
+
+export declare class DynafetchInputError extends Error {
+  status: number;
+  constructor(message: string, status?: number);
+}
+
+/**
+ * Fetch a URL with full browser emulation — Chrome TLS fingerprinting,
+ * JavaScript execution, and network interception — then return the
+ * rendered HTML and metadata.
+ *
+ * Uses Chrome 146 headers by default. Any headers you provide are merged
+ * on top — your values override the defaults, everything else stays.
+ *
+ * @example
+ * ```ts
+ * // Minimal
+ * const page = await dynafetch("https://example.com");
+ *
+ * // With custom headers, cookies, and proxy
+ * const page = await dynafetch({
+ *   url: "https://example.com",
+ *   headers: { "Accept-Language": "fr-FR" },
+ *   cookies: { session: "abc123" },
+ *   proxy: "http://user:pass@ip:port",
+ * });
+ *
+ * // Smart proxy — only proxy the HTML page and API calls
+ * const page = await dynafetch({
+ *   url: "https://example.com",
+ *   proxy: { url: "http://user:pass@ip:port", only: ["page", "api"] },
+ * });
+ * ```
+ *
+ * **Options at a glance:**
+ *
+ * | Option | Default | Description |
+ * |---|---|---|
+ * | `headers` | Chrome 146 | Merged on top of defaults — yours override on conflict |
+ * | `cookies` | none | String, array, or `Record<string, string>` |
+ * | `proxy` | none | `"http://user:pass@ip:port"` or `{ url, only: ["page","api","assets"] }` |
+ * | `minWaitMs` | `75` | Min ms before checking if page is idle |
+ * | `idleWaitMs` | `100` | Ms of zero pending requests = settled |
+ * | `maxWaitMs` | `2000` | Hard cap on wait time regardless of activity |
+ * | `moduleWaitMs` | `6000` | Max ms for ES module bundling (esbuild) |
+ * | `timeoutMs` | none | Overall timeout for the entire operation |
+ * | `thirdPartyPolicy` | `"skip-noncritical"` | Skip analytics/ads/chat scripts |
+ *
+ * **Proxy scopes** — when using `{ url, only }`:
+ * - `"page"` — initial HTML document fetch
+ * - `"api"` — fetch() and XHR calls from page scripts
+ * - `"assets"` — JS scripts, ES modules, static resources
+ *
+ * **Speed presets:**
+ * - Fast: `{ maxWaitMs: 1000, idleWaitMs: 50 }`
+ * - Thorough: `{ maxWaitMs: 5000, idleWaitMs: 200 }`
+ */
+export declare function dynafetch(input: string | DynafetchOptions): Promise<DynafetchResult>;