@vakra-dev/reader-js 0.2.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/client.ts"],"sourcesContent":["export { ReaderClient } from \"./client.js\";\nexport {\n  ReaderApiError,\n  InvalidRequestError,\n  UnauthenticatedError,\n  InsufficientCreditsError,\n  UrlBlockedError,\n  NotFoundError,\n  ConflictError,\n  RateLimitedError,\n  ConcurrencyLimitedError,\n  InternalServerError,\n  UpstreamUnavailableError,\n  ScrapeTimeoutError,\n  toReaderApiError,\n} from \"./errors.js\";\nexport type { ReaderErrorCode, ApiErrorBody } from \"./errors.js\";\nexport type {\n  ReaderClientConfig,\n  ReadParams,\n  ReadResult,\n  ScrapeResult,\n  ScrapeMetadata,\n  Page,\n  Job,\n  JobStatus,\n  JobMode,\n  ProxyMode,\n  Pagination,\n  Credits,\n  UsageEntry,\n  StreamEvent,\n  SuccessEnvelope,\n  PaginatedEnvelope,\n  ErrorEnvelope,\n  ApiEnvelope,\n  SessionInfo,\n  CreateSessionParams,\n  StopSessionResult,\n  SessionStatus,\n} from \"./types.js\";\n","/**\n * Typed error classes mirroring the reader-api error code catalog.\n *\n * The API returns a stable `code` field on every error response. The SDK\n * branches on that code and throws a specific subclass, so callers can\n * write:\n *\n *   try {\n *     await client.read({ url });\n *   } catch (err) {\n *     if (err instanceof InsufficientCreditsError) {\n *       // err.required, err.available, err.resetAt\n *     }\n *   }\n *\n * There is one subclass per code in the catalog. Unknown codes fall through\n * to the base `ReaderApiError`.\n */\n\nexport type ReaderErrorCode =\n  | \"invalid_request\"\n  | \"unauthenticated\"\n  | \"insufficient_credits\"\n  | \"url_blocked\"\n  | \"not_found\"\n  | \"conflict\"\n  | \"rate_limited\"\n  | \"concurrency_limited\"\n  | \"internal_error\"\n  | \"upstream_unavailable\"\n  | \"scrape_timeout\";\n\nexport interface ApiErrorBody {\n  code: ReaderErrorCode | string;\n  message: string;\n  details?: Record<string, unknown>;\n  docsUrl?: string;\n}\n\nexport class ReaderApiError extends Error {\n  readonly code: string;\n  readonly httpStatus: number;\n  readonly details?: Record<string, unknown>;\n  readonly docsUrl?: string;\n  readonly requestId?: string;\n\n  constructor(body: ApiErrorBody, httpStatus: number, requestId?: string) {\n    super(body.message);\n    this.name = \"ReaderApiError\";\n    this.code = body.code;\n    this.httpStatus = httpStatus;\n    this.details = body.details;\n    this.docsUrl = body.docsUrl;\n    this.requestId = requestId;\n  }\n}\n\nexport class InvalidRequestError extends ReaderApiError {\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"InvalidRequestError\";\n  }\n}\n\nexport class UnauthenticatedError extends ReaderApiError {\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"UnauthenticatedError\";\n  }\n}\n\nexport class InsufficientCreditsError extends ReaderApiError {\n  readonly required?: number;\n  readonly available?: number;\n  readonly resetAt?: string;\n\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"InsufficientCreditsError\";\n    this.required = body.details?.required as number | undefined;\n    this.available = body.details?.available as number | undefined;\n    this.resetAt = body.details?.resetAt as string | undefined;\n  }\n}\n\nexport class UrlBlockedError extends ReaderApiError {\n  readonly url?: string;\n  readonly reason?: string;\n\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"UrlBlockedError\";\n    this.url = body.details?.url as string | undefined;\n    this.reason = body.details?.reason as string | undefined;\n  }\n}\n\nexport class NotFoundError extends ReaderApiError {\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"NotFoundError\";\n  }\n}\n\nexport class ConflictError extends ReaderApiError {\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"ConflictError\";\n  }\n}\n\nexport class RateLimitedError extends ReaderApiError {\n  readonly retryAfterSeconds?: number;\n  readonly limit?: number;\n  readonly windowSeconds?: number;\n\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"RateLimitedError\";\n    this.retryAfterSeconds = body.details?.retryAfterSeconds as number | undefined;\n    this.limit = body.details?.limit as number | undefined;\n    this.windowSeconds = body.details?.windowSeconds as number | undefined;\n  }\n}\n\nexport class ConcurrencyLimitedError extends ReaderApiError {\n  readonly active?: number;\n  readonly max?: number;\n\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"ConcurrencyLimitedError\";\n    this.active = body.details?.active as number | undefined;\n    this.max = body.details?.max as number | undefined;\n  }\n}\n\nexport class InternalServerError extends ReaderApiError {\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"InternalServerError\";\n  }\n}\n\nexport class UpstreamUnavailableError extends ReaderApiError {\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"UpstreamUnavailableError\";\n  }\n}\n\nexport class ScrapeTimeoutError extends ReaderApiError {\n  readonly timeoutMs?: number;\n\n  constructor(body: ApiErrorBody, status: number, requestId?: string) {\n    super(body, status, requestId);\n    this.name = \"ScrapeTimeoutError\";\n    this.timeoutMs = body.details?.timeoutMs as number | undefined;\n  }\n}\n\n/**\n * Construct the right error subclass from an error response body.\n * Unknown codes fall through to the base class.\n */\nexport function toReaderApiError(\n  body: ApiErrorBody,\n  httpStatus: number,\n  requestId?: string,\n): ReaderApiError {\n  switch (body.code) {\n    case \"invalid_request\":\n      return new InvalidRequestError(body, httpStatus, requestId);\n    case \"unauthenticated\":\n      return new UnauthenticatedError(body, httpStatus, requestId);\n    case \"insufficient_credits\":\n      return new InsufficientCreditsError(body, httpStatus, requestId);\n    case \"url_blocked\":\n      return new UrlBlockedError(body, httpStatus, requestId);\n    case \"not_found\":\n      return new NotFoundError(body, httpStatus, requestId);\n    case \"conflict\":\n      return new ConflictError(body, httpStatus, requestId);\n    case \"rate_limited\":\n      return new RateLimitedError(body, httpStatus, requestId);\n    case \"concurrency_limited\":\n      return new ConcurrencyLimitedError(body, httpStatus, requestId);\n    case \"internal_error\":\n      return new InternalServerError(body, httpStatus, requestId);\n    case \"upstream_unavailable\":\n      return new UpstreamUnavailableError(body, httpStatus, requestId);\n    case \"scrape_timeout\":\n      return new ScrapeTimeoutError(body, httpStatus, requestId);\n    default:\n      return new ReaderApiError(body, httpStatus, requestId);\n  }\n}\n","/**\n * Reader SDK Client\n *\n * @example\n * import { ReaderClient } from \"@vakra-dev/reader-js\";\n *\n * const client = new ReaderClient({ apiKey: \"rdr_your_key\" });\n *\n * // Synchronous scrape (single URL)\n * const result = await client.read({ url: \"https://example.com\" });\n * if (result.kind === \"scrape\") {\n *   console.log(result.data.markdown);\n * }\n *\n * // Batch (returns a completed Job with all results collected)\n * const batch = await client.read({ urls: [\"url1\", \"url2\"] });\n * if (batch.kind === \"job\") {\n *   for (const page of batch.data.results) {\n *     console.log(page.url, page.markdown?.length);\n *   }\n * }\n */\n\nimport type {\n  ReaderClientConfig,\n  ReadParams,\n  ReadResult,\n  ScrapeResult,\n  Job,\n  Credits,\n  Page,\n  StreamEvent,\n  SuccessEnvelope,\n  PaginatedEnvelope,\n  ErrorEnvelope,\n  SessionInfo,\n  CreateSessionParams,\n  StopSessionResult,\n} from \"./types.js\";\nimport {\n  toReaderApiError,\n  ReaderApiError,\n  ScrapeTimeoutError,\n  RateLimitedError,\n} from \"./errors.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.reader.dev\";\nconst DEFAULT_TIMEOUT = 60_000;\nconst DEFAULT_MAX_RETRIES = 2;\nconst DEFAULT_POLL_INTERVAL = 2_000;\nconst DEFAULT_POLL_TIMEOUT = 300_000; // 5 minutes\n\ninterface JobWithPagination {\n  data: Job;\n  pagination: { total: number; skip: number; limit: number; hasMore: boolean; next?: string };\n}\n\nexport class ReaderClient {\n  private apiKey: string;\n  private baseUrl: string;\n  private timeout: number;\n  private maxRetries: number;\n  private extraHeaders: Record<string, string>;\n  private _sessions: SessionsAPI | null = null;\n\n  constructor(config: ReaderClientConfig) {\n    if (!config.apiKey) {\n      throw new Error(\"API key is required\");\n    }\n    this.apiKey = config.apiKey;\n    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\\/$/, \"\");\n    this.timeout = config.timeout || DEFAULT_TIMEOUT;\n    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;\n    this.extraHeaders = config.headers || {};\n  }\n\n  /**\n   * Browser sessions API.\n   *\n   * @example\n   * ```typescript\n   * const session = await client.sessions.create();\n   * const browser = await chromium.connectOverCDP(session.wsEndpoint);\n   * // ... use Playwright ...\n   * await client.sessions.stop(session.sessionId);\n   * ```\n   */\n  get sessions(): SessionsAPI {\n    if (!this._sessions) {\n      this._sessions = new SessionsAPI(this.request.bind(this));\n    }\n    return this._sessions;\n  }\n\n  /**\n   * Read (scrape, batch, or crawl) one or more URLs.\n   *\n   * - Single URL → sync scrape, returns immediately with `{ kind: \"scrape\", data }`\n   * - Multiple URLs or URL + maxDepth/maxPages → async job; this method polls\n   *   until the job terminates and returns `{ kind: \"job\", data }`.\n   */\n  async read(params: ReadParams): Promise<ReadResult> {\n    const envelope = await this.request<SuccessEnvelope<unknown>>(\n      \"POST\",\n      \"/v1/read\",\n      params,\n    );\n\n    const data = envelope.data as Record<string, unknown>;\n\n    // Async job response: data.id + data.status present, no markdown/html/metadata\n    if (\n      data &&\n      typeof data === \"object\" &&\n      \"status\" in data &&\n      \"mode\" in data &&\n      !(\"markdown\" in data) &&\n      !(\"metadata\" in data)\n    ) {\n      const jobId = String((data as { id: unknown }).id);\n      const job = await this.waitForJob(jobId);\n      return { kind: \"job\", data: job };\n    }\n\n    // Synchronous scrape: data has markdown/html/metadata\n    return { kind: \"scrape\", data: data as unknown as ScrapeResult };\n  }\n\n  /**\n   * Get job status and a single page of results.\n   */\n  async getJob(\n    jobId: string,\n    opts?: { skip?: number; limit?: number },\n  ): Promise<{ job: Job; hasMore: boolean; next?: string }> {\n    const query = new URLSearchParams();\n    if (opts?.skip !== undefined) query.set(\"skip\", String(opts.skip));\n    if (opts?.limit !== undefined) query.set(\"limit\", String(opts.limit));\n    const qs = query.toString();\n\n    const envelope = await this.request<JobWithPagination>(\n      \"GET\",\n      `/v1/jobs/${jobId}${qs ? `?${qs}` : \"\"}`,\n    );\n\n    return {\n      job: envelope.data,\n      hasMore: envelope.pagination.hasMore,\n      next: envelope.pagination.next,\n    };\n  }\n\n  /**\n   * Fetch all job result pages by following pagination.\n   */\n  async getAllJobResults(jobId: string): Promise<Page[]> {\n    const pages: Page[] = [];\n    let skip = 0;\n    const limit = 100;\n\n    while (true) {\n      const { job, hasMore } = await this.getJob(jobId, { skip, limit });\n      pages.push(...(job.results ?? []));\n      if (!hasMore) break;\n      skip += limit;\n    }\n\n    return pages;\n  }\n\n  /**\n   * Cancel a job. Throws `ConflictError` if the job is already terminal.\n   */\n  async cancelJob(jobId: string): Promise<void> {\n    await this.request(\"DELETE\", `/v1/jobs/${jobId}`);\n  }\n\n  /**\n   * Retry the failed URLs in a job. Throws `InvalidRequestError` if no\n   * failed URLs exist.\n   */\n  async retryJob(jobId: string): Promise<{ id: string; status: string; retrying: number }> {\n    const envelope = await this.request<\n      SuccessEnvelope<{ id: string; status: string; retrying: number }>\n    >(\"POST\", `/v1/jobs/${jobId}/retry`);\n    return envelope.data;\n  }\n\n  /**\n   * Poll a job until it completes, fails, or is cancelled. Collects all\n   * paginated results when complete.\n   */\n  async waitForJob(\n    jobId: string,\n    options?: { pollInterval?: number; timeout?: number },\n  ): Promise<Job> {\n    const interval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL;\n    const timeout = options?.timeout ?? DEFAULT_POLL_TIMEOUT;\n    const start = Date.now();\n\n    while (Date.now() - start < timeout) {\n      const { job } = await this.getJob(jobId, { limit: 1 });\n\n      if (\n        job.status === \"completed\" ||\n        job.status === \"failed\" ||\n        job.status === \"cancelled\"\n      ) {\n        if (job.status === \"completed\") {\n          job.results = await this.getAllJobResults(jobId);\n        }\n        return job;\n      }\n\n      await sleep(interval);\n    }\n\n    throw new ScrapeTimeoutError(\n      {\n        code: \"scrape_timeout\",\n        message: `Job ${jobId} polling timed out after ${timeout}ms`,\n        details: { timeoutMs: timeout },\n      },\n      504,\n    );\n  }\n\n  /**\n   * Stream job results as they arrive via polling.\n   *\n   * @example\n   * for await (const event of client.stream(jobId)) {\n   *   if (event.type === \"page\") console.log(event.data.url);\n   *   if (event.type === \"done\") break;\n   * }\n   */\n  async *stream(\n    jobId: string,\n    options?: { pollInterval?: number; timeout?: number },\n  ): AsyncGenerator<StreamEvent> {\n    const interval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL;\n    const timeout = options?.timeout ?? DEFAULT_POLL_TIMEOUT;\n    const start = Date.now();\n    let lastCompleted = 0;\n\n    while (Date.now() - start < timeout) {\n      const { job } = await this.getJob(jobId, { skip: lastCompleted, limit: 100 });\n\n      yield {\n        type: \"progress\",\n        completed: job.completed,\n        total: job.total,\n        status: job.status,\n      };\n\n      for (const page of job.results ?? []) {\n        if (page.error) {\n          yield { type: \"error\", url: page.url, error: page.error };\n        } else {\n          yield { type: \"page\", data: page };\n        }\n        lastCompleted += 1;\n      }\n\n      if (\n        job.status === \"completed\" ||\n        job.status === \"failed\" ||\n        job.status === \"cancelled\"\n      ) {\n        yield {\n          type: \"done\",\n          completed: job.completed,\n          total: job.total,\n          status: job.status,\n        };\n        return;\n      }\n\n      await sleep(interval);\n    }\n\n    throw new ScrapeTimeoutError(\n      {\n        code: \"scrape_timeout\",\n        message: `Job ${jobId} stream timed out`,\n        details: { timeoutMs: timeout },\n      },\n      504,\n    );\n  }\n\n  /**\n   * Get the current credit balance for this workspace.\n   */\n  async getCredits(): Promise<Credits> {\n    const envelope = await this.request<SuccessEnvelope<Credits>>(\"GET\", \"/v1/usage/credits\");\n    return envelope.data;\n  }\n\n  // --- Internal ---\n\n  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {\n    const url = path.startsWith(\"http\") ? path : `${this.baseUrl}${path}`;\n    let lastError: Error | null = null;\n\n    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {\n      try {\n        const controller = new AbortController();\n        const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n        const res = await fetch(url, {\n          method,\n          headers: {\n            \"Content-Type\": \"application/json\",\n            \"x-api-key\": this.apiKey,\n            ...this.extraHeaders,\n          },\n          body: body ? JSON.stringify(body) : undefined,\n          signal: controller.signal,\n        });\n\n        clearTimeout(timeoutId);\n\n        const requestId = res.headers.get(\"x-request-id\") ?? undefined;\n        const parsed = (await res.json().catch(() => null)) as\n          | SuccessEnvelope<unknown>\n          | PaginatedEnvelope<unknown>\n          | ErrorEnvelope\n          | null;\n\n        if (!res.ok) {\n          if (parsed && \"error\" in parsed && parsed.error) {\n            const err = toReaderApiError(parsed.error, res.status, requestId);\n\n            // Don't retry client errors except 429\n            if (res.status < 500 && res.status !== 429) throw err;\n\n            // Honor Retry-After from the rate-limited response\n            if (err instanceof RateLimitedError && err.retryAfterSeconds) {\n              await sleep(err.retryAfterSeconds * 1000);\n            }\n\n            lastError = err;\n          } else {\n            const genericErr = new ReaderApiError(\n              {\n                code: \"internal_error\",\n                message: `Request failed with status ${res.status}`,\n              },\n              res.status,\n              requestId,\n            );\n            if (res.status < 500) throw genericErr;\n            lastError = genericErr;\n          }\n        } else {\n          return parsed as unknown as T;\n        }\n      } catch (err) {\n        if (err instanceof ReaderApiError) {\n          if (err.httpStatus < 500 && err.httpStatus !== 429) throw err;\n          lastError = err;\n        } else if (err instanceof Error) {\n          if (err.name === \"AbortError\") {\n            lastError = new ReaderApiError(\n              { code: \"scrape_timeout\", message: \"Request timed out\" },\n              504,\n            );\n          } else {\n            lastError = err;\n          }\n        }\n      }\n\n      // Exponential backoff before retry\n      if (attempt < this.maxRetries) {\n        await sleep(Math.pow(2, attempt) * 1000);\n      }\n    }\n\n    throw (\n      lastError ??\n      new ReaderApiError({ code: \"internal_error\", message: \"Request failed\" }, 500)\n    );\n  }\n}\n\n// ─── Sessions API ────────────────────────────────────────────────────\n\ntype RequestFn = <T>(method: string, path: string, body?: unknown) => Promise<T>;\n\nclass SessionsAPI {\n  constructor(private request: RequestFn) {}\n\n  /**\n   * Create a browser session. Returns a CDP WebSocket URL for\n   * Playwright/Puppeteer connection.\n   */\n  async create(params?: CreateSessionParams): Promise<SessionInfo> {\n    const envelope = await this.request<SuccessEnvelope<SessionInfo>>(\n      \"POST\",\n      \"/v1/sessions\",\n      params ?? {},\n    );\n    return envelope.data;\n  }\n\n  /**\n   * Get session status.\n   */\n  async get(sessionId: string): Promise<SessionInfo> {\n    const envelope = await this.request<SuccessEnvelope<SessionInfo>>(\n      \"GET\",\n      `/v1/sessions/${sessionId}`,\n    );\n    return envelope.data;\n  }\n\n  /**\n   * Stop a browser session.\n   */\n  async stop(sessionId: string): Promise<StopSessionResult> {\n    const envelope = await this.request<SuccessEnvelope<StopSessionResult>>(\n      \"DELETE\",\n      `/v1/sessions/${sessionId}`,\n    );\n    return envelope.data;\n  }\n\n  /**\n   * List active sessions.\n   */\n  async list(): Promise<SessionInfo[]> {\n    const envelope = await this.request<SuccessEnvelope<SessionInfo[]>>(\n      \"GET\",\n      \"/v1/sessions\",\n    );\n    return envelope.data;\n  }\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,403 @@
+/**
+ * Reader SDK types. Shapes mirror the reader-api envelope contract.
+ */
+interface ReaderClientConfig {
+    /** API key (required) */
+    apiKey: string;
+    /** API base URL (default: https://api.reader.dev) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 60000) */
+    timeout?: number;
+    /** Max retries on transient failures (default: 2) */
+    maxRetries?: number;
+    /** Extra headers to include in every request (e.g. x-request-id for tracing) */
+    headers?: Record<string, string>;
+}
+/** Public proxy mode. `auto` picks standard first and escalates to stealth on block. */
+type ProxyMode = "standard" | "stealth" | "auto";
+interface ReadParams {
+    /** Single URL to scrape */
+    url?: string;
+    /** Multiple URLs for batch scraping */
+    urls?: string[];
+    /** Output formats (default: ["markdown"]) */
+    formats?: Array<"markdown" | "html">;
+    /** Extract main content only (default: true) */
+    onlyMainContent?: boolean;
+    /** CSS selectors to include */
+    includeTags?: string[];
+    /** CSS selectors to exclude */
+    excludeTags?: string[];
+    /** Wait for CSS selector before scraping */
+    waitForSelector?: string;
+    /** Per-URL timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** Proxy mode: standard, stealth, or auto (default: auto) */
+    proxyMode?: ProxyMode;
+    /** Max crawl depth (triggers crawl mode) */
+    maxDepth?: number;
+    /** Max pages to crawl (triggers crawl mode) */
+    maxPages?: number;
+    /** Use cache (default: true) */
+    cache?: boolean;
+    /** Webhook for async job notifications */
+    webhook?: {
+        url: string;
+        events?: string[];
+        secret?: string;
+    };
+    /** Batch concurrency override */
+    batchConcurrency?: number;
+}
+interface ScrapeMetadata {
+    title?: string | null;
+    description?: string | null;
+    statusCode?: number;
+    duration: number;
+    cached: boolean;
+    /** Resolved proxy mode — `"standard"` or `"stealth"`. Omitted on cache hits. */
+    proxyMode?: "standard" | "stealth";
+    /** True if `auto` escalated from standard to stealth for this page. */
+    proxyEscalated?: boolean;
+    scrapedAt: string;
+}
+interface Page {
+    url: string;
+    markdown?: string;
+    html?: string;
+    statusCode?: number;
+    proxyMode?: "standard" | "stealth";
+    proxyEscalated?: boolean;
+    credits?: number;
+    metadata?: ScrapeMetadata | Record<string, unknown>;
+    error?: string;
+}
+/** Result of a synchronous scrape — single URL, returned immediately. */
+interface ScrapeResult {
+    url: string;
+    /** Final URL after redirects (only present if different from `url`) */
+    finalUrl?: string;
+    markdown?: string;
+    html?: string;
+    metadata: ScrapeMetadata;
+}
+type JobStatus = "queued" | "processing" | "completed" | "failed" | "cancelled";
+type JobMode = "scrape" | "batch" | "crawl";
+/** Job as returned from GET /v1/jobs/:id (data portion of envelope). */
+interface Job {
+    id: string;
+    status: JobStatus;
+    mode: JobMode;
+    completed: number;
+    total: number;
+    creditsUsed: number;
+    error: string | null;
+    /** Paginated page results. `waitForJob` auto-collects all pages across pages. */
+    results: Page[];
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+}
+interface Pagination {
+    total: number;
+    skip: number;
+    limit: number;
+    hasMore: boolean;
+    next?: string;
+}
+/** Return type of `client.read(...)`. Discriminated by `kind`. */
+type ReadResult = {
+    kind: "scrape";
+    data: ScrapeResult;
+} | {
+    kind: "job";
+    data: Job;
+};
+interface Credits {
+    balance: number;
+    limit: number;
+    used: number;
+    tier: "free" | "pro" | "business" | "enterprise" | string;
+    resetAt: string;
+}
+interface UsageEntry {
+    id: string;
+    url: string;
+    duration: number;
+    status: "success" | "error";
+    cached: boolean;
+    proxyMode: "standard" | "stealth" | null;
+    credits: number;
+    error: string | null;
+    createdAt: string;
+}
+type StreamEvent = {
+    type: "progress";
+    completed: number;
+    total: number;
+    status: JobStatus;
+} | {
+    type: "page";
+    data: Page;
+} | {
+    type: "error";
+    url: string;
+    error: string;
+} | {
+    type: "done";
+    completed: number;
+    total: number;
+    status: JobStatus;
+};
+interface SuccessEnvelope<T> {
+    success: true;
+    data: T;
+}
+interface PaginatedEnvelope<T> {
+    success: true;
+    data: T[];
+    pagination: Pagination;
+}
+interface ErrorEnvelope {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+        docsUrl?: string;
+    };
+}
+type ApiEnvelope<T> = SuccessEnvelope<T> | ErrorEnvelope;
+type SessionStatus = "active" | "stopped" | "expired";
+interface SessionInfo {
+    sessionId: string;
+    wsEndpoint: string;
+    token: string;
+    status: SessionStatus;
+    createdAt: string;
+    expiresAt: string;
+}
+interface CreateSessionParams {
+    /** Max session lifetime in ms (default: 3600000 = 60 min) */
+    maxDurationMs?: number;
+}
+interface StopSessionResult {
+    sessionId: string;
+    status: "stopped";
+    durationMs: number;
+    creditsCharged: number;
+}
+
+/**
+ * Reader SDK Client
+ *
+ * @example
+ * import { ReaderClient } from "@vakra-dev/reader-js";
+ *
+ * const client = new ReaderClient({ apiKey: "rdr_your_key" });
+ *
+ * // Synchronous scrape (single URL)
+ * const result = await client.read({ url: "https://example.com" });
+ * if (result.kind === "scrape") {
+ *   console.log(result.data.markdown);
+ * }
+ *
+ * // Batch (returns a completed Job with all results collected)
+ * const batch = await client.read({ urls: ["url1", "url2"] });
+ * if (batch.kind === "job") {
+ *   for (const page of batch.data.results) {
+ *     console.log(page.url, page.markdown?.length);
+ *   }
+ * }
+ */
+
+declare class ReaderClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private maxRetries;
+    private extraHeaders;
+    private _sessions;
+    constructor(config: ReaderClientConfig);
+    /**
+     * Browser sessions API.
+     *
+     * @example
+     * ```typescript
+     * const session = await client.sessions.create();
+     * const browser = await chromium.connectOverCDP(session.wsEndpoint);
+     * // ... use Playwright ...
+     * await client.sessions.stop(session.sessionId);
+     * ```
+     */
+    get sessions(): SessionsAPI;
+    /**
+     * Read (scrape, batch, or crawl) one or more URLs.
+     *
+     * - Single URL → sync scrape, returns immediately with `{ kind: "scrape", data }`
+     * - Multiple URLs or URL + maxDepth/maxPages → async job; this method polls
+     *   until the job terminates and returns `{ kind: "job", data }`.
+     */
+    read(params: ReadParams): Promise<ReadResult>;
+    /**
+     * Get job status and a single page of results.
+     */
+    getJob(jobId: string, opts?: {
+        skip?: number;
+        limit?: number;
+    }): Promise<{
+        job: Job;
+        hasMore: boolean;
+        next?: string;
+    }>;
+    /**
+     * Fetch all job result pages by following pagination.
+     */
+    getAllJobResults(jobId: string): Promise<Page[]>;
+    /**
+     * Cancel a job. Throws `ConflictError` if the job is already terminal.
+     */
+    cancelJob(jobId: string): Promise<void>;
+    /**
+     * Retry the failed URLs in a job. Throws `InvalidRequestError` if no
+     * failed URLs exist.
+     */
+    retryJob(jobId: string): Promise<{
+        id: string;
+        status: string;
+        retrying: number;
+    }>;
+    /**
+     * Poll a job until it completes, fails, or is cancelled. Collects all
+     * paginated results when complete.
+     */
+    waitForJob(jobId: string, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<Job>;
+    /**
+     * Stream job results as they arrive via polling.
+     *
+     * @example
+     * for await (const event of client.stream(jobId)) {
+     *   if (event.type === "page") console.log(event.data.url);
+     *   if (event.type === "done") break;
+     * }
+     */
+    stream(jobId: string, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): AsyncGenerator<StreamEvent>;
+    /**
+     * Get the current credit balance for this workspace.
+     */
+    getCredits(): Promise<Credits>;
+    private request;
+}
+type RequestFn = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+declare class SessionsAPI {
+    private request;
+    constructor(request: RequestFn);
+    /**
+     * Create a browser session. Returns a CDP WebSocket URL for
+     * Playwright/Puppeteer connection.
+     */
+    create(params?: CreateSessionParams): Promise<SessionInfo>;
+    /**
+     * Get session status.
+     */
+    get(sessionId: string): Promise<SessionInfo>;
+    /**
+     * Stop a browser session.
+     */
+    stop(sessionId: string): Promise<StopSessionResult>;
+    /**
+     * List active sessions.
+     */
+    list(): Promise<SessionInfo[]>;
+}
+
+/**
+ * Typed error classes mirroring the reader-api error code catalog.
+ *
+ * The API returns a stable `code` field on every error response. The SDK
+ * branches on that code and throws a specific subclass, so callers can
+ * write:
+ *
+ *   try {
+ *     await client.read({ url });
+ *   } catch (err) {
+ *     if (err instanceof InsufficientCreditsError) {
+ *       // err.required, err.available, err.resetAt
+ *     }
+ *   }
+ *
+ * There is one subclass per code in the catalog. Unknown codes fall through
+ * to the base `ReaderApiError`.
+ */
+type ReaderErrorCode = "invalid_request" | "unauthenticated" | "insufficient_credits" | "url_blocked" | "not_found" | "conflict" | "rate_limited" | "concurrency_limited" | "internal_error" | "upstream_unavailable" | "scrape_timeout";
+interface ApiErrorBody {
+    code: ReaderErrorCode | string;
+    message: string;
+    details?: Record<string, unknown>;
+    docsUrl?: string;
+}
+declare class ReaderApiError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly details?: Record<string, unknown>;
+    readonly docsUrl?: string;
+    readonly requestId?: string;
+    constructor(body: ApiErrorBody, httpStatus: number, requestId?: string);
+}
+declare class InvalidRequestError extends ReaderApiError {
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class UnauthenticatedError extends ReaderApiError {
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class InsufficientCreditsError extends ReaderApiError {
+    readonly required?: number;
+    readonly available?: number;
+    readonly resetAt?: string;
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class UrlBlockedError extends ReaderApiError {
+    readonly url?: string;
+    readonly reason?: string;
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class NotFoundError extends ReaderApiError {
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class ConflictError extends ReaderApiError {
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class RateLimitedError extends ReaderApiError {
+    readonly retryAfterSeconds?: number;
+    readonly limit?: number;
+    readonly windowSeconds?: number;
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class ConcurrencyLimitedError extends ReaderApiError {
+    readonly active?: number;
+    readonly max?: number;
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class InternalServerError extends ReaderApiError {
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class UpstreamUnavailableError extends ReaderApiError {
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+declare class ScrapeTimeoutError extends ReaderApiError {
+    readonly timeoutMs?: number;
+    constructor(body: ApiErrorBody, status: number, requestId?: string);
+}
+/**
+ * Construct the right error subclass from an error response body.
+ * Unknown codes fall through to the base class.
+ */
+declare function toReaderApiError(body: ApiErrorBody, httpStatus: number, requestId?: string): ReaderApiError;
+
+export { type ApiEnvelope, type ApiErrorBody, ConcurrencyLimitedError, ConflictError, type CreateSessionParams, type Credits, type ErrorEnvelope, InsufficientCreditsError, InternalServerError, InvalidRequestError, type Job, type JobMode, type JobStatus, NotFoundError, type Page, type PaginatedEnvelope, type Pagination, type ProxyMode, RateLimitedError, type ReadParams, type ReadResult, ReaderApiError, ReaderClient, type ReaderClientConfig, type ReaderErrorCode, type ScrapeMetadata, type ScrapeResult, ScrapeTimeoutError, type SessionInfo, type SessionStatus, type StopSessionResult, type StreamEvent, type SuccessEnvelope, UnauthenticatedError, UpstreamUnavailableError, UrlBlockedError, type UsageEntry, toReaderApiError };