@apifuse/provider-sdk 2.1.0-beta.10 → 2.1.0-beta.12

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.12
+
+- Release candidate for main commit 2bc1061c6a68facaa2efde08bee31bf5cd96945e.
+
+## 2.1.0-beta.11
+
+- Release candidate for main commit b98ddc5024698f8c79e05e3295f7c8c8e8fe5a8a.
+
 ## 2.1.0-beta.9
 
 - Preserve raw stealth response bytes through the public SDK response wrapper.

package/README.md

@@ -124,12 +124,16 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `flowId`; preserve any returned `contextPatch` in the next local request's
   `context` object.
 - **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
-  `ctx.stealth.fetch()` when you need browser-like session or cookie control. `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and accepts request
-  controls for `params`, `proxy`, `timeout`, `profile`, `throwOnHttpError`, and
-  `stealth.insecureSkipVerify`. Select an SDK stealth `profile` such as
-  `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or pseudo-header order in
-  provider code. Chrome/Firefox-style profiles are supported; use `ctx.browser`
-  when Safari-specific behavior is required.
+  `ctx.stealth.fetch()` when you need browser-like session or cookie control.
+  `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and
+  accepts request controls for `params`, `proxy`, `timeout`, `profile`,
+  `redirect`, `throwOnHttpError`, and `stealth.insecureSkipVerify`. For login
+  flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
+  a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
+  inspect accumulated cookies through `session.cookies`. Select an SDK stealth
+  `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
+  pseudo-header order in provider code. Chrome/Firefox-style profiles are
+  supported; use `ctx.browser` when Safari-specific behavior is required.
 - **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
   `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
   Install local browser assets with `bunx playwright install chromium` when

package/dist/cli/create.js

@@ -544,8 +544,8 @@ function renderAuthBlock(authMode) {
             return `{
     mode: "credentials",
     flow: {
-      start: async () => ({
-        kind: "input",
+      start: async (_ctx) => ({
+        kind: "form",
         turnId: crypto.randomUUID(),
         expectedInput: {
           schema: {
@@ -588,7 +588,7 @@ function renderAuthBlock(authMode) {
             return `{
     mode: "oauth2",
     flow: {
-      start: async () => ({
+      start: async (_ctx) => ({
         kind: "redirect",
         turnId: crypto.randomUUID(),
         data: {

package/dist/index.d.ts

@@ -33,7 +33,7 @@ export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SEN
 export { createServerApp, type ServeOptions, serve } from "./server";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles";
 export * from "./stream";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, ConnectionMode, ContextDeclaration, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderHealthMonitorConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthFetchOptions, StealthPlatform, StealthProfile, StealthResponse, StealthSession, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderHealthMonitorConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types";
 export * from "./utils/date";
 export * from "./utils/parse";

package/dist/runtime/stealth.d.ts

@@ -12,7 +12,10 @@ export type StealthClientOptions = ProxyResolutionOptions & {
         insecureSkipVerify?: boolean;
     };
 };
-type StealthTransportResponse = Pick<ImpitResponse, "arrayBuffer" | "headers" | "json" | "ok" | "status" | "text" | "url">;
-export declare function normalizeResponse(response: StealthTransportResponse): Promise<StealthResponse>;
+type StealthTransportResponse = Pick<ImpitResponse, "arrayBuffer" | "headers" | "json" | "ok" | "status" | "text"> & {
+    url?: string;
+    redirected?: boolean;
+};
+export declare function normalizeResponse(response: StealthTransportResponse, requestUrl?: string): Promise<StealthResponse>;
 export declare function createStealthClient(baseUrl: string, defaultProfileOrOptions?: string | StealthClientOptions, clientOptions?: StealthClientOptions): StealthClient;
 export {};

package/dist/runtime/stealth.js

@@ -102,11 +102,32 @@ class CookieJarImpl {
     getAll() {
         return { ...this.cookies };
     }
+    has(name) {
+        return Object.hasOwn(this.cookies, name);
+    }
     toString() {
         return Object.entries(this.cookies)
             .map(([name, value]) => `${name}=${value}`)
             .join("; ");
     }
+    toHeader() {
+        return this.toString();
+    }
+    snapshot() {
+        return this.getAll();
+    }
+    restore(cookies) {
+        this.clear();
+        for (const [name, value] of Object.entries(cookies)) {
+            if (name)
+                this.cookies[name] = value;
+        }
+    }
+    clear() {
+        for (const name of Object.keys(this.cookies)) {
+            delete this.cookies[name];
+        }
+    }
     find(predicate) {
         for (const [name, value] of Object.entries(this.cookies)) {
             const cookie = `${name}=${value}`;
@@ -237,7 +258,7 @@ function splitCombinedSetCookieHeader(headerValue) {
         cookieStrings.push(finalCookie);
     return cookieStrings;
 }
-export async function normalizeResponse(response) {
+export async function normalizeResponse(response, requestUrl) {
     const headers = Object.fromEntries(response.headers.entries());
     const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers));
     const bodyBytes = await response.arrayBuffer();
@@ -245,6 +266,12 @@ export async function normalizeResponse(response) {
     return {
         status: response.status,
         ok: response.status >= 200 && response.status < 300,
+        ...(response.url ? { url: response.url } : {}),
+        ...(response.redirected !== undefined
+            ? { redirected: response.redirected }
+            : requestUrl && response.url
+                ? { redirected: response.url !== requestUrl }
+                : {}),
         headers,
         rawHeaders: headerEntriesFromHeaders(response.headers),
         body,
@@ -537,6 +564,23 @@ function normalizeMethod(method) {
             throw new SDKError(`Unsupported stealth method: ${method}`);
     }
 }
+function isRedirectStatus(status) {
+    return [301, 302, 303, 307, 308].includes(status);
+}
+function nextRedirectMethod(status, method) {
+    if (status === 303 && method !== "HEAD")
+        return "GET";
+    if ((status === 301 || status === 302) && method === "POST")
+        return "GET";
+    return method;
+}
+function locationHeader(headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === "location")
+            return value;
+    }
+    return undefined;
+}
 function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     const clients = new Map();
     let closed = false;
@@ -588,7 +632,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             proxyHash: proxyEndpointHash(resolvedProxy.url),
         };
     }
-    return {
+    const session = {
         async fetch(url, options = {}) {
             const method = normalizeMethod(options.method ?? "GET");
             const hasExplicitRetryPolicy = options.retry !== undefined;
@@ -656,13 +700,14 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const requestInit = {
                             headers: normalizeHeaders(headers),
                             method,
+                            ...(options.redirect ? { redirect: options.redirect } : {}),
                             ...(options.timeout ? { timeout: options.timeout } : {}),
                         };
                         if (options.body !== undefined) {
                             requestInit.body = normalizeBody(options.body);
                         }
                         const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(requestUrl, requestInit);
-                        const normalized = await normalizeResponse(response);
+                        const normalized = await normalizeResponse(response, requestUrl);
                         cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
                         if (proxy &&
                             isProxyConnectFailureResponse(response, normalized.body)) {
@@ -758,11 +803,112 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             }
             throw normalizeStealthTransportError(lastError);
         },
+        cookies: cookieJar,
+        redirects: {
+            async run(options) {
+                const maxHops = options.maxHops === undefined || !Number.isFinite(options.maxHops)
+                    ? 10
+                    : Math.max(0, Math.floor(options.maxHops));
+                const hops = [];
+                let currentUrl = resolveUrl(baseUrl, options.url);
+                let method = normalizeMethod(options.method ?? "GET");
+                let body = options.body;
+                let response;
+                const visitedRequests = new Set();
+                const { url: _url, maxHops: _maxHops, stopWhen, params, ...fetchOptions } = options;
+                for (let hopIndex = 0; hopIndex <= maxHops; hopIndex += 1) {
+                    visitedRequests.add(`${method} ${currentUrl}`);
+                    response = await session.fetch(currentUrl, {
+                        ...fetchOptions,
+                        body,
+                        method,
+                        ...(hopIndex === 0 && params ? { params } : {}),
+                        redirect: "manual",
+                        throwOnHttpError: false,
+                    });
+                    if (!isRedirectStatus(response.status)) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "completed",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    const location = locationHeader(response.headers);
+                    const nextUrl = location
+                        ? new URL(location, response.url ?? currentUrl).toString()
+                        : undefined;
+                    const hop = {
+                        url: response.url ?? currentUrl,
+                        status: response.status,
+                        method,
+                        ...(location ? { location } : {}),
+                        ...(nextUrl ? { nextUrl } : {}),
+                    };
+                    hops.push(hop);
+                    if (stopWhen && (await stopWhen(hop))) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "stopped",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    if (!nextUrl) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "missing_location",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    if (hops.length > maxHops) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "max_hops",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    const nextMethod = nextRedirectMethod(response.status, method);
+                    if (nextMethod !== method) {
+                        body = undefined;
+                    }
+                    if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "loop",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    method = nextMethod;
+                    currentUrl = nextUrl;
+                }
+                if (!response) {
+                    response = await session.fetch(currentUrl, {
+                        ...fetchOptions,
+                        body,
+                        method,
+                        ...(params ? { params } : {}),
+                        redirect: "manual",
+                        throwOnHttpError: false,
+                    });
+                }
+                return {
+                    final: response,
+                    hops,
+                    reason: "max_hops",
+                    cookies: cookieJar.snapshot(),
+                };
+            },
+        },
         close() {
             closed = true;
             clients.clear();
         },
     };
+    return session;
     async function classifyProxyAuthDiagnostic(profileName, proxy) {
         try {
             const response = await getClient(profileName, proxy, false).fetch(PROXY_AUTH_DIAGNOSTIC_URL, {

package/dist/types.d.ts

@@ -805,6 +805,7 @@ export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PU
 export interface StealthFetchOptions extends RequestOptions {
     method?: HttpMethod;
     body?: string | Buffer;
+    redirect?: "follow" | "manual" | "error";
     /**
      * Offsets policy-managed proxy pool selection for caller-managed retries.
      * Use when a request receives an upstream challenge page rather than a
@@ -829,9 +830,19 @@ export interface CookieJar {
     toString(): string;
     find?(predicate: (cookie: string) => boolean): string | undefined;
 }
+export interface StealthSessionCookies extends CookieJar {
+    has(name: string): boolean;
+    setFromCookieStrings(cookieStrings: readonly string[]): void;
+    toHeader(): string;
+    snapshot(): Record<string, string>;
+    restore(cookies: Record<string, string>): void;
+    clear(): void;
+}
 export interface DeclarativeStealthResponse {
     status: number;
     ok: boolean;
+    url?: string;
+    redirected?: boolean;
     headers: Record<string, string>;
     rawHeaders: [string, string][];
     body: string;
@@ -851,8 +862,30 @@ export type RequestWithMethodOptions = RequestOptions & {
     method?: string;
     body?: unknown;
 };
+export interface StealthRedirectHop {
+    url: string;
+    status: number;
+    method: string;
+    location?: string;
+    nextUrl?: string;
+}
+export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "redirect"> {
+    url: string;
+    maxHops?: number;
+    stopWhen?: (hop: StealthRedirectHop) => boolean | Promise<boolean>;
+}
+export interface StealthRedirectRunResult {
+    final: StealthResponse;
+    hops: StealthRedirectHop[];
+    reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    cookies: Record<string, string>;
+}
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+    cookies: StealthSessionCookies;
+    redirects: {
+        run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
+    };
     close(): void;
 }
 export interface ApiFuseResponse<T> {

package/package.json

@@ -1,6 +1,6 @@
 {
+	"version": "2.1.0-beta.12",
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.10",
 	"private": false,
 	"type": "module",
 	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",

package/src/cli/create.ts

@@ -734,8 +734,8 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
 			return `{
     mode: "credentials",
     flow: {
-      start: async () => ({
-        kind: "input",
+      start: async (_ctx) => ({
+        kind: "form",
         turnId: crypto.randomUUID(),
         expectedInput: {
           schema: {
@@ -778,7 +778,7 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
 			return `{
     mode: "oauth2",
     flow: {
-      start: async () => ({
+      start: async (_ctx) => ({
         kind: "redirect",
         turnId: crypto.randomUUID(),
         data: {

package/src/index.ts

@@ -124,6 +124,7 @@ export type {
 	BrowserOptions,
 	ConnectionMode,
 	ContextDeclaration,
+	CookieJar,
 	ContextScratchpad,
 	CredentialContext,
 	CredentialDeclaration,
@@ -229,8 +230,12 @@ export type {
 	StealthFetchOptions,
 	StealthPlatform,
 	StealthProfile,
+	StealthRedirectHop,
+	StealthRedirectRunOptions,
+	StealthRedirectRunResult,
 	StealthResponse,
 	StealthSession,
+	StealthSessionCookies,
 	SttAudioInput,
 	SttContext,
 	SttPromptPolicy,

package/src/runtime/stealth.ts

@@ -18,6 +18,7 @@ import type {
 	HttpRetryOptions,
 	StealthClient,
 	StealthFetchOptions,
+	StealthRedirectHop,
 	StealthResponse,
 	StealthSession,
 } from "../types";
@@ -128,10 +129,16 @@ const FIREFOX_IMPIT_BY_MAJOR: Record<number, ImpitBrowser> = {
 
 type StealthTransportResponse = Pick<
 	ImpitResponse,
-	"arrayBuffer" | "headers" | "json" | "ok" | "status" | "text" | "url"
->;
+	"arrayBuffer" | "headers" | "json" | "ok" | "status" | "text"
+> & {
+	url?: string;
+	redirected?: boolean;
+};
 
 type StealthMethod = NonNullable<ImpitRequestInit["method"]>;
+type StealthRequestInit = ImpitRequestInit & {
+	redirect?: NonNullable<StealthFetchOptions["redirect"]>;
+};
 type NormalizedStealthRetryOptions = {
 	attempts: number;
 	methods: readonly string[];
@@ -177,12 +184,37 @@ class CookieJarImpl implements CookieJar {
 		return { ...this.cookies };
 	}
 
+	has(name: string): boolean {
+		return Object.hasOwn(this.cookies, name);
+	}
+
 	toString(): string {
 		return Object.entries(this.cookies)
 			.map(([name, value]) => `${name}=${value}`)
 			.join("; ");
 	}
 
+	toHeader(): string {
+		return this.toString();
+	}
+
+	snapshot(): Record<string, string> {
+		return this.getAll();
+	}
+
+	restore(cookies: Record<string, string>): void {
+		this.clear();
+		for (const [name, value] of Object.entries(cookies)) {
+			if (name) this.cookies[name] = value;
+		}
+	}
+
+	clear(): void {
+		for (const name of Object.keys(this.cookies)) {
+			delete this.cookies[name];
+		}
+	}
+
 	find(predicate: (cookie: string) => boolean): string | undefined {
 		for (const [name, value] of Object.entries(this.cookies)) {
 			const cookie = `${name}=${value}`;
@@ -335,6 +367,7 @@ function splitCombinedSetCookieHeader(headerValue: string): string[] {
 
 export async function normalizeResponse(
 	response: StealthTransportResponse,
+	requestUrl?: string,
 ): Promise<StealthResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
 	const cookies = new CookieJarImpl(
@@ -346,6 +379,12 @@ export async function normalizeResponse(
 	return {
 		status: response.status,
 		ok: response.status >= 200 && response.status < 300,
+		...(response.url ? { url: response.url } : {}),
+		...(response.redirected !== undefined
+			? { redirected: response.redirected }
+			: requestUrl && response.url
+				? { redirected: response.url !== requestUrl }
+				: {}),
 		headers,
 		rawHeaders: headerEntriesFromHeaders(response.headers),
 		body,
@@ -743,6 +782,26 @@ function normalizeMethod(method: HttpMethod | string): StealthMethod {
 	}
 }
 
+function isRedirectStatus(status: number): boolean {
+	return [301, 302, 303, 307, 308].includes(status);
+}
+
+function nextRedirectMethod(
+	status: number,
+	method: StealthMethod,
+): StealthMethod {
+	if (status === 303 && method !== "HEAD") return "GET";
+	if ((status === 301 || status === 302) && method === "POST") return "GET";
+	return method;
+}
+
+function locationHeader(headers: Record<string, string>): string | undefined {
+	for (const [name, value] of Object.entries(headers)) {
+		if (name.toLowerCase() === "location") return value;
+	}
+	return undefined;
+}
+
 function createSessionFetcher(
 	baseUrl: string,
 	defaultProfile: string,
@@ -811,7 +870,7 @@ function createSessionFetcher(
 		};
 	}
 
-	return {
+	const session: StealthSession = {
 		async fetch(url, options: StealthFetchOptions = {}) {
 			const method = normalizeMethod(options.method ?? "GET");
 			const hasExplicitRetryPolicy = options.retry !== undefined;
@@ -896,9 +955,10 @@ function createSessionFetcher(
 							const cookieHeader = cookieJar.toString();
 							if (cookieHeader) headers.Cookie = cookieHeader;
 						}
-						const requestInit: ImpitRequestInit = {
+						const requestInit: StealthRequestInit = {
 							headers: normalizeHeaders(headers),
 							method,
+							...(options.redirect ? { redirect: options.redirect } : {}),
 							...(options.timeout ? { timeout: options.timeout } : {}),
 						};
 						if (options.body !== undefined) {
@@ -909,7 +969,7 @@ function createSessionFetcher(
 							proxy,
 							ignoreTlsErrors,
 						).fetch(requestUrl, requestInit);
-						const normalized = await normalizeResponse(response);
+						const normalized = await normalizeResponse(response, requestUrl);
 						cookieJar.setFromCookieStrings(
 							setCookieHeadersFromResponse(response.headers),
 						);
@@ -1052,11 +1112,128 @@ function createSessionFetcher(
 
 			throw normalizeStealthTransportError(lastError);
 		},
+		cookies: cookieJar,
+		redirects: {
+			async run(options) {
+				const maxHops =
+					options.maxHops === undefined || !Number.isFinite(options.maxHops)
+						? 10
+						: Math.max(0, Math.floor(options.maxHops));
+				const hops: StealthRedirectHop[] = [];
+				let currentUrl = resolveUrl(baseUrl, options.url);
+				let method = normalizeMethod(options.method ?? "GET");
+				let body = options.body;
+				let response: StealthResponse | undefined;
+				const visitedRequests = new Set<string>();
+
+				const {
+					url: _url,
+					maxHops: _maxHops,
+					stopWhen,
+					params,
+					...fetchOptions
+				} = options;
+
+				for (let hopIndex = 0; hopIndex <= maxHops; hopIndex += 1) {
+					visitedRequests.add(`${method} ${currentUrl}`);
+					response = await session.fetch(currentUrl, {
+						...fetchOptions,
+						body,
+						method,
+						...(hopIndex === 0 && params ? { params } : {}),
+						redirect: "manual",
+						throwOnHttpError: false,
+					});
+
+					if (!isRedirectStatus(response.status)) {
+						return {
+							final: response,
+							hops,
+							reason: "completed",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					const location = locationHeader(response.headers);
+					const nextUrl = location
+						? new URL(location, response.url ?? currentUrl).toString()
+						: undefined;
+					const hop: StealthRedirectHop = {
+						url: response.url ?? currentUrl,
+						status: response.status,
+						method,
+						...(location ? { location } : {}),
+						...(nextUrl ? { nextUrl } : {}),
+					};
+					hops.push(hop);
+
+					if (stopWhen && (await stopWhen(hop))) {
+						return {
+							final: response,
+							hops,
+							reason: "stopped",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					if (!nextUrl) {
+						return {
+							final: response,
+							hops,
+							reason: "missing_location",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					if (hops.length > maxHops) {
+						return {
+							final: response,
+							hops,
+							reason: "max_hops",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					const nextMethod = nextRedirectMethod(response.status, method);
+					if (nextMethod !== method) {
+						body = undefined;
+					}
+					if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
+						return {
+							final: response,
+							hops,
+							reason: "loop",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+					method = nextMethod;
+					currentUrl = nextUrl;
+				}
+
+				if (!response) {
+					response = await session.fetch(currentUrl, {
+						...fetchOptions,
+						body,
+						method,
+						...(params ? { params } : {}),
+						redirect: "manual",
+						throwOnHttpError: false,
+					});
+				}
+				return {
+					final: response,
+					hops,
+					reason: "max_hops",
+					cookies: cookieJar.snapshot(),
+				};
+			},
+		},
 		close() {
 			closed = true;
 			clients.clear();
 		},
 	};
+	return session;
 
 	async function classifyProxyAuthDiagnostic(
 		profileName: string,

package/src/types.ts

@@ -979,6 +979,7 @@ export type HttpMethod =
 export interface StealthFetchOptions extends RequestOptions {
 	method?: HttpMethod;
 	body?: string | Buffer;
+	redirect?: "follow" | "manual" | "error";
 	/**
 	 * Offsets policy-managed proxy pool selection for caller-managed retries.
 	 * Use when a request receives an upstream challenge page rather than a
@@ -1005,9 +1006,20 @@ export interface CookieJar {
 	find?(predicate: (cookie: string) => boolean): string | undefined;
 }
 
+export interface StealthSessionCookies extends CookieJar {
+	has(name: string): boolean;
+	setFromCookieStrings(cookieStrings: readonly string[]): void;
+	toHeader(): string;
+	snapshot(): Record<string, string>;
+	restore(cookies: Record<string, string>): void;
+	clear(): void;
+}
+
 export interface DeclarativeStealthResponse {
 	status: number;
 	ok: boolean;
+	url?: string;
+	redirected?: boolean;
 	headers: Record<string, string>;
 	rawHeaders: [string, string][];
 	body: string;
@@ -1026,8 +1038,34 @@ export type RequestWithMethodOptions = RequestOptions & {
 	body?: unknown;
 };
 
+export interface StealthRedirectHop {
+	url: string;
+	status: number;
+	method: string;
+	location?: string;
+	nextUrl?: string;
+}
+
+export interface StealthRedirectRunOptions
+	extends Omit<StealthFetchOptions, "redirect"> {
+	url: string;
+	maxHops?: number;
+	stopWhen?: (hop: StealthRedirectHop) => boolean | Promise<boolean>;
+}
+
+export interface StealthRedirectRunResult {
+	final: StealthResponse;
+	hops: StealthRedirectHop[];
+	reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+	cookies: Record<string, string>;
+}
+
 export interface StealthSession {
 	fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+	cookies: StealthSessionCookies;
+	redirects: {
+		run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
+	};
 	close(): void;
 }