@expandai/sdk 0.20.1 → 0.20.2

package/build/esm/Tunnel/Tunnel.js

@@ -0,0 +1,302 @@
+import { createServer } from 'node:http';
+import { Cookies, FetchHttpClient, HttpBody, HttpClient, HttpClientRequest, Path, Socket, } from '@effect/platform';
+import { NodeFileSystem, NodeHttpServer, NodePath } from '@effect/platform-node';
+import { Config, Deferred, Duration, Effect, FiberMap, Iterable, Layer, Match, Option, Schema, Stream } from 'effect';
+import { WebSocket } from 'ws';
+import { ExpandLocalTargetError } from '../Error.js';
+import { endToEndHeaders } from './Headers.js';
+import { LocalTarget, resolveLocalTarget, resolveSafeDirectory } from './LocalTarget.js';
+import { decodeBodyFrame, encodeBodyFrame, encodeClientToRelay, MAX_BODY_BYTES, MAX_INFLIGHT_REQUESTS, PROTOCOL_VERSION, RelayToClient, splitBodyChunk, } from './Protocol.js';
+import { serveDirectory, serveFile } from './StaticServer.js';
+export class TunnelError extends Schema.TaggedError()('TunnelError', {
+    reason: Schema.Literal('Unauthorized', 'Configuration', 'RelayUnreachable'),
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+}) {
+}
+const HELLO_TIMEOUT = Duration.seconds(10);
+const MAX_QUEUED_RELAY_BYTES = 16 * 1024 * 1024;
+// A masked WebSocket frame has at most 14 bytes of framing in addition to its payload.
+const MAX_WEBSOCKET_FRAME_OVERHEAD = 14;
+const RELAY_URLS = new Map([
+    ['https://api.expand.ai', 'https://expandusercontent.com'],
+    ['https://api.staging.expand.ai', 'https://staging.expandusercontent.com'],
+]);
+const decodeControlFrame = Schema.decodeUnknownOption(Schema.parseJson(RelayToClient));
+const decodeBody = Option.liftThrowable(decodeBodyFrame);
+// Hop-by-hop or recomputed by `fetch`; forwarding them breaks the local request.
+const DROPPED_REQUEST_HEADERS = new Set(['host', 'content-length', 'accept-encoding']);
+// `fetch` decoded the body; cookies are forwarded separately to preserve repeated fields.
+const DROPPED_RESPONSE_HEADERS = new Set(['content-encoding', 'content-length', 'set-cookie']);
+function rewriteLocalLocation(value, localUrl, publicUrl) {
+    if (!URL.canParse(value))
+        return value;
+    const location = new URL(value);
+    return location.origin === new URL(localUrl).origin
+        ? `${publicUrl}${location.pathname}${location.search}${location.hash}`
+        : value;
+}
+// `fetch` reports "fetch failed" and hides the reason in `cause`; a refused connection is an
+// `AggregateError` (one attempt per address) with an empty message and the reason in `code`.
+function describeFetchError(error) {
+    const cause = error instanceof Error && error.cause instanceof Error ? error.cause : error;
+    if (!(cause instanceof Error))
+        return String(cause);
+    return cause.message || ('code' in cause && typeof cause.code === 'string' ? cause.code : cause.name);
+}
+/** Uses the relay for the selected API environment, unless `EXPAND_TUNNEL_URL` says otherwise. */
+const relayUrlFor = Effect.fn('Tunnel.relayUrlFor')(function* (baseUrl) {
+    const override = yield* Config.option(Config.string('EXPAND_TUNNEL_URL')).pipe(Effect.orDie);
+    const configured = Option.orElse(override, () => Option.fromNullable(RELAY_URLS.get(baseUrl.replace(/\/+$/u, ''))));
+    if (Option.isNone(configured)) {
+        return yield* new TunnelError({
+            reason: 'Configuration',
+            message: `No tunnel relay is known for ${baseUrl}; set EXPAND_TUNNEL_URL.`,
+        });
+    }
+    const relayUrl = configured.value;
+    if (!URL.canParse(relayUrl) || !['http:', 'https:'].includes(new URL(relayUrl).protocol)) {
+        return yield* new TunnelError({
+            reason: 'Configuration',
+            message: 'EXPAND_TUNNEL_URL must be an http:// or https:// relay address.',
+        });
+    }
+    return relayUrl.replace(/\/+$/u, '');
+});
+function tunnelOpenError(relayUrl, status) {
+    if (status === 401 || status === 403) {
+        return new TunnelError({ reason: 'Unauthorized', message: 'The tunnel relay rejected the Expand credentials.' });
+    }
+    const retryable = status === 0 || status === 408 || status === 429 || status >= 500;
+    return new TunnelError({
+        reason: retryable ? 'RelayUnreachable' : 'Configuration',
+        message: `Could not open a tunnel at ${relayUrl}${status === 0 ? '' : ` (HTTP ${status})`}.`,
+    });
+}
+// Effect owns receiving and socket lifetime; native send callbacks supply the backpressure its writer lacks.
+const makeRelaySocket = Effect.fn('Tunnel.makeRelaySocket')(function* (relayUrl, headers) {
+    const opened = yield* Deferred.make();
+    let rejectedStatus = 0;
+    const acquire = Effect.acquireRelease(Effect.sync(() => {
+        // Disable compression so bufferedAmount plus frame overhead bounds the actual native send queue.
+        const ws = new WebSocket(`${relayUrl.replace(/^http/u, 'ws')}/v1/connect`, { headers, perMessageDeflate: false });
+        ws.once('open', () => Deferred.unsafeDone(opened, Effect.succeed(ws)));
+        ws.once('unexpected-response', (_request, response) => {
+            rejectedStatus = response.statusCode ?? 0;
+            ws.terminate();
+        });
+        return ws;
+    }), 
+    // Graceful close queues behind body frames and can retain them for ws's 30-second close timeout.
+    (ws) => Effect.sync(() => ws.terminate()));
+    const socket = yield* Socket.fromWebSocket(
+    // `ws` implements the WHATWG event interface `fromWebSocket` uses.
+    acquire.pipe(Effect.map((ws) => ws)));
+    const writer = Effect.map(socket.writer, (closeWrite) => Effect.fnUntraced(function* (chunk) {
+        if (Socket.isCloseEvent(chunk))
+            return yield* closeWrite(chunk);
+        const ws = yield* Deferred.await(opened);
+        return yield* Effect.async((resume) => {
+            const fail = (cause) => Effect.fail(new Socket.SocketGenericError({ reason: 'Write', cause }));
+            if (ws.readyState !== WebSocket.OPEN) {
+                resume(fail(new Error('Tunnel connection closed.')));
+                return;
+            }
+            const bytes = typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.byteLength;
+            if (ws.bufferedAmount + bytes + MAX_WEBSOCKET_FRAME_OVERHEAD > MAX_QUEUED_RELAY_BYTES) {
+                // Cancelled requests leave native writes queued, so overflow must end the whole transport.
+                ws.terminate();
+                resume(fail(new Error('Tunnel relay stopped reading.')));
+                return;
+            }
+            let complete = resume;
+            try {
+                ws.send(chunk, (error) => {
+                    complete?.(error ? fail(error) : Effect.void);
+                    complete = undefined;
+                });
+            }
+            catch (error) {
+                complete = undefined;
+                resume(fail(error));
+            }
+            // ws retains the send callback until flushing or close; don't retain an interrupted request fiber.
+            return Effect.sync(() => {
+                complete = undefined;
+            });
+        });
+    }));
+    return { socket: Socket.Socket.of({ ...socket, writer }), rejectedStatus: () => rejectedStatus };
+});
+// Where the relay's requests go, and the path on the public URL that shows the target.
+const localOrigin = Effect.fn('Tunnel.localOrigin')(function* (target) {
+    if (LocalTarget.$is('Port')(target))
+        return { host: target.host, port: target.port, path: target.path };
+    const path = yield* Path.Path;
+    const isFile = LocalTarget.$is('File')(target);
+    const directory = isFile ? target.path : yield* resolveSafeDirectory(target.path);
+    // Build into the tunnel's scope so the listener stays open after this function returns.
+    const port = yield* Layer.build(NodeHttpServer.layer(() => createServer(), { host: '127.0.0.1', port: 0 })).pipe(Effect.flatMap((context) => (isFile ? serveFile(target.path) : serveDirectory(directory)).pipe(Effect.provide(context))), Effect.mapError((cause) => new ExpandLocalTargetError({
+        reason: 'Unavailable',
+        input: target.path,
+        cause,
+        message: `Could not start a local file server for "${target.path}". ${cause.message}`,
+    })));
+    return { host: '127.0.0.1', port, path: isFile ? `/${encodeURIComponent(path.basename(target.path))}` : '/' };
+}, Effect.provide(Layer.merge(NodePath.layer, NodeFileSystem.layer)));
+const makeResponder = Effect.fn('Tunnel.makeResponder')(function* (socket, localUrl, hello) {
+    // Loopback requests must not inherit API proxies or trace user paths and forwarded credentials.
+    const http = HttpClient.withScope(yield* HttpClient.HttpClient).pipe(HttpClient.withTracerDisabledWhen(() => true), HttpClient.withTracerPropagation(false));
+    const write = yield* socket.writer;
+    const send = (frame) => write(encodeClientToRelay(frame));
+    return Effect.fn('Tunnel.respond')(function* (start, body) {
+        const { url: publicUrl } = yield* Deferred.await(hello);
+        const response = yield* http
+            .execute(
+        // Effect's method union is narrower than fetch; preserve custom methods from the relay.
+        HttpClientRequest.make(start.method)(`${localUrl}${start.path}`, {
+            headers: endToEndHeaders(start.headers).filter(([name]) => !DROPPED_REQUEST_HEADERS.has(name.toLowerCase())),
+            body: Option.isSome(body) ? HttpBody.raw(body.value) : undefined,
+        }))
+            .pipe(Effect.mapError((error) => describeFetchError(error.cause ?? error)));
+        yield* send({
+            _tag: 'ResponseStart',
+            v: PROTOCOL_VERSION,
+            id: start.id,
+            status: response.status,
+            headers: endToEndHeaders(Object.entries(response.headers))
+                .filter(([name]) => !DROPPED_RESPONSE_HEADERS.has(name))
+                // A dev server redirecting to its own absolute URL must send the fetcher back through the tunnel.
+                .map(([name, value]) => [
+                name,
+                name === 'location' ? rewriteLocalLocation(value, localUrl, publicUrl) : value,
+            ])
+                // Effect's flat Headers record loses repeated Set-Cookie fields.
+                .concat(Cookies.toSetCookieHeaders(response.cookies).map((cookie) => ['set-cookie', cookie])),
+        });
+        let responseBytes = 0;
+        yield* response.stream.pipe(Stream.catchTag('ResponseError', (error) => error.reason === 'EmptyBody' ? Stream.empty : Stream.fail(describeFetchError(error.cause ?? error))), Stream.runForEach(Effect.fnUntraced(function* (chunk) {
+            responseBytes += chunk.byteLength;
+            // Enforce the response bound independently of transport backpressure and relay cancellation.
+            if (responseBytes > MAX_BODY_BYTES)
+                return yield* Effect.fail('response body too large');
+            yield* Effect.forEach(splitBodyChunk(chunk), (slice) => write(encodeBodyFrame(start.id, slice)));
+        })));
+        yield* send({ _tag: 'ResponseEnd', v: PROTOCOL_VERSION, id: start.id });
+    }, (effect, start) => effect.pipe(Effect.scoped, Effect.catchAll((error) => send({
+        _tag: 'ResponseError',
+        v: PROTOCOL_VERSION,
+        id: start.id,
+        message: `${localUrl} did not answer: ${String(error)}`,
+    })), Effect.ignore));
+});
+const runRequests = Effect.fn('Tunnel.runRequests')(function* (socket, localUrl, hello) {
+    const write = yield* socket.writer;
+    const send = (frame) => write(encodeClientToRelay(frame));
+    const requestFibers = yield* FiberMap.make();
+    const run = yield* FiberMap.runtime(requestFibers)();
+    const respond = yield* makeResponder(socket, localUrl, hello);
+    function runRequest(start, body) {
+        run(start.id, respond(start, body));
+    }
+    // Bookkeeping runs synchronously in frame order so body chunks always land after their
+    // `RequestStart` and before their `RequestEnd`; only the returned effects run concurrently.
+    const bodies = new Map();
+    function handleBodyFrame(data) {
+        const body = decodeBody(data);
+        if (Option.isNone(body))
+            return;
+        const pending = bodies.get(body.value.id);
+        if (pending === undefined)
+            return;
+        pending.chunks.push(body.value.chunk);
+        pending.bytes += body.value.chunk.byteLength;
+        // The public URL is open to anyone who learns it; do not let a request body exhaust memory.
+        if (pending.bytes <= MAX_BODY_BYTES)
+            return;
+        bodies.delete(body.value.id);
+        return send({
+            _tag: 'ResponseError',
+            v: PROTOCOL_VERSION,
+            id: body.value.id,
+            message: 'request body too large',
+        });
+    }
+    function handleControlFrame(data) {
+        return Option.match(decodeControlFrame(data), {
+            onNone: () => Effect.logDebug('Ignoring unrecognised tunnel frame'),
+            onSome: Match.valueTags({
+                Hello: (frame) => Deferred.succeed(hello, frame),
+                RequestStart: (start) => {
+                    if (bodies.has(start.id) || FiberMap.unsafeHas(requestFibers, start.id))
+                        return;
+                    if (bodies.size + Iterable.size(requestFibers) >= MAX_INFLIGHT_REQUESTS) {
+                        return send({
+                            _tag: 'ResponseError',
+                            v: PROTOCOL_VERSION,
+                            id: start.id,
+                            message: 'too many local requests',
+                        });
+                    }
+                    if (!start.hasBody) {
+                        runRequest(start, Option.none());
+                        return;
+                    }
+                    bodies.set(start.id, { start, chunks: [], bytes: 0 });
+                    return Effect.void;
+                },
+                RequestCancel: ({ id }) => {
+                    bodies.delete(id);
+                    return FiberMap.remove(requestFibers, id);
+                },
+                RequestEnd: ({ id }) => {
+                    const pending = Option.fromNullable(bodies.get(id));
+                    bodies.delete(id);
+                    return Option.match(pending, {
+                        onNone: () => Effect.void,
+                        onSome: ({ start, chunks }) => {
+                            runRequest(start, Option.some(Buffer.concat(chunks)));
+                            return Effect.void;
+                        },
+                    });
+                },
+            }),
+        });
+    }
+    return yield* socket
+        .runRaw((data) => (typeof data === 'string' ? handleControlFrame(data) : handleBodyFrame(data)))
+        .pipe(Effect.ensuring(Effect.sync(() => bodies.clear())));
+});
+/**
+ * Opens a tunnel from the relay to `target` for the lifetime of the scope and returns its public URL.
+ * Closing the scope closes the socket and, for file targets, the static server.
+ */
+export const openTunnel = Effect.fn('Tunnel.openTunnel')(function* (target, relayUrl, headers) {
+    const origin = yield* localOrigin(target);
+    const { socket, rejectedStatus } = yield* makeRelaySocket(relayUrl, headers);
+    const hello = yield* Deferred.make();
+    // If the socket ends before Hello the open fails; after Hello, the API simply sees the origin go away.
+    yield* runRequests(socket, `http://${origin.host}:${origin.port}`, hello).pipe(Effect.scoped, Effect.exit, Effect.flatMap(() => Deferred.fail(hello, tunnelOpenError(relayUrl, rejectedStatus()))), Effect.forkScoped);
+    const { url } = yield* Deferred.await(hello).pipe(Effect.timeoutFail({
+        duration: HELLO_TIMEOUT,
+        onTimeout: () => new TunnelError({
+            reason: 'RelayUnreachable',
+            message: `No answer from the tunnel relay at ${relayUrl}.`,
+        }),
+    }));
+    return `${url}${origin.path}`;
+}, Effect.provide(FetchHttpClient.layer), Effect.provideService(FetchHttpClient.RequestInit, { redirect: 'manual' }));
+/**
+ * Runs `use` with a public URL for `input`, which must be a local target (see `resolveLocalTarget`),
+ * and closes the tunnel afterwards.
+ */
+export const withLocalTunnel = Effect.fn('Tunnel.withLocalTunnel')(function* (input, credentials, use) {
+    const target = yield* resolveLocalTarget(input).pipe(Effect.provide(Layer.merge(NodeFileSystem.layer, NodePath.layer)));
+    const { baseUrl, headers } = yield* credentials;
+    const relayUrl = yield* relayUrlFor(baseUrl);
+    const url = yield* openTunnel(target, relayUrl, headers);
+    return yield* use(url);
+}, (effect, input) => effect.pipe(Effect.mapError((error) => error instanceof ExpandLocalTargetError && error.input !== input
+    ? new ExpandLocalTargetError({ reason: error.reason, input, message: error.message, cause: error.cause })
+    : error), Effect.scoped));
+//# sourceMappingURL=Tunnel.js.map

package/build/esm/Tunnel/Tunnel.js.map

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

package/build/esm/index.js

@@ -1,7 +1,7 @@
 export { APPENDIX_MARKER_PREFIX, AppendixMarkerLevel, isAppendixMarkerLine, parseAppendixMarkerLine, parseAppendixMarkers, stripAppendixMarkers, withoutFencedCode, } from './AppendixMarkers.js';
 export { Expand, ExpandClient } from './Client.js';
 export * from './Crawls.js';
-export { ExpandApiError, ExpandClientApiError, ExpandClientConnectionError, ExpandClientError, ExpandClientTimeoutError, ExpandConnectionError, ExpandSdkError, ExpandTimeoutError, } from './Error.js';
+export { ExpandApiError, ExpandClientApiError, ExpandClientConnectionError, ExpandClientError, ExpandClientLocalTargetError, ExpandClientTimeoutError, ExpandConnectionError, ExpandLocalTargetError, ExpandSdkError, ExpandTimeoutError, } from './Error.js';
 export { isFetchOriginError } from './FetchJson.js';
 export { citationUrl, DEFAULT_PLAYGROUND_HOST, parseSnapshotHandle, playgroundAppendixUrl, playgroundBase, playgroundContentUrl, resolvePlaygroundHost, } from './Playground.js';
 export { ExpandService, ExpandServiceOptions, RequestOptions } from './Service.js';

package/build/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GACjB,MAAM,sBAAsB,CAAA;AAqB7B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAClD,cAAc,aAAa,CAAA;AAE3B,OAAO,EACN,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAC3B,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,GAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,EACN,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,GACrB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GACjB,MAAM,sBAAsB,CAAA;AAqB7B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAClD,cAAc,aAAa,CAAA;AAE3B,OAAO,EACN,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAC3B,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,kBAAkB,GAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,EACN,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,GACrB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA"}

package/package.json

@@ -4,7 +4,7 @@
 	"engines": {
 		"node": ">=20.3.0"
 	},
-	"version": "0.20.1",
+	"version": "0.20.2",
 	"private": false,
 	"description": "TypeScript SDK for ExpandAI",
 	"author": "ExpandAI",
@@ -67,14 +67,17 @@
 		"@durable-streams/client": "^0.2.6",
 		"@effect/platform": "0.96.1",
 		"@effect/platform-node": "0.106.0",
-		"effect": "3.21.2"
+		"effect": "3.21.2",
+		"mime": "^4.1.0",
+		"ws": "^8.21.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.14",
 		"@effect/vitest": "0.29.0",
 		"@tim-smart/openapi-gen": "0.3.12",
 		"@types/node": "^25.5.2",
+		"@types/ws": "^8.18.1",
 		"vitest": "4.1.4"
 	},
-	"expandSourceSha": "8d673e5359545b0494ca8396a90aa0006205b279"
+	"expandSourceSha": "71e04d6b697d70cdca5566e162dc4b9fdc98dba3"
 }

package/src/Error.ts

@@ -1,5 +1,34 @@
 import { Schema } from 'effect'
 
+const LOCAL_TARGET_ERROR_REASON = Schema.Literal(
+	'InvalidInput',
+	'NotLocal',
+	'UnsupportedProtocol',
+	'NotFound',
+	'PermissionDenied',
+	'UnsupportedFileType',
+	'Unavailable',
+	'UnsafeDirectory',
+)
+
+export type LocalTargetErrorReason = typeof LOCAL_TARGET_ERROR_REASON.Type
+
+/** A local input cannot be fetched. Inspect `reason` rather than parsing the message. */
+export class ExpandLocalTargetError extends Schema.TaggedError<ExpandLocalTargetError>()('ExpandLocalTargetError', {
+	reason: LOCAL_TARGET_ERROR_REASON,
+	input: Schema.String,
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect),
+}) {
+	toPublicError() {
+		return new ExpandClientLocalTargetError(this.message, {
+			reason: this.reason,
+			input: this.input,
+			cause: this.cause,
+		})
+	}
+}
+
 /**
  * Effect-side base error. Schema.TaggedError; Effect consumers receive these in the error channel.
  */
@@ -54,7 +83,12 @@ export class ExpandTimeoutError extends Schema.TaggedError<ExpandTimeoutError>()
 /**
  * Union of every error the Effect-side `ExpandService` can fail with.
  */
-export type ExpandError = ExpandSdkError | ExpandApiError | ExpandConnectionError | ExpandTimeoutError
+export type ExpandError =
+	| ExpandSdkError
+	| ExpandApiError
+	| ExpandConnectionError
+	| ExpandTimeoutError
+	| ExpandLocalTargetError
 
 /**
  * Promise-side base class. Catch this to handle any failure thrown by `ExpandClient`.
@@ -66,6 +100,24 @@ export class ExpandClientError extends Error {
 	}
 }
 
+interface LocalTargetErrorOptions extends ErrorOptions {
+	readonly reason: LocalTargetErrorReason
+	readonly input: string
+}
+
+/** A local input cannot be fetched. Includes the input, stable reason, and original filesystem cause. */
+export class ExpandClientLocalTargetError extends ExpandClientError {
+	readonly reason: LocalTargetErrorReason
+	readonly input: string
+
+	constructor(message: string, options: LocalTargetErrorOptions) {
+		super(message, options)
+		this.name = 'ExpandClientLocalTargetError'
+		this.reason = options.reason
+		this.input = options.input
+	}
+}
+
 /**
  * Promise-side error for non-2xx API responses. Inspect `status` and `body` for details.
  */

package/src/Internal.ts

@@ -5,9 +5,11 @@ import {
 	ExpandClientApiError,
 	ExpandClientConnectionError,
 	ExpandClientError,
+	ExpandClientLocalTargetError,
 	ExpandClientTimeoutError,
 	ExpandConnectionError,
 	type ExpandError,
+	ExpandLocalTargetError,
 	ExpandSdkError,
 	ExpandTimeoutError,
 } from './Error.js'
@@ -115,9 +117,17 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 		error instanceof ExpandApiError ||
 		error instanceof ExpandConnectionError ||
 		error instanceof ExpandTimeoutError ||
+		error instanceof ExpandLocalTargetError ||
 		error instanceof ExpandSdkError
 	)
 		return error
+	if (error instanceof ExpandClientLocalTargetError)
+		return new ExpandLocalTargetError({
+			reason: error.reason,
+			input: error.input,
+			message: error.message,
+			cause: error.cause,
+		})
 	if (error instanceof ExpandClientApiError)
 		return new ExpandApiError({ message: error.message, status: error.status, body: error.body, cause: error })
 	if (error instanceof ExpandClientTimeoutError)

package/src/RetryAfter.ts

@@ -25,6 +25,9 @@ export const MAX_RETRY_AFTER = Duration.minutes(2)
  */
 const currentRetryAfter = FiberRef.unsafeMake(Option.none<Duration.Duration>())
 
+/** Start an attempt with no previous response's delay, including when setup fails before HTTP. */
+export const clearRetryAfter = FiberRef.set(currentRetryAfter, Option.none())
+
 /**
  * Rounded to whole milliseconds rather than kept as fractional seconds.
  *
@@ -59,7 +62,7 @@ export const recordRetryAfter = <E, R>(client: HttpClient.HttpClient.With<E, R>)
 		// transport level never produces a response to overwrite the previous one, so without this the
 		// next attempt would sleep on a wait some earlier response asked for — a connection reset would
 		// inherit a saturated gate's 20s.
-		HttpClient.tapRequest(client, () => FiberRef.set(currentRetryAfter, Option.none())),
+		HttpClient.tapRequest(client, () => clearRetryAfter),
 		(response) =>
 			FiberRef.set(
 				currentRetryAfter,

package/src/Service.ts

@@ -10,7 +10,7 @@ import type {
 	CrawlSyncPolicy,
 } from './Crawls.js'
 import * as EnvProxyHttpClient from './EnvProxyHttpClient.js'
-import { ExpandApiError, type ExpandError, ExpandSdkError } from './Error.js'
+import { ExpandApiError, ExpandConnectionError, type ExpandError, ExpandSdkError } from './Error.js'
 import {
 	type FetchObjectModeJsonResponse,
 	type FetchSnapshotHighlightsResultWithJson,
@@ -20,7 +20,8 @@ import {
 import * as Generated from './Generated.js'
 import { decodeError, unexpectedStatus } from './HttpClientHelpers.js'
 import { isRetryable, toExpandError } from './Internal.js'
-import { nextRetryDelay, recordRetryAfter } from './RetryAfter.js'
+import { clearRetryAfter, nextRetryDelay, recordRetryAfter } from './RetryAfter.js'
+import { TunnelError, withLocalTunnel } from './Tunnel/Tunnel.js'
 
 const DEFAULT_BASE_URL = 'https://api.expand.ai'
 const DEFAULT_TIMEOUT_MS = 60_000
@@ -79,15 +80,23 @@ export class RequestOptions extends Schema.Class<RequestOptions>('RequestOptions
 	{ description: 'Per-request overrides for an `ExpandService` operation.' },
 ) {}
 
+interface LocalOptions {
+	/**
+	 * The URL is a localhost server or a file path on this machine: fetch it through a short-lived tunnel
+	 * (Node.js only). Never set this for user-supplied URLs; it exposes this machine's loopback and files.
+	 */
+	readonly local?: boolean
+}
+
 export type FetchParams = typeof Generated.FetchFetchRequest.Encoded
 export type FetchResponse = string
-export type FetchRequestOptions = RequestOptions & typeof Generated.FetchFetchParams.Encoded
+export type FetchRequestOptions = RequestOptions & typeof Generated.FetchFetchParams.Encoded & LocalOptions
 export type FetchJsonParams = typeof Generated.FetchFetchJsonRequest.Encoded
 // `*WithJson` rather than the generated result: the codegen drops the statejson snippet `json`, so
 // the service decodes the body with the recovering schemas (see `FetchJson.ts`). A union because an
 // origin that never answered has no content to describe — narrow on `_tag`.
 export type FetchJsonResponse = FetchObjectModeJsonResponse
-export type FetchJsonRequestOptions = RequestOptions & typeof Generated.FetchFetchJsonParams.Encoded
+export type FetchJsonRequestOptions = RequestOptions & typeof Generated.FetchFetchJsonParams.Encoded & LocalOptions
 export interface SnapshotHighlightsParams extends Schema.Schema.Encoded<typeof Generated.SnapshotHighlightsInput> {
 	readonly snapshotId: string
 }
@@ -257,6 +266,7 @@ export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sd
 				),
 			)
 			return yield* Effect.sync(() => MutableRef.set(pendingRefusal, Option.none())).pipe(
+				Effect.zipRight(clearRetryAfter),
 				Effect.zipRight(operation),
 				Effect.retry(retrySchedule),
 				Effect.timeoutFail({
@@ -268,23 +278,53 @@ export class ExpandService extends Effect.Service<ExpandService>()('@expandai/sd
 			)
 		})
 
+		// Tunnel setup and local access belong to the attempt covered by the existing retry/timeout policy.
+		function viaLocalTunnel<A, E, R>(
+			url: string,
+			local: boolean | undefined,
+			run: (url: string) => Effect.Effect<A, E, R>,
+		) {
+			return local === true
+				? withLocalTunnel(
+						url,
+						Effect.succeed({ baseUrl: config.baseUrl, headers: { 'x-expand-api-key': config.apiKey } }),
+						run,
+					).pipe(
+						Effect.mapError((error) => {
+							if (!(error instanceof TunnelError)) return error
+							return error.reason === 'RelayUnreachable'
+								? new ExpandConnectionError({ message: error.message, cause: error })
+								: new ExpandSdkError({ message: error.message, cause: error })
+						}),
+					)
+				: run(url)
+		}
+
 		const fetch = Effect.fn('ExpandService.fetch')(function* (
 			params: FetchParams,
 			requestOptions: FetchRequestOptions = {},
 		) {
-			const { include, ...retryOptions } = requestOptions
-			return yield* withRetries(fetchMarkdown(params, { include }), retryOptions)
+			const { include, local, ...retryOptions } = requestOptions
+			return yield* withRetries(
+				viaLocalTunnel(params.url, local, (url) => fetchMarkdown({ ...params, url }, { include })),
+				retryOptions,
+			)
 		})
 
 		const fetchJson = Effect.fn('ExpandService.fetchJson')(function* (
 			params: FetchJsonParams,
 			requestOptions: FetchJsonRequestOptions = {},
 		) {
-			const { include, ...retryOptions } = requestOptions
+			const { include, local, ...retryOptions } = requestOptions
 			// `fetchObjectModeJson` mirrors the generated call but preserves the statejson snippet `json`.
 			// Coalesce null -> undefined before `setUrlParams`, which throws on null.
 			return yield* withRetries(
-				fetchObjectModeJson(authedClient, { params: { include: include ?? undefined }, payload: params }),
+				viaLocalTunnel(params.url, local, (url) =>
+					fetchObjectModeJson(authedClient, {
+						params: { include: include ?? undefined },
+						payload: { ...params, url },
+					}),
+				),
 				retryOptions,
 			)
 		})

package/src/Tunnel/Headers.ts

@@ -0,0 +1,22 @@
+const HOP_BY_HOP_HEADERS = new Set([
+	'connection',
+	'keep-alive',
+	'proxy-authenticate',
+	'proxy-authorization',
+	'te',
+	'trailer',
+	'transfer-encoding',
+	'upgrade',
+])
+
+export function endToEndHeaders(headers: Iterable<readonly [string, string]>): Array<readonly [string, string]> {
+	const entries = [...headers]
+	const connectionTokens = new Set(
+		entries
+			.filter(([name]) => name.toLowerCase() === 'connection')
+			.flatMap(([, value]) => value.split(',').map((token) => token.trim().toLowerCase())),
+	)
+	return entries.filter(
+		([name]) => !HOP_BY_HOP_HEADERS.has(name.toLowerCase()) && !connectionTokens.has(name.toLowerCase()),
+	)
+}