@oomol-lab/open-connector 1.7.0 → 1.9.0

package/src/core/guarded-fetch.js

@@ -77,6 +77,8 @@ export const crossOriginSafeHeaders = new Set([
 const bodyHeaders = ["content-encoding", "content-language", "content-length", "content-location", "content-type"];
 /** Base transport behind each guarded fetch (undefined = global fetch) so re-wrapping never stacks guards. */
 const guardedFetchBases = new WeakMap();
+/** Retain admission when a caller replaces the egress policy without stacking guards. */
+const guardedFetchDispatchers = new WeakMap();
 let defaultLookupOverridden = false;
 let defaultLookupOverride = null;
 let nodeDnsLookupPromise;
@@ -134,17 +136,33 @@ export function unwrapGuardedFetch(fetcher) {
  */
 export function createGuardedFetch(options = {}) {
     const baseFetch = unwrapGuardedFetch(options.fetch);
+    const dispatchAttempt = options.dispatchAttempt ?? (options.fetch && guardedFetchDispatchers.get(options.fetch));
     const createError = options.createError ?? ((message) => new TypeError(message));
     const maxRedirects = options.maxRedirects ?? defaultMaxRedirects;
     const guardedFetch = (async (input, init) => {
         const transport = baseFetch ?? globalThis.fetch;
+        const requestId = dispatchAttempt ? crypto.randomUUID() : "";
+        let redirectHop = 0;
         const fetchTransport = async (transportInput, transportInit) => {
-            try {
-                return await transport(transportInput, transportInit);
-            }
-            catch (error) {
-                throw options.mapTransportError?.(error) ?? error;
-            }
+            const send = async () => {
+                try {
+                    return await transport(transportInput, transportInit);
+                }
+                catch (error) {
+                    throw options.mapTransportError?.(error) ?? error;
+                }
+            };
+            const transportRequest = transportInput instanceof Request ? transportInput : undefined;
+            return dispatchAttempt
+                ? dispatchAttempt(Object.freeze({
+                    requestId,
+                    redirectHop,
+                    origin: url.origin,
+                    method: (transportInit?.method ?? transportRequest?.method ?? "GET").toUpperCase(),
+                }), transportInit?.signal ?? transportRequest?.signal ?? undefined, send, async () => {
+                    await guardHop(url.toString(), "request URL");
+                })
+                : send();
         };
         const allowPrivateNetwork = typeof options.allowPrivateNetwork === "function"
             ? options.allowPrivateNetwork()
@@ -154,17 +172,29 @@ export function createGuardedFetch(options = {}) {
             : options.lookup === undefined
                 ? await resolveDefaultLookup()
                 : options.lookup;
-        const guardHop = (value, fieldName) => assertGuardedEgressUrl(value, { fieldName, createError, allowPrivateNetwork, lookup });
+        const guardHop = (value, fieldName) => assertGuardedEgressUrl(value, {
+            fieldName,
+            createError,
+            allowPrivateNetwork,
+            lookup,
+            allowTrustedHosts: options.allowTrustedHosts,
+            createResolutionError: options.createResolutionError,
+        });
         const request = input instanceof Request ? input : undefined;
         let url = await guardHop(request?.url ?? (input instanceof URL ? input.href : String(input)), "request URL");
         const redirectMode = init?.redirect ?? request?.redirect ?? "follow";
         if (redirectMode !== "follow") {
-            return fetchTransport(input, init);
+            // Keep the screened URL and method stable while admission is queued. A
+            // caller may otherwise mutate a URL or RequestInit before transport runs.
+            return dispatchAttempt
+                ? fetchTransport(request ?? (input instanceof URL ? new URL(url) : url.toString()), init ? { ...init } : init)
+                : fetchTransport(input, init);
         }
         let method = (init?.method ?? request?.method ?? "GET").toUpperCase();
         const headers = new Headers(init?.headers ?? request?.headers);
         let body = init?.body !== undefined ? init.body : request?.body;
         for (let redirects = 0;; redirects++) {
+            redirectHop = redirects;
             const response = redirects === 0
                 ? request
                     ? await fetchTransport(new Request(request, { ...init, redirect: "manual" }))
@@ -222,6 +252,7 @@ export function createGuardedFetch(options = {}) {
         }
     });
     guardedFetchBases.set(guardedFetch, baseFetch);
+    guardedFetchDispatchers.set(guardedFetch, dispatchAttempt);
     return guardedFetch;
 }
 /**
@@ -255,6 +286,7 @@ export async function resolveGuardedEgressTarget(value, options) {
         createError: options.createError,
         createResolutionError: options.createResolutionError ?? options.createError,
         lookup,
+        allowTrustedHosts: options.allowTrustedHosts !== false,
     });
     return { url, addresses };
 }
@@ -289,7 +321,7 @@ async function assertResolvedAddressesAllowed(hostname, fieldName, policy) {
     // Deployment-level trusted-host setting, resolved per request so a bootstrap that
     // configures it after module load is honored. It may open private and
     // VPN-mapped results, while unsafe special-use targets remain blocked.
-    const trustedHost = isEgressTrustedHost(hostname);
+    const trustedHost = policy.allowTrustedHosts && isEgressTrustedHost(hostname);
     for (const entry of results) {
         if (entry && typeof entry.address === "string") {
             const addressClass = classifyIpAddress(entry.address);
@@ -311,8 +343,9 @@ async function assertResolvedAddressesAllowed(hostname, fieldName, policy) {
             // would turn the guard into a DNS/internal-range probe oracle, a property
             // src/mail/imap-smtp/host-pinning.test.ts asserts.
             throw policy.createError(`${fieldName} must not resolve to private or reserved IP addresses ` +
-                `(if this host is reached through a corporate VPN or split DNS, add it to ` +
-                `OOMOL_CONNECT_EGRESS_TRUSTED_HOSTS)`);
+                (policy.allowTrustedHosts
+                    ? `(if this host is reached through a corporate VPN or split DNS, add it to OOMOL_CONNECT_EGRESS_TRUSTED_HOSTS)`
+                    : `(check proxy Fake-IP and DNS settings; this request requires a public address)`));
         }
     }
     return results;

package/src/core/json-schema.js

@@ -207,7 +207,13 @@ export const jsonSchema = {
         return withOptions({ oneOf: schemas }, options);
     },
     nullable(schema) {
-        return { anyOf: [schema, { type: "null" }] };
+        const nullableSchema = { anyOf: [schema, { type: "null" }] };
+        // Tool schemas and the action guide read a property's description from the
+        // property schema itself, so surface the inner description on the wrapper.
+        if (typeof schema.description === "string") {
+            nullableSchema.description = schema.description;
+        }
+        return nullableSchema;
     },
     ref(ref, options = {}) {
         return withOptions({ $ref: ref }, options);

package/src/core/provider-http-dispatch.d.ts

@@ -0,0 +1,82 @@
+/** Runtime-owned identity. Never populate these fields from action input or HTTP headers. */
+export interface ProviderDispatchContext {
+    readonly operation: "runtime" | "action" | "proxy" | "trigger" | "credential_validation" | "oauth";
+    readonly service?: string;
+    readonly actionId?: string;
+    readonly executionId?: string;
+    readonly connectionId?: string;
+    /** Alias from the resolved stored connection, not the caller's requested alias. */
+    readonly connectionName?: string;
+}
+/** Opaque authority supplied by the embedding host, independently of provider credentials. */
+export interface ProviderDispatchAuthority {
+    readonly workspaceId?: string;
+    readonly connectionLineageId?: string;
+    readonly workClass?: string;
+}
+/** A screened HTTP hop. URLs, paths, queries, headers and bodies are deliberately absent. */
+export interface ProviderHttpAttempt {
+    readonly attemptId: string;
+    readonly requestId: string;
+    readonly redirectHop: number;
+    readonly method: string;
+    readonly origin: string;
+    readonly context: ProviderDispatchContext;
+    readonly authority: ProviderDispatchAuthority;
+}
+/** Transport failures may have reached the provider; they are never evidence for a credit refund. */
+export type ProviderHttpAttemptResult = {
+    readonly kind: "response";
+    readonly status: number;
+    readonly retryAfter?: string;
+} | {
+    readonly kind: "transport_error";
+} | {
+    readonly kind: "not_dispatched";
+    readonly reason: "cancelled" | "dispatch_failed";
+};
+export interface ProviderHttpPermit {
+    readonly allow: true;
+    /** Awaited immediately before transport. Persist dispatch commitment here; failures deny egress. */
+    readonly onDispatch?: () => void | Promise<void>;
+    /** Started exactly once after a permit is returned; never awaited before returning the transport outcome. */
+    readonly onResult?: (result: ProviderHttpAttemptResult) => void | Promise<void>;
+}
+export interface ProviderHttpDenial {
+    readonly allow: false;
+    /** Retry-After delay in whole seconds. */
+    readonly retryAfterSeconds?: number;
+}
+export interface ProviderHttpDispatchOptions {
+    /** Await admission to delay a request, or return a denial. Honour the signal while queued. */
+    readonly beforeAttempt: (attempt: ProviderHttpAttempt, signal: AbortSignal | undefined) => ProviderHttpPermit | ProviderHttpDenial | Promise<ProviderHttpPermit | ProviderHttpDenial>;
+    /** Resolve workspace/lineage authority from runtime identity, never request credentials. */
+    readonly bindAuthority?: (context: ProviderDispatchContext) => ProviderDispatchAuthority | Promise<ProviderDispatchAuthority>;
+    /** Feedback failure leaves the attempt spent/unknown. This observer cannot change the transport result. */
+    readonly onFeedbackError?: (attempt: ProviderHttpAttempt) => void | Promise<void>;
+}
+export interface GuardedHttpAttempt {
+    readonly requestId: string;
+    readonly redirectHop: number;
+    readonly method: string;
+    readonly origin: string;
+}
+export type GuardedHttpDispatcher = (attempt: GuardedHttpAttempt, signal: AbortSignal | undefined, transport: () => Promise<Response>, revalidate: () => Promise<void>) => Promise<Response>;
+/** Safe retryable denial, including hook/readiness failures; it contains no callback error details. */
+export declare class ProviderHttpDispatchError extends Error {
+    readonly retryAfterSeconds?: number;
+    constructor(retryAfterSeconds?: number);
+}
+/**
+ * Bind a hook to asynchronous provider work. Nested scopes inherit the configured hook;
+ * concurrent requests stay isolated. Standalone providerFetch users can opt in here too.
+ */
+export declare function withProviderHttpDispatch<T>(context: ProviderDispatchContext, run: () => T, options?: ProviderHttpDispatchOptions): T;
+/**
+ * A provider invocation boundary: retain the original denial even if provider code catches,
+ * replaces, or converts it to a result. Each invocation owns its marker, so a sibling's
+ * denial cannot override another invocation's successful retry or fallback.
+ */
+export declare function runWithProviderHttpDispatch<T>(context: ProviderDispatchContext, run: () => T | Promise<T>, options?: ProviderHttpDispatchOptions): Promise<T>;
+/** Called only at the screened raw-transport seam, once for every HTTP attempt and redirect hop. */
+export declare const dispatchProviderHttpAttempt: GuardedHttpDispatcher;

package/src/core/provider-http-dispatch.js

@@ -0,0 +1,177 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const scopes = new AsyncLocalStorage();
+/** Safe retryable denial, including hook/readiness failures; it contains no callback error details. */
+export class ProviderHttpDispatchError extends Error {
+    retryAfterSeconds;
+    constructor(retryAfterSeconds) {
+        super("Provider HTTP dispatch is temporarily unavailable.");
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/**
+ * Bind a hook to asynchronous provider work. Nested scopes inherit the configured hook;
+ * concurrent requests stay isolated. Standalone providerFetch users can opt in here too.
+ */
+export function withProviderHttpDispatch(context, run, options) {
+    const parent = scopes.getStore();
+    const configured = options ?? parent?.options;
+    if (!configured)
+        return run();
+    // Copy an explicit allowlist so accidental credential-bearing extra fields cannot escape.
+    const snapshot = Object.freeze({
+        operation: context.operation,
+        service: context.service,
+        actionId: context.actionId,
+        executionId: context.executionId,
+        connectionId: context.connectionId,
+        connectionName: context.connectionName,
+    });
+    return scopes.run({ options: configured, context: snapshot, receipt: parent?.options === configured ? parent.receipt : {} }, run);
+}
+/**
+ * A provider invocation boundary: retain the original denial even if provider code catches,
+ * replaces, or converts it to a result. Each invocation owns its marker, so a sibling's
+ * denial cannot override another invocation's successful retry or fallback.
+ */
+export async function runWithProviderHttpDispatch(context, run, options) {
+    return withProviderHttpDispatch(context, async () => {
+        const inherited = scopes.getStore();
+        if (!inherited)
+            return run();
+        const scope = { ...inherited, receipt: {} };
+        return scopes.run(scope, async () => {
+            try {
+                const result = await run();
+                if (scope.receipt.denial)
+                    throw scope.receipt.denial;
+                return result;
+            }
+            catch (error) {
+                throw scope.receipt.denial ?? error;
+            }
+        });
+    }, options);
+}
+function deny(scope, retryAfterSeconds) {
+    return (scope.receipt.denial ??= Object.freeze(new ProviderHttpDispatchError(retryAfterSeconds)));
+}
+/** Called only at the screened raw-transport seam, once for every HTTP attempt and redirect hop. */
+export const dispatchProviderHttpAttempt = async (target, signal, transport, revalidate) => {
+    const scope = scopes.getStore();
+    if (!scope)
+        return transport();
+    signal?.throwIfAborted();
+    // Denial is terminal for this invocation. A provider may catch it, but must not complete
+    // later side effects that the boundary would then misreport as a retryable denial.
+    if (scope.receipt.denial)
+        throw scope.receipt.denial;
+    let permit;
+    let attempt;
+    try {
+        const authority = await waitForSignal(Promise.resolve(scope.options.bindAuthority?.(scope.context)), signal);
+        signal?.throwIfAborted();
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+        attempt = Object.freeze({
+            attemptId: crypto.randomUUID(),
+            requestId: target.requestId,
+            redirectHop: target.redirectHop,
+            method: target.method,
+            origin: target.origin,
+            context: scope.context,
+            authority: Object.freeze({
+                workspaceId: authority?.workspaceId,
+                connectionLineageId: authority?.connectionLineageId,
+                workClass: authority?.workClass,
+            }),
+        });
+        permit = await waitForSignal(Promise.resolve(scope.options.beforeAttempt(attempt, signal)), signal, (late) => {
+            if (late?.allow)
+                void reportFeedback(scope.options, attempt, late, { kind: "not_dispatched", reason: "cancelled" });
+        });
+        if (!permit || typeof permit.allow !== "boolean")
+            throw new ProviderHttpDispatchError();
+    }
+    catch {
+        signal?.throwIfAborted();
+        throw deny(scope);
+    }
+    if (!permit.allow) {
+        const seconds = permit.retryAfterSeconds;
+        throw deny(scope, Number.isSafeInteger(seconds) && seconds >= 0 ? seconds : undefined);
+    }
+    const admitted = permit;
+    const feedback = (result) => reportFeedback(scope.options, attempt, admitted, result);
+    try {
+        signal?.throwIfAborted();
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+        await waitForSignal(Promise.resolve(admitted.onDispatch?.()), signal);
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+        // Admission can wait arbitrarily long. Re-screen DNS/URL before issuing the admitted hop.
+        await waitForSignal(revalidate(), signal);
+        signal?.throwIfAborted();
+        if (scope.receipt.denial)
+            throw scope.receipt.denial;
+    }
+    catch {
+        const denial = signal?.aborted ? undefined : deny(scope);
+        void feedback({ kind: "not_dispatched", reason: signal?.aborted ? "cancelled" : "dispatch_failed" });
+        signal?.throwIfAborted();
+        throw denial;
+    }
+    let response;
+    try {
+        response = await transport();
+    }
+    catch (error) {
+        void feedback({ kind: "transport_error" });
+        throw error;
+    }
+    // Report every HTTP status, including redirect responses. No response body is read or exposed.
+    void feedback({
+        kind: "response",
+        status: response.status,
+        retryAfter: response.headers.get("retry-after") ?? undefined,
+    });
+    return response;
+};
+async function reportFeedback(options, attempt, permit, result) {
+    try {
+        await permit.onResult?.(Object.freeze(result));
+    }
+    catch {
+        try {
+            await options.onFeedbackError?.(attempt);
+        }
+        catch {
+            // Feedback cannot turn an already-issued request into a failure that a caller might replay.
+        }
+    }
+}
+function waitForSignal(pending, signal, onLate) {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        let cancelled = false;
+        const abort = () => {
+            cancelled = true;
+            reject(signal.reason);
+        };
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener("abort", abort, { once: true });
+        void pending.then((value) => {
+            signal.removeEventListener("abort", abort);
+            if (cancelled)
+                onLate?.(value);
+            else
+                resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+}

package/src/core/provider-scenarios.js

@@ -118,7 +118,6 @@ const scenarioByService = new Map([
     ["triplewhale", "cross-border-ecommerce"],
     ["vercel", "developer"],
     ["shopify", "cross-border-ecommerce"],
-    ["shopifyadmin", "cross-border-ecommerce"],
     ["shopifypartner", "cross-border-ecommerce"],
     ["shopifystorefront", "cross-border-ecommerce"],
     ["shipbob", "cross-border-ecommerce"],

package/src/core/provider-setup.d.ts

@@ -18,6 +18,8 @@ export type ProviderAuthSetup = {
     clientFields: OAuthClientConfigFieldDefinition[];
     clientSetup?: OAuth2AuthDefinition["clientSetup"];
     scopes: string[];
+    /** Additional scopes for explicit selection; requestedScopes replaces the default list. */
+    optionalScopes?: string[];
     authorizationOptions?: OAuth2AuthDefinition["authorizationOptions"];
 };
 /** Describe the inputs accepted by the existing connection and OAuth-client APIs. */

package/src/core/provider-setup.js

@@ -13,6 +13,7 @@ export function describeProviderAuth(auth) {
                 clientFields: oauthClientFields(auth),
                 clientSetup: auth.clientSetup,
                 scopes: auth.scopes,
+                optionalScopes: auth.optionalScopes,
                 authorizationOptions: auth.authorizationOptions,
             };
     }

package/src/core/remote-http.d.ts

@@ -0,0 +1,33 @@
+export type RemoteHttpFailure = "invalid_url" | "dns" | "redirect" | "network" | "invalid_json" | "too_large";
+export declare class RemoteHttpError extends Error {
+    readonly kind: RemoteHttpFailure;
+    constructor(kind: RemoteHttpFailure, message: string);
+}
+export interface RemoteHttpOptions {
+    url: string | URL;
+    label: string;
+    init?: RequestInit;
+    timeoutMs?: number;
+    fetcher?: typeof fetch;
+    requireHttps?: boolean;
+    allowTrustedHosts?: boolean;
+}
+export interface RemoteJsonOptions {
+    label: string;
+    maxBytes: number;
+    signal?: AbortSignal;
+}
+/** Keep the request budget active through response consumption; never follow redirects with a service key. */
+export declare function requestRemote<T>(options: RemoteHttpOptions, consume: (response: Response, signal: AbortSignal | undefined) => Promise<T>): Promise<T>;
+/** Limits decoded transport bytes, including chunked and error responses, without exposing raw JSON errors. */
+export declare function readRemoteJson(response: Response, options: RemoteJsonOptions): Promise<unknown>;
+export declare function isSuccessEnvelope(value: unknown): value is {
+    success: true;
+    data: unknown;
+};
+export declare function isFailureEnvelope(value: unknown): value is {
+    success: false;
+    message: string;
+    errorCode: string;
+    data: unknown;
+};

package/src/core/remote-http.js

@@ -0,0 +1,104 @@
+import { isAbortLikeError } from "../providers/provider-runtime.js";
+import { optionalRecord } from "./cast.js";
+import { createGuardedFetch } from "./guarded-fetch.js";
+import { assertPublicHttpUrl, readBoundedResponseBytes } from "./request.js";
+export class RemoteHttpError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+    }
+}
+/** Keep the request budget active through response consumption; never follow redirects with a service key. */
+export async function requestRemote(options, consume) {
+    const url = assertPublicHttpUrl(String(options.url), {
+        fieldName: `${options.label} URL`,
+        createError: (message) => new RemoteHttpError("invalid_url", message),
+    });
+    if (options.requireHttps !== false && url.protocol !== "https:") {
+        throw new RemoteHttpError("invalid_url", `${options.label} requires HTTPS.`);
+    }
+    if (url.username || url.password || url.hash) {
+        throw new RemoteHttpError("invalid_url", `${options.label} does not allow URL credentials or fragments.`);
+    }
+    const signals = [
+        options.init?.signal,
+        options.timeoutMs === undefined ? undefined : AbortSignal.timeout(options.timeoutMs),
+    ].filter((signal) => signal != null);
+    const signal = signals.length ? AbortSignal.any(signals) : undefined;
+    signal?.throwIfAborted();
+    const guardOptions = {
+        fetch: options.fetcher,
+        allowTrustedHosts: options.allowTrustedHosts ?? false,
+        createError: (message) => new RemoteHttpError("invalid_url", message),
+        createResolutionError: (message) => new RemoteHttpError("dns", message),
+    };
+    const run = async () => {
+        let response;
+        try {
+            response = await createGuardedFetch(guardOptions)(url, { ...options.init, redirect: "manual", signal });
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (error instanceof RemoteHttpError || isAbortLikeError(error))
+                throw error;
+            throw new RemoteHttpError("network", `${options.label} request failed.`);
+        }
+        try {
+            signal?.throwIfAborted();
+            if (response.status >= 300 && response.status < 400) {
+                throw new RemoteHttpError("redirect", `${options.label} redirects are not allowed.`);
+            }
+            return await consume(response, signal);
+        }
+        finally {
+            if (!response.bodyUsed)
+                void response.body?.cancel().catch(() => undefined);
+        }
+    };
+    if (!signal)
+        return run();
+    let abort = () => undefined;
+    const aborted = new Promise((_resolve, reject) => {
+        abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+    try {
+        return await Promise.race([run(), aborted]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
+/** Limits decoded transport bytes, including chunked and error responses, without exposing raw JSON errors. */
+export async function readRemoteJson(response, options) {
+    let bytes;
+    try {
+        bytes = await readBoundedResponseBytes(response, {
+            maxBytes: options.maxBytes,
+            fieldName: options.label,
+            signal: options.signal,
+            createError: (message) => new RemoteHttpError("too_large", message),
+        });
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        if (error instanceof RemoteHttpError || isAbortLikeError(error))
+            throw error;
+        throw new RemoteHttpError("network", `${options.label} could not be read.`);
+    }
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new RemoteHttpError("invalid_json", `${options.label} is not valid JSON.`);
+    }
+}
+export function isSuccessEnvelope(value) {
+    const record = optionalRecord(value);
+    return record?.success === true && "data" in record;
+}
+export function isFailureEnvelope(value) {
+    const record = optionalRecord(value);
+    return record?.success === false && typeof record.message === "string" && typeof record.errorCode === "string";
+}

package/src/core/request.d.ts

@@ -1,3 +1,4 @@
+import type { TransitFileUpload, TransitFileWriter } from "./types.ts";
 /**
  * Query parameter values accepted by provider HTTP helpers.
  */
@@ -31,11 +32,31 @@ export interface BoundedResponseBytesOptions {
     maxBytes: number;
     fieldName: string;
     createError: (message: string) => Error;
+    signal?: AbortSignal;
 }
 /**
  * Read a response body into memory while enforcing a byte limit.
  */
 export declare function readBoundedResponseBytes(response: Response, options: BoundedResponseBytesOptions): Promise<Uint8Array>;
+export interface TransitResponseOptions {
+    /** Name the stored transit file carries. */
+    name: string;
+    mimeType: string;
+    /** Used in the size-limit error, as in {@link readBoundedResponseBytes}. */
+    fieldName: string;
+    createError: (message: string) => Error;
+    signal?: AbortSignal;
+}
+/**
+ * Store a provider download in transit storage without holding it in memory.
+ *
+ * A backend that accepts unknown-length streams (the filesystem store) gets the
+ * response body piped straight to disk, so memory stays flat whatever the file
+ * size or the number of concurrent downloads; the store enforces `maxBytes` as
+ * the bytes arrive. Any other backend keeps the buffered path, bounded exactly
+ * as before.
+ */
+export declare function storeResponseInTransit(response: Response, transitFiles: TransitFileWriter, options: TransitResponseOptions): Promise<TransitFileUpload>;
 export interface PublicHttpUrlOptions {
     fieldName: string;
     createError: (message: string) => Error;