@fal-ai/server-proxy/src/config.d.ts

The fal.ai server proxy adapter for JavaScript and TypeScript Web frameworks

import { ProxyBehavior } from "./types";
/**
 * The fal REST API URL used for storage operations.
 */
export declare const FAL_REST_API_URL = "rest.fal.ai";
/**
 * The default allowed URL patterns. Only `fal.run` and `queue.fal.run` are allowed by default.
 * You can add patterns like `fal.ai/**` or `fal.dev/**` if needed for your use case.
 *
 * Note: Uses picomatch glob syntax. The `?` character is escaped with `\\?` for literal matching.
 */
export declare const DEFAULT_ALLOWED_URL_PATTERNS: string[];
/**
 * Creates a matcher function for URL patterns using picomatch.
 * Supports glob patterns like `*` (single segment) and `**` (any path).
 *
 * @param patterns the URL patterns to match against.
 * @returns a function that checks if a URL matches any of the patterns.
 */
export declare function createUrlMatcher(patterns: string[]): (url: string) => boolean;
/**
 * Proxy configuration options.
 */
export interface ProxyConfig {
    /**
     * URL patterns (glob-style) that are allowed to be proxied.
     * Supports `*` (matches any characters except `/`) and `**` (matches any characters including `/`).
     *
     * By default only `fal.run/**` and `queue.fal.run/**` are allowed.
     * You can add patterns like `fal.ai/**` or `fal.dev/**` if needed for your use case.
     *
     * @example
     * ```ts
     * allowedUrlPatterns: ["fal.run/**", "queue.fal.run/**", "fal.ai/my-app/**"]
     * ```
     *
     * @default ["fal.run/**", "queue.fal.run/**"]
     */
    allowedUrlPatterns?: string[];
    /**
     * Endpoint patterns (glob-style) that are allowed to be called via POST requests.
     * The endpoint is the path portion of the URL without the leading slash.
     *
     * For example, for `https://fal.run/fal-ai/flux/dev`, the endpoint is `fal-ai/flux/dev`.
     *
     * Supports `*` (matches any characters except `/`) and `**` (matches any characters including `/`).
     *
     * Currently for backwards compatibility an empty array means all endpoints are allowed.
     * In the future the behavior might change to disallow all endpoints by default and require
     * explicitly allowing endpoints.
     *
     * @example
     * ```ts
     * // Allow only specific endpoints
     * allowedEndpoints: ["fal-ai/flux/**", "fal-ai/fast-sdxl"]
     * ```
     *
     * @default [] (all endpoints allowed)
     */
    allowedEndpoints?: string[] | undefined;
    /**
     * Whether to allow requests without an authorization header. Currently for backwards compatibility
     * this is set to `true` by default. In the future the behavior might change to disallow unauthorized
     * requests by default and require explicitly allowing unauthorized requests.
     */
    allowUnauthorizedRequests?: boolean;
    /**
     * A function to check if the request is authenticated. This is implemented by the app owner
     * to inform the proxy whether the request is authenticated or not.
     *
     * @param behavior the proxy behavior.
     * @returns whether the request is authenticated.
     *
     * @see isAuthorizationHeaderPresent
     */
    isAuthenticated?: (behavior: ProxyBehavior<unknown>) => Promise<boolean>;
    /**
     * A function to resolve the authorization header value. By default it uses the `FAL_KEY` environment variable.
     * You can use this to use a different authorization mechanism, for example a custom token based authentication.
     *
     * @returns the authorization header value.
     */
    resolveFalAuth?: (behavior: ProxyBehavior<unknown>) => Promise<string | undefined>;
}
export declare function useEnvironmentFalKey(): Promise<string | undefined>;
export declare function fallbackToFalKey(behavior: ProxyBehavior<unknown>): Promise<string | undefined>;
export declare function isAuthorizationHeaderPresent(behavior: ProxyBehavior<unknown>): Promise<boolean>;
export declare const DEFAULT_PROXY_CONFIG: ProxyConfig;
/**
 * Merges the default proxy configuration with the provided configuration.
 *
 * @param config the proxy configuration to apply.
 * @returns the resolved proxy configuration.
 */
export declare function applyProxyConfig(config: Partial<ProxyConfig>): ProxyConfig;
/**
 * Resolves the proxy configuration once. Use this at handler creation time
 * to avoid logging warnings on every request.
 *
 * @param config the proxy configuration to apply.
 * @returns the resolved proxy configuration.
 */
export declare function resolveProxyConfig(config: Partial<ProxyConfig>): ProxyConfig;