@grabbit-labs/dynafetch 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grabbit Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -16,6 +16,12 @@ export type DynafetchStrategy =
   | "framework-probe"
   | "jsdom-fallback";
 
+export type DynafetchHarvestSnapshot = {
+  html: string;
+  initialState: Record<string, unknown>;
+  scripts: Array<{ url?: string }>;
+};
+
 export type DynafetchProxyScope = "page" | "api" | "assets";
 
 export type DynafetchProxyConfig = string | {
@@ -24,87 +30,20 @@ export type DynafetchProxyConfig = string | {
 };
 
 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;
 };
 
@@ -133,60 +72,64 @@ export type DynafetchPlan = {
   reason: string;
 };
 
+export type DynafetchNetRequest = {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  headerOrder?: string[];
+  body: string;
+  proxy?: string;
+};
+
+export type DynafetchNetResponse = {
+  status: number;
+  body: string;
+  headers: Record<string, string>;
+  finalUrl?: string;
+  error?: string;
+  retried?: boolean;
+};
+
+export type DynafetchSessionOptions = {
+  browserProfile?: string;
+  timeoutSeconds?: number;
+  proxy?: string;
+  rpcTimeoutMs?: number;
+};
+
+export type DynafetchNetFetchOptions = DynafetchSessionOptions & {
+  followRedirect?: boolean;
+  maxRedirects?: number;
+};
+
 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 detectFramework(harvest: DynafetchHarvestSnapshot): DynafetchFramework;
+
+export declare function planDynafetch(
+  framework: DynafetchFramework,
+  harvest: DynafetchHarvestSnapshot,
+  allowJsdomFallback: boolean,
+): DynafetchPlan;
+
+export declare function withDynafetchSession<T>(
+  options: DynafetchSessionOptions,
+  run: () => Promise<T>,
+): Promise<T>;
+
+export declare function dynafetchNetHealth(): Promise<{ ok: boolean; service: string }>;
+
+export declare function dynafetchNetFetch(
+  request: DynafetchNetRequest,
+  options?: DynafetchNetFetchOptions,
+): Promise<DynafetchNetResponse>;
+
+export declare function dynafetchNetBatchFetch(
+  requests: DynafetchNetRequest[],
+  options?: DynafetchNetFetchOptions,
+): Promise<DynafetchNetResponse[]>;
+
 export declare function dynafetch(input: string | DynafetchOptions): Promise<DynafetchResult>;