@geekmidas/testkit 10.0.0-alpha.9 → 10.0.0-alpha.90

package/dist/browser.cjs

@@ -0,0 +1,149 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_context = require("./context.cjs");
+let node_crypto = require("node:crypto");
+let tough_cookie = require("tough-cookie");
+//#region src/browser.ts
+/**
+* A browser, for tests: a `fetch` that keeps cookies the way a browser does.
+*
+* An app's real clients — its typed API client, better-auth's client — run on
+* whatever `fetch` they are given. Give them this one and a test signs in the
+* way a person does: the auth server's `Set-Cookie` lands in the jar, and every
+* later request to a URL the cookie belongs to carries it. The jar follows the
+* browser's rules (RFC 6265 — Domain, Path, Secure, Expires), so a cookie set
+* for the wrong domain is not sent, exactly as a browser would not send it.
+*
+* Extend it once per app with that app's clients:
+*
+* ```ts
+* export class Browser extends TestBrowser {
+*   readonly api = createApi({ baseURL: process.env.API_URL, fetch: this.fetch });
+* }
+* ```
+*/
+/** How many redirects `fetch` follows before giving up, as browsers do. */
+const MAX_REDIRECTS = 20;
+var Browser = class {
+	/** The cookies this browser holds. */
+	jar = new tough_cookie.CookieJar();
+	/**
+	* The address this browser connects from, sent as `x-forwarded-for` the way
+	* a proxy in front of the app adds it. Each browser is a different person on
+	* a different connection, so what an app keys by client — an auth server's
+	* rate limit — counts each on its own. Without it every browser was the same
+	* client, and concurrent tests queued on the same rate-limit row of each
+	* other's open transactions. A request that sets the header itself — a test
+	* that is several machines — keeps its own.
+	*/
+	address;
+	/**
+	* This browser's `fetch`: cookies from the jar on the way out, `Set-Cookie`
+	* into the jar on the way back, redirects followed hop by hop so each hop's
+	* cookies are kept.
+	*
+	* On the server side of a test — a handler serving a request — it is the
+	* plain `fetch`: a server forwards what it was handed and never reaches into
+	* a browser's jar.
+	*/
+	fetch;
+	send;
+	constructor(options = {}) {
+		this.send = options.fetch ?? globalThis.fetch;
+		this.address = options.address ?? privateAddress();
+		this.fetch = (input, init) => {
+			if (require_context.currentTestContext()?.side === "server") return this.send(input, init);
+			return this.start(new Request(input, init), init?.redirect);
+		};
+	}
+	/** Open a URL the way clicking a link does: a GET, redirects followed. */
+	visit(url) {
+		return this.fetch(String(url));
+	}
+	/** The cookies this browser would send to `url`, as a header value. */
+	cookieHeader(url) {
+		return this.jar.getCookieString(String(url));
+	}
+	/**
+	* Make this browser the global `fetch`, for code that uses the global one —
+	* an app's module-level clients. Returns what puts the previous one back.
+	*/
+	install() {
+		const previous = globalThis.fetch;
+		globalThis.fetch = this.fetch;
+		return () => {
+			globalThis.fetch = previous;
+		};
+	}
+	/** Read the body once, so a redirect that keeps the method can send it again. */
+	async start(request, redirect) {
+		const body = request.method === "GET" || request.method === "HEAD" ? void 0 : await request.arrayBuffer();
+		const headers = new Headers(request.headers);
+		if (!headers.has("x-forwarded-for")) headers.set("x-forwarded-for", this.address);
+		return this.request({
+			url: request.url,
+			method: request.method,
+			headers,
+			body
+		}, redirect);
+	}
+	async request(request, redirect, hops = 0) {
+		const headers = new Headers(request.headers);
+		const cookie = await this.jar.getCookieString(request.url);
+		if (cookie) {
+			const existing = headers.get("cookie");
+			headers.set("cookie", existing ? `${existing}; ${cookie}` : cookie);
+		}
+		const response = await this.send(request.url, {
+			method: request.method,
+			headers,
+			body: request.body,
+			redirect: "manual"
+		});
+		for (const set of response.headers.getSetCookie()) await this.jar.setCookie(set, request.url, { ignoreError: true });
+		const location = response.headers.get("location");
+		if (redirect === "manual" || !location || response.status < 300 || response.status >= 400) return response;
+		if (hops >= MAX_REDIRECTS) throw new TooManyRedirects(request.url, MAX_REDIRECTS);
+		const keepsMethod = response.status === 307 || response.status === 308 || request.method === "GET" || request.method === "HEAD";
+		const url = new URL(location, request.url).toString();
+		const next = keepsMethod ? {
+			...request,
+			url
+		} : {
+			url,
+			method: "GET",
+			headers: withoutBody(request.headers)
+		};
+		return this.request(next, redirect, hops + 1);
+	}
+};
+/** Headers for a request that no longer carries the body they described. */
+function withoutBody(headers) {
+	const next = new Headers(headers);
+	next.delete("content-type");
+	next.delete("content-length");
+	return next;
+}
+/** A redirect chain longer than any browser follows. */
+var TooManyRedirects = class extends Error {
+	url;
+	limit;
+	constructor(url, limit) {
+		super(`${url} redirected more than ${limit} times. A browser gives up here too — look for a redirect loop.`);
+		this.url = url;
+		this.limit = limit;
+		this.name = "TooManyRedirects";
+	}
+};
+/**
+* An address from 10.0.0.0/8, which nothing routes to. Random rather than
+* counted: test files run in separate workers that share no counter.
+*/
+function privateAddress() {
+	const n = (0, node_crypto.randomInt)(1, 2 ** 24 - 1);
+	return `10.${n >> 16 & 255}.${n >> 8 & 255}.${n & 255}`;
+}
+//#endregion
+exports.Browser = Browser;
+exports.TooManyRedirects = TooManyRedirects;
+
+//# sourceMappingURL=browser.cjs.map

package/dist/browser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.cjs","names":["CookieJar","currentTestContext","randomInt"],"sources":["../src/browser.ts"],"sourcesContent":["/**\n * A browser, for tests: a `fetch` that keeps cookies the way a browser does.\n *\n * An app's real clients — its typed API client, better-auth's client — run on\n * whatever `fetch` they are given. Give them this one and a test signs in the\n * way a person does: the auth server's `Set-Cookie` lands in the jar, and every\n * later request to a URL the cookie belongs to carries it. The jar follows the\n * browser's rules (RFC 6265 — Domain, Path, Secure, Expires), so a cookie set\n * for the wrong domain is not sent, exactly as a browser would not send it.\n *\n * Extend it once per app with that app's clients:\n *\n * ```ts\n * export class Browser extends TestBrowser {\n *   readonly api = createApi({ baseURL: process.env.API_URL, fetch: this.fetch });\n * }\n * ```\n */\n\nimport { randomInt } from 'node:crypto';\nimport { CookieJar } from 'tough-cookie';\nimport { currentTestContext } from './context';\n\n/** How many redirects `fetch` follows before giving up, as browsers do. */\nconst MAX_REDIRECTS = 20;\n\nexport interface BrowserOptions {\n\t/**\n\t * The `fetch` requests go out on. Defaults to the global one at the time\n\t * the browser is created — so a browser made inside a test goes through\n\t * whatever the test installed (MSW, the context stamp) and never through\n\t * itself once installed.\n\t */\n\tfetch?: typeof fetch;\n\t/**\n\t * The address this browser connects from. A fresh one by default, from a\n\t * private range nothing routes to — see {@link Browser.address}.\n\t */\n\taddress?: string;\n}\n\nexport class Browser {\n\t/** The cookies this browser holds. */\n\treadonly jar = new CookieJar();\n\n\t/**\n\t * The address this browser connects from, sent as `x-forwarded-for` the way\n\t * a proxy in front of the app adds it. Each browser is a different person on\n\t * a different connection, so what an app keys by client — an auth server's\n\t * rate limit — counts each on its own. Without it every browser was the same\n\t * client, and concurrent tests queued on the same rate-limit row of each\n\t * other's open transactions. A request that sets the header itself — a test\n\t * that is several machines — keeps its own.\n\t */\n\treadonly address: string;\n\n\t/**\n\t * This browser's `fetch`: cookies from the jar on the way out, `Set-Cookie`\n\t * into the jar on the way back, redirects followed hop by hop so each hop's\n\t * cookies are kept.\n\t *\n\t * On the server side of a test — a handler serving a request — it is the\n\t * plain `fetch`: a server forwards what it was handed and never reaches into\n\t * a browser's jar.\n\t */\n\treadonly fetch: typeof fetch;\n\n\tprivate readonly send: typeof fetch;\n\n\tconstructor(options: BrowserOptions = {}) {\n\t\tthis.send = options.fetch ?? globalThis.fetch;\n\t\tthis.address = options.address ?? privateAddress();\n\t\tthis.fetch = (input, init) => {\n\t\t\tif (currentTestContext()?.side === 'server') {\n\t\t\t\treturn this.send(input, init);\n\t\t\t}\n\t\t\treturn this.start(new Request(input, init), init?.redirect);\n\t\t};\n\t}\n\n\t/** Open a URL the way clicking a link does: a GET, redirects followed. */\n\tvisit(url: string | URL): Promise<Response> {\n\t\treturn this.fetch(String(url));\n\t}\n\n\t/** The cookies this browser would send to `url`, as a header value. */\n\tcookieHeader(url: string | URL): Promise<string> {\n\t\treturn this.jar.getCookieString(String(url));\n\t}\n\n\t/**\n\t * Make this browser the global `fetch`, for code that uses the global one —\n\t * an app's module-level clients. Returns what puts the previous one back.\n\t */\n\tinstall(): () => void {\n\t\tconst previous = globalThis.fetch;\n\t\tglobalThis.fetch = this.fetch;\n\t\treturn () => {\n\t\t\tglobalThis.fetch = previous;\n\t\t};\n\t}\n\n\t/** Read the body once, so a redirect that keeps the method can send it again. */\n\tprivate async start(\n\t\trequest: Request,\n\t\tredirect: RequestInit['redirect'],\n\t): Promise<Response> {\n\t\tconst body =\n\t\t\trequest.method === 'GET' || request.method === 'HEAD'\n\t\t\t\t? undefined\n\t\t\t\t: await request.arrayBuffer();\n\t\tconst headers = new Headers(request.headers);\n\t\tif (!headers.has('x-forwarded-for')) {\n\t\t\theaders.set('x-forwarded-for', this.address);\n\t\t}\n\t\treturn this.request(\n\t\t\t{ url: request.url, method: request.method, headers, body },\n\t\t\tredirect,\n\t\t);\n\t}\n\n\tprivate async request(\n\t\trequest: Hop,\n\t\tredirect: RequestInit['redirect'],\n\t\thops = 0,\n\t): Promise<Response> {\n\t\tconst headers = new Headers(request.headers);\n\t\tconst cookie = await this.jar.getCookieString(request.url);\n\t\tif (cookie) {\n\t\t\tconst existing = headers.get('cookie');\n\t\t\theaders.set('cookie', existing ? `${existing}; ${cookie}` : cookie);\n\t\t}\n\n\t\tconst response = await this.send(request.url, {\n\t\t\tmethod: request.method,\n\t\t\theaders,\n\t\t\tbody: request.body,\n\t\t\tredirect: 'manual',\n\t\t});\n\n\t\tfor (const set of response.headers.getSetCookie()) {\n\t\t\t// A cookie a browser would refuse — the wrong domain, Secure over\n\t\t\t// plain HTTP — is dropped silently, as a browser drops it.\n\t\t\tawait this.jar.setCookie(set, request.url, { ignoreError: true });\n\t\t}\n\n\t\tconst location = response.headers.get('location');\n\t\tif (\n\t\t\tredirect === 'manual' ||\n\t\t\t!location ||\n\t\t\tresponse.status < 300 ||\n\t\t\tresponse.status >= 400\n\t\t) {\n\t\t\treturn response;\n\t\t}\n\n\t\tif (hops >= MAX_REDIRECTS) {\n\t\t\tthrow new TooManyRedirects(request.url, MAX_REDIRECTS);\n\t\t}\n\n\t\t// 303, and 301/302 after a POST, continue as a GET without a body — what\n\t\t// every browser does, whatever the spec once said about 302.\n\t\tconst keepsMethod =\n\t\t\tresponse.status === 307 ||\n\t\t\tresponse.status === 308 ||\n\t\t\trequest.method === 'GET' ||\n\t\t\trequest.method === 'HEAD';\n\n\t\tconst url = new URL(location, request.url).toString();\n\t\tconst next: Hop = keepsMethod\n\t\t\t? { ...request, url }\n\t\t\t: { url, method: 'GET', headers: withoutBody(request.headers) };\n\n\t\treturn this.request(next, redirect, hops + 1);\n\t}\n}\n\n/** One request in a redirect chain, with its body already read. */\ninterface Hop {\n\turl: string;\n\tmethod: string;\n\theaders: Headers;\n\tbody?: ArrayBuffer;\n}\n\n/** Headers for a request that no longer carries the body they described. */\nfunction withoutBody(headers: Headers): Headers {\n\tconst next = new Headers(headers);\n\tnext.delete('content-type');\n\tnext.delete('content-length');\n\treturn next;\n}\n\n/** A redirect chain longer than any browser follows. */\nexport class TooManyRedirects extends Error {\n\tconstructor(\n\t\treadonly url: string,\n\t\treadonly limit: number,\n\t) {\n\t\tsuper(\n\t\t\t`${url} redirected more than ${limit} times. A browser gives up here ` +\n\t\t\t\t`too — look for a redirect loop.`,\n\t\t);\n\t\tthis.name = 'TooManyRedirects';\n\t}\n}\n\n/**\n * An address from 10.0.0.0/8, which nothing routes to. Random rather than\n * counted: test files run in separate workers that share no counter.\n */\nfunction privateAddress(): string {\n\tconst n = randomInt(1, 2 ** 24 - 1);\n\treturn `10.${(n >> 16) & 255}.${(n >> 8) & 255}.${n & 255}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAwBA,MAAM,gBAAgB;AAiBtB,IAAa,UAAb,MAAqB;;CAEpB,MAAe,IAAIA,aAAAA,UAAU;;;;;;;;;;CAW7B;;;;;;;;;;CAWA;CAEA;CAEA,YAAY,UAA0B,CAAC,GAAG;EACzC,KAAK,OAAO,QAAQ,SAAS,WAAW;EACxC,KAAK,UAAU,QAAQ,WAAW,eAAe;EACjD,KAAK,SAAS,OAAO,SAAS;GAC7B,IAAIC,gBAAAA,mBAAmB,CAAC,EAAE,SAAS,UAClC,OAAO,KAAK,KAAK,OAAO,IAAI;GAE7B,OAAO,KAAK,MAAM,IAAI,QAAQ,OAAO,IAAI,GAAG,MAAM,QAAQ;EAC3D;CACD;;CAGA,MAAM,KAAsC;EAC3C,OAAO,KAAK,MAAM,OAAO,GAAG,CAAC;CAC9B;;CAGA,aAAa,KAAoC;EAChD,OAAO,KAAK,IAAI,gBAAgB,OAAO,GAAG,CAAC;CAC5C;;;;;CAMA,UAAsB;EACrB,MAAM,WAAW,WAAW;EAC5B,WAAW,QAAQ,KAAK;EACxB,aAAa;GACZ,WAAW,QAAQ;EACpB;CACD;;CAGA,MAAc,MACb,SACA,UACoB;EACpB,MAAM,OACL,QAAQ,WAAW,SAAS,QAAQ,WAAW,SAC5C,KAAA,IACA,MAAM,QAAQ,YAAY;EAC9B,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;EAC3C,IAAI,CAAC,QAAQ,IAAI,iBAAiB,GACjC,QAAQ,IAAI,mBAAmB,KAAK,OAAO;EAE5C,OAAO,KAAK,QACX;GAAE,KAAK,QAAQ;GAAK,QAAQ,QAAQ;GAAQ;GAAS;EAAK,GAC1D,QACD;CACD;CAEA,MAAc,QACb,SACA,UACA,OAAO,GACa;EACpB,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;EAC3C,MAAM,SAAS,MAAM,KAAK,IAAI,gBAAgB,QAAQ,GAAG;EACzD,IAAI,QAAQ;GACX,MAAM,WAAW,QAAQ,IAAI,QAAQ;GACrC,QAAQ,IAAI,UAAU,WAAW,GAAG,SAAS,IAAI,WAAW,MAAM;EACnE;EAEA,MAAM,WAAW,MAAM,KAAK,KAAK,QAAQ,KAAK;GAC7C,QAAQ,QAAQ;GAChB;GACA,MAAM,QAAQ;GACd,UAAU;EACX,CAAC;EAED,KAAK,MAAM,OAAO,SAAS,QAAQ,aAAa,GAG/C,MAAM,KAAK,IAAI,UAAU,KAAK,QAAQ,KAAK,EAAE,aAAa,KAAK,CAAC;EAGjE,MAAM,WAAW,SAAS,QAAQ,IAAI,UAAU;EAChD,IACC,aAAa,YACb,CAAC,YACD,SAAS,SAAS,OAClB,SAAS,UAAU,KAEnB,OAAO;EAGR,IAAI,QAAQ,eACX,MAAM,IAAI,iBAAiB,QAAQ,KAAK,aAAa;EAKtD,MAAM,cACL,SAAS,WAAW,OACpB,SAAS,WAAW,OACpB,QAAQ,WAAW,SACnB,QAAQ,WAAW;EAEpB,MAAM,MAAM,IAAI,IAAI,UAAU,QAAQ,GAAG,CAAC,CAAC,SAAS;EACpD,MAAM,OAAY,cACf;GAAE,GAAG;GAAS;EAAI,IAClB;GAAE;GAAK,QAAQ;GAAO,SAAS,YAAY,QAAQ,OAAO;EAAE;EAE/D,OAAO,KAAK,QAAQ,MAAM,UAAU,OAAO,CAAC;CAC7C;AACD;;AAWA,SAAS,YAAY,SAA2B;CAC/C,MAAM,OAAO,IAAI,QAAQ,OAAO;CAChC,KAAK,OAAO,cAAc;CAC1B,KAAK,OAAO,gBAAgB;CAC5B,OAAO;AACR;;AAGA,IAAa,mBAAb,cAAsC,MAAM;CAEjC;CACA;CAFV,YACC,KACA,OACC;EACD,MACC,GAAG,IAAI,wBAAwB,MAAM,gEAEtC;EANS,KAAA,MAAA;EACA,KAAA,QAAA;EAMT,KAAK,OAAO;CACb;AACD;;;;;AAMA,SAAS,iBAAyB;CACjC,MAAM,KAAA,GAAIC,YAAAA,UAAAA,CAAU,GAAG,KAAK,KAAK,CAAC;CAClC,OAAO,MAAO,KAAK,KAAM,IAAI,GAAI,KAAK,IAAK,IAAI,GAAG,IAAI;AACvD"}

package/dist/browser.d.cts

@@ -0,0 +1,62 @@
+import { CookieJar } from "tough-cookie";
+//#region src/browser.d.ts
+export interface BrowserOptions {
+  /**
+   * The `fetch` requests go out on. Defaults to the global one at the time
+   * the browser is created — so a browser made inside a test goes through
+   * whatever the test installed (MSW, the context stamp) and never through
+   * itself once installed.
+   */
+  fetch?: typeof fetch;
+  /**
+   * The address this browser connects from. A fresh one by default, from a
+   * private range nothing routes to — see {@link Browser.address}.
+   */
+  address?: string;
+}
+export declare class Browser {
+  /** The cookies this browser holds. */
+  readonly jar: CookieJar;
+  /**
+   * The address this browser connects from, sent as `x-forwarded-for` the way
+   * a proxy in front of the app adds it. Each browser is a different person on
+   * a different connection, so what an app keys by client — an auth server's
+   * rate limit — counts each on its own. Without it every browser was the same
+   * client, and concurrent tests queued on the same rate-limit row of each
+   * other's open transactions. A request that sets the header itself — a test
+   * that is several machines — keeps its own.
+   */
+  readonly address: string;
+  /**
+   * This browser's `fetch`: cookies from the jar on the way out, `Set-Cookie`
+   * into the jar on the way back, redirects followed hop by hop so each hop's
+   * cookies are kept.
+   *
+   * On the server side of a test — a handler serving a request — it is the
+   * plain `fetch`: a server forwards what it was handed and never reaches into
+   * a browser's jar.
+   */
+  readonly fetch: typeof fetch;
+  private readonly send;
+  constructor(options?: BrowserOptions);
+  /** Open a URL the way clicking a link does: a GET, redirects followed. */
+  visit(url: string | URL): Promise<Response>;
+  /** The cookies this browser would send to `url`, as a header value. */
+  cookieHeader(url: string | URL): Promise<string>;
+  /**
+   * Make this browser the global `fetch`, for code that uses the global one —
+   * an app's module-level clients. Returns what puts the previous one back.
+   */
+  install(): () => void;
+  /** Read the body once, so a redirect that keeps the method can send it again. */
+  private start;
+  private request;
+}
+/** A redirect chain longer than any browser follows. */
+export declare class TooManyRedirects extends Error {
+  readonly url: string;
+  readonly limit: number;
+  constructor(url: string, limit: number);
+}
+//#endregion
+//# sourceMappingURL=browser.d.cts.map

package/dist/browser.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.cts","names":[],"sources":["../src/browser.ts"],"mappings":";;iBA0BiB;;;;;;;EAOhB,eAAe;;;;;EAKf;;qBAGY;;WAEH,KAAG;;;;;;;;;;WAWH;;;;;;;;;;WAWA,cAAc;mBAEN;EAEjB,YAAY,UAAS;;EAYrB,MAAM,cAAc,MAAM,QAAQ;;EAKlC,aAAa,cAAc,MAAM;;;;;EAQjC;;UASc;UAkBA;;;qBAyEF,yBAAyB;WAE3B;WACA;EAFV,YACU,aACA"}

package/dist/browser.d.mts

@@ -0,0 +1,62 @@
+import { CookieJar } from "tough-cookie";
+//#region src/browser.d.ts
+export interface BrowserOptions {
+  /**
+   * The `fetch` requests go out on. Defaults to the global one at the time
+   * the browser is created — so a browser made inside a test goes through
+   * whatever the test installed (MSW, the context stamp) and never through
+   * itself once installed.
+   */
+  fetch?: typeof fetch;
+  /**
+   * The address this browser connects from. A fresh one by default, from a
+   * private range nothing routes to — see {@link Browser.address}.
+   */
+  address?: string;
+}
+export declare class Browser {
+  /** The cookies this browser holds. */
+  readonly jar: CookieJar;
+  /**
+   * The address this browser connects from, sent as `x-forwarded-for` the way
+   * a proxy in front of the app adds it. Each browser is a different person on
+   * a different connection, so what an app keys by client — an auth server's
+   * rate limit — counts each on its own. Without it every browser was the same
+   * client, and concurrent tests queued on the same rate-limit row of each
+   * other's open transactions. A request that sets the header itself — a test
+   * that is several machines — keeps its own.
+   */
+  readonly address: string;
+  /**
+   * This browser's `fetch`: cookies from the jar on the way out, `Set-Cookie`
+   * into the jar on the way back, redirects followed hop by hop so each hop's
+   * cookies are kept.
+   *
+   * On the server side of a test — a handler serving a request — it is the
+   * plain `fetch`: a server forwards what it was handed and never reaches into
+   * a browser's jar.
+   */
+  readonly fetch: typeof fetch;
+  private readonly send;
+  constructor(options?: BrowserOptions);
+  /** Open a URL the way clicking a link does: a GET, redirects followed. */
+  visit(url: string | URL): Promise<Response>;
+  /** The cookies this browser would send to `url`, as a header value. */
+  cookieHeader(url: string | URL): Promise<string>;
+  /**
+   * Make this browser the global `fetch`, for code that uses the global one —
+   * an app's module-level clients. Returns what puts the previous one back.
+   */
+  install(): () => void;
+  /** Read the body once, so a redirect that keeps the method can send it again. */
+  private start;
+  private request;
+}
+/** A redirect chain longer than any browser follows. */
+export declare class TooManyRedirects extends Error {
+  readonly url: string;
+  readonly limit: number;
+  constructor(url: string, limit: number);
+}
+//#endregion
+//# sourceMappingURL=browser.d.mts.map

package/dist/browser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.mts","names":[],"sources":["../src/browser.ts"],"mappings":";;iBA0BiB;;;;;;;EAOhB,eAAe;;;;;EAKf;;qBAGY;;WAEH,KAAG;;;;;;;;;;WAWH;;;;;;;;;;WAWA,cAAc;mBAEN;EAEjB,YAAY,UAAS;;EAYrB,MAAM,cAAc,MAAM,QAAQ;;EAKlC,aAAa,cAAc,MAAM;;;;;EAQjC;;UASc;UAkBA;;;qBAyEF,yBAAyB;WAE3B;WACA;EAFV,YACU,aACA"}

package/dist/browser.mjs

@@ -0,0 +1,147 @@
+import { currentTestContext } from "./context.mjs";
+import { randomInt } from "node:crypto";
+import { CookieJar } from "tough-cookie";
+//#region src/browser.ts
+/**
+* A browser, for tests: a `fetch` that keeps cookies the way a browser does.
+*
+* An app's real clients — its typed API client, better-auth's client — run on
+* whatever `fetch` they are given. Give them this one and a test signs in the
+* way a person does: the auth server's `Set-Cookie` lands in the jar, and every
+* later request to a URL the cookie belongs to carries it. The jar follows the
+* browser's rules (RFC 6265 — Domain, Path, Secure, Expires), so a cookie set
+* for the wrong domain is not sent, exactly as a browser would not send it.
+*
+* Extend it once per app with that app's clients:
+*
+* ```ts
+* export class Browser extends TestBrowser {
+*   readonly api = createApi({ baseURL: process.env.API_URL, fetch: this.fetch });
+* }
+* ```
+*/
+/** How many redirects `fetch` follows before giving up, as browsers do. */
+const MAX_REDIRECTS = 20;
+var Browser = class {
+	/** The cookies this browser holds. */
+	jar = new CookieJar();
+	/**
+	* The address this browser connects from, sent as `x-forwarded-for` the way
+	* a proxy in front of the app adds it. Each browser is a different person on
+	* a different connection, so what an app keys by client — an auth server's
+	* rate limit — counts each on its own. Without it every browser was the same
+	* client, and concurrent tests queued on the same rate-limit row of each
+	* other's open transactions. A request that sets the header itself — a test
+	* that is several machines — keeps its own.
+	*/
+	address;
+	/**
+	* This browser's `fetch`: cookies from the jar on the way out, `Set-Cookie`
+	* into the jar on the way back, redirects followed hop by hop so each hop's
+	* cookies are kept.
+	*
+	* On the server side of a test — a handler serving a request — it is the
+	* plain `fetch`: a server forwards what it was handed and never reaches into
+	* a browser's jar.
+	*/
+	fetch;
+	send;
+	constructor(options = {}) {
+		this.send = options.fetch ?? globalThis.fetch;
+		this.address = options.address ?? privateAddress();
+		this.fetch = (input, init) => {
+			if (currentTestContext()?.side === "server") return this.send(input, init);
+			return this.start(new Request(input, init), init?.redirect);
+		};
+	}
+	/** Open a URL the way clicking a link does: a GET, redirects followed. */
+	visit(url) {
+		return this.fetch(String(url));
+	}
+	/** The cookies this browser would send to `url`, as a header value. */
+	cookieHeader(url) {
+		return this.jar.getCookieString(String(url));
+	}
+	/**
+	* Make this browser the global `fetch`, for code that uses the global one —
+	* an app's module-level clients. Returns what puts the previous one back.
+	*/
+	install() {
+		const previous = globalThis.fetch;
+		globalThis.fetch = this.fetch;
+		return () => {
+			globalThis.fetch = previous;
+		};
+	}
+	/** Read the body once, so a redirect that keeps the method can send it again. */
+	async start(request, redirect) {
+		const body = request.method === "GET" || request.method === "HEAD" ? void 0 : await request.arrayBuffer();
+		const headers = new Headers(request.headers);
+		if (!headers.has("x-forwarded-for")) headers.set("x-forwarded-for", this.address);
+		return this.request({
+			url: request.url,
+			method: request.method,
+			headers,
+			body
+		}, redirect);
+	}
+	async request(request, redirect, hops = 0) {
+		const headers = new Headers(request.headers);
+		const cookie = await this.jar.getCookieString(request.url);
+		if (cookie) {
+			const existing = headers.get("cookie");
+			headers.set("cookie", existing ? `${existing}; ${cookie}` : cookie);
+		}
+		const response = await this.send(request.url, {
+			method: request.method,
+			headers,
+			body: request.body,
+			redirect: "manual"
+		});
+		for (const set of response.headers.getSetCookie()) await this.jar.setCookie(set, request.url, { ignoreError: true });
+		const location = response.headers.get("location");
+		if (redirect === "manual" || !location || response.status < 300 || response.status >= 400) return response;
+		if (hops >= MAX_REDIRECTS) throw new TooManyRedirects(request.url, MAX_REDIRECTS);
+		const keepsMethod = response.status === 307 || response.status === 308 || request.method === "GET" || request.method === "HEAD";
+		const url = new URL(location, request.url).toString();
+		const next = keepsMethod ? {
+			...request,
+			url
+		} : {
+			url,
+			method: "GET",
+			headers: withoutBody(request.headers)
+		};
+		return this.request(next, redirect, hops + 1);
+	}
+};
+/** Headers for a request that no longer carries the body they described. */
+function withoutBody(headers) {
+	const next = new Headers(headers);
+	next.delete("content-type");
+	next.delete("content-length");
+	return next;
+}
+/** A redirect chain longer than any browser follows. */
+var TooManyRedirects = class extends Error {
+	url;
+	limit;
+	constructor(url, limit) {
+		super(`${url} redirected more than ${limit} times. A browser gives up here too — look for a redirect loop.`);
+		this.url = url;
+		this.limit = limit;
+		this.name = "TooManyRedirects";
+	}
+};
+/**
+* An address from 10.0.0.0/8, which nothing routes to. Random rather than
+* counted: test files run in separate workers that share no counter.
+*/
+function privateAddress() {
+	const n = randomInt(1, 2 ** 24 - 1);
+	return `10.${n >> 16 & 255}.${n >> 8 & 255}.${n & 255}`;
+}
+//#endregion
+export { Browser, TooManyRedirects };
+
+//# sourceMappingURL=browser.mjs.map

package/dist/browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.mjs","names":[],"sources":["../src/browser.ts"],"sourcesContent":["/**\n * A browser, for tests: a `fetch` that keeps cookies the way a browser does.\n *\n * An app's real clients — its typed API client, better-auth's client — run on\n * whatever `fetch` they are given. Give them this one and a test signs in the\n * way a person does: the auth server's `Set-Cookie` lands in the jar, and every\n * later request to a URL the cookie belongs to carries it. The jar follows the\n * browser's rules (RFC 6265 — Domain, Path, Secure, Expires), so a cookie set\n * for the wrong domain is not sent, exactly as a browser would not send it.\n *\n * Extend it once per app with that app's clients:\n *\n * ```ts\n * export class Browser extends TestBrowser {\n *   readonly api = createApi({ baseURL: process.env.API_URL, fetch: this.fetch });\n * }\n * ```\n */\n\nimport { randomInt } from 'node:crypto';\nimport { CookieJar } from 'tough-cookie';\nimport { currentTestContext } from './context';\n\n/** How many redirects `fetch` follows before giving up, as browsers do. */\nconst MAX_REDIRECTS = 20;\n\nexport interface BrowserOptions {\n\t/**\n\t * The `fetch` requests go out on. Defaults to the global one at the time\n\t * the browser is created — so a browser made inside a test goes through\n\t * whatever the test installed (MSW, the context stamp) and never through\n\t * itself once installed.\n\t */\n\tfetch?: typeof fetch;\n\t/**\n\t * The address this browser connects from. A fresh one by default, from a\n\t * private range nothing routes to — see {@link Browser.address}.\n\t */\n\taddress?: string;\n}\n\nexport class Browser {\n\t/** The cookies this browser holds. */\n\treadonly jar = new CookieJar();\n\n\t/**\n\t * The address this browser connects from, sent as `x-forwarded-for` the way\n\t * a proxy in front of the app adds it. Each browser is a different person on\n\t * a different connection, so what an app keys by client — an auth server's\n\t * rate limit — counts each on its own. Without it every browser was the same\n\t * client, and concurrent tests queued on the same rate-limit row of each\n\t * other's open transactions. A request that sets the header itself — a test\n\t * that is several machines — keeps its own.\n\t */\n\treadonly address: string;\n\n\t/**\n\t * This browser's `fetch`: cookies from the jar on the way out, `Set-Cookie`\n\t * into the jar on the way back, redirects followed hop by hop so each hop's\n\t * cookies are kept.\n\t *\n\t * On the server side of a test — a handler serving a request — it is the\n\t * plain `fetch`: a server forwards what it was handed and never reaches into\n\t * a browser's jar.\n\t */\n\treadonly fetch: typeof fetch;\n\n\tprivate readonly send: typeof fetch;\n\n\tconstructor(options: BrowserOptions = {}) {\n\t\tthis.send = options.fetch ?? globalThis.fetch;\n\t\tthis.address = options.address ?? privateAddress();\n\t\tthis.fetch = (input, init) => {\n\t\t\tif (currentTestContext()?.side === 'server') {\n\t\t\t\treturn this.send(input, init);\n\t\t\t}\n\t\t\treturn this.start(new Request(input, init), init?.redirect);\n\t\t};\n\t}\n\n\t/** Open a URL the way clicking a link does: a GET, redirects followed. */\n\tvisit(url: string | URL): Promise<Response> {\n\t\treturn this.fetch(String(url));\n\t}\n\n\t/** The cookies this browser would send to `url`, as a header value. */\n\tcookieHeader(url: string | URL): Promise<string> {\n\t\treturn this.jar.getCookieString(String(url));\n\t}\n\n\t/**\n\t * Make this browser the global `fetch`, for code that uses the global one —\n\t * an app's module-level clients. Returns what puts the previous one back.\n\t */\n\tinstall(): () => void {\n\t\tconst previous = globalThis.fetch;\n\t\tglobalThis.fetch = this.fetch;\n\t\treturn () => {\n\t\t\tglobalThis.fetch = previous;\n\t\t};\n\t}\n\n\t/** Read the body once, so a redirect that keeps the method can send it again. */\n\tprivate async start(\n\t\trequest: Request,\n\t\tredirect: RequestInit['redirect'],\n\t): Promise<Response> {\n\t\tconst body =\n\t\t\trequest.method === 'GET' || request.method === 'HEAD'\n\t\t\t\t? undefined\n\t\t\t\t: await request.arrayBuffer();\n\t\tconst headers = new Headers(request.headers);\n\t\tif (!headers.has('x-forwarded-for')) {\n\t\t\theaders.set('x-forwarded-for', this.address);\n\t\t}\n\t\treturn this.request(\n\t\t\t{ url: request.url, method: request.method, headers, body },\n\t\t\tredirect,\n\t\t);\n\t}\n\n\tprivate async request(\n\t\trequest: Hop,\n\t\tredirect: RequestInit['redirect'],\n\t\thops = 0,\n\t): Promise<Response> {\n\t\tconst headers = new Headers(request.headers);\n\t\tconst cookie = await this.jar.getCookieString(request.url);\n\t\tif (cookie) {\n\t\t\tconst existing = headers.get('cookie');\n\t\t\theaders.set('cookie', existing ? `${existing}; ${cookie}` : cookie);\n\t\t}\n\n\t\tconst response = await this.send(request.url, {\n\t\t\tmethod: request.method,\n\t\t\theaders,\n\t\t\tbody: request.body,\n\t\t\tredirect: 'manual',\n\t\t});\n\n\t\tfor (const set of response.headers.getSetCookie()) {\n\t\t\t// A cookie a browser would refuse — the wrong domain, Secure over\n\t\t\t// plain HTTP — is dropped silently, as a browser drops it.\n\t\t\tawait this.jar.setCookie(set, request.url, { ignoreError: true });\n\t\t}\n\n\t\tconst location = response.headers.get('location');\n\t\tif (\n\t\t\tredirect === 'manual' ||\n\t\t\t!location ||\n\t\t\tresponse.status < 300 ||\n\t\t\tresponse.status >= 400\n\t\t) {\n\t\t\treturn response;\n\t\t}\n\n\t\tif (hops >= MAX_REDIRECTS) {\n\t\t\tthrow new TooManyRedirects(request.url, MAX_REDIRECTS);\n\t\t}\n\n\t\t// 303, and 301/302 after a POST, continue as a GET without a body — what\n\t\t// every browser does, whatever the spec once said about 302.\n\t\tconst keepsMethod =\n\t\t\tresponse.status === 307 ||\n\t\t\tresponse.status === 308 ||\n\t\t\trequest.method === 'GET' ||\n\t\t\trequest.method === 'HEAD';\n\n\t\tconst url = new URL(location, request.url).toString();\n\t\tconst next: Hop = keepsMethod\n\t\t\t? { ...request, url }\n\t\t\t: { url, method: 'GET', headers: withoutBody(request.headers) };\n\n\t\treturn this.request(next, redirect, hops + 1);\n\t}\n}\n\n/** One request in a redirect chain, with its body already read. */\ninterface Hop {\n\turl: string;\n\tmethod: string;\n\theaders: Headers;\n\tbody?: ArrayBuffer;\n}\n\n/** Headers for a request that no longer carries the body they described. */\nfunction withoutBody(headers: Headers): Headers {\n\tconst next = new Headers(headers);\n\tnext.delete('content-type');\n\tnext.delete('content-length');\n\treturn next;\n}\n\n/** A redirect chain longer than any browser follows. */\nexport class TooManyRedirects extends Error {\n\tconstructor(\n\t\treadonly url: string,\n\t\treadonly limit: number,\n\t) {\n\t\tsuper(\n\t\t\t`${url} redirected more than ${limit} times. A browser gives up here ` +\n\t\t\t\t`too — look for a redirect loop.`,\n\t\t);\n\t\tthis.name = 'TooManyRedirects';\n\t}\n}\n\n/**\n * An address from 10.0.0.0/8, which nothing routes to. Random rather than\n * counted: test files run in separate workers that share no counter.\n */\nfunction privateAddress(): string {\n\tconst n = randomInt(1, 2 ** 24 - 1);\n\treturn `10.${(n >> 16) & 255}.${(n >> 8) & 255}.${n & 255}`;\n}\n"],"mappings":"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"}

package/dist/context.cjs

@@ -0,0 +1,80 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_async_hooks = require("node:async_hooks");
+//#region src/context.ts
+/**
+* The test a request belongs to.
+*
+* A feature test drives an app the way it runs deployed: a browser calls the
+* API, the API calls the auth server, each over a URL. In a test those URLs are
+* served in-process, and every request made on behalf of one test has to reach
+* *that test's* transactions — its own call to the API, and the API's call to
+* the auth server made while handling it.
+*
+* The id travels two ways. In-process, an `AsyncLocalStorage` carries it
+* through every await a test and its handlers make. On the wire it is the
+* `x-test-context-id` header, which a stamped `fetch` adds to every request made
+* inside a context, so whatever serves the URL can find the context again —
+* without any caller, including code under test, writing the header.
+*/
+/** The header a test context travels in between client and server. */
+const TEST_CONTEXT_HEADER = "x-test-context-id";
+const storage = new node_async_hooks.AsyncLocalStorage();
+/** The context the running code belongs to, if any. */
+function currentTestContext() {
+	return storage.getStore();
+}
+/** Run `fn` as the client side of the test `id`. */
+function runInTestContext(id, fn) {
+	return storage.run({
+		id,
+		side: "client"
+	}, fn);
+}
+/**
+* Run `fn` as a server handling a request for the test `id` — what whatever
+* serves a URL in-process wraps each request in.
+*/
+function runAsServer(id, fn) {
+	return storage.run({
+		id,
+		side: "server"
+	}, fn);
+}
+/** The test a request was made for, read off its header. */
+function testContextOf(request) {
+	return request.headers.get("x-test-context-id") ?? void 0;
+}
+/** `fetch`, adding the current test's id to every request made inside one. */
+function stampedFetch(inner) {
+	return (input, init) => {
+		const context = currentTestContext();
+		if (!context) return inner(input, init);
+		const request = new Request(input, init);
+		if (!request.headers.has("x-test-context-id")) request.headers.set(TEST_CONTEXT_HEADER, context.id);
+		return inner(request);
+	};
+}
+/**
+* Stamp the global `fetch` with the current test's id.
+*
+* Install it after anything else that patches `fetch` — MSW's interceptor in
+* particular — so the stamp is added before the request is intercepted.
+* Returns what puts the previous `fetch` back.
+*/
+function installContextFetch() {
+	const previous = globalThis.fetch;
+	globalThis.fetch = stampedFetch(previous);
+	return () => {
+		globalThis.fetch = previous;
+	};
+}
+//#endregion
+exports.TEST_CONTEXT_HEADER = TEST_CONTEXT_HEADER;
+exports.currentTestContext = currentTestContext;
+exports.installContextFetch = installContextFetch;
+exports.runAsServer = runAsServer;
+exports.runInTestContext = runInTestContext;
+exports.stampedFetch = stampedFetch;
+exports.testContextOf = testContextOf;
+
+//# sourceMappingURL=context.cjs.map

package/dist/context.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.cjs","names":["AsyncLocalStorage"],"sources":["../src/context.ts"],"sourcesContent":["/**\n * The test a request belongs to.\n *\n * A feature test drives an app the way it runs deployed: a browser calls the\n * API, the API calls the auth server, each over a URL. In a test those URLs are\n * served in-process, and every request made on behalf of one test has to reach\n * *that test's* transactions — its own call to the API, and the API's call to\n * the auth server made while handling it.\n *\n * The id travels two ways. In-process, an `AsyncLocalStorage` carries it\n * through every await a test and its handlers make. On the wire it is the\n * `x-test-context-id` header, which a stamped `fetch` adds to every request made\n * inside a context, so whatever serves the URL can find the context again —\n * without any caller, including code under test, writing the header.\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n/** The header a test context travels in between client and server. */\nexport const TEST_CONTEXT_HEADER = 'x-test-context-id';\n\n/**\n * Which side of a URL the running code is on.\n *\n * `client` is the test itself and the frontend it renders — what a browser\n * does. `server` is a handler serving a request. The difference matters for\n * cookies: a browser attaches its cookies to what it sends, a server forwards\n * only what it was handed. A server call that picked up the browser's cookies\n * would hide the bug of a server that forgets to forward them.\n */\nexport type TestSide = 'client' | 'server';\n\nexport interface TestContext {\n\treadonly id: string;\n\treadonly side: TestSide;\n}\n\nconst storage = new AsyncLocalStorage<TestContext>();\n\n/** The context the running code belongs to, if any. */\nexport function currentTestContext(): TestContext | undefined {\n\treturn storage.getStore();\n}\n\n/** Run `fn` as the client side of the test `id`. */\nexport function runInTestContext<T>(id: string, fn: () => T): T {\n\treturn storage.run({ id, side: 'client' }, fn);\n}\n\n/**\n * Run `fn` as a server handling a request for the test `id` — what whatever\n * serves a URL in-process wraps each request in.\n */\nexport function runAsServer<T>(id: string, fn: () => T): T {\n\treturn storage.run({ id, side: 'server' }, fn);\n}\n\n/** The test a request was made for, read off its header. */\nexport function testContextOf(request: Request): string | undefined {\n\treturn request.headers.get(TEST_CONTEXT_HEADER) ?? undefined;\n}\n\n/** `fetch`, adding the current test's id to every request made inside one. */\nexport function stampedFetch(inner: typeof fetch): typeof fetch {\n\treturn (input, init) => {\n\t\tconst context = currentTestContext();\n\t\tif (!context) return inner(input, init);\n\n\t\tconst request = new Request(input, init);\n\t\tif (!request.headers.has(TEST_CONTEXT_HEADER)) {\n\t\t\trequest.headers.set(TEST_CONTEXT_HEADER, context.id);\n\t\t}\n\t\treturn inner(request);\n\t};\n}\n\n/**\n * Stamp the global `fetch` with the current test's id.\n *\n * Install it after anything else that patches `fetch` — MSW's interceptor in\n * particular — so the stamp is added before the request is intercepted.\n * Returns what puts the previous `fetch` back.\n */\nexport function installContextFetch(): () => void {\n\tconst previous = globalThis.fetch;\n\tglobalThis.fetch = stampedFetch(previous);\n\treturn () => {\n\t\tglobalThis.fetch = previous;\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,MAAa,sBAAsB;AAkBnC,MAAM,UAAU,IAAIA,iBAAAA,kBAA+B;;AAGnD,SAAgB,qBAA8C;CAC7D,OAAO,QAAQ,SAAS;AACzB;;AAGA,SAAgB,iBAAoB,IAAY,IAAgB;CAC/D,OAAO,QAAQ,IAAI;EAAE;EAAI,MAAM;CAAS,GAAG,EAAE;AAC9C;;;;;AAMA,SAAgB,YAAe,IAAY,IAAgB;CAC1D,OAAO,QAAQ,IAAI;EAAE;EAAI,MAAM;CAAS,GAAG,EAAE;AAC9C;;AAGA,SAAgB,cAAc,SAAsC;CACnE,OAAO,QAAQ,QAAQ,IAAA,mBAAuB,KAAK,KAAA;AACpD;;AAGA,SAAgB,aAAa,OAAmC;CAC/D,QAAQ,OAAO,SAAS;EACvB,MAAM,UAAU,mBAAmB;EACnC,IAAI,CAAC,SAAS,OAAO,MAAM,OAAO,IAAI;EAEtC,MAAM,UAAU,IAAI,QAAQ,OAAO,IAAI;EACvC,IAAI,CAAC,QAAQ,QAAQ,IAAA,mBAAuB,GAC3C,QAAQ,QAAQ,IAAI,qBAAqB,QAAQ,EAAE;EAEpD,OAAO,MAAM,OAAO;CACrB;AACD;;;;;;;;AASA,SAAgB,sBAAkC;CACjD,MAAM,WAAW,WAAW;CAC5B,WAAW,QAAQ,aAAa,QAAQ;CACxC,aAAa;EACZ,WAAW,QAAQ;CACpB;AACD"}

package/dist/context.d.cts

@@ -0,0 +1,55 @@
+//#region src/context.d.ts
+/**
+ * The test a request belongs to.
+ *
+ * A feature test drives an app the way it runs deployed: a browser calls the
+ * API, the API calls the auth server, each over a URL. In a test those URLs are
+ * served in-process, and every request made on behalf of one test has to reach
+ * *that test's* transactions — its own call to the API, and the API's call to
+ * the auth server made while handling it.
+ *
+ * The id travels two ways. In-process, an `AsyncLocalStorage` carries it
+ * through every await a test and its handlers make. On the wire it is the
+ * `x-test-context-id` header, which a stamped `fetch` adds to every request made
+ * inside a context, so whatever serves the URL can find the context again —
+ * without any caller, including code under test, writing the header.
+ */
+/** The header a test context travels in between client and server. */
+export declare const TEST_CONTEXT_HEADER = "x-test-context-id";
+/**
+ * Which side of a URL the running code is on.
+ *
+ * `client` is the test itself and the frontend it renders — what a browser
+ * does. `server` is a handler serving a request. The difference matters for
+ * cookies: a browser attaches its cookies to what it sends, a server forwards
+ * only what it was handed. A server call that picked up the browser's cookies
+ * would hide the bug of a server that forgets to forward them.
+ */
+export type TestSide = 'client' | 'server';
+export interface TestContext {
+  readonly id: string;
+  readonly side: TestSide;
+}
+/** The context the running code belongs to, if any. */
+export declare function currentTestContext(): TestContext | undefined;
+/** Run `fn` as the client side of the test `id`. */
+export declare function runInTestContext<T>(id: string, fn: () => T): T;
+/**
+ * Run `fn` as a server handling a request for the test `id` — what whatever
+ * serves a URL in-process wraps each request in.
+ */
+export declare function runAsServer<T>(id: string, fn: () => T): T;
+/** The test a request was made for, read off its header. */
+export declare function testContextOf(request: Request): string | undefined;
+/** `fetch`, adding the current test's id to every request made inside one. */
+export declare function stampedFetch(inner: typeof fetch): typeof fetch;
+/**
+ * Stamp the global `fetch` with the current test's id.
+ *
+ * Install it after anything else that patches `fetch` — MSW's interceptor in
+ * particular — so the stamp is added before the request is intercepted.
+ * Returns what puts the previous `fetch` back.
+ */
+export declare function installContextFetch(): () => void;
+//#endregion
+//# sourceMappingURL=context.d.cts.map

package/dist/context.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.cts","names":[],"sources":["../src/context.ts"],"mappings":";;;;;;;;;;;;;;;;;qBAmBa;;;;;;;;;;YAWD;iBAEK;WACP;WACA,MAAM;;;wBAMA,sBAAsB;;wBAKtB,iBAAiB,GAAG,YAAY,UAAU,IAAI;;;;;wBAQ9C,YAAY,GAAG,YAAY,UAAU,IAAI;;wBAKzC,cAAc,SAAS;;wBAKvB,aAAa,cAAc,eAAe;;;;;;;;wBAoB1C"}