@vakra-dev/reader-js 0.2.0

package/dist/index.d.ts

@@ -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 };