@ai-sdk/gateway 0.0.0-64aae7dd-20260114144918 → 0.0.0-98261322-20260122142521

package/src/errors/gateway-error-types.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, it } from 'vitest';
+import {
+  GatewayError,
+  GatewayAuthenticationError,
+  GatewayInvalidRequestError,
+  GatewayRateLimitError,
+  GatewayModelNotFoundError,
+  GatewayInternalServerError,
+  GatewayResponseError,
+} from './index';
+
+describe('GatewayAuthenticationError', () => {
+  it('should create error with default values', () => {
+    const error = new GatewayAuthenticationError();
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(GatewayError);
+    expect(error.name).toBe('GatewayAuthenticationError');
+    expect(error.type).toBe('authentication_error');
+    expect(error.message).toBe('Authentication failed');
+    expect(error.statusCode).toBe(401);
+    expect(error.cause).toBeUndefined();
+  });
+
+  it('should create error with custom values', () => {
+    const cause = new Error('Original error');
+    const error = new GatewayAuthenticationError({
+      message: 'Custom auth failed',
+      statusCode: 403,
+      cause,
+    });
+
+    expect(error.message).toBe('Custom auth failed');
+    expect(error.statusCode).toBe(403);
+    expect(error.cause).toBe(cause);
+  });
+
+  it('should be identifiable via instance check', () => {
+    const error = new GatewayAuthenticationError();
+    const otherError = new Error('Not a gateway error');
+
+    expect(GatewayAuthenticationError.isInstance(error)).toBe(true);
+    expect(GatewayAuthenticationError.isInstance(otherError)).toBe(false);
+    expect(GatewayError.isInstance(error)).toBe(true);
+  });
+
+  describe('createContextualError', () => {
+    it('should create error for invalid API key only', () => {
+      const error = GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: true,
+        oidcTokenProvided: false,
+      });
+
+      expect(error.message).toContain('Invalid API key');
+      expect(error.message).toContain('vercel.com/d?to=');
+      expect(error.statusCode).toBe(401);
+    });
+
+    it('should create error for invalid OIDC token only', () => {
+      const error = GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: false,
+        oidcTokenProvided: true,
+      });
+
+      expect(error.message).toContain('Invalid OIDC token');
+      expect(error.message).toContain('npx vercel link');
+      expect(error.statusCode).toBe(401);
+    });
+
+    it('should create error for no authentication provided', () => {
+      const error = GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: false,
+        oidcTokenProvided: false,
+      });
+
+      expect(error.message).toContain('No authentication provided');
+      expect(error.message).toContain('Option 1');
+      expect(error.message).toContain('Option 2');
+      expect(error.statusCode).toBe(401);
+    });
+
+    it('should prioritize API key error when both were provided', () => {
+      const error = GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: true,
+        oidcTokenProvided: true,
+      });
+
+      expect(error.message).toContain('Invalid API key');
+      expect(error.message).toContain('vercel.com/d?to=');
+      expect(error.statusCode).toBe(401);
+    });
+
+    it('should create error for neither provided (legacy test)', () => {
+      const error = GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: false,
+        oidcTokenProvided: false,
+      });
+
+      expect(error.message).toContain('No authentication provided');
+      expect(error.message).toContain('Option 1');
+      expect(error.message).toContain('Option 2');
+      expect(error.statusCode).toBe(401);
+    });
+  });
+});
+
+describe('GatewayInvalidRequestError', () => {
+  it('should create error with default values', () => {
+    const error = new GatewayInvalidRequestError();
+
+    expect(error.name).toBe('GatewayInvalidRequestError');
+    expect(error.type).toBe('invalid_request_error');
+    expect(error.message).toBe('Invalid request');
+    expect(error.statusCode).toBe(400);
+  });
+
+  it('should create error with custom values', () => {
+    const error = new GatewayInvalidRequestError({
+      message: 'Missing required field',
+      statusCode: 422,
+    });
+
+    expect(error.message).toBe('Missing required field');
+    expect(error.statusCode).toBe(422);
+  });
+
+  it('should be identifiable via instance check', () => {
+    const error = new GatewayInvalidRequestError();
+
+    expect(GatewayInvalidRequestError.isInstance(error)).toBe(true);
+    expect(GatewayAuthenticationError.isInstance(error)).toBe(false);
+    expect(GatewayError.isInstance(error)).toBe(true);
+  });
+});
+
+describe('GatewayRateLimitError', () => {
+  it('should create error with default values', () => {
+    const error = new GatewayRateLimitError();
+
+    expect(error.name).toBe('GatewayRateLimitError');
+    expect(error.type).toBe('rate_limit_exceeded');
+    expect(error.message).toBe('Rate limit exceeded');
+    expect(error.statusCode).toBe(429);
+  });
+
+  it('should be identifiable via instance check', () => {
+    const error = new GatewayRateLimitError();
+
+    expect(GatewayRateLimitError.isInstance(error)).toBe(true);
+    expect(GatewayError.isInstance(error)).toBe(true);
+  });
+});
+
+describe('GatewayModelNotFoundError', () => {
+  it('should create error with default values', () => {
+    const error = new GatewayModelNotFoundError();
+
+    expect(error.name).toBe('GatewayModelNotFoundError');
+    expect(error.type).toBe('model_not_found');
+    expect(error.message).toBe('Model not found');
+    expect(error.statusCode).toBe(404);
+    expect(error.modelId).toBeUndefined();
+  });
+
+  it('should create error with model ID', () => {
+    const error = new GatewayModelNotFoundError({
+      message: 'Model gpt-4 not found',
+      modelId: 'gpt-4',
+    });
+
+    expect(error.message).toBe('Model gpt-4 not found');
+    expect(error.modelId).toBe('gpt-4');
+  });
+
+  it('should be identifiable via instance check', () => {
+    const error = new GatewayModelNotFoundError();
+
+    expect(GatewayModelNotFoundError.isInstance(error)).toBe(true);
+    expect(GatewayError.isInstance(error)).toBe(true);
+  });
+});
+
+describe('GatewayInternalServerError', () => {
+  it('should create error with default values', () => {
+    const error = new GatewayInternalServerError();
+
+    expect(error.name).toBe('GatewayInternalServerError');
+    expect(error.type).toBe('internal_server_error');
+    expect(error.message).toBe('Internal server error');
+    expect(error.statusCode).toBe(500);
+  });
+
+  it('should be identifiable via instance check', () => {
+    const error = new GatewayInternalServerError();
+
+    expect(GatewayInternalServerError.isInstance(error)).toBe(true);
+    expect(GatewayError.isInstance(error)).toBe(true);
+  });
+});
+
+describe('GatewayResponseError', () => {
+  it('should create error with default values', () => {
+    const error = new GatewayResponseError();
+
+    expect(error.name).toBe('GatewayResponseError');
+    expect(error.type).toBe('response_error');
+    expect(error.message).toBe('Invalid response from Gateway');
+    expect(error.statusCode).toBe(502);
+    expect(error.response).toBeUndefined();
+    expect(error.validationError).toBeUndefined();
+  });
+
+  it('should create error with response and validation error details', () => {
+    const response = { invalidField: 'value' };
+    const validationError = {
+      issues: [{ path: ['error'], message: 'Required' }],
+    } as any; // Mock ZodError structure
+
+    const error = new GatewayResponseError({
+      message: 'Custom parsing error',
+      statusCode: 422,
+      response,
+      validationError,
+    });
+
+    expect(error.message).toBe('Custom parsing error');
+    expect(error.statusCode).toBe(422);
+    expect(error.response).toBe(response);
+    expect(error.validationError).toBe(validationError);
+  });
+
+  it('should be identifiable via instance check', () => {
+    const error = new GatewayResponseError();
+
+    expect(GatewayResponseError.isInstance(error)).toBe(true);
+    expect(GatewayError.isInstance(error)).toBe(true);
+  });
+});
+
+describe('Cross-realm instance checking', () => {
+  it('should work with symbol-based type checking', () => {
+    const error = new GatewayAuthenticationError();
+
+    // Simulate different realm by creating a new instance in different context
+    const gatewayErrorMarker = Symbol.for('vercel.ai.gateway.error');
+    const authErrorMarker = Symbol.for(
+      'vercel.ai.gateway.error.GatewayAuthenticationError',
+    );
+
+    // Verify the symbols are present
+    expect((error as any)[gatewayErrorMarker]).toBe(true);
+    expect((error as any)[authErrorMarker]).toBe(true);
+
+    // Test cross-realm safety
+    expect(GatewayError.hasMarker(error)).toBe(true);
+    expect(GatewayAuthenticationError.isInstance(error)).toBe(true);
+  });
+});
+
+describe('Error inheritance chain', () => {
+  it('should maintain proper inheritance', () => {
+    const error = new GatewayAuthenticationError();
+
+    expect(error instanceof Error).toBe(true);
+    expect(error instanceof GatewayError).toBe(true);
+    expect(error instanceof GatewayAuthenticationError).toBe(true);
+  });
+
+  it('should have proper stack traces', () => {
+    const error = new GatewayAuthenticationError({
+      message: 'Test error',
+    });
+
+    expect(error.stack).toBeDefined();
+    expect(error.stack).toContain('GatewayAuthenticationError');
+    expect(error.stack).toContain('Test error');
+  });
+});

package/src/errors/gateway-error.ts

@@ -0,0 +1,47 @@
+const marker = 'vercel.ai.gateway.error';
+const symbol = Symbol.for(marker);
+
+export abstract class GatewayError extends Error {
+  private readonly [symbol] = true; // used in isInstance
+
+  abstract readonly name: string;
+  abstract readonly type: string;
+  readonly statusCode: number;
+  readonly cause?: unknown;
+  readonly generationId?: string;
+
+  constructor({
+    message,
+    statusCode = 500,
+    cause,
+    generationId,
+  }: {
+    message: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  }) {
+    super(generationId ? `${message} [${generationId}]` : message);
+    this.statusCode = statusCode;
+    this.cause = cause;
+    this.generationId = generationId;
+  }
+
+  /**
+   * Checks if the given error is a Gateway Error.
+   * @param {unknown} error - The error to check.
+   * @returns {boolean} True if the error is a Gateway Error, false otherwise.
+   */
+  static isInstance(error: unknown): error is GatewayError {
+    return GatewayError.hasMarker(error);
+  }
+
+  static hasMarker(error: unknown): error is GatewayError {
+    return (
+      typeof error === 'object' &&
+      error !== null &&
+      symbol in error &&
+      (error as any)[symbol] === true
+    );
+  }
+}

package/src/errors/gateway-internal-server-error.ts

@@ -0,0 +1,33 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayInternalServerError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Internal server error from the Gateway
+ */
+export class GatewayInternalServerError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'internal_server_error';
+
+  constructor({
+    message = 'Internal server error',
+    statusCode = 500,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayInternalServerError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-invalid-request-error.ts

@@ -0,0 +1,33 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayInvalidRequestError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Invalid request - missing headers, malformed data, etc.
+ */
+export class GatewayInvalidRequestError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'invalid_request_error';
+
+  constructor({
+    message = 'Invalid request',
+    statusCode = 400,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayInvalidRequestError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-model-not-found-error.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod/v4';
+import { GatewayError } from './gateway-error';
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+
+const name = 'GatewayModelNotFoundError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+export const modelNotFoundParamSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      modelId: z.string(),
+    }),
+  ),
+);
+
+/**
+ * Model not found or not available
+ */
+export class GatewayModelNotFoundError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'model_not_found';
+  readonly modelId?: string;
+
+  constructor({
+    message = 'Model not found',
+    statusCode = 404,
+    modelId,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    modelId?: string;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+    this.modelId = modelId;
+  }
+
+  static isInstance(error: unknown): error is GatewayModelNotFoundError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-rate-limit-error.ts

@@ -0,0 +1,33 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayRateLimitError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Rate limit exceeded.
+ */
+export class GatewayRateLimitError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'rate_limit_exceeded';
+
+  constructor({
+    message = 'Rate limit exceeded',
+    statusCode = 429,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayRateLimitError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-response-error.ts

@@ -0,0 +1,42 @@
+import { TypeValidationError } from '@ai-sdk/provider';
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayResponseError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Gateway response parsing error
+ */
+export class GatewayResponseError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'response_error';
+  readonly response?: unknown;
+  readonly validationError?: TypeValidationError;
+
+  constructor({
+    message = 'Invalid response from Gateway',
+    statusCode = 502,
+    response,
+    validationError,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    response?: unknown;
+    validationError?: TypeValidationError;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+    this.response = response;
+    this.validationError = validationError;
+  }
+
+  static isInstance(error: unknown): error is GatewayResponseError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,16 @@
+export { asGatewayError } from './as-gateway-error';
+export {
+  createGatewayErrorFromResponse,
+  type GatewayErrorResponse,
+} from './create-gateway-error';
+export { extractApiCallResponse } from './extract-api-call-response';
+export { GatewayError } from './gateway-error';
+export { GatewayAuthenticationError } from './gateway-authentication-error';
+export { GatewayInternalServerError } from './gateway-internal-server-error';
+export { GatewayInvalidRequestError } from './gateway-invalid-request-error';
+export {
+  GatewayModelNotFoundError,
+  modelNotFoundParamSchema,
+} from './gateway-model-not-found-error';
+export { GatewayRateLimitError } from './gateway-rate-limit-error';
+export { GatewayResponseError } from './gateway-response-error';

package/src/errors/parse-auth-method.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import {
+  GATEWAY_AUTH_METHOD_HEADER,
+  parseAuthMethod,
+} from './parse-auth-method';
+
+describe('GATEWAY_AUTH_METHOD_HEADER', () => {
+  it('should export the correct header name', () => {
+    expect(GATEWAY_AUTH_METHOD_HEADER).toBe('ai-gateway-auth-method');
+  });
+});
+
+describe('parseAuthMethod', () => {
+  describe('valid authentication methods', () => {
+    it('should parse "api-key" auth method', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: 'api-key',
+      };
+
+      const result = await parseAuthMethod(headers);
+
+      expect(result).toBe('api-key');
+    });
+
+    it('should parse "oidc" auth method', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: 'oidc',
+      };
+
+      const result = await parseAuthMethod(headers);
+
+      expect(result).toBe('oidc');
+    });
+
+    it('should handle headers with other fields present', async () => {
+      const headers = {
+        authorization: 'Bearer token',
+        'content-type': 'application/json',
+        [GATEWAY_AUTH_METHOD_HEADER]: 'api-key',
+        'user-agent': 'test-agent',
+      };
+
+      const result = await parseAuthMethod(headers);
+
+      expect(result).toBe('api-key');
+    });
+  });
+
+  describe('invalid authentication methods', () => {
+    it('should return undefined for invalid auth method string', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: 'invalid-method',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined for empty string', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: '',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined for numeric value', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: '123',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined for boolean-like strings', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: 'true',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined for case-sensitive variations', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: 'API-KEY',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined for OIDC case variations', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: 'OIDC',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+  });
+
+  describe('missing or undefined headers', () => {
+    it('should return undefined when header is missing', async () => {
+      const headers = {
+        authorization: 'Bearer token',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined when header is undefined', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: undefined,
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined when headers object is empty', async () => {
+      const headers = {};
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should return undefined for whitespace-only strings', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: '   ',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should return undefined for auth methods with extra whitespace', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: ' api-key ',
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+
+    it('should handle null values', async () => {
+      const headers = {
+        [GATEWAY_AUTH_METHOD_HEADER]: null as any,
+      };
+      expect(await parseAuthMethod(headers)).toBeUndefined();
+    });
+  });
+});

package/src/errors/parse-auth-method.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod/v4';
+import {
+  lazySchema,
+  safeValidateTypes,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+
+export const GATEWAY_AUTH_METHOD_HEADER = 'ai-gateway-auth-method' as const;
+
+export async function parseAuthMethod(
+  headers: Record<string, string | undefined>,
+) {
+  const result = await safeValidateTypes({
+    value: headers[GATEWAY_AUTH_METHOD_HEADER],
+    schema: gatewayAuthMethodSchema,
+  });
+
+  return result.success ? result.value : undefined;
+}
+
+const gatewayAuthMethodSchema = lazySchema(() =>
+  zodSchema(z.union([z.literal('api-key'), z.literal('oidc')])),
+);