@aws/nx-plugin 0.20.0 → 0.22.0

package/src/py/fast-api/__snapshots__/generator.spec.ts.snap

@@ -2,6 +2,13 @@
 
 exports[`fastapi project generator > should match snapshot > main-snapshot 1`] = `
 {
+  "apps/test_api/scripts/generate_open_api.py": "from test_api.main import app
+import json, os, sys
+
+os.makedirs(os.path.dirname(sys.argv[1]), exist_ok=True)
+with open(sys.argv[1], 'w') as f:
+  json.dump(app.openapi(), f)
+",
   "apps/test_api/test_api/__init__.py": """"Automatically generated by Nx."""
 ",
   "apps/test_api/test_api/init.py": "import os
@@ -156,3 +163,968 @@ def test_main():
 ",
 }
 `;
+
+exports[`fastapi project generator > should set up shared constructs for http > http-api.ts 1`] = `
+"import { Construct } from 'constructs';
+import { RuntimeConfig } from '../runtime-config.js';
+import { Grant, IGrantable } from 'aws-cdk-lib/aws-iam';
+import { HttpApiIntegration, OperationDetails } from './utils.js';
+import { CfnOutput } from 'aws-cdk-lib';
+import {
+  HttpApi as _HttpApi,
+  HttpApiProps as _HttpApiProps,
+  HttpMethod,
+} from 'aws-cdk-lib/aws-apigatewayv2';
+
+/**
+ * Properties for creating an HttpApi construct.
+ *
+ * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TOperation - String literal type representing operation names
+ */
+export interface HttpApiProps<
+  TIntegrations extends Record<TOperation, HttpApiIntegration>,
+  TOperation extends string,
+> extends _HttpApiProps {
+  /**
+   * Unique name for the API, used in runtime configuration
+   */
+  readonly apiName: string;
+  /**
+   * Map of operation names to their API path and HTTP method details
+   */
+  readonly operations: Record<TOperation, OperationDetails>;
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  readonly integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway HTTP API.
+ *
+ * This class extends the base CDK HttpApi with additional functionality:
+ * - Type-safe operation and integration management
+ * - Automatic resource creation based on path patterns
+ * - Integration with runtime configuration for client discovery
+ *
+ * @template TOperation - String literal type representing operation names
+ * @template TIntegrations - Record mapping operation names to their integrations
+ */
+export class HttpApi<
+  TOperation extends string,
+  TIntegrations extends Record<TOperation, HttpApiIntegration>,
+> extends Construct {
+  /** The underlying CDK HttpApi instance */
+  public readonly api: _HttpApi;
+
+  /** Map of operation names to their API Gateway integrations */
+  public readonly integrations: TIntegrations;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    {
+      apiName,
+      operations,
+      integrations,
+      ...props
+    }: HttpApiProps<TIntegrations, TOperation>,
+  ) {
+    super(scope, id);
+    this.integrations = integrations;
+
+    // Create the API Gateway REST API with logging enabled
+    this.api = new _HttpApi(this, 'Api', {
+      ...props,
+    });
+
+    // Create API resources and methods for each operation
+    (Object.entries(operations) as [TOperation, OperationDetails][]).map(
+      ([op, details]) => {
+        this.api.addRoutes({
+          path: details.path.startsWith('/')
+            ? details.path
+            : \`/\${details.path}\`,
+          methods: [details.method as HttpMethod],
+          integration: integrations[op].integration,
+          ...integrations[op].options,
+        });
+      },
+    );
+
+    new CfnOutput(this, \`\${apiName}Url\`, {
+      value: this.api.url!,
+    });
+
+    // Register the API URL in runtime configuration for client discovery
+    RuntimeConfig.ensure(this).config.apis = {
+      ...RuntimeConfig.ensure(this).config.apis!,
+      [apiName]: this.api.url!,
+    };
+  }
+
+  /**
+   * Grants IAM permissions to invoke any method on this API.
+   *
+   * @param grantee - The IAM principal to grant permissions to
+   */
+  public grantInvokeAccess(grantee: IGrantable) {
+    Grant.addToPrincipal({
+      grantee,
+      actions: ['execute-api:Invoke'],
+      resourceArns: [this.api.arnForExecuteApi('*', '/*', '*')],
+    });
+  }
+}
+"
+`;
+
+exports[`fastapi project generator > should set up shared constructs for http > test-api.ts 1`] = `
+"import { Construct } from 'constructs';
+import * as url from 'url';
+import {
+  Code,
+  Runtime,
+  Function,
+  FunctionProps,
+  Tracing,
+} from 'aws-cdk-lib/aws-lambda';
+import { Duration } from 'aws-cdk-lib';
+import { CorsHttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+import { HttpIamAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
+import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import {
+  HttpApiIntegration,
+  IntegrationBuilder,
+} from '../../core/api/utils.js';
+import { HttpApi } from '../../core/api/http-api.js';
+import {
+  OPERATION_DETAILS,
+  Operations,
+} from '../../generated/test-api/metadata.gen.js';
+
+/**
+ * Properties for creating a TestApi construct
+ *
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export interface TestApiProps<
+  TIntegrations extends Record<Operations, HttpApiIntegration>,
+> {
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway HTTP API
+ * specifically for TestApi.
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export class TestApi<
+  TIntegrations extends Record<Operations, HttpApiIntegration>,
+> extends HttpApi<Operations, TIntegrations> {
+  /**
+   * Creates default integrations for all operations, which implement each operation as
+   * its own individual lambda function.
+   *
+   * @param scope - The CDK construct scope
+   * @returns An IntegrationBuilder with default lambda integrations
+   */
+  public static defaultIntegrations = (scope: Construct) => {
+    return IntegrationBuilder.http({
+      operations: OPERATION_DETAILS,
+      defaultIntegrationOptions: {
+        runtime: Runtime.PYTHON_3_12,
+        handler: 'test_api.main.handler',
+        code: Code.fromAsset(
+          url.fileURLToPath(
+            new URL(
+              '../../../../../../dist/apps/nested/path/test_api/bundle',
+              import.meta.url,
+            ),
+          ),
+        ),
+        timeout: Duration.seconds(30),
+        tracing: Tracing.ACTIVE,
+        environment: {
+          AWS_CONNECTION_REUSE_ENABLED: '1',
+        },
+      } satisfies FunctionProps,
+      buildDefaultIntegration: (op, props: FunctionProps) => {
+        const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
+        return {
+          handler,
+          integration: new HttpLambdaIntegration(
+            \`TestApi\${op}Integration\`,
+            handler,
+          ),
+        };
+      },
+    });
+  };
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: TestApiProps<TIntegrations>,
+  ) {
+    super(scope, id, {
+      apiName: 'TestApi',
+      corsPreflight: {
+        allowOrigins: ['*'],
+        allowMethods: [CorsHttpMethod.ANY],
+        allowHeaders: [
+          'authorization',
+          'content-type',
+          'x-amz-content-sha256',
+          'x-amz-date',
+          'x-amz-security-token',
+        ],
+      },
+      defaultAuthorizer: new HttpIamAuthorizer(),
+      operations: OPERATION_DETAILS,
+      ...props,
+    });
+  }
+}
+"
+`;
+
+exports[`fastapi project generator > should set up shared constructs for http > utils.ts 1`] = `
+"import { Integration, MethodOptions } from 'aws-cdk-lib/aws-apigateway';
+import {
+  HttpRouteIntegration,
+  AddRoutesOptions,
+} from 'aws-cdk-lib/aws-apigatewayv2';
+
+/**
+ * Type representing applicable HTTP Methods in API Gateway
+ */
+export type HttpMethod =
+  | 'ANY'
+  | 'DELETE'
+  | 'GET'
+  | 'HEAD'
+  | 'OPTIONS'
+  | 'PATCH'
+  | 'POST'
+  | 'PUT';
+
+/**
+ * Defines the details of an API operation.
+ */
+export interface OperationDetails {
+  /**
+   * The URL path for the operation
+   */
+  path: string;
+
+  /**
+   * The HTTP method for the operation
+   */
+  method: HttpMethod;
+}
+
+/**
+ * Represents an API Gateway REST API integration that can be attached to API methods.
+ */
+export interface RestApiIntegration {
+  integration: Integration;
+  options?: MethodOptions;
+}
+
+/**
+ * Represents an API Gateway HTTP API that can be attached to API methods.
+ */
+export interface HttpApiIntegration {
+  integration: HttpRouteIntegration;
+  options?: Omit<AddRoutesOptions, 'path' | 'methods' | 'integration'>;
+}
+
+/**
+ * Options for constructing an IntegrationBuilder
+ */
+export interface IntegrationBuilderProps<
+  TOperation extends string,
+  TBaseIntegration,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+> {
+  /** Map of operation names to their API path and HTTP method details */
+  operations: Record<TOperation, OperationDetails>;
+
+  /** Default configuration options for integrations */
+  defaultIntegrationOptions: TDefaultIntegrationProps;
+
+  /** Function to create a default integration for an operation */
+  buildDefaultIntegration: (
+    op: TOperation,
+    props: TDefaultIntegrationProps,
+  ) => TDefaultIntegration;
+}
+
+/**
+ * A builder class for creating API integrations with flexible configuration options.
+ *
+ * This class implements the builder pattern to create a set of API integrations
+ * with support for default configurations and selective overrides.
+ *
+ * @template TOperation - String literal type representing operation names
+ * @template TBaseIntegration - Base type for all integrations
+ * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TDefaultIntegrationProps - Type for default integration properties
+ * @template TDefaultIntegration - Type for default integration implementation
+ */
+export class IntegrationBuilder<
+  TOperation extends string,
+  TBaseIntegration,
+  TIntegrations extends Record<TOperation, TBaseIntegration>,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+> {
+  /** Options for the integration builder */
+  private options: IntegrationBuilderProps<
+    TOperation,
+    TBaseIntegration,
+    TDefaultIntegrationProps,
+    TDefaultIntegration
+  >;
+
+  /** Map of operation names to their custom integrations */
+  private integrations: Partial<TIntegrations> = {};
+
+  /**
+   * Create an Integration Builder for an HTTP API
+   */
+  public static http = <
+    TOperation extends string,
+    TIntegrations extends Record<TOperation, TDefaultIntegration>,
+    TDefaultIntegrationProps extends object,
+    TDefaultIntegration extends HttpApiIntegration,
+  >(
+    options: IntegrationBuilderProps<
+      TOperation,
+      HttpApiIntegration,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >,
+  ) => {
+    return new IntegrationBuilder<
+      TOperation,
+      HttpApiIntegration,
+      TIntegrations,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >(options);
+  };
+
+  /**
+   * Create an Integration Builder for a REST API
+   */
+  public static rest = <
+    TOperation extends string,
+    TIntegrations extends Record<TOperation, TDefaultIntegration>,
+    TDefaultIntegrationProps extends object,
+    TDefaultIntegration extends RestApiIntegration,
+  >(
+    options: IntegrationBuilderProps<
+      TOperation,
+      RestApiIntegration,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >,
+  ) => {
+    return new IntegrationBuilder<
+      TOperation,
+      RestApiIntegration,
+      TIntegrations,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >(options);
+  };
+
+  private constructor(
+    options: IntegrationBuilderProps<
+      TOperation,
+      TBaseIntegration,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >,
+  ) {
+    this.options = options;
+  }
+
+  /**
+   * Overrides default integrations with custom implementations for specific operations.
+   *
+   * @param overrides - Map of operation names to their custom integration implementations
+   * @returns The builder instance with updated type information reflecting the overrides
+   */
+  public withOverrides<
+    TOverrideIntegrations extends Partial<Record<TOperation, TBaseIntegration>>,
+  >(overrides: TOverrideIntegrations) {
+    this.integrations = { ...this.integrations, ...overrides };
+    // Re-type to include the overridden integration types
+    return this as unknown as IntegrationBuilder<
+      TOperation,
+      TBaseIntegration,
+      Omit<TIntegrations, keyof TOverrideIntegrations> & TOverrideIntegrations,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >;
+  }
+
+  /**
+   * Updates the default integration options that will be used for operations
+   * without custom overrides.
+   *
+   * @param options - Partial default integration options to merge with existing defaults
+   * @returns The builder instance
+   */
+  public withDefaultOptions(options: Partial<TDefaultIntegrationProps>) {
+    this.options.defaultIntegrationOptions = {
+      ...this.options.defaultIntegrationOptions,
+      ...options,
+    };
+    return this;
+  }
+
+  /**
+   * Builds and returns the complete set of integrations.
+   *
+   * This method creates the final integration map by:
+   * 1. Including all custom overrides provided via withOverrides()
+   * 2. Creating default integrations for any operations without custom overrides
+   *
+   * @returns A complete map of operation names to their integrations
+   */
+  public build(): TIntegrations {
+    return {
+      ...this.integrations,
+      ...Object.fromEntries(
+        (Object.keys(this.options.operations) as TOperation[])
+          .filter(
+            (op) => !this.integrations[op as keyof typeof this.integrations],
+          )
+          .map((op) => [
+            op,
+            this.options.buildDefaultIntegration(
+              op,
+              this.options.defaultIntegrationOptions,
+            ),
+          ]),
+      ),
+    } as unknown as TIntegrations;
+  }
+}
+"
+`;
+
+exports[`fastapi project generator > should set up shared constructs for rest > rest-api.ts 1`] = `
+"import { Construct } from 'constructs';
+import {
+  RestApi as _RestApi,
+  RestApiProps as _RestApiProps,
+  AccessLogFormat,
+  IResource,
+  LogGroupLogDestination,
+  MethodLoggingLevel,
+} from 'aws-cdk-lib/aws-apigateway';
+import { LogGroup } from 'aws-cdk-lib/aws-logs';
+import { RuntimeConfig } from '../runtime-config.js';
+import { Grant, IGrantable } from 'aws-cdk-lib/aws-iam';
+import { OperationDetails, RestApiIntegration } from './utils.js';
+
+/**
+ * Properties for creating a RestApi construct.
+ *
+ * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TOperation - String literal type representing operation names
+ */
+export interface RestApiProps<
+  TIntegrations extends Record<TOperation, RestApiIntegration>,
+  TOperation extends string,
+> extends _RestApiProps {
+  /**
+   * Unique name for the API, used in runtime configuration
+   */
+  readonly apiName: string;
+  /**
+   * Map of operation names to their API path and HTTP method details
+   */
+  readonly operations: Record<TOperation, OperationDetails>;
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  readonly integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway REST API.
+ *
+ * This class extends the base CDK RestApi with additional functionality:
+ * - Type-safe operation and integration management
+ * - Automatic resource creation based on path patterns
+ * - Integration with runtime configuration for client discovery
+ *
+ * @template TOperation - String literal type representing operation names
+ * @template TIntegrations - Record mapping operation names to their integrations
+ */
+export class RestApi<
+  TOperation extends string,
+  TIntegrations extends Record<TOperation, RestApiIntegration>,
+> extends Construct {
+  /** The underlying CDK RestApi instance */
+  public readonly api: _RestApi;
+
+  /** Map of operation names to their API Gateway integrations */
+  public readonly integrations: TIntegrations;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    {
+      apiName,
+      operations,
+      integrations,
+      ...props
+    }: RestApiProps<TIntegrations, TOperation>,
+  ) {
+    super(scope, id);
+    this.integrations = integrations;
+
+    // Create the API Gateway REST API with logging enabled
+    this.api = new _RestApi(this, 'Api', {
+      deployOptions: {
+        accessLogDestination: new LogGroupLogDestination(
+          new LogGroup(this, 'AccessLogs'),
+        ),
+        accessLogFormat: AccessLogFormat.clf(),
+        loggingLevel: MethodLoggingLevel.INFO,
+      },
+      ...props,
+    });
+
+    // Create API resources and methods for each operation
+    (Object.entries(operations) as [TOperation, OperationDetails][]).map(
+      ([op, details]) => {
+        const resource = this.getOrCreateResource(
+          this.api.root,
+          (details.path.startsWith('/')
+            ? details.path.slice(1)
+            : details.path
+          ).split('/'),
+        );
+        resource.addMethod(
+          details.method,
+          integrations[op].integration,
+          integrations[op].options,
+        );
+      },
+    );
+
+    // Register the API URL in runtime configuration for client discovery
+    RuntimeConfig.ensure(this).config.apis = {
+      ...RuntimeConfig.ensure(this).config.apis!,
+      [apiName]: this.api.url!,
+    };
+  }
+
+  /**
+   * Recursively creates or retrieves API Gateway resources based on a path pattern.
+   *
+   * @param resource - The parent API Gateway resource
+   * @param pathParts - Array of path segments to create or retrieve
+   * @returns The API Gateway resource at the end of the path
+   */
+  private getOrCreateResource(
+    resource: IResource,
+    [nextPathPart, ...pathParts]: string[],
+  ): IResource {
+    if (!nextPathPart) {
+      return resource;
+    }
+    const childResource =
+      resource.getResource(nextPathPart) ?? resource.addResource(nextPathPart);
+    return this.getOrCreateResource(childResource, pathParts);
+  }
+
+  /**
+   * Grants IAM permissions to invoke any method on this API.
+   *
+   * @param grantee - The IAM principal to grant permissions to
+   */
+  public grantInvokeAccess(grantee: IGrantable) {
+    Grant.addToPrincipal({
+      grantee,
+      actions: ['execute-api:Invoke'],
+      resourceArns: [this.api.arnForExecuteApi('*', '/*', '*')],
+    });
+  }
+}
+"
+`;
+
+exports[`fastapi project generator > should set up shared constructs for rest > test-api.ts 1`] = `
+"import { Construct } from 'constructs';
+import * as url from 'url';
+import {
+  Code,
+  Runtime,
+  Function,
+  FunctionProps,
+  Tracing,
+} from 'aws-cdk-lib/aws-lambda';
+import {
+  AuthorizationType,
+  Cors,
+  LambdaIntegration,
+} from 'aws-cdk-lib/aws-apigateway';
+import { Duration, Stack } from 'aws-cdk-lib';
+import {
+  PolicyDocument,
+  PolicyStatement,
+  Effect,
+  AccountPrincipal,
+  AnyPrincipal,
+} from 'aws-cdk-lib/aws-iam';
+import {
+  IntegrationBuilder,
+  RestApiIntegration,
+} from '../../core/api/utils.js';
+import { RestApi } from '../../core/api/rest-api.js';
+import {
+  OPERATION_DETAILS,
+  Operations,
+} from '../../generated/test-api/metadata.gen.js';
+
+/**
+ * Properties for creating a TestApi construct
+ *
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export interface TestApiProps<
+  TIntegrations extends Record<Operations, RestApiIntegration>,
+> {
+  /**
+   * Map of operation names to their API Gateway integrations
+   */
+  integrations: TIntegrations;
+}
+
+/**
+ * A CDK construct that creates and configures an AWS API Gateway REST API
+ * specifically for TestApi.
+ * @template TIntegrations - Map of operation names to their integrations
+ */
+export class TestApi<
+  TIntegrations extends Record<Operations, RestApiIntegration>,
+> extends RestApi<Operations, TIntegrations> {
+  /**
+   * Creates default integrations for all operations, which implement each operation as
+   * its own individual lambda function.
+   *
+   * @param scope - The CDK construct scope
+   * @returns An IntegrationBuilder with default lambda integrations
+   */
+  public static defaultIntegrations = (scope: Construct) => {
+    return IntegrationBuilder.rest({
+      operations: OPERATION_DETAILS,
+      defaultIntegrationOptions: {
+        runtime: Runtime.PYTHON_3_12,
+        handler: 'test_api.main.handler',
+        code: Code.fromAsset(
+          url.fileURLToPath(
+            new URL(
+              '../../../../../../dist/apps/nested/path/test_api/bundle',
+              import.meta.url,
+            ),
+          ),
+        ),
+        timeout: Duration.seconds(30),
+        tracing: Tracing.ACTIVE,
+        environment: {
+          AWS_CONNECTION_REUSE_ENABLED: '1',
+        },
+      } satisfies FunctionProps,
+      buildDefaultIntegration: (op, props: FunctionProps) => {
+        const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
+        return { handler, integration: new LambdaIntegration(handler) };
+      },
+    });
+  };
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: TestApiProps<TIntegrations>,
+  ) {
+    super(scope, id, {
+      apiName: 'TestApi',
+      defaultMethodOptions: {
+        authorizationType: AuthorizationType.IAM,
+      },
+      defaultCorsPreflightOptions: {
+        allowOrigins: Cors.ALL_ORIGINS,
+        allowMethods: Cors.ALL_METHODS,
+      },
+      policy: new PolicyDocument({
+        statements: [
+          // Here we grant any AWS credentials from the account that the project is deployed in to call the api.
+          // Machine to machine fine-grained access can be defined here using more specific principals (eg roles or
+          // users) and resources (eg which api paths may be invoked by which principal) if required.
+          new PolicyStatement({
+            effect: Effect.ALLOW,
+            principals: [new AccountPrincipal(Stack.of(scope).account)],
+            actions: ['execute-api:Invoke'],
+            resources: ['execute-api:/*'],
+          }),
+          // Open up OPTIONS to allow browsers to make unauthenticated preflight requests
+          new PolicyStatement({
+            effect: Effect.ALLOW,
+            principals: [new AnyPrincipal()],
+            actions: ['execute-api:Invoke'],
+            resources: ['execute-api:/*/OPTIONS/*'],
+          }),
+        ],
+      }),
+      operations: OPERATION_DETAILS,
+      ...props,
+    });
+  }
+}
+"
+`;
+
+exports[`fastapi project generator > should set up shared constructs for rest > utils.ts 1`] = `
+"import { Integration, MethodOptions } from 'aws-cdk-lib/aws-apigateway';
+import {
+  HttpRouteIntegration,
+  AddRoutesOptions,
+} from 'aws-cdk-lib/aws-apigatewayv2';
+
+/**
+ * Type representing applicable HTTP Methods in API Gateway
+ */
+export type HttpMethod =
+  | 'ANY'
+  | 'DELETE'
+  | 'GET'
+  | 'HEAD'
+  | 'OPTIONS'
+  | 'PATCH'
+  | 'POST'
+  | 'PUT';
+
+/**
+ * Defines the details of an API operation.
+ */
+export interface OperationDetails {
+  /**
+   * The URL path for the operation
+   */
+  path: string;
+
+  /**
+   * The HTTP method for the operation
+   */
+  method: HttpMethod;
+}
+
+/**
+ * Represents an API Gateway REST API integration that can be attached to API methods.
+ */
+export interface RestApiIntegration {
+  integration: Integration;
+  options?: MethodOptions;
+}
+
+/**
+ * Represents an API Gateway HTTP API that can be attached to API methods.
+ */
+export interface HttpApiIntegration {
+  integration: HttpRouteIntegration;
+  options?: Omit<AddRoutesOptions, 'path' | 'methods' | 'integration'>;
+}
+
+/**
+ * Options for constructing an IntegrationBuilder
+ */
+export interface IntegrationBuilderProps<
+  TOperation extends string,
+  TBaseIntegration,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+> {
+  /** Map of operation names to their API path and HTTP method details */
+  operations: Record<TOperation, OperationDetails>;
+
+  /** Default configuration options for integrations */
+  defaultIntegrationOptions: TDefaultIntegrationProps;
+
+  /** Function to create a default integration for an operation */
+  buildDefaultIntegration: (
+    op: TOperation,
+    props: TDefaultIntegrationProps,
+  ) => TDefaultIntegration;
+}
+
+/**
+ * A builder class for creating API integrations with flexible configuration options.
+ *
+ * This class implements the builder pattern to create a set of API integrations
+ * with support for default configurations and selective overrides.
+ *
+ * @template TOperation - String literal type representing operation names
+ * @template TBaseIntegration - Base type for all integrations
+ * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TDefaultIntegrationProps - Type for default integration properties
+ * @template TDefaultIntegration - Type for default integration implementation
+ */
+export class IntegrationBuilder<
+  TOperation extends string,
+  TBaseIntegration,
+  TIntegrations extends Record<TOperation, TBaseIntegration>,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+> {
+  /** Options for the integration builder */
+  private options: IntegrationBuilderProps<
+    TOperation,
+    TBaseIntegration,
+    TDefaultIntegrationProps,
+    TDefaultIntegration
+  >;
+
+  /** Map of operation names to their custom integrations */
+  private integrations: Partial<TIntegrations> = {};
+
+  /**
+   * Create an Integration Builder for an HTTP API
+   */
+  public static http = <
+    TOperation extends string,
+    TIntegrations extends Record<TOperation, TDefaultIntegration>,
+    TDefaultIntegrationProps extends object,
+    TDefaultIntegration extends HttpApiIntegration,
+  >(
+    options: IntegrationBuilderProps<
+      TOperation,
+      HttpApiIntegration,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >,
+  ) => {
+    return new IntegrationBuilder<
+      TOperation,
+      HttpApiIntegration,
+      TIntegrations,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >(options);
+  };
+
+  /**
+   * Create an Integration Builder for a REST API
+   */
+  public static rest = <
+    TOperation extends string,
+    TIntegrations extends Record<TOperation, TDefaultIntegration>,
+    TDefaultIntegrationProps extends object,
+    TDefaultIntegration extends RestApiIntegration,
+  >(
+    options: IntegrationBuilderProps<
+      TOperation,
+      RestApiIntegration,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >,
+  ) => {
+    return new IntegrationBuilder<
+      TOperation,
+      RestApiIntegration,
+      TIntegrations,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >(options);
+  };
+
+  private constructor(
+    options: IntegrationBuilderProps<
+      TOperation,
+      TBaseIntegration,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >,
+  ) {
+    this.options = options;
+  }
+
+  /**
+   * Overrides default integrations with custom implementations for specific operations.
+   *
+   * @param overrides - Map of operation names to their custom integration implementations
+   * @returns The builder instance with updated type information reflecting the overrides
+   */
+  public withOverrides<
+    TOverrideIntegrations extends Partial<Record<TOperation, TBaseIntegration>>,
+  >(overrides: TOverrideIntegrations) {
+    this.integrations = { ...this.integrations, ...overrides };
+    // Re-type to include the overridden integration types
+    return this as unknown as IntegrationBuilder<
+      TOperation,
+      TBaseIntegration,
+      Omit<TIntegrations, keyof TOverrideIntegrations> & TOverrideIntegrations,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >;
+  }
+
+  /**
+   * Updates the default integration options that will be used for operations
+   * without custom overrides.
+   *
+   * @param options - Partial default integration options to merge with existing defaults
+   * @returns The builder instance
+   */
+  public withDefaultOptions(options: Partial<TDefaultIntegrationProps>) {
+    this.options.defaultIntegrationOptions = {
+      ...this.options.defaultIntegrationOptions,
+      ...options,
+    };
+    return this;
+  }
+
+  /**
+   * Builds and returns the complete set of integrations.
+   *
+   * This method creates the final integration map by:
+   * 1. Including all custom overrides provided via withOverrides()
+   * 2. Creating default integrations for any operations without custom overrides
+   *
+   * @returns A complete map of operation names to their integrations
+   */
+  public build(): TIntegrations {
+    return {
+      ...this.integrations,
+      ...Object.fromEntries(
+        (Object.keys(this.options.operations) as TOperation[])
+          .filter(
+            (op) => !this.integrations[op as keyof typeof this.integrations],
+          )
+          .map((op) => [
+            op,
+            this.options.buildDefaultIntegration(
+              op,
+              this.options.defaultIntegrationOptions,
+            ),
+          ]),
+      ),
+    } as unknown as TIntegrations;
+  }
+}
+"
+`;