Node SDK

npm install predev-api

import { PredevAPI } from 'predev-api';

const predev = new PredevAPI({ apiKey: process.env.PREDEV_API_KEY! });

const result = await predev.browserAgent([
  {
    url: 'https://example.com',
    instruction: 'Extract the page heading.',
    output: {
      type: 'object',
      properties: { heading: { type: 'string' } },
      required: ['heading'],
    },
  },
]);

console.log(result.results[0].data);
// → { heading: "Example Domain" }

const predev = new PredevAPI({ apiKey: 'YOUR_API_KEY' });

// Sync / async → Promise<BrowserAgentResponse>
predev.browserAgent(tasks, { concurrency?: number; async?: boolean }): Promise<BrowserAgentResponse>;

// Streaming → AsyncGenerator<BrowserAgentSSEMessage>
predev.browserAgent(tasks, { concurrency?: number; stream: true }): AsyncGenerator<BrowserAgentSSEMessage>;

interface BrowserTask {
  url: string;                           // required
  instruction?: string;                  // natural-language goal
  input?: Record<string, string>;        // string inputs the agent uses during the run
  output?: Record<string, any>;          // JSON Schema for the data to extract
}

const result = await predev.getBrowserAgent(id, { includeEvents?: boolean });

const { batches, total, hasMore } = await client.listBrowserAgents({
  limit: 20,          // optional
  skip: 0,            // optional
  status: 'completed' // optional: 'processing' | 'completed'
});

const q = await client.browserAgentStatus();
// { userId, running, claimed, pending, total, cap }
if (q.total < q.cap - 10) {
  await client.browserAgent(nextChunk, { async: true });
}

interface BrowserAgentTaskResult {
  url: string;
  status:
    | 'SUCCESS'
    | 'PENDING'
    | 'ERROR'
    | 'TIMEOUT'
    | 'BLOCKED'
    | 'CAPTCHA_FAILED'
    | 'LOOP'
    | 'NO_TARGET';
  data?: unknown;
  creditsUsed: number;
  durationMs: number;
  error?: string;
}

interface BrowserAgentResponse {
  id: string;
  total: number;
  completed: number;
  results: BrowserAgentTaskResult[];
  totalCreditsUsed: number;
  status: 'processing' | 'completed' | 'failed';
  createdAt?: string;
  completedAt?: string;
}

type BrowserAgentEventType =
  | 'navigation'    // agent loaded a URL
  | 'screenshot'    // frame captured
  | 'plan'          // agent reasoned about next steps
  | 'action'        // click / type / scroll / extract
  | 'validation'    // output schema or success condition checked
  | 'done'          // task finished
  | 'error';        // task errored

interface BrowserAgentStreamEvent {
  taskIndex: number;
  type: BrowserAgentEventType;
  timestamp: number;
  iteration?: number;
  data: any;
}

type BrowserAgentSSEMessage =
  | { event: 'task_event';  data: BrowserAgentStreamEvent }
  | { event: 'task_result'; data: BrowserAgentTaskResult & { taskIndex: number } }
  | { event: 'done';        data: BrowserAgentResponse }
  | { event: 'error';       data: { error: string } };

const result = await predev.browserAgent(
  [
    { url: 'https://news.ycombinator.com', instruction: 'Extract the top 5 story titles.' },
    { url: 'https://www.reddit.com/r/programming', instruction: 'Extract the top 5 post titles.' },
  ],
  { concurrency: 2 },
);

for (const r of result.results) {
  console.log(r.status, r.data);
}

const { id } = await predev.browserAgent(tasks, { async: true });

while (true) {
  const status = await predev.getBrowserAgent(id);
  if (status.status === 'completed' || status.status === 'failed') {
    console.log(status.results);
    break;
  }
  console.log(`${status.completed}/${status.total} done`);
  await new Promise(r => setTimeout(r, 5000));
}

for await (const msg of predev.browserAgent(tasks, { stream: true })) {
  if (msg.event === 'task_event') {
    console.log(`[task ${msg.data.taskIndex}]`, msg.data.type);
  } else if (msg.event === 'task_result') {
    console.log(`[task ${msg.data.taskIndex}]`, msg.data.status, msg.data.data);
  } else if (msg.event === 'done') {
    console.log('batch done:', msg.data.id, msg.data.totalCreditsUsed, 'credits');
  } else if (msg.event === 'error') {
    console.error('error:', msg.data.error);
  }
}

const result = await predev.getBrowserAgent(id, { includeEvents: true });

for (const task of result.results) {
  console.log(task.status, task.url);
  for (const event of (task as any).events ?? []) {
    console.log('  -', event.type);
  }
}

import {
  PredevAPIError,
  AuthenticationError,
  RateLimitError,
  SubscriptionRequiredError,
  InsufficientCreditsError,
  QueueFullError,
  BatchTooLargeError,
} from 'predev-api';

try {
  const result = await predev.browserAgent(tasks);
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // Subscription is fine, balance is too low — send the user to the credits modal.
    if (err.actionUrl) window.open(err.actionUrl, '_blank');
  } else if (err instanceof SubscriptionRequiredError) {
    // Trial limit hit — send the user to the subscribe modal.
    if (err.actionUrl) window.open(err.actionUrl, '_blank');
  } else if (err instanceof AuthenticationError) {
    // 401 — invalid or missing API key
  } else if (err instanceof RateLimitError) {
    // 429 RATE_LIMITED — back off and retry
  } else if (err instanceof QueueFullError) {
    // 429 QUEUE_FULL — wait for in-flight tasks to drain
  } else if (err instanceof BatchTooLargeError) {
    // 400 — split into smaller batches
  } else if (err instanceof PredevAPIError) {
    console.error(err.message);
  }
}