@vercel/config 0.0.9

package/dist/router.d.ts

@@ -0,0 +1,555 @@
+/**
+ * Helper function to reference a path parameter in transforms.
+ * Path parameters are extracted from the route pattern (e.g., :userId).
+ *
+ * @example
+ * param('userId') // Returns '$userId'
+ */
+export declare function param(name: string): string;
+/**
+ * Helper function to reference a runtime environment variable in transforms.
+ * These are environment variables that get resolved at request time by Vercel's routing layer,
+ * not at build time.
+ *
+ * @example
+ * runtimeEnv('BEARER_TOKEN') // Returns '$BEARER_TOKEN'
+ */
+export declare function runtimeEnv(name: string): string;
+/**
+ * Template literal type for durations recognized by pretty-cache-header.
+ *
+ * Usage examples: '10s', '1week', '2months', '12hrs'
+ */
+export type TimeUnit = 'ms' | 'milli' | 'millisecond' | 'milliseconds' | 's' | 'sec' | 'secs' | 'second' | 'seconds' | 'm' | 'min' | 'mins' | 'minute' | 'minutes' | 'h' | 'hr' | 'hrs' | 'hour' | 'hours' | 'd' | 'day' | 'days' | 'w' | 'week' | 'weeks' | 'mon' | 'mth' | 'mths' | 'month' | 'months' | 'y' | 'yr' | 'yrs' | 'year' | 'years';
+export type TimeString = `${number}${TimeUnit}`;
+/**
+ * Options for constructing the Cache-Control header.
+ * All fields are optional; set only what you need.
+ */
+export interface CacheOptions {
+    /**
+     * Indicates that the response can be cached by any cache.
+     * Equivalent to "public" in Cache-Control.
+     */
+    public?: true;
+    /**
+     * Indicates that the response is intended for a single user
+     * and must not be stored by a shared cache.
+     */
+    private?: true;
+    /**
+     * Indicates that the resource will not be updated and,
+     * therefore, does not need revalidation.
+     */
+    immutable?: true;
+    /**
+     * Indicates that a response must not be stored in any cache.
+     */
+    noStore?: true;
+    /**
+     * Indicates that the response cannot be used to satisfy a subsequent request
+     * without validation on the origin server.
+     */
+    noCache?: true;
+    /**
+     * Indicates that the client must revalidate the response with the origin server
+     * before using it again.
+     */
+    mustRevalidate?: true;
+    /**
+     * Same as must-revalidate, but specifically for shared caches.
+     */
+    proxyRevalidate?: true;
+    /**
+     * The maximum amount of time a resource is considered fresh.
+     * e.g. '1week', '30s', '3days'.
+     */
+    maxAge?: TimeString;
+    /**
+     * If s-maxage is present in a response, it takes priority over max-age
+     * when a shared cache (e.g., CDN) is satisfied.
+     */
+    sMaxAge?: TimeString;
+    /**
+     * How long (in seconds) a resource remains fresh (beyond its max-age)
+     * while a background revalidation is attempted.
+     */
+    staleWhileRevalidate?: TimeString;
+    /**
+     * Allows clients to use stale data when an error is encountered
+     * while attempting to revalidate.
+     */
+    staleIfError?: TimeString;
+}
+/**
+ * Condition type for matching in redirects, headers, and rewrites.
+ * - 'header': Match if a specific HTTP header key/value is present (or missing).
+ * - 'cookie': Match if a specific cookie is present (or missing).
+ * - 'host':   Match if the incoming host matches a given pattern.
+ * - 'query':  Match if a query parameter is present (or missing).
+ */
+export type ConditionType = 'header' | 'cookie' | 'host' | 'query';
+/**
+ * Used to define "has" or "missing" conditions.
+ */
+export interface Condition {
+    type: ConditionType;
+    key: string;
+    value?: string;
+}
+/**
+ * Transform type specifies the scope of what the transform will apply to.
+ * - 'request.query': Transform query parameters in the request
+ * - 'request.headers': Transform headers in the request
+ * - 'response.headers': Transform headers in the response
+ */
+export type TransformType = 'request.query' | 'request.headers' | 'response.headers';
+/**
+ * Transform operation type.
+ * - 'set': Sets the key and value if missing
+ * - 'append': Appends args to the value of the key, and will set if missing
+ * - 'delete': Deletes the key entirely if args is not provided; otherwise, it will delete the value of args from the matching key
+ */
+export type TransformOp = 'set' | 'append' | 'delete';
+/**
+ * Conditional matching properties for transform keys.
+ * When the key property is an object, it can contain one or more of these properties.
+ */
+export interface TransformKeyConditions {
+    /** Check equality on a value */
+    eq?: string | number;
+    /** Check inequality on a value */
+    neq?: string;
+    /** Check inclusion in an array of values */
+    inc?: string[];
+    /** Check non-inclusion in an array of values */
+    ninc?: string[];
+    /** Check if value starts with a prefix */
+    pre?: string;
+    /** Check if value ends with a suffix */
+    suf?: string;
+    /** Check if value is greater than */
+    gt?: number;
+    /** Check if value is greater than or equal to */
+    gte?: number;
+    /** Check if value is less than */
+    lt?: number;
+    /** Check if value is less than or equal to */
+    lte?: number;
+}
+/**
+ * Transform target specifies what key to target for the transform.
+ * The key can be a string (exact match) or an object with conditional matching.
+ */
+export interface TransformTarget {
+    key: string | TransformKeyConditions;
+}
+/**
+ * Transform defines a single transformation operation on request or response data.
+ * Supports environment variables (e.g., $BEARER_TOKEN) and path parameters (e.g., $userId).
+ */
+export interface Transform {
+    /** The scope of what the transform will apply to */
+    type: TransformType;
+    /** The operation to perform */
+    op: TransformOp;
+    /** The target key to transform */
+    target: TransformTarget;
+    /** The value(s) to use for the operation. Can include environment variables ($VAR) and path parameters ($param) */
+    args?: string | string[];
+    /** List of environment variable names that are used in args (without the $ prefix) */
+    env?: string[];
+}
+/**
+ * Route defines a routing rule with transforms.
+ * This is the newer, more powerful route format that supports transforms.
+ *
+ * @example
+ * {
+ *   src: "/users/:userId/posts/:postId",
+ *   transforms: [
+ *     {
+ *       type: "request.headers",
+ *       op: "set",
+ *       target: { key: "x-user-id" },
+ *       args: "$userId"
+ *     },
+ *     {
+ *       type: "request.headers",
+ *       op: "set",
+ *       target: { key: "authorization" },
+ *       args: "Bearer $BEARER_TOKEN"
+ *     }
+ *   ]
+ * }
+ */
+export interface Route {
+    /** Pattern to match request paths using path-to-regexp syntax */
+    src: string;
+    /** Optional destination for rewrite/redirect */
+    dest?: string;
+    /** Array of transforms to apply */
+    transforms?: Transform[];
+    /** Optional conditions that must be present */
+    has?: Condition[];
+    /** Optional conditions that must be absent */
+    missing?: Condition[];
+    /** If true, this is a redirect (status defaults to 308 or specified) */
+    redirect?: boolean;
+    /** Status code for redirects */
+    status?: number;
+    /** Headers to set (alternative to using transforms) */
+    headers?: Record<string, string>;
+}
+/**
+ * Represents a single HTTP header key/value pair.
+ */
+export interface Header {
+    key: string;
+    value: string;
+}
+/**
+ * Options for transform operations on headers and query parameters.
+ * These are converted internally to Vercel's transforms format.
+ */
+export interface TransformOptions {
+    /**
+     * Headers to set/modify on the incoming request.
+     * Use param() for path parameters and runtimeEnv() for environment variables.
+     *
+     * @example
+     * requestHeaders: {
+     *   'x-user-id': param('userId'),
+     *   'authorization': `Bearer ${runtimeEnv('API_TOKEN')}`
+     * }
+     */
+    requestHeaders?: Record<string, string | string[]>;
+    /**
+     * Headers to set/modify on the outgoing response.
+     * Use param() for path parameters and runtimeEnv() for environment variables.
+     *
+     * @example
+     * responseHeaders: {
+     *   'x-post-id': param('postId')
+     * }
+     */
+    responseHeaders?: Record<string, string | string[]>;
+    /**
+     * Query parameters to set/modify on the request.
+     *
+     * @example
+     * requestQuery: {
+     *   'theme': 'dark'
+     * }
+     */
+    requestQuery?: Record<string, string | string[]>;
+}
+/**
+ * HeaderRule defines one or more headers to set for requests
+ * matching a given source pattern, plus optional "has" / "missing" conditions.
+ */
+export interface HeaderRule {
+    /**
+     * Pattern to match request paths using path-to-regexp syntax.
+     * @example
+     * "/api/(.*)"           // Basic capture group
+     * "/blog/:slug"         // Named parameter
+     * "/feedback/((?!general).*)" // Negative lookahead in a group
+     */
+    source: string;
+    /** An array of key/value pairs to set as headers. */
+    headers: Header[];
+    /** Optional conditions that must be present. */
+    has?: Condition[];
+    /** Optional conditions that must be absent. */
+    missing?: Condition[];
+}
+/**
+ * RedirectRule defines a URL rewrite in which the user is redirected
+ * (3xx response) to a destination, with optional conditions.
+ */
+export interface RedirectRule {
+    /**
+     * Pattern to match request paths using path-to-regexp syntax.
+     * @example
+     * "/api/(.*)"           // Basic capture group
+     * "/blog/:slug"         // Named parameter
+     * "/feedback/((?!general).*)" // Negative lookahead in a group
+     */
+    source: string;
+    destination: string;
+    /**
+     * If true, default status code is 308; if false, 307.
+     * Can be overridden by `statusCode`.
+     */
+    permanent?: boolean;
+    /**
+     * Allows specifying a custom HTTP status code instead of 307 or 308.
+     */
+    statusCode?: number;
+    has?: Condition[];
+    missing?: Condition[];
+}
+/**
+ * RewriteRule defines an internal rewrite from the source pattern
+ * to the specified destination, without exposing a redirect to the user.
+ */
+export interface RewriteRule {
+    /**
+     * Pattern to match request paths using path-to-regexp syntax.
+     * @example
+     * "/api/(.*)"           // Basic capture group
+     * "/blog/:slug"         // Named parameter
+     * "/feedback/((?!general).*)" // Negative lookahead in a group
+     */
+    source: string;
+    destination: string;
+    has?: Condition[];
+    missing?: Condition[];
+    /** Internal field: transforms generated from requestHeaders/responseHeaders/requestQuery */
+    transforms?: Transform[];
+}
+/**
+ * CronRule defines a scheduled function invocation on Vercel.
+ */
+export interface CronRule {
+    /**
+     * The URL path to invoke, must start with '/'.
+     */
+    path: string;
+    /**
+     * Cron expression string (e.g., '0 0 * * *' for daily midnight).
+     */
+    schedule: string;
+}
+/**
+ * Providers can be used to asynchronously load sets of rules.
+ */
+export type RedirectProvider = () => Promise<RedirectRule[]>;
+export type HeaderProvider = () => Promise<HeaderRule[]>;
+export type RewriteProvider = () => Promise<RewriteRule[]>;
+export type CronProvider = () => Promise<CronRule[]>;
+/**
+ * The aggregated router configuration, suitable for exporting as
+ * a JSON or TypeScript object that can be consumed by Vercel.
+ */
+export interface RouterConfig {
+    redirects?: RedirectRule[];
+    headers?: HeaderRule[];
+    rewrites?: RewriteRule[];
+    /**
+     * Array of routes with transforms support.
+     * This is the newer, more powerful routing format.
+     * When routes is present, other fields (redirects, headers, rewrites, crons) are excluded.
+     */
+    routes?: Route[];
+    /**
+     * When true, Vercel automatically removes file extensions and normalizes
+     * certain paths, serving HTML and serverless routes extension-free.
+     */
+    cleanUrls?: boolean;
+    /**
+     * When true, routes are normalized to include a trailing slash.
+     */
+    trailingSlash?: boolean;
+    /**
+     * Array of cron definitions for scheduled invocations.
+     */
+    crons?: CronRule[];
+    /**
+     * Custom build command to run during deployment.
+     */
+    buildCommand?: string;
+    /**
+     * Custom install command to run during deployment.
+     */
+    installCommand?: string;
+}
+/**
+ * The main Router class for building a Vercel configuration object in code.
+ * Supports synchronous or asynchronous addition of rewrites, redirects, headers,
+ * plus convenience methods for crons, caching, and more.
+ */
+export declare class Router {
+    private redirectRules;
+    private headerRules;
+    private rewriteRules;
+    private routeRules;
+    private cronRules;
+    private cleanUrlsConfig;
+    private trailingSlashConfig;
+    private buildCommandConfig;
+    private installCommandConfig;
+    /**
+     * Helper to extract environment variable names from a string or string array.
+     * Environment variables are identified by the pattern $VAR_NAME where VAR_NAME
+     * is typically uppercase with underscores (e.g., $API_KEY, $BEARER_TOKEN).
+     */
+    private extractEnvVars;
+    /**
+     * Internal helper to convert TransformOptions to Transform array
+     */
+    private transformOptionsToTransforms;
+    /**
+     * Adds a single rewrite rule (synchronous).
+     * Automatically enables rewrite caching by adding the x-vercel-enable-rewrite-caching header.
+     *
+     * @example
+     *    // This will automatically enable caching for the rewrite
+     *    import { createRouter, param, runtimeEnv } from '@vercel/router-sdk';
+     *    const router = createRouter();
+     *    router.rewrite('/api/(.*)', 'https://old-on-prem.com/$1')
+     *
+     *    // With transforms
+     *    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', {
+     *      requestHeaders: {
+     *        'x-user-id': param('userId'),
+     *        'authorization': `Bearer ${runtimeEnv('API_TOKEN')}`
+     *      }
+     *    });
+     */
+    rewrite(source: string, destination: string, options?: {
+        has?: Condition[];
+        missing?: Condition[];
+        requestHeaders?: Record<string, string | string[]>;
+        responseHeaders?: Record<string, string | string[]>;
+        requestQuery?: Record<string, string | string[]>;
+    }): this;
+    /**
+     * Loads rewrite rules asynchronously and appends them.
+     * Automatically enables rewrite caching for all loaded rules by adding the x-vercel-enable-rewrite-caching header.
+     *
+     * @example
+     *    // This will automatically enable caching for all rewrites
+     *    await router.rewrites(() => fetchRewriteRulesFromDB());
+     */
+    rewrites(provider: RewriteProvider): Promise<this>;
+    /**
+     * Adds a single redirect rule (synchronous).
+     * @example
+     *    router.redirect('/old-path', '/new-path', { permanent: true })
+     *
+     *    // With transforms
+     *    router.redirect('/users/:userId', '/new-users/$1', {
+     *      permanent: true,
+     *      requestHeaders: {
+     *        'x-user-id': param('userId')
+     *      }
+     *    })
+     */
+    redirect(source: string, destination: string, options?: {
+        permanent?: boolean;
+        statusCode?: number;
+        has?: Condition[];
+        missing?: Condition[];
+        requestHeaders?: Record<string, string | string[]>;
+        responseHeaders?: Record<string, string | string[]>;
+        requestQuery?: Record<string, string | string[]>;
+    }): this;
+    /**
+     * Loads redirect rules asynchronously and appends them.
+     */
+    redirects(provider: RedirectProvider): Promise<this>;
+    /**
+     * Adds a single header rule (synchronous).
+     * @example
+     *    router.header('/api/(.*)', [{ key: 'X-Custom', value: 'HelloWorld' }])
+     */
+    header(source: string, headers: Header[], options?: {
+        has?: Condition[];
+        missing?: Condition[];
+    }): this;
+    /**
+     * Loads header rules asynchronously and appends them.
+     */
+    headers(provider: HeaderProvider): Promise<this>;
+    /**
+     * Adds a typed "Cache-Control" header, leveraging `pretty-cache-header`.
+     * This method is purely for convenience, so you can do:
+     *
+     *   router.cacheControl('/my-page', {
+     *     public: true,
+     *     maxAge: '1week',
+     *     staleWhileRevalidate: '1year'
+     *   });
+     */
+    cacheControl(source: string, cacheOptions: CacheOptions, options?: {
+        has?: Condition[];
+        missing?: Condition[];
+    }): this;
+    /**
+     * Adds a route with transforms support.
+     * This is the newer, more powerful routing format that supports transforms.
+     *
+     * @example
+     *    // Add a route with transforms for path parameters and environment variables
+     *    router.route({
+     *      src: '/users/:userId/posts/:postId',
+     *      dest: 'https://api.example.com/users/$userId/posts/$postId',
+     *      transforms: [
+     *        {
+     *          type: 'request.headers',
+     *          op: 'set',
+     *          target: { key: 'x-user-id' },
+     *          args: '$userId'
+     *        },
+     *        {
+     *          type: 'request.headers',
+     *          op: 'set',
+     *          target: { key: 'authorization' },
+     *          args: 'Bearer $BEARER_TOKEN'
+     *        }
+     *      ]
+     *    });
+     */
+    route(config: Route): this;
+    /**
+     * When true, automatically serve HTML files and serverless functions
+     * without the .html or .js extension. This is a built-in Vercel feature.
+     */
+    setCleanUrls(value: boolean): this;
+    /**
+     * When true, automatically normalize paths to include a trailing slash.
+     */
+    setTrailingSlash(value: boolean): this;
+    /**
+     * Sets a custom build command to run during deployment.
+     * @example
+     *   router.setBuildCommand('pnpm run generate-config')
+     */
+    setBuildCommand(value: string): this;
+    /**
+     * Sets a custom install command to run during deployment.
+     * @example
+     *   router.setInstallCommand('pnpm install --no-frozen-lockfile')
+     */
+    setInstallCommand(value: string): this;
+    /**
+     * Adds a single cron rule (synchronous).
+     */
+    cron(path: string, schedule: string): this;
+    /**
+     * Loads cron rules asynchronously and appends them.
+     */
+    crons(provider: CronProvider): Promise<this>;
+    /**
+     * Returns the complete router configuration.
+     * Typically, you'll export or return this in your build scripts,
+     * so that Vercel can pick it up.
+     */
+    getConfig(): RouterConfig;
+    /**
+     * Visualizes the routing tree in the order that Vercel applies routes.
+     * Returns a formatted string showing the routing hierarchy.
+     */
+    visualize(): string;
+    private validateSourcePattern;
+    private validateCronExpression;
+}
+/**
+ * A simple factory function for creating a new Router instance.
+ * @example
+ *   import { createRouter } from '@vercel/router-sdk';
+ *   const router = createRouter();
+ */
+export declare function createRouter(): Router;