@vercel/config 0.0.12 → 0.0.13

package/README.md

@@ -147,6 +147,194 @@ Set the path to a bulk redirects JSON file.
 router.bulkRedirectsPath = './bulkRedirectsDemo.json';
 ```
 
+## Conditional Routing
+
+The SDK supports powerful conditional routing using `has` and `missing` conditions. These conditions can be added to rewrites, redirects, headers, and cache control rules.
+
+### Condition Types
+
+- `header`: Match HTTP headers
+- `cookie`: Match cookies
+- `host`: Match the request host
+- `query`: Match query parameters
+- `path`: Match the request path pattern
+
+### Simple Presence Check
+
+```typescript
+// Only rewrite if x-api-key header exists
+router.rewrite('/api/(.*)', 'https://backend.com/$1', {
+  has: [
+    { type: 'header', key: 'x-api-key' }
+  ]
+});
+
+// Redirect if auth-token cookie is missing
+router.redirect('/dashboard', '/login', {
+  missing: [
+    { type: 'cookie', key: 'auth-token' }
+  ]
+});
+```
+
+### Conditional Operators
+
+The SDK supports advanced matching operators for more complex conditions:
+
+#### Equality Operators
+
+```typescript
+// Exact match using 'eq'
+router.rewrite('/api/(.*)', 'https://backend.com/$1', {
+  has: [
+    { type: 'header', key: 'x-api-version', eq: 'v2' }
+  ]
+});
+
+// Not equal using 'neq'
+router.redirect('/beta/(.*)', '/stable/$1', {
+  has: [
+    { type: 'cookie', key: 'beta-access', neq: 'granted' }
+  ]
+});
+```
+
+#### Inclusion Operators
+
+```typescript
+// Must be one of (inclusion)
+router.rewrite('/admin/(.*)', 'https://admin.backend.com/$1', {
+  has: [
+    { type: 'header', key: 'x-user-role', inc: ['admin', 'moderator', 'superuser'] }
+  ]
+});
+
+// Must NOT be one of (non-inclusion)
+router.redirect('/public/(.*)', '/private/$1', {
+  has: [
+    { type: 'header', key: 'x-user-role', ninc: ['guest', 'anonymous'] }
+  ]
+});
+```
+
+#### String Pattern Operators
+
+```typescript
+// Starts with (prefix)
+router.rewrite('/staging/(.*)', 'https://staging.backend.com/$1', {
+  has: [
+    { type: 'cookie', key: 'session', pre: 'staging-' }
+  ]
+});
+
+// Ends with (suffix)
+router.redirect('/dev/(.*)', '/development/$1', {
+  has: [
+    { type: 'header', key: 'x-environment', suf: '-dev' }
+  ]
+});
+```
+
+#### Numeric Comparison Operators
+
+```typescript
+// Greater than
+router.rewrite('/api/v3/(.*)', 'https://api-v3.backend.com/$1', {
+  has: [
+    { type: 'query', key: 'version', gt: 2 }
+  ]
+});
+
+// Greater than or equal
+router.rewrite('/premium/(.*)', '/premium-content/$1', {
+  has: [
+    { type: 'header', key: 'x-subscription-tier', gte: 3 }
+  ]
+});
+
+// Less than
+router.redirect('/legacy/(.*)', '/upgrade/$1', {
+  has: [
+    { type: 'query', key: 'api-version', lt: 2 }
+  ]
+});
+
+// Less than or equal
+router.rewrite('/free/(.*)', '/free-tier/$1', {
+  has: [
+    { type: 'header', key: 'x-plan', lte: 1 }
+  ]
+});
+```
+
+### Host and Path Matching
+
+```typescript
+// Host matching (no key required)
+router.redirect('/(.*)', 'https://www.example.com/$1', {
+  has: [
+    { type: 'host', value: 'example.com' }
+  ]
+});
+
+// Path pattern matching (no key required)
+router.rewrite('/(.*)', '/internal/$1', {
+  has: [
+    { type: 'path', value: '^/api/v[0-9]+/.*' }
+  ]
+});
+```
+
+### Multiple Conditions
+
+All conditions in a `has` or `missing` array must match (AND logic):
+
+```typescript
+router.rewrite('/secure/(.*)', 'https://secure.backend.com/$1', {
+  has: [
+    { type: 'header', key: 'x-api-key' },
+    { type: 'header', key: 'x-user-role', inc: ['admin', 'superuser'] },
+    { type: 'cookie', key: 'session', pre: 'secure-' },
+    { type: 'query', key: 'version', gte: 2 }
+  ]
+});
+```
+
+### Combining with Transforms
+
+You can combine conditions with transforms for powerful routing logic:
+
+```typescript
+router.rewrite('/api/users/:userId', 'https://backend.com/users/$1', ({ userId, env }) => ({
+  has: [
+    { type: 'header', key: 'authorization', pre: 'Bearer ' },
+    { type: 'header', key: 'x-api-version', gte: 2 }
+  ],
+  missing: [
+    { type: 'header', key: 'x-deprecated-header' }
+  ],
+  requestHeaders: {
+    'x-user-id': userId,
+    'x-internal-key': env.INTERNAL_API_KEY
+  }
+}));
+```
+
+### Available Operators
+
+| Operator | Type | Description | Example |
+|----------|------|-------------|---------|
+| `eq` | string \| number | Exact equality match | `{ eq: 'v2' }` |
+| `neq` | string | Not equal | `{ neq: 'guest' }` |
+| `inc` | string[] | Value is one of | `{ inc: ['admin', 'mod'] }` |
+| `ninc` | string[] | Value is not one of | `{ ninc: ['guest', 'banned'] }` |
+| `pre` | string | Starts with prefix | `{ pre: 'Bearer ' }` |
+| `suf` | string | Ends with suffix | `{ suf: '-dev' }` |
+| `gt` | number | Greater than | `{ gt: 2 }` |
+| `gte` | number | Greater than or equal | `{ gte: 3 }` |
+| `lt` | number | Less than | `{ lt: 5 }` |
+| `lte` | number | Less than or equal | `{ lte: 10 }` |
+
 ## Important Notes
 
 - **One config file only**: You cannot have both `vercel.ts` and `vercel.json`. The build will fail if both exist.

package/dist/router.d.ts

@@ -87,14 +87,75 @@ export interface CacheOptions {
  * - '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).
+ * - 'path':   Match if the path matches a given pattern.
  */
-export type ConditionType = 'header' | 'cookie' | 'host' | 'query';
+export type ConditionType = 'header' | 'cookie' | 'host' | 'query' | 'path';
 /**
- * Used to define "has" or "missing" conditions.
+ * Conditional matching operators for has/missing conditions.
+ * These can be used with the value field to perform advanced matching.
  */
-export interface Condition {
+export interface ConditionOperators {
+    /** Check equality on a value (exact match) */
+    eq?: string | number;
+    /** Check inequality on a value (not equal) */
+    neq?: string;
+    /** Check inclusion in an array of values (value is one of) */
+    inc?: string[];
+    /** Check non-inclusion in an array of values (value is not one of) */
+    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 (numeric comparison) */
+    gt?: number;
+    /** Check if value is greater than or equal to */
+    gte?: number;
+    /** Check if value is less than (numeric comparison) */
+    lt?: number;
+    /** Check if value is less than or equal to */
+    lte?: number;
+}
+/**
+ * Used to define "has" or "missing" conditions with advanced matching operators.
+ *
+ * @example
+ * // Simple header presence check
+ * { type: 'header', key: 'x-api-key' }
+ *
+ * @example
+ * // Header with exact value match
+ * { type: 'header', key: 'x-api-version', value: 'v2' }
+ *
+ * @example
+ * // Header with conditional operators
+ * { type: 'header', key: 'x-user-role', inc: ['admin', 'moderator'] }
+ *
+ * @example
+ * // Cookie with prefix matching
+ * { type: 'cookie', key: 'session', pre: 'prod-' }
+ *
+ * @example
+ * // Host matching
+ * { type: 'host', value: 'api.example.com' }
+ *
+ * @example
+ * // Query parameter with numeric comparison
+ * { type: 'query', key: 'version', gte: 2 }
+ *
+ * @example
+ * // Path pattern matching
+ * { type: 'path', value: '^/api/v[0-9]+/.*' }
+ */
+export interface Condition extends ConditionOperators {
     type: ConditionType;
-    key: string;
+    /** The key to match. Not used for 'host' or 'path' types. */
+    key?: string;
+    /**
+     * Simple string/regex pattern to match against.
+     * For 'host' and 'path' types, this is the only matching option.
+     * For other types, you can use value OR the conditional operators (eq, neq, etc).
+     */
     value?: string;
 }
 /**
@@ -188,6 +249,8 @@ export interface Route {
     src: string;
     /** Optional destination for rewrite/redirect */
     dest?: string;
+    /** Array of HTTP methods to match. If not provided, matches all methods */
+    methods?: string[];
     /** Array of transforms to apply */
     transforms?: Transform[];
     /** Optional conditions that must be present */
@@ -196,7 +259,7 @@ export interface Route {
     missing?: Condition[];
     /** If true, this is a redirect (status defaults to 308 or specified) */
     redirect?: boolean;
-    /** Status code for redirects */
+    /** Status code for the response */
     status?: number;
     /** Headers to set (alternative to using transforms) */
     headers?: Record<string, string>;
@@ -359,6 +422,10 @@ export interface RewriteRule {
      */
     source: string;
     destination: string;
+    /** Array of HTTP methods to match. If not provided, matches all methods */
+    methods?: string[];
+    /** Status code for the response */
+    status?: number;
     has?: Condition[];
     missing?: Condition[];
     /** Internal field: transforms generated from requestHeaders/responseHeaders/requestQuery */
@@ -512,6 +579,8 @@ export declare class Router {
      *    });
      */
     rewrite(source: string, destination: string, optionsOrCallback?: {
+        methods?: string[];
+        status?: number;
         has?: Condition[];
         missing?: Condition[];
         requestHeaders?: Record<string, string | string[]>;
@@ -526,6 +595,8 @@ export declare class Router {
     } | ((params: Record<string, string> & {
         env: any;
     }) => {
+        methods?: string[];
+        status?: number;
         has?: Condition[];
         missing?: Condition[];
         requestHeaders?: Record<string, string | string[]>;

package/dist/router.js

@@ -305,7 +305,7 @@ class Router {
             options = optionsOrCallback;
         }
         // Extract transform options
-        const { requestHeaders, responseHeaders, requestQuery, appendRequestHeaders, appendResponseHeaders, appendRequestQuery, deleteRequestHeaders, deleteResponseHeaders, deleteRequestQuery, has, missing } = options || {};
+        const { methods, status, requestHeaders, responseHeaders, requestQuery, appendRequestHeaders, appendResponseHeaders, appendRequestQuery, deleteRequestHeaders, deleteResponseHeaders, deleteRequestQuery, has, missing } = options || {};
         const transformOpts = {
             requestHeaders,
             responseHeaders,
@@ -327,6 +327,8 @@ class Router {
         this.rewriteRules.push({
             source,
             destination,
+            ...(methods && { methods }),
+            ...(status && { status }),
             has,
             missing,
             transforms,
@@ -410,7 +412,7 @@ class Router {
             options = optionsOrCallback;
         }
         // Extract transform options
-        const { requestHeaders, responseHeaders, requestQuery, appendRequestHeaders, appendResponseHeaders, appendRequestQuery, deleteRequestHeaders, deleteResponseHeaders, deleteRequestQuery, permanent, statusCode, has, missing, } = options || {};
+        const { methods, requestHeaders, responseHeaders, requestQuery, appendRequestHeaders, appendResponseHeaders, appendRequestQuery, deleteRequestHeaders, deleteResponseHeaders, deleteRequestQuery, permanent, statusCode, has, missing, } = options || {};
         // If transforms are provided, create a route instead of a redirect
         const hasTransforms = requestHeaders || responseHeaders || requestQuery ||
             appendRequestHeaders || appendResponseHeaders || appendRequestQuery ||
@@ -431,6 +433,7 @@ class Router {
             this.routeRules.push({
                 src: source,
                 dest: destination,
+                ...(methods && { methods }),
                 transforms,
                 redirect: true,
                 status: statusCode || (permanent ? 308 : 307),
@@ -580,16 +583,22 @@ class Router {
      * so that Vercel can pick it up.
      */
     getConfig() {
-        // Separate rewrites into those with and without transforms
-        const rewritesWithoutTransforms = this.rewriteRules.filter((r) => !r.transforms);
-        const rewritesWithTransforms = this.rewriteRules.filter((r) => r.transforms);
-        // Convert rewrites with transforms to routes
-        const routesFromRewrites = rewritesWithTransforms.map((rewrite) => {
+        // Separate rewrites into those that need to be routes vs. legacy rewrites
+        // Routes are needed for: transforms, methods, or custom status
+        const rewritesNeedingRoutes = this.rewriteRules.filter((r) => r.transforms || r.methods || r.status);
+        const legacyRewrites = this.rewriteRules.filter((r) => !r.transforms && !r.methods && !r.status);
+        // Convert rewrites to routes
+        const routesFromRewrites = rewritesNeedingRoutes.map((rewrite) => {
             const route = {
                 src: rewrite.source,
                 dest: rewrite.destination,
-                transforms: rewrite.transforms,
             };
+            if (rewrite.transforms)
+                route.transforms = rewrite.transforms;
+            if (rewrite.methods)
+                route.methods = rewrite.methods;
+            if (rewrite.status)
+                route.status = rewrite.status;
             if (rewrite.has)
                 route.has = rewrite.has;
             if (rewrite.missing)
@@ -619,7 +628,7 @@ class Router {
         const config = {
             redirects: this.redirectRules,
             headers: this.headerRules,
-            rewrites: rewritesWithoutTransforms,
+            rewrites: legacyRewrites,
             cleanUrls: this.cleanUrlsConfig,
             trailingSlash: this.trailingSlashConfig,
             crons: this.cronRules,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/config",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "A TypeScript SDK for programmatically generating Vercel configuration files",
   "bugs": {
     "url": "https://github.com/vercel/router-sdk/issues"