@unfenced-ai/sdk 0.1.0

package/dist/protocol.d.ts

@@ -0,0 +1,296 @@
+/**
+ * The wire, declared once.
+ *
+ * Every client of the unfenced server needs the same handful of shapes — the
+ * cleaned document, the fetch metadata, the outcome envelope — and until this
+ * file existed each one declared its own. Three copies of `ExtractedDoc` were in
+ * the tree at the same time: `packages/extract/src/types.ts` (the producer, 21
+ * fields), this package (8 fields plus `[key: string]: unknown`), and
+ * `packages/ui/src/api.ts` (15 fields, hand-typed). They disagreed, and the
+ * disagreement was invisible: an index signature makes `doc.markdwn` compile and
+ * return `undefined`, and a field the dashboard never declared is a field no
+ * dashboard view can render.
+ *
+ * @unfenced-ai/sdk is the right home for it. It has no runtime dependencies and is
+ * meant to keep none, so a browser bundle can carry it; every other client
+ * already depends on it; and it is one of the two packages that actually
+ * publish, so its types are the ones a stranger receives.
+ *
+ * WHY THIS FILE IS SEPARATE FROM `index.ts`: this module is pure declaration —
+ * no imports, no client, no `fetch`. `packages/ui` may therefore
+ * `import type` from it and get the types with nothing to erase, honouring the
+ * boundary in docs/ARCHITECTURE.md that the dashboard owns no `@unfenced/*`
+ * runtime import. Importing `index.ts` would put the `Unfenced` class in the
+ * dashboard's module graph for a type it does not need.
+ *
+ * THIS IS STILL A MIRROR, and mirrors drift — that is the whole reason this file
+ * exists. So it is BOUND rather than trusted: `test/wire-contract.test.ts` reads
+ * the producer's own declarations off disk and fails when a field is renamed,
+ * dropped or added on either side. See that file for why the binding runs
+ * against the source rather than against a live server.
+ */
+/** Which payload the server renders as `content`. */
+export type OutputFormat = "markdown" | "json" | "text" | "html";
+/** 1 = plain HTTP, 2 = stealth headless browser, 3 = headed browser. */
+export type Tier = 1 | 2 | 3;
+export interface ContentOmission {
+    kind: "hidden-text" | "listing-prose" | "pdf-page-cap" | "settle-timeout" | "byte-cap" | "word-cap" | "character-cap" | "navigation-incomplete";
+    amount?: number;
+    unit?: "words" | "pages" | "bytes" | "characters";
+}
+export interface LinkRef {
+    /** Absolute when the page had a base URL to resolve against, else the raw href. */
+    url: string;
+    /** Anchor text, whitespace-collapsed. */
+    text: string;
+}
+export interface ImageRef {
+    src: string;
+    alt: string;
+    title?: string;
+}
+export type StructuredDataKind = "ld+json" | "next-data" | "initial-state" | "embedded-json";
+export interface StructuredDatum {
+    kind: StructuredDataKind;
+    /** Where it came from, e.g. `script#__NEXT_DATA__` or `window.__INITIAL_STATE__`. */
+    source: string;
+    data: unknown;
+}
+/** What kind of other address the page declared for itself. */
+export type AlternateKind = "markdown" | "amp" | "feed" | "canonical" | "print" | "language" | "other";
+export interface Alternate {
+    kind: AlternateKind;
+    /** Absolute, resolved against the document's base. */
+    url: string;
+    /** The MIME type the document declared, verbatim, or null. */
+    type: string | null;
+    title: string | null;
+    /** Present on language alternates: "de", "en-GB", "x-default". */
+    hreflang: string | null;
+}
+/** How the main content was isolated. Useful for judging a bad extraction. */
+export type ExtractionMethod = "readability" | "heuristic" | "whole-body" | "listing" | "thread" | "plain-text"
+/** A PDF's own text layer. Never OCR: a scan has no text layer to read. */
+ | "pdf";
+export type PageType = "article" | "listing" | "thread" | "data" | "feed";
+/**
+ * How much to trust that what came back is what the URL is about.
+ *
+ * `low` does not mean the content is useless — it means check before relying on
+ * it. The canonical case is a login wall: the extractor cleanly pulls the
+ * suggestions sidebar and reports a tidy result about the wrong thing.
+ */
+export interface ContentConfidence {
+    level: "high" | "low";
+    /** Plain-language reasons, safe to show an agent or a human. */
+    reasons: string[];
+}
+/**
+ * The cleaned document a fetch returns — the whole of it.
+ *
+ * Produced by `packages/extract/src/index.ts#extractDoc` and passed to the
+ * client untouched: core caps `markdown` and `text` when `maxWords` bites
+ * (`packages/core/src/fetch.ts#capRendered`) and the job route sends the result
+ * verbatim (`packages/server/src/routes/jobs.ts`, `result: job.result`).
+ * Nothing in between adds or removes a field, which is what lets the contract
+ * test bind this declaration to the producer's.
+ *
+ * There is deliberately NO index signature. The previous one made every typo a
+ * silent `undefined` on the primary return value of the client library, and it
+ * let thirteen real fields go undeclared for as long as nobody noticed.
+ */
+export interface ExtractedDoc {
+    /** The URL the document was extracted for, or null when none was supplied. */
+    url: string | null;
+    title: string;
+    description: string | null;
+    author: string | null;
+    /** ISO 8601, normalised from whichever of three sources answered. */
+    publishedAt: string | null;
+    siteName: string | null;
+    lang: string | null;
+    dir: "ltr" | "rtl" | null;
+    /** Main content as markdown. Always populated. */
+    markdown: string;
+    /** Main content as plain text. Always populated. */
+    text: string;
+    /** Cleaned main-content HTML (not the full page). */
+    contentHtml: string;
+    links: LinkRef[];
+    images: ImageRef[];
+    structuredData: StructuredDatum[];
+    /**
+     * Other addresses this page says it has: a markdown twin, an AMP document, a
+     * feed, a canonical, a translation. Each is the SITE declaring an
+     * equivalence, so following one is a lookup rather than a guess.
+     */
+    alternates: Alternate[];
+    extractionMethod: ExtractionMethod;
+    pageType: PageType;
+    /** Counted on the extracted text in the page's own script, not on the render. */
+    wordCount: number;
+    /** Content supplied by the page but not included in the delivered answer. */
+    omissions?: ContentOmission[];
+    /** Whether the extraction looks like the page's real content. */
+    confidence?: ContentConfidence;
+    /**
+     * The markdown converter threw and this document fell back to raw DOM text:
+     * no headings, no links, no tables — the prose, in reading order, and
+     * nothing else.
+     *
+     * On the document rather than only inside the confidence it produced,
+     * because the confidence is RE-ASSESSED downstream once a browser tier is
+     * known. Declared here because a field the SDK does not declare arrives at a
+     * typed caller as nothing: the reason a page came back without its structure
+     * would reach the extractor's own return and no customer.
+     */
+    converterFailed?: boolean;
+    /** Populated for listing pages so the caller can see what was detected. */
+    listing?: {
+        itemCount: number;
+        /** Other qualifying result sets on the page that were not rendered. */
+        otherSetsFound: number;
+    };
+    /** Populated for threaded discussion, so a flat render is explainable. */
+    thread?: {
+        itemCount: number;
+        maxDepth: number;
+        /** How reply depth was established: DOM nesting, an attribute, or neither. */
+        depthSource: "nesting" | "attribute" | "flat";
+    };
+}
+export interface TokenEstimate {
+    /** Tokens the agent would have burned on the raw HTML. */
+    rawHtml: number;
+    /** Tokens in the emitted content for the requested format. */
+    output: number;
+    /** Percentage saved, 0-100, rounded to one decimal. */
+    savedPct: number;
+}
+export interface EscalationRecord {
+    from: Tier;
+    to: Tier;
+    reason: string;
+}
+/**
+ * What the fetch consumed. Present on every arm including the failures: a fetch
+ * that ended in a 403 still ran a browser and still moved bytes.
+ */
+export interface Meter {
+    /** Response bytes read. Exact at tier 1; see `basis` for the browser tiers. */
+    bytesIn: number;
+    /** Wall-clock in plain HTTP. */
+    httpMs: number;
+    /** Wall-clock with a browser up. The expensive second. */
+    browserMs: number;
+    /** True when any byte went through a paid egress. */
+    proxied: boolean;
+    /**
+     * How much of `bytesIn` was actually observed. `partial` means the total is a
+     * floor, not a figure — do not compare it to an invoice as if it were one.
+     */
+    basis: "measured" | "partial" | "none";
+    /** How many responses could not report a size. Zero when `basis` is measured. */
+    unsizedResponses: number;
+}
+/** What that consumption is worth, priced from the meter. */
+export interface Cost {
+    /** Authoritative. */
+    micros: number;
+    /** ceil(micros / 10_000). Display only — never compared, never summed. */
+    cents: number;
+    currency: "USD";
+    /** A price computed from a floor is a floor, and says so here. */
+    basis: "measured" | "partial" | "estimated";
+    rateCardVersion: string;
+    breakdown: {
+        egressMicros: number;
+        browserMicros: number;
+        httpMicros: number;
+    };
+}
+/**
+ * The metadata on a DELIVERED fetch.
+ *
+ * No index signature, for the same reason `ExtractedDoc` has none: with one,
+ * `meta.tokenEstimte` compiled and fourteen real fields stayed undeclared — so
+ * every caller that wanted the token saving or the cache flag had to cast.
+ */
+export interface FetchMeta {
+    meter: Meter;
+    cost: Cost;
+    tier: Tier;
+    renderedJs: boolean;
+    /**
+     * robots.txt forbade this path and we fetched it anyway — only ever set in
+     * `report` mode. On the SUCCESS shape deliberately: a log that records only
+     * refusals cannot answer "did you know?".
+     */
+    robotsDisallowed?: boolean;
+    /** The rule that decided it, so the record can be checked rather than trusted. */
+    robotsRule?: string;
+    finalUrl: string;
+    fetchedAt: string;
+    status: number | null;
+    durationMs: number;
+    /** ms spent per stage, e.g. `{ tier1: 380, tier2: 4120, extracting: 46 }`. */
+    timings: Record<string, number>;
+    tokenEstimate: TokenEstimate;
+    extractionMethod: string;
+    escalations: EscalationRecord[];
+    /** Which tier the domain cache suggested we start at. */
+    startedAtTier: Tier;
+    /** The locale this fetch actually presented, so a caller need not assume. */
+    locale?: string;
+    /** True when `maxWords` cut the content. `doc.wordCount` is the full count. */
+    contentTruncated?: boolean;
+    omissions?: ContentOmission[];
+    /** How many words the body held before the cap bit. */
+    totalWords?: number;
+    /** True when this answer came from a recent identical fetch, not the network. */
+    cached?: boolean;
+}
+/**
+ * The metadata on a FAILED fetch, which is not `Partial<FetchMeta>`.
+ *
+ * It carries two fields a success never does — `retryAfterMs` and `retryAfter`,
+ * the answer to "when may I try again" — and it omits the ones that only exist
+ * once a document was produced. Typing it as a partial success said the
+ * schedulable fields did not exist, which is why the MCP layer reads them
+ * through `meta?.["retryAfter"]` instead of by name.
+ *
+ * A type alias rather than an interface, deliberately: an interface has no
+ * implicit index signature, so it is not assignable to `Record<string, unknown>`
+ * — and `packages/mcp/src/tools.ts#failurePayload` takes exactly that.
+ */
+export type FetchFailureMeta = {
+    meter?: Meter;
+    cost?: Cost;
+    durationMs: number;
+    timings?: Record<string, number>;
+    escalations: EscalationRecord[];
+    startedAtTier: Tier;
+    finalUrl?: string;
+    /** How long until we will contact the site again, as a duration. */
+    retryAfterMs?: number;
+    /**
+     * …and as an ISO instant. Both forms, because a duration is measured from a
+     * moment the caller cannot see and so cannot be scheduled against.
+     */
+    retryAfter?: string;
+    robotsDisallowed?: boolean;
+    robotsRule?: string;
+};
+/**
+ * Every field name on `ExtractedDoc`, as data.
+ *
+ * The contract test needs the declared field set at RUNTIME to diff it against
+ * the producer's source, and a TypeScript interface leaves nothing behind to
+ * read. `satisfies` stops the list naming a field that does not exist; the
+ * `_DocFieldsAreComplete` alias below stops it omitting one. Between them the
+ * list cannot drift from the interface it describes without failing `tsc`.
+ */
+export declare const WIRE_DOC_FIELDS: readonly ["url", "title", "description", "author", "publishedAt", "siteName", "lang", "dir", "markdown", "text", "contentHtml", "links", "images", "structuredData", "alternates", "extractionMethod", "pageType", "wordCount", "omissions", "confidence", "converterFailed", "listing", "thread"];
+/** The same, for the delivered-fetch metadata. */
+export declare const WIRE_META_FIELDS: readonly ["meter", "cost", "tier", "renderedJs", "robotsDisallowed", "robotsRule", "finalUrl", "fetchedAt", "status", "durationMs", "timings", "tokenEstimate", "extractionMethod", "escalations", "startedAtTier", "locale", "contentTruncated", "omissions", "totalWords", "cached"];
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,89 @@
+/**
+ * The wire, declared once.
+ *
+ * Every client of the unfenced server needs the same handful of shapes — the
+ * cleaned document, the fetch metadata, the outcome envelope — and until this
+ * file existed each one declared its own. Three copies of `ExtractedDoc` were in
+ * the tree at the same time: `packages/extract/src/types.ts` (the producer, 21
+ * fields), this package (8 fields plus `[key: string]: unknown`), and
+ * `packages/ui/src/api.ts` (15 fields, hand-typed). They disagreed, and the
+ * disagreement was invisible: an index signature makes `doc.markdwn` compile and
+ * return `undefined`, and a field the dashboard never declared is a field no
+ * dashboard view can render.
+ *
+ * @unfenced-ai/sdk is the right home for it. It has no runtime dependencies and is
+ * meant to keep none, so a browser bundle can carry it; every other client
+ * already depends on it; and it is one of the two packages that actually
+ * publish, so its types are the ones a stranger receives.
+ *
+ * WHY THIS FILE IS SEPARATE FROM `index.ts`: this module is pure declaration —
+ * no imports, no client, no `fetch`. `packages/ui` may therefore
+ * `import type` from it and get the types with nothing to erase, honouring the
+ * boundary in docs/ARCHITECTURE.md that the dashboard owns no `@unfenced/*`
+ * runtime import. Importing `index.ts` would put the `Unfenced` class in the
+ * dashboard's module graph for a type it does not need.
+ *
+ * THIS IS STILL A MIRROR, and mirrors drift — that is the whole reason this file
+ * exists. So it is BOUND rather than trusted: `test/wire-contract.test.ts` reads
+ * the producer's own declarations off disk and fails when a field is renamed,
+ * dropped or added on either side. See that file for why the binding runs
+ * against the source rather than against a live server.
+ */
+/**
+ * Every field name on `ExtractedDoc`, as data.
+ *
+ * The contract test needs the declared field set at RUNTIME to diff it against
+ * the producer's source, and a TypeScript interface leaves nothing behind to
+ * read. `satisfies` stops the list naming a field that does not exist; the
+ * `_DocFieldsAreComplete` alias below stops it omitting one. Between them the
+ * list cannot drift from the interface it describes without failing `tsc`.
+ */
+export const WIRE_DOC_FIELDS = [
+    "url",
+    "title",
+    "description",
+    "author",
+    "publishedAt",
+    "siteName",
+    "lang",
+    "dir",
+    "markdown",
+    "text",
+    "contentHtml",
+    "links",
+    "images",
+    "structuredData",
+    "alternates",
+    "extractionMethod",
+    "pageType",
+    "wordCount",
+    "omissions",
+    "confidence",
+    "converterFailed",
+    "listing",
+    "thread",
+];
+/** The same, for the delivered-fetch metadata. */
+export const WIRE_META_FIELDS = [
+    "meter",
+    "cost",
+    "tier",
+    "renderedJs",
+    "robotsDisallowed",
+    "robotsRule",
+    "finalUrl",
+    "fetchedAt",
+    "status",
+    "durationMs",
+    "timings",
+    "tokenEstimate",
+    "extractionMethod",
+    "escalations",
+    "startedAtTier",
+    "locale",
+    "contentTruncated",
+    "omissions",
+    "totalWords",
+    "cached",
+];
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA+RH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK;IACL,OAAO;IACP,aAAa;IACb,QAAQ;IACR,aAAa;IACb,UAAU;IACV,MAAM;IACN,KAAK;IACL,UAAU;IACV,MAAM;IACN,aAAa;IACb,OAAO;IACP,QAAQ;IACR,gBAAgB;IAChB,YAAY;IACZ,kBAAkB;IAClB,UAAU;IACV,WAAW;IACX,WAAW;IACX,YAAY;IACZ,iBAAiB;IACjB,SAAS;IACT,QAAQ;CAC0C,CAAC;AAErD,kDAAkD;AAClD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,OAAO;IACP,MAAM;IACN,MAAM;IACN,YAAY;IACZ,kBAAkB;IAClB,YAAY;IACZ,UAAU;IACV,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,SAAS;IACT,eAAe;IACf,kBAAkB;IAClB,aAAa;IACb,eAAe;IACf,QAAQ;IACR,kBAAkB;IAClB,WAAW;IACX,YAAY;IACZ,QAAQ;CACuC,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The `Session` handle — a thin façade over the live-session methods on the
+ * `Unfenced` client. Moved out of the single-file entry unchanged; every method
+ * still delegates to `this.client`, so its behaviour is exactly the client's.
+ */
+import type { Unfenced } from "./client.js";
+import type { ExtractedDoc } from "./protocol.js";
+import type { Action, ActExpectation, ActResult, DownloadInfo, Format, OnAction, PageSnapshot, ProviderSessionReason } from "./types.js";
+/** Options that change how an action is reported, not what the page is asked to do. */
+export interface SessionActOptions {
+    acceptDialog?: boolean;
+    dialogText?: string;
+    brief?: boolean;
+    see?: boolean;
+    expect?: ActExpectation;
+}
+/**
+ * A handle to one live browser session.
+ *
+ * Keep it around across steps: observe to see what is on the page, act to
+ * change it, extract to read it clean, screenshot to watch it. Refs come from
+ * the latest snapshot and go stale on navigation — observe again after acting.
+ */
+export declare class Session {
+    private readonly client;
+    readonly id: string;
+    /** The snapshot from when the session opened. */
+    readonly initial: PageSnapshot;
+    constructor(client: Unfenced, id: string, 
+    /** The snapshot from when the session opened. */
+    initial: PageSnapshot);
+    observe(opts?: {
+        match?: string;
+        maxControls?: number;
+        maxLinks?: number;
+        excerptChars?: number;
+        media?: boolean;
+    }): Promise<PageSnapshot>;
+    /**
+     * Re-read the page after a reconnect and retain the provider continuity
+     * signal returned by the worker.
+     */
+    refresh(opts?: {
+        match?: string;
+    }): Promise<{
+        page: PageSnapshot;
+        providerSession?: ProviderSessionReason;
+    }>;
+    act(action: Action | OnAction, opts?: SessionActOptions): Promise<ActResult>;
+    click(ref: string, opts?: {
+        confirm?: boolean;
+    } & SessionActOptions): Promise<ActResult>;
+    type(ref: string, text: string, opts?: {
+        submit?: boolean;
+        confirm?: boolean;
+        append?: boolean;
+    } & SessionActOptions): Promise<ActResult>;
+    select(ref: string, value: string, opts?: SessionActOptions): Promise<ActResult>;
+    press(key: string, opts?: {
+        confirm?: boolean;
+    } & SessionActOptions): Promise<ActResult>;
+    scroll(to: "top" | "bottom" | {
+        ref: string;
+    }, opts?: SessionActOptions): Promise<ActResult>;
+    /** `settleMs` is the pause after the document commits, not the navigation's
+     *  own timeout — see the `navigate` action. Default 4000, maximum 15000. */
+    navigate(url: string, opts?: {
+        settleMs?: number;
+    } & SessionActOptions): Promise<ActResult>;
+    back(opts?: SessionActOptions): Promise<ActResult>;
+    extract(format?: Format, maxWords?: number): Promise<{
+        doc: ExtractedDoc;
+        content: string;
+        url: string;
+        contentTruncated?: boolean;
+        totalWords?: number;
+    }>;
+    park(minutes?: number, reason?: string): Promise<{
+        ok: boolean;
+        until?: string;
+    }>;
+    downloads(): Promise<{
+        downloads: DownloadInfo[];
+    }>;
+    readDownload(filename: string): Promise<{
+        filename: string;
+        bytes: number;
+        content: string;
+        doc: ExtractedDoc;
+    }>;
+    screenshot(): Promise<string>;
+    close(): Promise<{
+        alreadyClosed?: boolean;
+        wasOpen?: boolean;
+    }>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -0,0 +1,88 @@
+/**
+ * A handle to one live browser session.
+ *
+ * Keep it around across steps: observe to see what is on the page, act to
+ * change it, extract to read it clean, screenshot to watch it. Refs come from
+ * the latest snapshot and go stale on navigation — observe again after acting.
+ */
+export class Session {
+    client;
+    id;
+    initial;
+    constructor(client, id, 
+    /** The snapshot from when the session opened. */
+    initial) {
+        this.client = client;
+        this.id = id;
+        this.initial = initial;
+    }
+    observe(opts) {
+        return this.client.observe(this.id, opts);
+    }
+    /**
+     * Re-read the page after a reconnect and retain the provider continuity
+     * signal returned by the worker.
+     */
+    refresh(opts) {
+        return this.client.refresh(this.id, opts);
+    }
+    act(action, opts) {
+        return this.client.act(this.id, action, opts);
+    }
+    click(ref, opts = {}) {
+        const { confirm, ...reporting } = opts;
+        return this.act({ kind: "click", ref, ...(confirm !== undefined ? { confirm } : {}) }, reporting);
+    }
+    type(ref, text, opts = {}) {
+        const { submit, confirm, append, ...reporting } = opts;
+        return this.act({
+            kind: "type",
+            ref,
+            text,
+            ...(submit !== undefined ? { submit } : {}),
+            ...(confirm !== undefined ? { confirm } : {}),
+            ...(append !== undefined ? { append } : {}),
+        }, reporting);
+    }
+    select(ref, value, opts = {}) {
+        return this.act({ kind: "select", ref, value }, opts);
+    }
+    press(key, opts = {}) {
+        const { confirm, ...reporting } = opts;
+        return this.act({ kind: "press", key, ...(confirm !== undefined ? { confirm } : {}) }, reporting);
+    }
+    scroll(to, opts = {}) {
+        return this.act({ kind: "scroll", to }, opts);
+    }
+    /** `settleMs` is the pause after the document commits, not the navigation's
+     *  own timeout — see the `navigate` action. Default 4000, maximum 15000. */
+    navigate(url, opts = {}) {
+        const { settleMs, ...reporting } = opts;
+        return this.act({ kind: "navigate", url, ...(settleMs !== undefined ? { settleMs } : {}) }, reporting);
+    }
+    back(opts = {}) {
+        return this.act({ kind: "back" }, opts);
+    }
+    extract(format = "markdown", maxWords) {
+        return this.client.extract(this.id, format, maxWords);
+    }
+    park(minutes, reason) {
+        return this.client.park(this.id, minutes, reason);
+    }
+    downloads() {
+        return this.client.downloads(this.id);
+    }
+    readDownload(filename) {
+        return this.client.readDownload(this.id, filename);
+    }
+    screenshot() {
+        return this.client.screenshot(this.id);
+    }
+    close() {
+        // Mirrors closeSession's own signature deliberately. Narrowing it here
+        // drops `wasOpen` for every caller that goes through a Session — the
+        // defect the comment on that method exists to prevent.
+        return this.client.closeSession(this.id);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}