@composurecdk/apigateway 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @composurecdk/apigateway
+
+API Gateway builders for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for API Gateway REST APIs with secure, AWS-recommended defaults. It wraps the CDK [RestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html) construct — refer to the CDK documentation for the full set of configurable properties.
+
+## REST API Builder
+
+```ts
+import { createRestApiBuilder } from "@composurecdk/apigateway";
+
+const api = createRestApiBuilder()
+  .restApiName("My Service")
+  .description("Public API")
+  .addResource("users", (users) =>
+    users
+      .addMethod("GET", listUsersIntegration)
+      .addResource("{id}", (user) => user.addMethod("GET", getUserIntegration)),
+  )
+  .build(stack, "MyApi");
+```
+
+Every [RestApiProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApiProps.html) property is available as a fluent setter on the builder.
+
+## Secure Defaults
+
+`createRestApiBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property           | Default | Rationale                                                                           |
+| ------------------ | ------- | ----------------------------------------------------------------------------------- |
+| `accessLogging`    | `true`  | Auto-creates a CloudWatch log group for access logging with structured JSON output. |
+| `tracingEnabled`   | `true`  | Enables X-Ray distributed tracing on the stage.                                     |
+| `loggingLevel`     | `INFO`  | Enables CloudWatch execution logging for all methods.                               |
+| `dataTraceEnabled` | `false` | Prevents sensitive request/response bodies from appearing in logs.                  |
+
+These defaults are guided by the [AWS Well-Architected Serverless Applications Lens](https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-distributed-tracing.html).
+
+The defaults are exported as `REST_API_DEFAULTS` for visibility and testing:
+
+```ts
+import { REST_API_DEFAULTS } from "@composurecdk/apigateway";
+```
+
+### Overriding defaults
+
+```ts
+import { MethodLoggingLevel } from "aws-cdk-lib/aws-apigateway";
+
+const api = createRestApiBuilder()
+  .restApiName("My Service")
+  .accessLogging(false)
+  .deployOptions({ tracingEnabled: false, loggingLevel: MethodLoggingLevel.ERROR })
+  .build(stack, "MyApi");
+```
+
+### Access logging
+
+By default, the builder creates a CloudWatch log group (using `@composurecdk/logs` with its secure defaults) and configures it as the stage's access log destination. The created log group is returned in the build result:
+
+```ts
+const result = createRestApiBuilder()
+  .restApiName("My Service")
+  .addMethod("GET", integration, methodResponse)
+  .build(stack, "MyApi");
+
+result.api; // RestApi
+result.accessLogGroup; // LogGroup | undefined
+```
+
+To provide your own destination instead, set `deployOptions.accessLogDestination` — the auto-created log group is skipped. To disable access logging entirely, set `.accessLogging(false)`.
+
+## Examples
+
+- [LambdaApiStack](../examples/src/lambda-api-app.ts) — REST API backed by a Lambda function, wired with `ref`
+- [MockApiStack](../examples/src/mock-api-app.ts) — CRUD REST API with mock integrations
+- [MultiStackApp](../examples/src/multi-stack-app.ts) — REST API split across stacks via `.withStacks()`
+- [StrategyStackApp](../examples/src/strategy-stack-app.ts) — REST API split across stacks via `.withStackStrategy()`

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import type { RestApiBuilderProps } from "./rest-api-builder.js";
+/**
+ * Secure, AWS-recommended defaults applied to every REST API built with
+ * {@link createRestApiBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ */
+export declare const REST_API_DEFAULTS: Partial<RestApiBuilderProps>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,mBAAmB,CA6B1D,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,34 @@
+import { MethodLoggingLevel } from "aws-cdk-lib/aws-apigateway";
+/**
+ * Secure, AWS-recommended defaults applied to every REST API built with
+ * {@link createRestApiBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ */
+export const REST_API_DEFAULTS = {
+    /**
+     * Automatically create an access log group with structured JSON output.
+     * Access logging provides an audit trail of all API calls for security
+     * monitoring and troubleshooting.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-logging.html
+     */
+    accessLogging: true,
+    deployOptions: {
+        /**
+         * Enable AWS X-Ray tracing on the API Gateway stage.
+         * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-distributed-tracing.html
+         */
+        tracingEnabled: true,
+        /**
+         * Enable CloudWatch execution logging for API Gateway methods.
+         * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-logging.html
+         */
+        loggingLevel: MethodLoggingLevel.INFO,
+        /**
+         * Disable full request/response body logging to prevent sensitive data
+         * from appearing in CloudWatch logs.
+         * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html
+         */
+        dataTraceEnabled: false,
+    },
+};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAiC;IAC7D;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB,aAAa,EAAE;QACb;;;WAGG;QACH,cAAc,EAAE,IAAI;QAEpB;;;WAGG;QACH,YAAY,EAAE,kBAAkB,CAAC,IAAI;QAErC;;;;WAIG;QACH,gBAAgB,EAAE,KAAK;KACxB;CACF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createRestApiBuilder, type RestApiBuilderProps, type RestApiBuilderResult, type IRestApiBuilder, } from "./rest-api-builder.js";
+export { REST_API_DEFAULTS } from "./defaults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createRestApiBuilder, } from "./rest-api-builder.js";
+export { REST_API_DEFAULTS } from "./defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAIrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/resource-builder.d.ts

@@ -0,0 +1,58 @@
+import { type Integration, type IResource, type MethodOptions } from "aws-cdk-lib/aws-apigateway";
+import { type Resolvable } from "@composurecdk/core";
+interface MethodDefinition {
+    httpMethod: string;
+    integration?: Resolvable<Integration>;
+    options?: MethodOptions;
+}
+interface ResourceDefinition {
+    methods: MethodDefinition[];
+    children: Map<string, ResourceDefinition>;
+}
+/**
+ * A declarative builder for defining API Gateway resources and methods.
+ *
+ * `ResourceBuilder` captures a tree of resource paths and HTTP methods as
+ * data. The tree is applied to actual CDK constructs during
+ * {@link RestApiBuilder.build}. Users do not construct `ResourceBuilder`
+ * directly — instances are provided via the {@link IRestApiBuilder.addResource}
+ * callback.
+ *
+ * @example
+ * ```ts
+ * createRestApiBuilder()
+ *   .addResource("users", users => users
+ *     .addMethod("GET", listIntegration)
+ *     .addResource("{id}", user => user
+ *       .addMethod("GET", getIntegration)
+ *       .addMethod("DELETE", deleteIntegration)
+ *     )
+ *   );
+ * ```
+ */
+export declare class ResourceBuilder {
+    /** @internal */
+    readonly definition: ResourceDefinition;
+    /**
+     * Adds an HTTP method to this resource.
+     *
+     * @param httpMethod - The HTTP verb (GET, POST, PUT, DELETE, etc.).
+     * @param integration - The backend integration for this method. Accepts a concrete
+     *   {@link Integration} or a {@link Ref} that resolves to one at build time.
+     * @param options - Additional method configuration such as authorization or method responses.
+     * @returns This builder for chaining.
+     */
+    addMethod(httpMethod: string, integration?: Resolvable<Integration>, options?: MethodOptions): this;
+    /**
+     * Adds a child resource under this resource.
+     *
+     * @param pathPart - The path segment for the child resource (e.g. "users" or "\{id\}").
+     * @param configure - Optional callback to configure the child resource's methods and nested resources.
+     * @returns This builder for chaining.
+     */
+    addResource(pathPart: string, configure?: (resource: ResourceBuilder) => void): this;
+    /** @internal */
+    applyTo(resource: IResource, context?: Record<string, object>): void;
+}
+export {};
+//# sourceMappingURL=resource-builder.d.ts.map

package/dist/resource-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-builder.d.ts","sourceRoot":"","sources":["../src/resource-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE9D,UAAU,gBAAgB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACtC,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,UAAU,kBAAkB;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,eAAe;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAwC;IAE/E;;;;;;;;OAQG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,EACrC,OAAO,CAAC,EAAE,aAAa,GACtB,IAAI;IAKP;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI;IASpF,gBAAgB;IAChB,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,IAAI;CAczE"}

package/dist/resource-builder.js

@@ -0,0 +1,69 @@
+import { resolve } from "@composurecdk/core";
+/**
+ * A declarative builder for defining API Gateway resources and methods.
+ *
+ * `ResourceBuilder` captures a tree of resource paths and HTTP methods as
+ * data. The tree is applied to actual CDK constructs during
+ * {@link RestApiBuilder.build}. Users do not construct `ResourceBuilder`
+ * directly — instances are provided via the {@link IRestApiBuilder.addResource}
+ * callback.
+ *
+ * @example
+ * ```ts
+ * createRestApiBuilder()
+ *   .addResource("users", users => users
+ *     .addMethod("GET", listIntegration)
+ *     .addResource("{id}", user => user
+ *       .addMethod("GET", getIntegration)
+ *       .addMethod("DELETE", deleteIntegration)
+ *     )
+ *   );
+ * ```
+ */
+export class ResourceBuilder {
+    /** @internal */
+    definition = { methods: [], children: new Map() };
+    /**
+     * Adds an HTTP method to this resource.
+     *
+     * @param httpMethod - The HTTP verb (GET, POST, PUT, DELETE, etc.).
+     * @param integration - The backend integration for this method. Accepts a concrete
+     *   {@link Integration} or a {@link Ref} that resolves to one at build time.
+     * @param options - Additional method configuration such as authorization or method responses.
+     * @returns This builder for chaining.
+     */
+    addMethod(httpMethod, integration, options) {
+        this.definition.methods.push({ httpMethod, integration, options });
+        return this;
+    }
+    /**
+     * Adds a child resource under this resource.
+     *
+     * @param pathPart - The path segment for the child resource (e.g. "users" or "\{id\}").
+     * @param configure - Optional callback to configure the child resource's methods and nested resources.
+     * @returns This builder for chaining.
+     */
+    addResource(pathPart, configure) {
+        const child = new ResourceBuilder();
+        if (configure) {
+            configure(child);
+        }
+        this.definition.children.set(pathPart, child.definition);
+        return this;
+    }
+    /** @internal */
+    applyTo(resource, context = {}) {
+        for (const method of this.definition.methods) {
+            const integration = method.integration !== undefined ? resolve(method.integration, context) : undefined;
+            resource.addMethod(method.httpMethod, integration, method.options);
+        }
+        for (const [pathPart, childDef] of this.definition.children) {
+            const childResource = resource.addResource(pathPart);
+            const childBuilder = new ResourceBuilder();
+            childBuilder.definition.methods = childDef.methods;
+            childDef.children.forEach((v, k) => childBuilder.definition.children.set(k, v));
+            childBuilder.applyTo(childResource, context);
+        }
+    }
+}
+//# sourceMappingURL=resource-builder.js.map

package/dist/resource-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-builder.js","sourceRoot":"","sources":["../src/resource-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAmB,MAAM,oBAAoB,CAAC;AAa9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,eAAe;IAC1B,gBAAgB;IACP,UAAU,GAAuB,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAE/E;;;;;;;;OAQG;IACH,SAAS,CACP,UAAkB,EAClB,WAAqC,EACrC,OAAuB;QAEvB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,QAAgB,EAAE,SAA+C;QAC3E,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,SAAS,EAAE,CAAC;YACd,SAAS,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gBAAgB;IAChB,OAAO,CAAC,QAAmB,EAAE,UAAkC,EAAE;QAC/D,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YAC7C,MAAM,WAAW,GACf,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACtF,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACrE,CAAC;QACD,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;YAC5D,MAAM,aAAa,GAAG,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YACrD,MAAM,YAAY,GAAG,IAAI,eAAe,EAAE,CAAC;YAC3C,YAAY,CAAC,UAAU,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;YACnD,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAChF,YAAY,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF"}

package/dist/rest-api-builder.d.ts

@@ -0,0 +1,126 @@
+import { type Integration, type MethodOptions, RestApi, type RestApiProps } from "aws-cdk-lib/aws-apigateway";
+import { type LogGroup } from "aws-cdk-lib/aws-logs";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { ResourceBuilder } from "./resource-builder.js";
+/**
+ * Configuration properties for the REST API builder.
+ *
+ * Extends the CDK {@link RestApiProps} with additional builder-specific options.
+ */
+export interface RestApiBuilderProps extends RestApiProps {
+    /**
+     * Whether to automatically create a CloudWatch log group for access logging.
+     *
+     * When `true`, the builder creates a log group using
+     * {@link createLogGroupBuilder} (with its secure defaults) and configures it
+     * as the stage's access log destination with JSON-formatted output. The
+     * created log group is returned in the build result as `accessLogGroup`.
+     *
+     * When `false`, no access log group is created. You can still provide your
+     * own destination via `deployOptions.accessLogDestination`.
+     *
+     * This setting is ignored when `deployOptions.accessLogDestination` is
+     * provided — the user-supplied destination takes precedence.
+     */
+    accessLogging?: boolean;
+}
+/**
+ * The build output of a {@link IRestApiBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface RestApiBuilderResult {
+    /** The REST API construct created by the builder. */
+    api: RestApi;
+    /**
+     * The CloudWatch log group created for access logging, or `undefined` if
+     * access logging was disabled or the user provided their own destination.
+     */
+    accessLogGroup?: LogGroup;
+}
+/**
+ * A fluent builder for configuring and creating an API Gateway REST API.
+ *
+ * Configuration properties from CDK {@link RestApiProps} are exposed as
+ * overloaded getter/setter methods via the builder proxy. The resource tree
+ * (paths and HTTP methods) is defined using {@link addResource} and
+ * {@link addMethod}, which accept the same arguments as their CDK equivalents.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * a REST API with the configured properties and resource tree, and returns
+ * a {@link RestApiBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const api = createRestApiBuilder()
+ *   .restApiName("My Service")
+ *   .description("Public API")
+ *   .addResource("users", users => users
+ *     .addMethod("GET", listUsersIntegration)
+ *     .addResource("{id}", user => user
+ *       .addMethod("GET", getUserIntegration)
+ *     )
+ *   );
+ * ```
+ */
+export type IRestApiBuilder = IBuilder<RestApiBuilderProps, RestApiBuilder>;
+declare class RestApiBuilder implements Lifecycle<RestApiBuilderResult> {
+    props: Partial<RestApiBuilderProps>;
+    private readonly root;
+    /**
+     * Adds an HTTP method to the API root resource (`/`).
+     *
+     * @param httpMethod - The HTTP verb (GET, POST, PUT, DELETE, etc.).
+     * @param integration - The backend integration for this method. Accepts a concrete
+     *   {@link Integration} or a {@link Ref} that resolves to one at build time.
+     * @param options - Additional method configuration such as authorization or method responses.
+     * @returns This builder for chaining.
+     */
+    addMethod(httpMethod: string, integration?: Resolvable<Integration>, options?: MethodOptions): this;
+    /**
+     * Adds a child resource under the API root resource (`/`).
+     *
+     * @param pathPart - The path segment for the resource (e.g. "users" or "\{id\}").
+     * @param configure - Optional callback to configure the resource's methods and nested resources.
+     * @returns This builder for chaining.
+     */
+    addResource(pathPart: string, configure?: (resource: ResourceBuilder) => void): this;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): RestApiBuilderResult;
+}
+/**
+ * Creates a new {@link IRestApiBuilder} for configuring an API Gateway REST API.
+ *
+ * This is the entry point for defining a REST API component. The returned
+ * builder exposes every {@link RestApiProps} property as a fluent setter/getter,
+ * plus {@link IRestApiBuilder.addResource | addResource} and
+ * {@link IRestApiBuilder.addMethod | addMethod} for defining the resource tree.
+ * It implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an API Gateway REST API.
+ *
+ * @example
+ * ```ts
+ * const api = createRestApiBuilder()
+ *   .restApiName("My Service")
+ *   .description("Public API")
+ *   .addResource("users", users => users
+ *     .addMethod("GET", listUsersIntegration)
+ *     .addResource("{id}", user => user
+ *       .addMethod("GET", getUserIntegration)
+ *     )
+ *   );
+ *
+ * // Use standalone:
+ * const result = api.build(stack, "MyApi");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { api, handler: createFunctionBuilder() },
+ *   { api: ["handler"], handler: [] },
+ * );
+ * ```
+ */
+export declare function createRestApiBuilder(): IRestApiBuilder;
+export {};
+//# sourceMappingURL=rest-api-builder.d.ts.map

package/dist/rest-api-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api-builder.d.ts","sourceRoot":"","sources":["../src/rest-api-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,aAAa,EAClB,OAAO,EACP,KAAK,YAAY,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE7F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,GAAG,EAAE,OAAO,CAAC;IAEb;;;OAGG;IACH,cAAc,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;AAE5E,cAAM,cAAe,YAAW,SAAS,CAAC,oBAAoB,CAAC;IAC7D,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAM;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAE9C;;;;;;;;OAQG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,EACrC,OAAO,CAAC,EAAE,aAAa,GACtB,IAAI;IAKP;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI;IAKpF,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,oBAAoB;CA8B7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,CAEtD"}

package/dist/rest-api-builder.js

@@ -0,0 +1,95 @@
+import { AccessLogFormat, LogGroupLogDestination, RestApi, } from "aws-cdk-lib/aws-apigateway";
+import { Builder } from "@composurecdk/core";
+import { createLogGroupBuilder } from "@composurecdk/logs";
+import { ResourceBuilder } from "./resource-builder.js";
+import { REST_API_DEFAULTS } from "./defaults.js";
+class RestApiBuilder {
+    props = {};
+    root = new ResourceBuilder();
+    /**
+     * Adds an HTTP method to the API root resource (`/`).
+     *
+     * @param httpMethod - The HTTP verb (GET, POST, PUT, DELETE, etc.).
+     * @param integration - The backend integration for this method. Accepts a concrete
+     *   {@link Integration} or a {@link Ref} that resolves to one at build time.
+     * @param options - Additional method configuration such as authorization or method responses.
+     * @returns This builder for chaining.
+     */
+    addMethod(httpMethod, integration, options) {
+        this.root.addMethod(httpMethod, integration, options);
+        return this;
+    }
+    /**
+     * Adds a child resource under the API root resource (`/`).
+     *
+     * @param pathPart - The path segment for the resource (e.g. "users" or "\{id\}").
+     * @param configure - Optional callback to configure the resource's methods and nested resources.
+     * @returns This builder for chaining.
+     */
+    addResource(pathPart, configure) {
+        this.root.addResource(pathPart, configure);
+        return this;
+    }
+    build(scope, id, context) {
+        const { accessLogging, ...restApiProps } = this.props;
+        const userDeployOptions = restApiProps.deployOptions ?? {};
+        const autoAccessLog = (accessLogging ?? REST_API_DEFAULTS.accessLogging) && !userDeployOptions.accessLogDestination;
+        let accessLogGroup;
+        let accessLogProps = {};
+        if (autoAccessLog) {
+            accessLogGroup = createLogGroupBuilder().build(scope, `${id}AccessLogs`).logGroup;
+            accessLogProps = {
+                accessLogDestination: new LogGroupLogDestination(accessLogGroup),
+                accessLogFormat: AccessLogFormat.jsonWithStandardFields(),
+            };
+        }
+        const mergedProps = {
+            ...restApiProps,
+            deployOptions: {
+                ...REST_API_DEFAULTS.deployOptions,
+                ...accessLogProps,
+                ...userDeployOptions,
+            },
+        };
+        const api = new RestApi(scope, id, mergedProps);
+        this.root.applyTo(api.root, context ?? {});
+        return { api, accessLogGroup };
+    }
+}
+/**
+ * Creates a new {@link IRestApiBuilder} for configuring an API Gateway REST API.
+ *
+ * This is the entry point for defining a REST API component. The returned
+ * builder exposes every {@link RestApiProps} property as a fluent setter/getter,
+ * plus {@link IRestApiBuilder.addResource | addResource} and
+ * {@link IRestApiBuilder.addMethod | addMethod} for defining the resource tree.
+ * It implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an API Gateway REST API.
+ *
+ * @example
+ * ```ts
+ * const api = createRestApiBuilder()
+ *   .restApiName("My Service")
+ *   .description("Public API")
+ *   .addResource("users", users => users
+ *     .addMethod("GET", listUsersIntegration)
+ *     .addResource("{id}", user => user
+ *       .addMethod("GET", getUserIntegration)
+ *     )
+ *   );
+ *
+ * // Use standalone:
+ * const result = api.build(stack, "MyApi");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { api, handler: createFunctionBuilder() },
+ *   { api: ["handler"], handler: [] },
+ * );
+ * ```
+ */
+export function createRestApiBuilder() {
+    return Builder(RestApiBuilder);
+}
+//# sourceMappingURL=rest-api-builder.js.map

package/dist/rest-api-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api-builder.js","sourceRoot":"","sources":["../src/rest-api-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAEf,sBAAsB,EAEtB,OAAO,GAER,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,OAAO,EAAkD,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAoElD,MAAM,cAAc;IAClB,KAAK,GAAiC,EAAE,CAAC;IACxB,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;IAE9C;;;;;;;;OAQG;IACH,SAAS,CACP,UAAkB,EAClB,WAAqC,EACrC,OAAuB;QAEvB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,QAAgB,EAAE,SAA+C;QAC3E,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,EAAE,aAAa,EAAE,GAAG,YAAY,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACtD,MAAM,iBAAiB,GAAG,YAAY,CAAC,aAAa,IAAI,EAAE,CAAC;QAC3D,MAAM,aAAa,GACjB,CAAC,aAAa,IAAI,iBAAiB,CAAC,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,oBAAoB,CAAC;QAEhG,IAAI,cAAoC,CAAC;QACzC,IAAI,cAAc,GAAG,EAAE,CAAC;QAExB,IAAI,aAAa,EAAE,CAAC;YAClB,cAAc,GAAG,qBAAqB,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC;YAClF,cAAc,GAAG;gBACf,oBAAoB,EAAE,IAAI,sBAAsB,CAAC,cAAc,CAAC;gBAChE,eAAe,EAAE,eAAe,CAAC,sBAAsB,EAAE;aAC1D,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,YAAY;YACf,aAAa,EAAE;gBACb,GAAG,iBAAiB,CAAC,aAAa;gBAClC,GAAG,cAAc;gBACjB,GAAG,iBAAiB;aACrB;SACc,CAAC;QAElB,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QAC3C,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAsC,cAAc,CAAC,CAAC;AACtE,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@composurecdk/apigateway",
+  "version": "0.1.0",
+  "description": "Composable API Gateway REST API builder with well-architected defaults",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/core": "^0.1.0",
+    "@composurecdk/logs": "^0.1.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "aws-cdk-lib": "^2.245.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}