timeout param + passive captcha handling

Author: SentienceDEV

src/backends/snapshot.ts

@@ -104,6 +104,8 @@ export interface SnapshotOptions {
   gridId?: number | null;
   /** Use server-side API (Pro/Enterprise tier) */
   useApi?: boolean;
+  /** Gateway snapshot timeout (milliseconds) */
+  gatewayTimeoutMs?: number;
   /** API key for server-side processing */
   sentienceApiKey?: string;
   /** Goal/task description for ordinal support and gateway reranking */

src/snapshot.ts

@@ -58,6 +58,7 @@ export interface SnapshotOptions {
     min_z_index?: number;
   };
   use_api?: boolean; // Force use of server-side API if True, local extension if False
+  gatewayTimeoutMs?: number; // Gateway snapshot timeout in milliseconds
   save_trace?: boolean; // Save raw_elements to JSON for benchmarking/training
   trace_path?: string; // Path to save trace file (default: "trace_{timestamp}.json")
   goal?: string; // Optional goal/task description for the snapshot
@@ -317,11 +318,20 @@ async function snapshotViaApi(
   };
 
   try {
-    const response = await fetch(gatewayUrl, {
-      method: 'POST',
-      headers,
-      body: payloadJson,
-    });
+    const timeoutMs = options.gatewayTimeoutMs ?? 30000;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    let response: Response;
+    try {
+      response = await fetch(gatewayUrl, {
+        method: 'POST',
+        headers,
+        body: payloadJson,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
 
     if (!response.ok) {
       let errorText: string | undefined = undefined;

tests/snapshot-gateway-timeout.test.ts

@@ -0,0 +1,86 @@
+import { snapshot } from '../src';
+import { BrowserEvaluator } from '../src/utils/browser-evaluator';
+
+jest.mock('../src/utils/browser-evaluator', () => ({
+  BrowserEvaluator: {
+    waitForCondition: jest.fn().mockResolvedValue(true),
+    evaluate: jest.fn(),
+  },
+}));
+
+const mockedBrowserEvaluator = BrowserEvaluator as jest.Mocked<typeof BrowserEvaluator>;
+
+function makeBrowser() {
+  return {
+    getApiKey: () => 'sk_test',
+    getApiUrl: () => 'https://api.sentienceapi.com',
+    getPage: () => ({}),
+  } as any;
+}
+
+describe('Snapshot gateway timeout', () => {
+  const rawResult = {
+    raw_elements: [],
+    url: 'https://example.com',
+    viewport: { width: 800, height: 600 },
+    diagnostics: {},
+  };
+
+  beforeEach(() => {
+    mockedBrowserEvaluator.evaluate.mockResolvedValue(rawResult as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('uses default gateway timeout when not provided', async () => {
+    const fetchMock = jest.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ status: 'success', elements: [], url: 'https://example.com' }),
+      headers: new Headers(),
+    });
+    (global as any).fetch = fetchMock;
+
+    const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(((
+      fn: (...args: any[]) => void,
+      _ms?: number
+    ) => {
+      return 123 as any;
+    }) as any);
+    const clearTimeoutSpy = jest.spyOn(global, 'clearTimeout').mockImplementation(() => {});
+
+    await snapshot(makeBrowser(), { screenshot: false, limit: 10 });
+
+    expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 30000);
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(123);
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.sentienceapi.com/v1/snapshot',
+      expect.objectContaining({
+        signal: expect.any(AbortSignal),
+      })
+    );
+  });
+
+  it('uses custom gateway timeout when provided', async () => {
+    const fetchMock = jest.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ status: 'success', elements: [], url: 'https://example.com' }),
+      headers: new Headers(),
+    });
+    (global as any).fetch = fetchMock;
+
+    const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(((
+      fn: (...args: any[]) => void,
+      _ms?: number
+    ) => {
+      return 456 as any;
+    }) as any);
+    const clearTimeoutSpy = jest.spyOn(global, 'clearTimeout').mockImplementation(() => {});
+
+    await snapshot(makeBrowser(), { screenshot: false, limit: 10, gatewayTimeoutMs: 12345 });
+
+    expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 12345);
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(456);
+  });
+});