@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/locator/pointer-element-actions.d.ts

@@ -0,0 +1,21 @@
+import type { ActionOptions } from "./actionability.js";
+import type { ElementAccess } from "./element-access.js";
+import type { CheckName } from "./element-state.js";
+import { type Modifier } from "./key-map.js";
+import { type Point, type PointerClickOptions } from "./pointer-actions.js";
+export interface PointerOptions extends ActionOptions {
+    /** Where on the element to point: pixels from its top left corner (default: the centre) */
+    position?: Point;
+    /** Keys held down during the action */
+    modifiers?: Modifier[];
+}
+export interface ClickOptions extends PointerOptions, PointerClickOptions {
+}
+/** Waits until the element passes `checks` (scrolled into view) and answers where on screen to point */
+export declare function pointAtElement(access: ElementAccess, method: string, checks: readonly CheckName[], options: PointerOptions | undefined): Promise<Point>;
+/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks it with real pointer input */
+export declare function clickElement(access: ElementAccess, options?: ClickOptions, method?: string): Promise<void>;
+/** Waits until the element is attached, visible, stable and not covered, then moves the mouse onto it */
+export declare function hoverElement(access: ElementAccess, options?: PointerOptions): Promise<void>;
+/** Waits like `click`, then touches the element with a finger (a touch pointer, not the mouse) */
+export declare function tapElement(access: ElementAccess, options?: PointerOptions): Promise<void>;

package/dist/locator/pointer-element-actions.js

@@ -0,0 +1,42 @@
+import { withModifiers } from "./key-actions.js";
+import { modifierCodes } from "./key-map.js";
+import { checkClick, pointerClick, pointerMoveTo, pointerTap, pointInRect, } from "./pointer-actions.js";
+import { CLICK_CHECKS, HOVER_CHECKS } from "./page-scripts.js";
+/** Checks `position` and `modifiers`; `method` names the public method for the error */
+function checkOptions(method, options) {
+    const position = options?.position;
+    if (position !== undefined &&
+        !(Number.isFinite(position.x) && Number.isFinite(position.y))) {
+        throw new Error(`${method}(): position must be { x, y } in pixels`);
+    }
+    return modifierCodes(options?.modifiers ?? [], undefined, method);
+}
+/** Waits until the element passes `checks` (scrolled into view) and answers where on screen to point */
+export async function pointAtElement(access, method, checks, options) {
+    const state = await access.waitForActionable(method, checks, {
+        scroll: true,
+        hitTest: true,
+        ...(options?.position && { at: options.position }),
+    }, options);
+    // "attached" is always required, so the box is present
+    return pointInRect(state.box, options?.position);
+}
+/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks it with real pointer input */
+export async function clickElement(access, options, method = "click") {
+    const modifiers = checkOptions(method, options);
+    checkClick(options ?? {}, method);
+    const point = await pointAtElement(access, method, CLICK_CHECKS, options);
+    await withModifiers(access.connector, access.contextId, modifiers, () => pointerClick(access.connector, access.contextId, point, options, method));
+}
+/** Waits until the element is attached, visible, stable and not covered, then moves the mouse onto it */
+export async function hoverElement(access, options) {
+    const modifiers = checkOptions("hover", options);
+    const point = await pointAtElement(access, "hover", HOVER_CHECKS, options);
+    await withModifiers(access.connector, access.contextId, modifiers, () => pointerMoveTo(access.connector, access.contextId, point));
+}
+/** Waits like `click`, then touches the element with a finger (a touch pointer, not the mouse) */
+export async function tapElement(access, options) {
+    const modifiers = checkOptions("tap", options);
+    const point = await pointAtElement(access, "tap", CLICK_CHECKS, options);
+    await withModifiers(access.connector, access.contextId, modifiers, () => pointerTap(access.connector, access.contextId, point));
+}

package/dist/request/api-request-context.d.ts

@@ -0,0 +1,65 @@
+import { APIResponse } from "./api-response.js";
+import type { CookieStore } from "./cookie-jar.js";
+import { type BodyOptions } from "./request-body.js";
+import type { StorageState } from "../types/use.js";
+/** Options of one request */
+export interface RequestOptions extends BodyOptions {
+    /** Only for `fetch`. @default "GET" */
+    method?: string;
+    /** Added to the context's `extraHTTPHeaders`; a name set in both takes this value */
+    headers?: Record<string, string>;
+    /** Query parameters, added to the ones the URL has */
+    params?: Record<string, string | number | boolean> | URLSearchParams | string;
+    /** Milliseconds for the whole request, redirects included; 0 for no limit. @default 30000 */
+    timeout?: number;
+    /** Throw for a status outside 200 to 299 instead of returning the response */
+    failOnStatusCode?: boolean;
+    /** Accept certificates that are self-signed, expired or for another host. @default the context's setting */
+    ignoreHTTPSErrors?: boolean;
+    /** Redirects to follow; 0 returns the 3xx response itself. @default 20 */
+    maxRedirects?: number;
+    /** Times to send the request again when the connection is reset before an answer. @default 0 */
+    maxRetries?: number;
+}
+/** What a context starts from; `BrowserContext.request` hands its own object and changes it as the run's `use` options arrive */
+export interface RequestContextOptions {
+    /** Relative request URLs resolve against it. @default the run's baseURL */
+    baseURL?: string | undefined;
+    /** Headers added to every request */
+    extraHTTPHeaders?: Record<string, string> | undefined;
+    /** Accept certificates that are self-signed, expired or for another host */
+    ignoreHTTPSErrors?: boolean | undefined;
+}
+/** A request given to `fetch` instead of a URL: anything with a `url` (such as a request the page made) */
+export interface RequestLike {
+    url: string;
+    method?: string;
+}
+/**
+ * Makes HTTP requests from the test, outside the browser: log in, set data up, check an API. Cookies come from
+ * its `CookieStore`: the browser context's cookies (`page.request`, `context.request`) or its own jar.
+ */
+export declare class APIRequestContext {
+    private readonly options;
+    private readonly cookies;
+    private readonly pending;
+    private disposed;
+    constructor(options: RequestContextOptions, cookies: CookieStore);
+    get(url: string, options?: RequestOptions): Promise<APIResponse>;
+    post(url: string, options?: RequestOptions): Promise<APIResponse>;
+    put(url: string, options?: RequestOptions): Promise<APIResponse>;
+    patch(url: string, options?: RequestOptions): Promise<APIResponse>;
+    delete(url: string, options?: RequestOptions): Promise<APIResponse>;
+    head(url: string, options?: RequestOptions): Promise<APIResponse>;
+    /** Sends a request with any method and returns its response (redirects followed unless `maxRedirects` is 0) */
+    fetch(urlOrRequest: string | URL | RequestLike, options?: RequestOptions): Promise<APIResponse>;
+    /** The cookies this context holds, as a `storageState` file lists them (it has no local storage) */
+    storageState(): Promise<StorageState>;
+    /** Stops the requests in flight; the context sends no more */
+    dispose(): Promise<void>;
+    private send;
+    /** One hop, sent again when the connection is reset and `maxRetries` allows */
+    private hop;
+    private urlOf;
+    private headersOf;
+}

package/dist/request/api-request-context.js

@@ -0,0 +1,198 @@
+import { RELATIVE_URL } from "../config/base-url.js";
+import { peekRunSettings } from "../config/run-settings.js";
+import { APIResponse } from "./api-response.js";
+import { sendHop, TransportError, describeURL } from "./http-transport.js";
+import { encodeBody } from "./request-body.js";
+import { followUp, redirectTarget } from "./redirect.js";
+/** Milliseconds a request may take, redirects included */
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_MAX_REDIRECTS = 20;
+const HAS_SCHEME = /^[a-z][a-z\d+.-]*:/i;
+/**
+ * Makes HTTP requests from the test, outside the browser: log in, set data up, check an API. Cookies come from
+ * its `CookieStore`: the browser context's cookies (`page.request`, `context.request`) or its own jar.
+ */
+export class APIRequestContext {
+    constructor(options, cookies) {
+        this.options = options;
+        this.cookies = cookies;
+        this.pending = new Set();
+        this.disposed = false;
+    }
+    get(url, options) {
+        return this.fetch(url, { ...options, method: "GET" });
+    }
+    post(url, options) {
+        return this.fetch(url, { ...options, method: "POST" });
+    }
+    put(url, options) {
+        return this.fetch(url, { ...options, method: "PUT" });
+    }
+    patch(url, options) {
+        return this.fetch(url, { ...options, method: "PATCH" });
+    }
+    delete(url, options) {
+        return this.fetch(url, { ...options, method: "DELETE" });
+    }
+    head(url, options) {
+        return this.fetch(url, { ...options, method: "HEAD" });
+    }
+    /** Sends a request with any method and returns its response (redirects followed unless `maxRedirects` is 0) */
+    async fetch(urlOrRequest, options = {}) {
+        if (this.disposed)
+            throw new Error("request context disposed");
+        const given = typeof urlOrRequest === "string" || urlOrRequest instanceof URL
+            ? { url: String(urlOrRequest) }
+            : urlOrRequest;
+        const method = (options.method ?? given.method ?? "GET").toUpperCase();
+        const url = this.urlOf(given.url, options.params);
+        const encoded = encodeBody(options);
+        const headers = this.headersOf(options.headers);
+        if (encoded && !("content-type" in headers))
+            headers["content-type"] = encoded.contentType;
+        const abort = new AbortController();
+        this.pending.add(abort);
+        try {
+            return await this.send({
+                url,
+                method,
+                headers,
+                body: encoded?.body,
+                options,
+                abort,
+            });
+        }
+        finally {
+            this.pending.delete(abort);
+        }
+    }
+    /** The cookies this context holds, as a `storageState` file lists them (it has no local storage) */
+    async storageState() {
+        return { cookies: await this.cookies.list(), origins: [] };
+    }
+    /** Stops the requests in flight; the context sends no more */
+    dispose() {
+        this.disposed = true;
+        for (const abort of this.pending)
+            abort.abort();
+        this.pending.clear();
+        return Promise.resolve();
+    }
+    async send(plan) {
+        const { options, abort } = plan;
+        const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        const deadline = timeout > 0 ? Date.now() + timeout : 0;
+        const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+        let { url, method, headers, body } = plan;
+        for (let hops = 0;; hops++) {
+            const sent = { ...headers };
+            const cookie = await this.cookies.cookieHeader(url);
+            if (cookie)
+                sent.cookie = sent.cookie ? `${sent.cookie}; ${cookie}` : cookie;
+            const remaining = deadline > 0 ? Math.max(1, deadline - Date.now()) : 0;
+            const hop = await this.hop({ url, method, headers: sent, body }, options, remaining, abort.signal);
+            if (hop.setCookies.length > 0)
+                await this.cookies.store(url, hop.setCookies);
+            const location = hop.headers.find((h) => h.name.toLowerCase() === "location")?.value;
+            const next = redirectTarget(hop.status, location, url);
+            if (next && maxRedirects > 0) {
+                if (hops >= maxRedirects)
+                    throw new Error(`fetch(): too many redirects, more than ${maxRedirects} (${method} ${describeURL(plan.url)})`);
+                const change = followUp(hop.status, method, body);
+                if (change.body === undefined && body !== undefined)
+                    headers = withoutBody(headers);
+                if (next.origin !== url.origin)
+                    delete headers.authorization;
+                ({ method, body } = change);
+                url = next;
+                continue;
+            }
+            const response = new APIResponse({
+                url: url.href,
+                status: hop.status,
+                statusText: hop.statusText,
+                headers: hop.headers,
+                body: hop.body,
+            });
+            if (options.failOnStatusCode && !response.ok())
+                throw new Error(`fetch(): ${hop.status} ${hop.statusText} (${method} ${describeURL(url)})`);
+            return response;
+        }
+    }
+    /** One hop, sent again when the connection is reset and `maxRetries` allows */
+    async hop(request, options, timeout, signal) {
+        const retries = options.maxRetries ?? 0;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await sendHop({
+                    ...request,
+                    ignoreHTTPSErrors: options.ignoreHTTPSErrors ??
+                        this.options.ignoreHTTPSErrors ??
+                        false,
+                    timeout,
+                    signal,
+                });
+            }
+            catch (err) {
+                const again = err instanceof TransportError &&
+                    err.code === "ECONNRESET" &&
+                    attempt < retries &&
+                    !signal.aborted;
+                if (!again)
+                    throw prefixed(err);
+            }
+        }
+    }
+    urlOf(given, params) {
+        let url;
+        try {
+            if (HAS_SCHEME.test(given) && !RELATIVE_URL.test(given))
+                url = new URL(given);
+            else {
+                const base = this.options.baseURL ?? peekRunSettings()?.baseURL;
+                if (!base)
+                    throw new Error(`fetch(): "${given}" needs a baseURL; set one in samurai.config.ts, the environment or request.newContext()`);
+                url = new URL(given, base);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith("fetch():"))
+                throw err;
+            throw new Error(`fetch(): "${given}" is not a valid URL`);
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            throw new Error(`fetch(): "${given}" must be an http or https URL`);
+        if (params !== undefined) {
+            if (typeof params === "object" && !(params instanceof URLSearchParams)) {
+                for (const [key, value] of Object.entries(params))
+                    url.searchParams.set(key, String(value));
+            }
+            else
+                for (const [key, value] of new URLSearchParams(params))
+                    url.searchParams.append(key, value);
+        }
+        return url;
+    }
+    headersOf(perCall) {
+        const headers = {
+            accept: "*/*",
+            "accept-encoding": "gzip,deflate,br",
+            "user-agent": "samurai-framework",
+        };
+        for (const source of [this.options.extraHTTPHeaders, perCall])
+            for (const [name, value] of Object.entries(source ?? {}))
+                headers[name.toLowerCase()] = String(value);
+        return headers;
+    }
+}
+function withoutBody(headers) {
+    const rest = { ...headers };
+    delete rest["content-type"];
+    delete rest["content-length"];
+    return rest;
+}
+function prefixed(err) {
+    return err instanceof TransportError
+        ? new Error(`fetch(): ${err.message}`)
+        : err;
+}

package/dist/request/api-response.d.ts

@@ -0,0 +1,34 @@
+export interface HeaderEntry {
+    name: string;
+    value: string;
+}
+/** What a request context hands to `APIResponse` */
+export interface ResponseInit {
+    url: string;
+    status: number;
+    statusText: string;
+    /** Every header as it arrived, in order, repeated names kept */
+    headers: HeaderEntry[];
+    body: Buffer;
+}
+/** The answer to a request made with an `APIRequestContext`. The body is already read. */
+export declare class APIResponse {
+    private readonly init;
+    private disposed;
+    constructor(init: ResponseInit);
+    status(): number;
+    statusText(): string;
+    /** True for a status from 200 to 299 */
+    ok(): boolean;
+    /** The URL the response came from: the last one when redirects were followed */
+    url(): string;
+    /** Header names lower-cased; a name that came more than once is joined with ", " (`set-cookie` with a new line) */
+    headers(): Record<string, string>;
+    /** Every header as it arrived, repeated names included (each `Set-Cookie` is an entry of its own) */
+    headersArray(): HeaderEntry[];
+    body(): Promise<Buffer>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    /** Frees the body: `body()`, `text()` and `json()` throw after it */
+    dispose(): Promise<void>;
+}

package/dist/request/api-response.js

@@ -0,0 +1,57 @@
+/** The answer to a request made with an `APIRequestContext`. The body is already read. */
+export class APIResponse {
+    constructor(init) {
+        this.init = init;
+        this.disposed = false;
+    }
+    status() {
+        return this.init.status;
+    }
+    statusText() {
+        return this.init.statusText;
+    }
+    /** True for a status from 200 to 299 */
+    ok() {
+        return this.init.status >= 200 && this.init.status < 300;
+    }
+    /** The URL the response came from: the last one when redirects were followed */
+    url() {
+        return this.init.url;
+    }
+    /** Header names lower-cased; a name that came more than once is joined with ", " (`set-cookie` with a new line) */
+    headers() {
+        const joined = {};
+        for (const { name, value } of this.init.headers) {
+            const key = name.toLowerCase();
+            const glue = key === "set-cookie" ? "\n" : ", ";
+            joined[key] = key in joined ? `${joined[key]}${glue}${value}` : value;
+        }
+        return joined;
+    }
+    /** Every header as it arrived, repeated names included (each `Set-Cookie` is an entry of its own) */
+    headersArray() {
+        return this.init.headers.map(({ name, value }) => ({ name, value }));
+    }
+    body() {
+        if (this.disposed)
+            return Promise.reject(new Error("response disposed"));
+        return Promise.resolve(this.init.body);
+    }
+    async text() {
+        return (await this.body()).toString("utf8");
+    }
+    async json() {
+        const text = await this.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch (err) {
+            throw new Error(`json(): the response body of ${this.init.url} is not JSON: ${err.message}`);
+        }
+    }
+    /** Frees the body: `body()`, `text()` and `json()` throw after it */
+    dispose() {
+        this.disposed = true;
+        return Promise.resolve();
+    }
+}

package/dist/request/cookie-jar.d.ts

@@ -0,0 +1,48 @@
+import type { StorageStateCookie } from "../types/use.js";
+/** A cookie as the jar keeps it */
+export interface StoredCookie {
+    name: string;
+    value: string;
+    /** Lower case, no leading dot */
+    domain: string;
+    /** True when no `Domain` was given: only that exact host gets the cookie */
+    hostOnly: boolean;
+    path: string;
+    secure: boolean;
+    httpOnly: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+    /** Seconds since the epoch; absent for a session cookie, in the past for a cookie the site deletes */
+    expires?: number;
+}
+/** Where a request context reads the cookies it sends and writes the ones it receives: its own jar, or a browser context */
+export interface CookieStore {
+    /** The `Cookie` header value for a request to `url`; `undefined` when no cookie applies */
+    cookieHeader(url: URL): Promise<string | undefined>;
+    /** Stores the cookies of the `Set-Cookie` headers a response from `url` carried (one entry per header) */
+    store(url: URL, setCookies: string[]): Promise<void>;
+    /** Every cookie, as a storage state lists them */
+    list(): Promise<StorageStateCookie[]>;
+}
+/**
+ * One `Set-Cookie` header of a response from `url`. `undefined` for a header that is not a cookie (no name, or a
+ * `Domain` the host does not belong to, which a browser would refuse as well).
+ */
+export declare function parseSetCookie(header: string, url: URL, now?: number): StoredCookie | undefined;
+export declare function isExpired(cookie: StoredCookie, now?: number): boolean;
+/**
+ * Whether a request to `url` carries `cookie`: host, path, `Secure` (https, or a loopback host the browsers treat
+ * as secure) and expiry. `SameSite` is not applied: a request made by the test is not made from another site.
+ */
+export declare function cookieMatches(cookie: StoredCookie, url: URL, now?: number): boolean;
+/** The `Cookie` header value for `cookies`: the longest path first, as a browser sends them */
+export declare function cookieHeaderOf(cookies: StoredCookie[]): string | undefined;
+/** The cookies of an in-memory request context: what its responses set, and what a storage state seeded */
+export declare class CookieJar implements CookieStore {
+    private cookies;
+    constructor(seed?: readonly StorageStateCookie[]);
+    cookieHeader(url: URL): Promise<string | undefined>;
+    store(url: URL, setCookies: string[]): Promise<void>;
+    list(): Promise<StorageStateCookie[]>;
+    /** Replaces the cookie with the same name, domain and path; an expired one only removes it */
+    private put;
+}

package/dist/request/cookie-jar.js

@@ -0,0 +1,164 @@
+const SAME_SITE = { strict: "Strict", lax: "Lax", none: "None" };
+const INTEGER = /^-?\d+$/;
+function isLoopback(host) {
+    return (host === "localhost" || host === "[::1]" || /^127(\.\d+){3}$/.test(host));
+}
+/** The default path of a cookie set without `Path`: the directory of the request path */
+function defaultPath(pathname) {
+    const last = pathname.lastIndexOf("/");
+    return pathname.startsWith("/") && last > 0 ? pathname.slice(0, last) : "/";
+}
+function domainMatches(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/**
+ * One `Set-Cookie` header of a response from `url`. `undefined` for a header that is not a cookie (no name, or a
+ * `Domain` the host does not belong to, which a browser would refuse as well).
+ */
+export function parseSetCookie(header, url, now = Date.now()) {
+    const [pair = "", ...attributes] = header.split(";");
+    const eq = pair.indexOf("=");
+    if (eq < 0)
+        return undefined;
+    const name = pair.slice(0, eq).trim();
+    if (name === "")
+        return undefined;
+    const cookie = {
+        name,
+        value: pair.slice(eq + 1).trim(),
+        domain: url.hostname.toLowerCase(),
+        hostOnly: true,
+        path: defaultPath(url.pathname),
+        secure: false,
+        httpOnly: false,
+    };
+    let maxAge;
+    for (const attribute of attributes) {
+        const at = attribute.indexOf("=");
+        const key = (at < 0 ? attribute : attribute.slice(0, at))
+            .trim()
+            .toLowerCase();
+        const value = at < 0 ? "" : attribute.slice(at + 1).trim();
+        if (key === "domain" && value !== "") {
+            const domain = value.replace(/^\./, "").toLowerCase();
+            if (!domainMatches(cookie.domain, domain))
+                return undefined;
+            cookie.domain = domain;
+            cookie.hostOnly = false;
+        }
+        else if (key === "path" && value.startsWith("/"))
+            cookie.path = value;
+        else if (key === "secure")
+            cookie.secure = true;
+        else if (key === "httponly")
+            cookie.httpOnly = true;
+        else if (key === "samesite" && value.toLowerCase() in SAME_SITE)
+            cookie.sameSite =
+                SAME_SITE[value.toLowerCase()];
+        else if (key === "max-age" && INTEGER.test(value))
+            maxAge = Number(value);
+        else if (key === "expires") {
+            const time = Date.parse(value);
+            if (!Number.isNaN(time))
+                cookie.expires = Math.floor(time / 1000);
+        }
+    }
+    // Max-Age wins over Expires
+    if (maxAge !== undefined)
+        cookie.expires = maxAge <= 0 ? 0 : Math.floor(now / 1000) + maxAge;
+    return cookie;
+}
+export function isExpired(cookie, now = Date.now()) {
+    return cookie.expires !== undefined && cookie.expires * 1000 <= now;
+}
+/**
+ * Whether a request to `url` carries `cookie`: host, path, `Secure` (https, or a loopback host the browsers treat
+ * as secure) and expiry. `SameSite` is not applied: a request made by the test is not made from another site.
+ */
+export function cookieMatches(cookie, url, now = Date.now()) {
+    if (isExpired(cookie, now))
+        return false;
+    const host = url.hostname.toLowerCase();
+    if (cookie.hostOnly
+        ? host !== cookie.domain
+        : !domainMatches(host, cookie.domain))
+        return false;
+    const { path } = cookie;
+    const here = url.pathname || "/";
+    const underPath = here === path ||
+        (here.startsWith(path) &&
+            (path.endsWith("/") || here[path.length] === "/"));
+    if (!underPath)
+        return false;
+    return !cookie.secure || url.protocol === "https:" || isLoopback(host);
+}
+/** The `Cookie` header value for `cookies`: the longest path first, as a browser sends them */
+export function cookieHeaderOf(cookies) {
+    if (cookies.length === 0)
+        return undefined;
+    return [...cookies]
+        .sort((a, b) => b.path.length - a.path.length)
+        .map((cookie) => `${cookie.name}=${cookie.value}`)
+        .join("; ");
+}
+/** The cookies of an in-memory request context: what its responses set, and what a storage state seeded */
+export class CookieJar {
+    constructor(seed = []) {
+        this.cookies = [];
+        for (const cookie of seed)
+            this.put(fromStorageState(cookie));
+    }
+    cookieHeader(url) {
+        const now = Date.now();
+        this.cookies = this.cookies.filter((cookie) => !isExpired(cookie, now));
+        return Promise.resolve(cookieHeaderOf(this.cookies.filter((c) => cookieMatches(c, url, now))));
+    }
+    store(url, setCookies) {
+        for (const header of setCookies) {
+            const cookie = parseSetCookie(header, url);
+            if (cookie)
+                this.put(cookie);
+        }
+        return Promise.resolve();
+    }
+    list() {
+        const now = Date.now();
+        return Promise.resolve(this.cookies
+            .filter((cookie) => !isExpired(cookie, now))
+            .map(toStorageState));
+    }
+    /** Replaces the cookie with the same name, domain and path; an expired one only removes it */
+    put(cookie) {
+        this.cookies = this.cookies.filter((old) => old.name !== cookie.name ||
+            old.domain !== cookie.domain ||
+            old.path !== cookie.path);
+        if (!isExpired(cookie))
+            this.cookies.push(cookie);
+    }
+}
+function fromStorageState(cookie) {
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain.replace(/^\./, "").toLowerCase(),
+        hostOnly: !cookie.domain.startsWith("."),
+        path: cookie.path ?? "/",
+        secure: cookie.secure ?? false,
+        httpOnly: cookie.httpOnly ?? false,
+        ...(cookie.sameSite !== undefined && { sameSite: cookie.sameSite }),
+        ...(cookie.expires !== undefined &&
+            cookie.expires > 0 && { expires: cookie.expires }),
+    };
+}
+function toStorageState(cookie) {
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.hostOnly ? cookie.domain : `.${cookie.domain}`,
+        path: cookie.path,
+        expires: cookie.expires ?? -1,
+        httpOnly: cookie.httpOnly,
+        secure: cookie.secure,
+        sameSite: cookie.sameSite ?? "Lax",
+    };
+}

package/dist/request/http-transport.d.ts

@@ -0,0 +1,31 @@
+import type { HeaderEntry } from "./api-response.js";
+/** One request to send, a single hop: redirects are the caller's business */
+export interface HopRequest {
+    url: URL;
+    method: string;
+    /** Names lower-cased */
+    headers: Record<string, string>;
+    body?: Buffer | undefined;
+    ignoreHTTPSErrors: boolean;
+    /** Milliseconds this hop may take; 0 is no limit */
+    timeout: number;
+    signal: AbortSignal;
+}
+export interface HopResponse {
+    status: number;
+    statusText: string;
+    headers: HeaderEntry[];
+    /** The `Set-Cookie` headers, one entry each */
+    setCookies: string[];
+    /** Decoded: `Content-Encoding` is already undone */
+    body: Buffer;
+}
+/** A request that failed before a response was complete */
+export declare class TransportError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/** The url without credentials or query: what an error may say about where the request went */
+export declare function describeURL(url: URL): string;
+/** Sends one request over `http` or `https` and reads the whole response. Errors never include header values. */
+export declare function sendHop(request: HopRequest): Promise<HopResponse>;