@fal-ai/client/src/config.d.ts

The fal.ai client for JavaScript and TypeScript

import { type ProxyRuntimeGate, type RequestMiddleware } from "./middleware";
import type { ResponseHandler } from "./response";
import { type RetryOptions } from "./retry";
export type CredentialsResolver = () => string | undefined;
/**
 * Full configuration for the proxy middleware. Use this object form of
 * `proxyUrl` to control when the proxy applies in non-browser runtimes.
 */
export type ProxyUrlConfig = {
    /**
     * The URL of the proxy server. The proxy server should forward the
     * requests to the fal api.
     */
    url: string;
    /**
     * When the proxy middleware should apply. Defaults to `"browser"`.
     * @see ProxyRuntimeGate
     */
    when?: ProxyRuntimeGate;
};
type FetchType = typeof fetch;
export declare function resolveDefaultFetch(): FetchType;
export type Config = {
    /**
     * The credentials to use for the fal client. When using the
     * client in the browser, it's recommended to use a proxy server to avoid
     * exposing the credentials in the client's environment.
     *
     * By default it tries to use the `FAL_KEY` environment variable, when
     * `process.env` is defined.
     *
     * @see https://fal.ai/docs/model-endpoints/server-side
     * @see #suppressLocalCredentialsWarning
     */
    credentials?: undefined | string | CredentialsResolver;
    /**
     * Suppresses the warning when the fal credentials are exposed in the
     * browser's environment. Make sure you understand the security implications
     * before enabling this option.
     */
    suppressLocalCredentialsWarning?: boolean;
    /**
     * The proxy server to use for the client requests. The proxy server should
     * forward the requests to the fal api.
     *
     * Pass a `string` for the common browser-only case — the middleware rewrites
     * requests to this URL when a DOM `window` is available and does nothing
     * otherwise (the default, recommended for standard web apps).
     *
     * Pass a {@link ProxyUrlConfig} object to opt into non-browser runtimes
     * (Electron, server, edge/worker, Bun, etc.) via the `when` gate.
     *
     * @example Browser-only (unchanged behavior):
     * ```ts
     * fal.config({ proxyUrl: "/api/fal/proxy" });
     * ```
     *
     * @example Always apply, regardless of runtime:
     * ```ts
     * fal.config({
     *   proxyUrl: { url: "/api/fal/proxy", when: "always" },
     * });
     * ```
     *
     * @example Custom predicate (e.g. Electron renderer only):
     * ```ts
     * fal.config({
     *   proxyUrl: {
     *     url: "/api/fal/proxy",
     *     when: ({ isBrowser }) => isBrowser || process.type === "renderer",
     *   },
     * });
     * ```
     */
    proxyUrl?: string | ProxyUrlConfig;
    /**
     * The request middleware to use for the client requests. By default it
     * doesn't apply any middleware.
     */
    requestMiddleware?: RequestMiddleware;
    /**
     * The response handler to use for the client requests. By default it uses
     * a built-in response handler that returns the JSON response.
     */
    responseHandler?: ResponseHandler<any>;
    /**
     * The fetch implementation to use for the client requests. By default it uses
     * the global `fetch` function.
     */
    fetch?: FetchType;
    /**
     * Retry configuration for handling transient errors like rate limiting and server errors.
     * When not specified, a default retry configuration is used.
     */
    retry?: Partial<RetryOptions>;
};
export type RequiredConfig = Required<Config>;
export declare const credentialsFromEnv: CredentialsResolver;
/**
 * Configures the fal client.
 *
 * @param config the new configuration.
 */
export declare function createConfig(config: Config): RequiredConfig;
/**
 * @returns the URL of the fal REST api endpoint.
 */
export declare function getRestApiUrl(): string;
export {};