@octocrawl/sdk 0.3.0

package/dist/types/cjs/client.d.ts

@@ -0,0 +1,362 @@
+import type { ActiveCrawlList, CrawlAccepted, DeliveryDestination, DeliveryDestinationInput, DeliveryDetail, DeliveryQuery, DeliveryPage, DeliveryPageQuery, WebhookDelivery, CrawlError, CrawlPage, CrawlPageList, CrawlPageQuery, CrawlReport, CrawlStartRequest, BatchAccepted, BatchErrorsQuery, BatchErrorsResponse, BatchStartRequest, BatchStatusResponse, BatchHandoffRequest, BatchHandoffResponse, LoginImportRequest, LoginImportResponse, SavedLogin, CompactScrapeResponse, MapRecord, MapRequest, MapResponse, MonitorRevision, MonitorView, MonitorPreview, MonitorRun, MonitorRunDetail, ScrapeRecord, ScrapeRequest, ScrapeResponse } from './contracts/index.js';
+import { RATE_LIMITED_CODE, type ApiErrorCode } from './contracts/index.js';
+import { JobWatcher, type WatchOptions } from './watcher.js';
+export interface W2LOptions {
+    baseUrl: string;
+    /**
+     * Bearer token for a server started with a token. Omitted, the
+     * W2L_API_TOKEN environment variable is used where there is one; '' sends
+     * no token.
+     */
+    token?: string;
+    fetch?: typeof fetch;
+}
+/** A scrape's options as a caller sends them: `handoff` as `true` or `{ waitMs }` (the API reads `true` as `{}`). */
+export type ScrapeOptions = Omit<ScrapeRequest, 'url' | 'handoff'> & {
+    handoff?: boolean | {
+        waitMs?: number;
+    };
+};
+/** How long past a map's own deadline (its `timeout`, 60 000 ms by default) the SDK waits for the API's answer: Firecrawl's timeout + 5000 convention. */
+export declare const MAP_ANSWER_MARGIN_MS = 5000;
+/**
+ * Cancels the HTTP request and the current execution of synchronous scrape/runMonitor.
+ * Use cancelCrawl for an already-created background crawl, or cancelMonitorRun for explicit persisted run control.
+ */
+export interface RequestOptions {
+    signal?: AbortSignal;
+    /**
+     * The `origin` a scrape, crawl or batch is recorded under when its options
+     * set none: a host built on the SDK (the MCP server) names its own client
+     * here. The default is `js-sdk@<SDK_VERSION>`.
+     */
+    origin?: string;
+}
+/** What the SDK records as `origin` unless the caller or the host says otherwise. */
+export declare const SDK_ORIGIN = "js-sdk@0.3.0";
+/**
+ * Polling for waitBatch and waitCrawl. A status request that fails with a
+ * network error, HTTP 408, 429 or 5xx is retried: after 1, 2, 4, 8, then
+ * 10 s, or after the response's Retry-After when it asks for a minute or
+ * less. Any other error ends the wait at once.
+ */
+export interface WaitOptions extends RequestOptions {
+    /** Delay between status requests. Default 500 ms. */
+    pollIntervalMs?: number;
+    /**
+     * Stop waiting after this long, a status request in flight or a retry's
+     * wait included, and throw a WaitTimeoutError. Default: no limit. The task
+     * keeps running.
+     */
+    timeoutMs?: number;
+    /** Consecutive failed status requests retried before the last error is thrown. Default 5; 0 retries none. */
+    maxRetries?: number;
+}
+/**
+ * The task was still unfinished when the wait's timeoutMs ran out. `last` is
+ * the final status read, null when no status request answered in time;
+ * `cause` is the error of the last status request that failed, when no
+ * status was read after it.
+ */
+export declare class WaitTimeoutError<T extends {
+    status: string;
+} = {
+    status: string;
+}> extends Error {
+    readonly taskId: string;
+    readonly last: T | null;
+    readonly timeoutMs: number;
+    readonly name = "WaitTimeoutError";
+    constructor(taskId: string, last: T | null, timeoutMs: number, options?: {
+        cause?: unknown;
+    });
+}
+/** What `appendToBatch` may send beside the URLs: what binds to them, and the attribution labels; the job's own options stay as they are. */
+export type AppendToBatchOptions = Pick<BatchStartRequest, 'ignoreInvalidURLs' | 'idempotencyKey' | 'robotsOverrides' | 'origin' | 'integration'>;
+/** How `batchScrapeChunked` splits a list and waits for each job (Python's `process_large_batch`: `chunk_size`, `poll_interval`, `timeout` are `chunkSize`, `pollIntervalMs`, `timeoutMs`). */
+export interface ChunkedBatchOptions extends WaitOptions {
+    /** URLs per job, 1 to 1000. Default 100. */
+    chunkSize?: number;
+    /** Items per request while a job's items are listed, 1 to 50. Default 50. */
+    itemLimit?: number;
+}
+/** One job `batchScrapeChunked` ran: its id, how many URLs it was given, its final status and the entries it skipped. */
+export interface ChunkedBatchJob {
+    taskId: string;
+    urls: number;
+    report: BatchStatusResponse;
+    invalidURLs?: string[];
+}
+/** `batchScrapeChunked`'s result: the jobs in submission order, every item of every job in the order the URLs were submitted, and every entry `ignoreInvalidURLs` skipped. */
+export interface ChunkedBatchResult {
+    jobs: ChunkedBatchJob[];
+    items: CrawlPage[];
+    invalidURLs: string[];
+}
+/** crawlAndWait's result: the final status, every page and every error of the crawl's latest attempt. */
+export interface CrawlCollected {
+    taskId: string;
+    report: CrawlReport;
+    pages: CrawlPage[];
+    errors: CrawlError[];
+}
+/** batchAndWait's result: the final status and every item, failed ones included. */
+export interface BatchCollected {
+    taskId: string;
+    report: BatchStatusResponse;
+    items: CrawlPage[];
+}
+/**
+ * Caps on a listing that follows cursors (listCrawlPages, listBatchItems,
+ * getCrawlDocuments, getBatchDocuments). None by default: the listing reads to
+ * the end. With `maxResults` each page is requested no larger than what is
+ * still wanted, so the cursor the listing stops at continues exactly where it
+ * left off.
+ */
+export interface PaginationLimits {
+    /** Pages read after the first; 0 reads the first page alone. */
+    maxPages?: number;
+    /** Items returned in all, at least 1. */
+    maxResults?: number;
+    /** Once this many milliseconds have passed since the first page was requested, no further page is requested. */
+    maxWaitMs?: number;
+}
+/** Why a bounded listing stopped: the last page (`end`), or the limit that stopped it with pages still unread. */
+export type PaginationStop = 'end' | 'maxPages' | 'maxResults' | 'maxWait';
+/** Where a bounded listing stopped: the cursor of the first page it did not read (null at the end) and what stopped it. */
+export interface PaginationEnd {
+    nextCursor: string | null;
+    stoppedBy: PaginationStop;
+}
+/** The items a bounded listing read, with where it stopped; `hasMore` is whether a page remains. */
+export interface PageCollection<T> extends PaginationEnd {
+    items: T[];
+    hasMore: boolean;
+}
+/** A crawl's status with its pages, as one answer: the latest attempt's pages unless `attemptId` is given. */
+export interface CrawlDocuments extends PaginationEnd {
+    report: CrawlReport;
+    pages: CrawlPage[];
+}
+/** A batch's status with its items, as one answer. */
+export interface BatchDocuments extends PaginationEnd {
+    report: BatchStatusResponse;
+    items: CrawlPage[];
+}
+/** A page listing's query (`limit`, `attemptId`, `debug`, `includeDuplicates`) with the caps on how far it follows cursors. */
+export type PagedListOptions = Omit<CrawlPageQuery, 'cursor'> & PaginationLimits;
+/**
+ * Split a URL list into lists of at most `chunkSize` (default 100), in order;
+ * an empty list gives none. Firecrawl's JS helper of the same name, exported
+ * here. `batchScrapeChunked` runs one batch per chunk.
+ */
+export declare function chunkUrls(urls: readonly string[], chunkSize?: number): string[][];
+/**
+ * The API answered with an error status. `code` is the API error code when the
+ * body carried one (`rate_limited` for HTTP 429); `body` is the parsed JSON
+ * body, or its text if it was not JSON. The SDK retries no 429 itself: a
+ * caller waits `retryAfterMs` and asks again.
+ */
+export declare class W2LError extends Error {
+    readonly status: number;
+    readonly code: ApiErrorCode | typeof RATE_LIMITED_CODE | undefined;
+    readonly method: 'GET' | 'POST' | 'DELETE';
+    readonly path: string;
+    readonly body: unknown;
+    /** The response's Retry-After in milliseconds; null when it sent none or one that does not parse. */
+    readonly retryAfterMs: number | null;
+    /** The body's `agentHints` (the next honest step for a refused option, the wait for a rate limit); empty when it carried none. */
+    readonly agentHints: readonly string[];
+    readonly name = "W2LError";
+    constructor(message: string, status: number, code: ApiErrorCode | typeof RATE_LIMITED_CODE | undefined, method: 'GET' | 'POST' | 'DELETE', path: string, body: unknown, 
+    /** The response's Retry-After in milliseconds; null when it sent none or one that does not parse. */
+    retryAfterMs?: number | null, 
+    /** The body's `agentHints` (the next honest step for a refused option, the wait for a rate limit); empty when it carried none. */
+    agentHints?: readonly string[]);
+}
+export type CreateMonitorRequest = (Omit<MonitorRevision, 'createdAt'> & {
+    enabled?: boolean;
+}) | {
+    preset: 'firecrawl-introduction';
+    enabled?: boolean;
+};
+export type ReviseMonitorRequest = Omit<MonitorRevision, 'monitorId' | 'createdAt'>;
+export interface RunMonitorRequest {
+    /** Reusing a key replays the same logical run within this monitor. */
+    triggerKey?: string;
+}
+export declare class W2L {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    /** The platform's fetch, not one passed in options, whose own limits are the caller's. */
+    private readonly platformFetch;
+    constructor(options: W2LOptions);
+    scrape(url: string, opts: ScrapeOptions & {
+        debug: false;
+    }, request?: RequestOptions): Promise<CompactScrapeResponse>;
+    scrape(url: string, opts?: ScrapeOptions, request?: RequestOptions): Promise<ScrapeResponse>;
+    /** The record of one scrape call, by the `scrapeId` its response carried (`metadata.scrapeId`); a W2LError with code `not_found` for an id the server has no record of. */
+    getScrape(id: string, request?: RequestOptions): Promise<ScrapeRecord>;
+    /**
+     * The URLs of a site from its sitemaps and its start page's links, without
+     * fetching each page (POST /v1/map). The API answers by the map's deadline
+     * with what it found; the SDK waits that long plus MAP_ANSWER_MARGIN_MS.
+     */
+    map(url: string, opts?: Omit<MapRequest, 'url'>, request?: RequestOptions): Promise<MapResponse>;
+    /** The record of one map, by the `id` its response carried; a W2LError with code `not_found` for an id the server has no record of. */
+    getMap(id: string, request?: RequestOptions): Promise<MapRecord>;
+    crawl(url: string, opts?: Omit<CrawlStartRequest, 'url'>, request?: RequestOptions): Promise<CrawlAccepted>;
+    /**
+     * Starts a batch: `{ taskId }`, plus `invalidURLs` (the entries skipped)
+     * when `ignoreInvalidURLs` was on; with `idempotencyKey` a retried start
+     * returns the first one's answer with `replayed: true`; with `appendToId`
+     * the URLs join that batch (see appendToBatch) and the answer carries
+     * `requested` and `appended`.
+     */
+    batchScrape(urls: readonly string[], opts?: Omit<BatchStartRequest, 'urls'>, request?: RequestOptions): Promise<BatchAccepted>;
+    /**
+     * Adds URLs to an existing batch (`appendToId`): the job keeps its mode,
+     * formats, includeLinks, maxConcurrency and page options, and its run picks
+     * the URLs up (a completed batch runs again for them). The answer carries
+     * `requested`, the job's URLs now, and `appended`. A cancelled or failed
+     * batch, a total over 1000 or a URL already in the batch is a W2LError.
+     */
+    appendToBatch(id: string, urls: readonly string[], opts?: AppendToBatchOptions, request?: RequestOptions): Promise<BatchAccepted>;
+    /**
+     * Runs a list of any length as batches of `chunkSize` URLs (default 100),
+     * one after another: each job is started, waited for (as waitBatch, with
+     * the WaitOptions) and listed before the next starts. The items are merged
+     * in the order the URLs were submitted; the jobs stay on the server as
+     * ordinary batches, each with its own task directory. A caller's
+     * `idempotencyKey` becomes `<key>:<chunkIndex>` per job, so a retry of the
+     * whole call replays the jobs that went through. A WaitTimeoutError or
+     * W2LError from any job ends the call, naming that job; the earlier jobs
+     * are complete and the later chunks were never sent.
+     */
+    batchScrapeChunked(urls: readonly string[], opts?: Omit<BatchStartRequest, 'urls' | 'appendToId'>, options?: ChunkedBatchOptions): Promise<ChunkedBatchResult>;
+    getBatch(id: string, request?: RequestOptions): Promise<BatchStatusResponse>;
+    /** The batch's failed, blocked, cancelled and budget-cut items across every attempt, in pages of up to 1000 (`limit`, `cursor`), with `robotsBlocked`, the URLs robots.txt refused. */
+    getBatchErrors(id: string, options?: BatchErrorsQuery, request?: RequestOptions): Promise<BatchErrorsResponse>;
+    getBatchItems(id: string, options?: CrawlPageQuery, request?: RequestOptions): Promise<CrawlPageList<CrawlPage>>;
+    /** Every item of a batch, page by page (at most 50 per request), or as many as the PaginationLimits allow; the generator's return value says where it stopped. */
+    listBatchItems(id: string, options?: PagedListOptions, request?: RequestOptions): AsyncGenerator<CrawlPage, PaginationEnd>;
+    /** The items listBatchItems would yield under the same options, collected, with where the listing stopped. */
+    collectBatchItems(id: string, options?: PagedListOptions, request?: RequestOptions): Promise<PageCollection<CrawlPage>>;
+    /** A batch's status and its items in one answer, every item unless the PaginationLimits stop the listing. */
+    getBatchDocuments(id: string, options?: PagedListOptions, request?: RequestOptions): Promise<BatchDocuments>;
+    /** Polls a batch until it completes, fails or is cancelled. Items come from listBatchItems. */
+    waitBatch(id: string, options?: WaitOptions): Promise<BatchStatusResponse>;
+    /** Starts a batch, waits for it (as waitBatch) and lists every item, failed ones included. */
+    batchAndWait(urls: readonly string[], opts?: Omit<BatchStartRequest, 'urls'>, wait?: WaitOptions): Promise<BatchCollected>;
+    /**
+     * Save the person's login to a site (a domain or a page URL) from the
+     * Chrome they use, as `octocrawl login import` does, on a server on their
+     * machine. Chrome asks them "Allow remote debugging?": the answer comes
+     * once they click Allow (within `approveTimeoutMs`, default 2 minutes).
+     * The saved login's cookies never leave the server: the answer names the
+     * domain, how many cookies and their hash.
+     */
+    importLogin(site: string, opts?: Omit<LoginImportRequest, 'site'>, request?: RequestOptions): Promise<LoginImportResponse>;
+    /** The person's saved logins, without their cookies. */
+    listLogins(request?: RequestOptions): Promise<{
+        logins: SavedLogin[];
+    }>;
+    /** Forget a saved login; a W2LError with code `not_found` when none was saved for the site. */
+    removeLogin(site: string, request?: RequestOptions): Promise<{
+        site: string;
+        removed: true;
+    }>;
+    /**
+     * Hands a finished batch's items that a check stopped (a captcha, a
+     * challenge, a login wall) to the person in their own Chrome, on a local
+     * server: each opens in a new tab, they get through it, and W2L reads the
+     * page there. Answers when every item is read or given up, so it waits for
+     * the person: `waitMs` is how long, per page (default 10 minutes). On
+     * Node the SDK waits for the answer as long as that takes (no 300 s limit
+     * on the response headers); `request.signal` ends the wait.
+     */
+    handOffBatch(id: string, body?: BatchHandoffRequest, request?: RequestOptions): Promise<BatchHandoffResponse>;
+    cancelBatch(id: string, request?: RequestOptions): Promise<BatchStatusResponse>;
+    /**
+     * Watches a crawl (`kind: 'crawl'`, the default) or a batch (`kind: 'batch'`)
+     * as it runs: `document` events with each page as it is recorded, `snapshot`
+     * events with the report, one `done` with the terminal report, or `error`.
+     * `transport: 'auto'` (default) tries the WebSocket route, then server-sent
+     * events, then polling (`pollIntervalMs`, default 2000, at least 250), each
+     * taking over from the last document seen; `timeoutMs` ends the watch with a
+     * `watcher_timeout` error while the job keeps running. `close()` stops
+     * watching only; cancelCrawl / cancelBatch stay explicit.
+     */
+    watcher(jobId: string, options?: WatchOptions): JobWatcher;
+    /** Starts a crawl and returns its watcher (as `crawl()` then `watcher(taskId, { kind: 'crawl' })`). */
+    crawlAndWatch(url: string, opts?: Omit<CrawlStartRequest, 'url'>, watch?: Omit<WatchOptions, 'kind'>, request?: RequestOptions): Promise<JobWatcher>;
+    /** Starts a batch and returns its watcher (as `batchScrape()` then `watcher(taskId, { kind: 'batch' })`). */
+    batchScrapeAndWatch(urls: readonly string[], opts?: Omit<BatchStartRequest, 'urls'>, watch?: Omit<WatchOptions, 'kind'>, request?: RequestOptions): Promise<JobWatcher>;
+    /** What a watcher needs of this client: the server, the token and fetch it was given, and the routes it polls, each carrying the bearer header. */
+    private watcherClient;
+    getCrawl(id: string, request?: RequestOptions): Promise<CrawlReport>;
+    /** The crawls the API process is running, with each one's start URL, status, pages so far and options; empty when nothing runs. */
+    getActiveCrawls(request?: RequestOptions): Promise<ActiveCrawlList>;
+    /** Polls a crawl until it completes, fails or is cancelled. Pages come from listCrawlPages. */
+    waitCrawl(id: string, options?: WaitOptions): Promise<CrawlReport>;
+    /** Starts a crawl, waits for it (as waitCrawl) and lists every page and every error of its latest attempt. */
+    crawlAndWait(url: string, opts?: Omit<CrawlStartRequest, 'url'>, wait?: WaitOptions): Promise<CrawlCollected>;
+    getCrawlPages(id: string, options?: CrawlPageQuery, request?: RequestOptions): Promise<CrawlPageList<CrawlPage>>;
+    /**
+     * A crawl's pages, page by page, or as many as the PaginationLimits allow;
+     * the generator's return value says where it stopped. The latest attempt's
+     * pages unless `attemptId` names another; a resume with `useCached` records
+     * the pages it reuses in its new attempt, so that attempt normally holds
+     * every page.
+     */
+    listCrawlPages(id: string, options?: PagedListOptions, request?: RequestOptions): AsyncGenerator<CrawlPage, PaginationEnd>;
+    /** The pages listCrawlPages would yield under the same options, collected, with where the listing stopped. */
+    collectCrawlPages(id: string, options?: PagedListOptions, request?: RequestOptions): Promise<PageCollection<CrawlPage>>;
+    /** A crawl's status and its pages in one answer, every page unless the PaginationLimits stop the listing. */
+    getCrawlDocuments(id: string, options?: PagedListOptions, request?: RequestOptions): Promise<CrawlDocuments>;
+    /**
+     * Follow a listing's cursors within its limits. Each page is requested no
+     * larger than the items still wanted, so a stop at `maxResults` leaves a
+     * cursor that continues exactly after the last item returned. A page's
+     * `hasMore` without a cursor is the API breaking its contract and throws.
+     */
+    private paginate;
+    getCrawlErrors(id: string, options?: CrawlPageQuery, request?: RequestOptions): Promise<CrawlPageList<CrawlError>>;
+    cancelCrawl(id: string, request?: RequestOptions): Promise<CrawlReport>;
+    /** Restarts a paused or failed crawl with the options it was started with; follow it with waitCrawl. */
+    resumeCrawl(id: string, request?: RequestOptions): Promise<CrawlAccepted>;
+    createMonitor(input: CreateMonitorRequest, request?: RequestOptions): Promise<MonitorRevision>;
+    previewMonitor(input: CreateMonitorRequest, request?: RequestOptions): Promise<MonitorPreview>;
+    reviseMonitor(id: string, input: ReviseMonitorRequest, request?: RequestOptions): Promise<MonitorRevision>;
+    listMonitors(request?: RequestOptions): Promise<MonitorView[]>;
+    getMonitor(id: string, request?: RequestOptions): Promise<MonitorView>;
+    getMonitorRun(id: string, runId: string, request?: RequestOptions): Promise<MonitorRunDetail>;
+    /** Durable run: returns after enqueue; client disconnect does not cancel it. */
+    enqueueMonitorRun(id: string, input?: RunMonitorRequest, request?: RequestOptions): Promise<MonitorRun>;
+    /** Waits for capture and assessment; baseline/events are included in the returned view. */
+    runMonitor(id: string, input?: RunMonitorRequest, request?: RequestOptions): Promise<MonitorView>;
+    pauseMonitor(id: string, request?: RequestOptions): Promise<MonitorView>;
+    resumeMonitor(id: string, request?: RequestOptions): Promise<MonitorView>;
+    cancelMonitorRun(id: string, runId: string, request?: RequestOptions): Promise<MonitorView>;
+    createDeliveryDestination(input: DeliveryDestinationInput, request?: RequestOptions): Promise<DeliveryDestination>;
+    /** The destinations of a Monitor (`monitorId`) or of a crawl or batch (`jobId`); every destination when neither is given. Header names only, never their values. */
+    listDeliveryDestinations(options?: {
+        monitorId?: string;
+        jobId?: string;
+    }, request?: RequestOptions): Promise<DeliveryDestination[]>;
+    pauseDeliveryDestination(id: string, request?: RequestOptions): Promise<DeliveryDestination>;
+    resumeDeliveryDestination(id: string, request?: RequestOptions): Promise<DeliveryDestination>;
+    /** The deliveries of a Monitor (`monitorId`) or of a crawl or batch (`jobId`, the task id), each with its payload. */
+    listDeliveries(options?: DeliveryQuery, request?: RequestOptions): Promise<WebhookDelivery[]>;
+    getDeliveriesPage(options?: DeliveryPageQuery, request?: RequestOptions): Promise<DeliveryPage>;
+    getDelivery(id: string, request?: RequestOptions): Promise<DeliveryDetail>;
+    retryDelivery(id: string, request?: RequestOptions): Promise<WebhookDelivery>;
+    private waitFor;
+    private headers;
+    /** `answerWithinMs`: how long the platform's fetch waits for the response headers, on Node instead of undici's 300 s. */
+    private post;
+    private getPageList;
+    private get;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/types/cjs/contracts/access.d.ts

@@ -0,0 +1,166 @@
+/**
+ * BYO Proxy and Inherited Session: the user's own access, and the record that
+ * proves whose it was.
+ *
+ * WHY THIS EXISTS. When a site gates us, three answers are honest and one is
+ * not. Honest: run a real browser (more capability we legitimately have), use
+ * the user's own logged-in session, leave from the user's own network. Not
+ * honest: defeat the gate. `escalationForBlock` already encodes that ladder;
+ * this module is the configuration surface for its last two rungs.
+ *
+ * WHY IT IS NOT JUST CONFIG. Routing a fetch through a user's proxy or session
+ * moves real responsibility onto them — their IP is what the publisher sees,
+ * their account is what the ToS binds, their contract governs the egress. A
+ * product that quietly accepts a proxy URL and says nothing has taken their
+ * risk without their acknowledgement. So the transfer is recorded: every
+ * compliance record carries an `AccessFact` stating who owned the egress, who
+ * owned the session, and who attested to the right to use them. Signed, that
+ * is a artifact both sides can point at afterwards — which is the difference
+ * between transferring responsibility and merely assuming it transferred.
+ *
+ * WHAT MUST NEVER BE IN THE RECORD. Proxy passwords and cookie values are
+ * credentials. They are hashed, never stored: `proxyCredentialSha256` lets two
+ * records be recognized as using the same credential without disclosing it,
+ * which is what an auditor actually needs. A compliance record is meant to be
+ * handed to a publisher or a court; a record that leaks the user's session
+ * cookie would be a breach dressed as an attestation.
+ *
+ * WHAT THIS IS NOT. There is no fingerprint spoofing here, no CDP patching, no
+ * captcha solving, and no rotating pool. A proxy is an egress path the user
+ * already has the right to use; the honest-mode UA is sent through it
+ * unchanged, and the identity honesty check still applies.
+ *
+ * 换 IP ≠ 换身份. Locale, timezone, viewport, and Client Hints stay the
+ * mode's bundle. Retuning timezone to a proxy's geo is refused.
+ */
+/** Who owned the network path a fetch actually left through. */
+export type EgressOwner = 
+/** Our own network. We hold the responsibility. */
+'operator'
+/** The user's proxy. Their IP, their contract, their responsibility. */
+ | 'user';
+/** Whose authenticated state, if any, a fetch carried. */
+export type SessionOwner = 
+/** No session; the fetch was anonymous. */
+'none'
+/** The user's own logged-in state, supplied by them. */
+ | 'user';
+/**
+ * A proxy the user brings. `url` carries scheme://host:port ONLY — credentials
+ * go in the separate fields so they are never accidentally logged, serialized
+ * into a trace, or embedded in an error message alongside the endpoint.
+ * `normalizeProxyConfig` enforces this rather than trusting the caller.
+ */
+export interface ProxyConfig {
+    /** e.g. `http://proxy.example:8080`. Userinfo here is stripped, not honoured. */
+    url: string;
+    username?: string;
+    password?: string;
+}
+/** One cookie of an inherited session, in the shape Playwright accepts. */
+export interface SessionCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * The user's own logged-in state. Either explicit cookies or an opaque
+ * Playwright storageState blob; both are credentials and both are hashed
+ * rather than recorded.
+ */
+export interface SessionConfig {
+    cookies?: readonly SessionCookie[];
+    /** Serialized Playwright storageState JSON. */
+    storageState?: string;
+}
+/**
+ * The user's explicit acknowledgement that they hold the right to use the
+ * proxy and session they supplied, and that fetches made through them are
+ * theirs. Required — `normalizeAccessConfig` rejects a proxy or session
+ * without one, because an unattested transfer is not a transfer.
+ */
+export interface AccessAttestation {
+    /** Identifier for the accepting principal: account id, email, org handle. */
+    principal: string;
+    /** ISO timestamp of acceptance. */
+    at: string;
+    /**
+     * What they accepted, verbatim. Stored in the record so the claim can be
+     * read later without trusting our summary of it.
+     */
+    statement: string;
+}
+export interface AccessConfig {
+    proxy?: ProxyConfig | null;
+    session?: SessionConfig | null;
+    attestation?: AccessAttestation | null;
+}
+/**
+ * The recorded, credential-free facts about whose access a fetch used. This is
+ * the field that makes the responsibility transfer provable; it is part of the
+ * canonical serialization, so it is covered by the record's contentHash and by
+ * any signature over it.
+ */
+export interface AccessFact {
+    egressOwner: EgressOwner;
+    /**
+     * `scheme://host:port` of the proxy, with any userinfo removed. Null under
+     * operator egress. The endpoint is not a secret and an auditor needs it;
+     * the credential is a secret and appears only as a hash.
+     */
+    proxyEndpoint: string | null;
+    /**
+     * sha256 of the proxy credential. Recognizes reuse across records without
+     * disclosing the credential. Null when the proxy needs no credential.
+     */
+    proxyCredentialSha256: string | null;
+    sessionOwner: SessionOwner;
+    /** sha256 of the session material. Null when no session was supplied. */
+    sessionSha256: string | null;
+    /** Principal who accepted responsibility. Null under operator egress. */
+    attestedBy: string | null;
+    /** ISO timestamp of that acceptance. Null under operator egress. */
+    attestedAt: string | null;
+    /** The statement they accepted, verbatim. Null under operator egress. */
+    attestationStatement: string | null;
+}
+/**
+ * The default: we supplied the egress, no session, nobody else's
+ * responsibility. Stated explicitly rather than left absent — "we did not
+ * track this" and "this was ours" are different claims, and a record that
+ * cannot tell them apart is not much of a record.
+ */
+export declare const OPERATOR_ACCESS_FACT: AccessFact;
+/**
+ * What the caller must supply for a given escalation target. Returned to a
+ * blocked caller so the guidance is a machine-readable requirement, not a
+ * sentence in a log line.
+ */
+export type AccessRequirement = 
+/** Nothing more is needed; we can run this lane ourselves. */
+'none'
+/** The user's own logged-in session (cookies or storageState). */
+ | 'session'
+/** The user's own proxy. */
+ | 'proxy';
+export interface AccessGuidance {
+    requirement: AccessRequirement;
+    /** Why this is being asked for, in one sentence the caller can surface. */
+    rationale: string;
+}
+/**
+ * The access a lane needs from the user. Lanes we can run on our own return
+ * `none`; the two user-access lanes name what they need and why.
+ *
+ * Note what is NOT here: no lane's requirement is "solve the challenge" or
+ * "rotate to a fresh IP". `provider` returns `none` because the provider lane
+ * is our own contracted capacity, not the user's — its own gating lives in the
+ * provider adapter's robots check, not here.
+ */
+export declare function accessGuidanceForLane(lane: string): AccessGuidance;
+//# sourceMappingURL=access.d.ts.map