@composurecdk/apigateway 0.1.3 → 0.3.2

package/README.md

@@ -69,6 +69,99 @@ 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)`.
 
+## Recommended Alarms
+
+Both builders create [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
+
+| Alarm         | Metric                    | Default threshold | Created when |
+| ------------- | ------------------------- | ----------------- | ------------ |
+| `clientError` | 4XXError (Average, 1 min) | > 0.05 (5%)       | Always       |
+| `serverError` | 5XXError (Average, 1 min) | > 0.05 (5%)       | Always       |
+| `latency`     | Latency (p90, 1 min)      | >= 2500ms         | Always       |
+
+Alarm metrics include both `ApiName` and `Stage` dimensions, targeting the deployment stage created by the builder.
+
+The defaults are exported as `REST_API_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { REST_API_ALARM_DEFAULTS } from "@composurecdk/apigateway";
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+const api = createRestApiBuilder()
+  .restApiName("My Service")
+  .addMethod("GET", integration, methodResponse)
+  .recommendedAlarms({
+    serverError: { threshold: 0.1 }, // 10% error rate
+    latency: { threshold: 1000 }, // 1 second p90
+    clientError: { evaluationPeriods: 3 }, // fewer evaluation periods
+  });
+```
+
+### Disabling alarms
+
+Disable all recommended alarms:
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+```
+
+Disable individual alarms:
+
+```ts
+builder.recommendedAlarms({ clientError: false, latency: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to `RestApiBase`, so the metric factory has access to the API's properties.
+
+```ts
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+
+const api = createRestApiBuilder()
+  .restApiName("My Service")
+  .addMethod("GET", integration, methodResponse)
+  .addAlarm("integrationLatency", (alarm) =>
+    alarm
+      .metric(
+        (api) =>
+          new Metric({
+            namespace: "AWS/ApiGateway",
+            metricName: "IntegrationLatency",
+            dimensionsMap: {
+              ApiName: api.restApiName,
+              Stage: api.deploymentStage.stageName,
+            },
+            statistic: "p90",
+            period: Duration.minutes(1),
+          }),
+      )
+      .threshold(2000)
+      .greaterThanOrEqual()
+      .description("Integration latency is elevated"),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = api.build(stack, "MyApi");
+
+const alertTopic = new Topic(stack, "AlertTopic");
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
 ## Examples
 
 - [LambdaApiStack](../examples/src/lambda-api-app.ts) — REST API backed by a Lambda function, wired with `ref`

package/dist/alarm-config.d.ts

@@ -0,0 +1,47 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an API Gateway REST API.
+ * All applicable alarms are enabled by default with AWS-recommended thresholds.
+ * Set individual alarms to `false` to disable them, or provide an
+ * {@link AlarmConfig} to tune thresholds.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+ */
+export interface RestApiAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when the API returns an elevated rate of client-side errors
+     * (4XX HTTP status codes).
+     *
+     * Metric: `AWS/ApiGateway 4XXError`, statistic Average, period 1 minute.
+     * Default threshold: > 0.05 (5% of requests).
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+     */
+    clientError?: AlarmConfig | false;
+    /**
+     * Alarm when the API returns an elevated rate of server-side errors
+     * (5XX HTTP status codes).
+     *
+     * Metric: `AWS/ApiGateway 5XXError`, statistic Average, period 1 minute.
+     * Default threshold: > 0.05 (5% of requests).
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+     */
+    serverError?: AlarmConfig | false;
+    /**
+     * Alarm when API latency is elevated.
+     *
+     * Metric: `AWS/ApiGateway Latency`, statistic p90, period 1 minute.
+     * Default threshold: >= 2500ms.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+     */
+    latency?: AlarmConfig | false;
+}
+//# sourceMappingURL=alarm-config.d.ts.map

package/dist/alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAElC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAElC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC/B"}

package/dist/alarm-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=alarm-config.js.map

package/dist/alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.js","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":""}

package/dist/alarm-defaults.d.ts

@@ -0,0 +1,15 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+interface RestApiAlarmDefaults {
+    enabled: true;
+    clientError: Required<AlarmConfig>;
+    serverError: Required<AlarmConfig>;
+    latency: Required<AlarmConfig>;
+}
+/**
+ * AWS-recommended default alarm configuration for API Gateway REST APIs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+ */
+export declare const REST_API_ALARM_DEFAULTS: RestApiAlarmDefaults;
+export {};
+//# sourceMappingURL=alarm-defaults.d.ts.map

package/dist/alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,UAAU,oBAAoB;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACnC,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACnC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,oBAsCrC,CAAC"}

package/dist/alarm-defaults.js

@@ -0,0 +1,43 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * AWS-recommended default alarm configuration for API Gateway REST APIs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+ */
+export const REST_API_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * Elevated 4XX error rate indicates client-side issues such as
+     * authorization failures, invalid parameters, or throttling.
+     * Threshold 0.05 = 5% of requests.
+     */
+    clientError: {
+        threshold: 0.05,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 5,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * Elevated 5XX error rate indicates server-side issues such as
+     * backend failures or integration errors.
+     * Threshold 0.05 = 5% of requests.
+     */
+    serverError: {
+        threshold: 0.05,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 3,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * Elevated p90 latency indicates slow API responses that may
+     * impact user experience or trigger downstream timeouts.
+     * Default 2500ms threshold per AWS recommendation.
+     */
+    latency: {
+        threshold: 2500,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 5,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=alarm-defaults.js.map

package/dist/alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAU9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAyB;IAC3D,OAAO,EAAE,IAAI;IAEb;;;;OAIG;IACH,WAAW,EAAE;QACX,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,WAAW,EAAE;QACX,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,OAAO,EAAE;QACP,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/builder-common.d.ts

@@ -0,0 +1,68 @@
+import type { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { RestApiBase } from "aws-cdk-lib/aws-apigateway";
+import type { LogGroup } from "aws-cdk-lib/aws-logs";
+import type { RestApiAlarmConfig } from "./alarm-config.js";
+/**
+ * Builder-specific properties shared by both {@link RestApiBuilderProps}
+ * and {@link SpecRestApiBuilderProps}.
+ */
+export interface RestApiBuilderPropsBase {
+    /**
+     * 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;
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates recommended alarms for client error rate,
+     * server error rate, and latency. Individual alarms can be customized or
+     * disabled. Set to `false` to disable all alarms.
+     *
+     * No alarm actions are configured by default since notification
+     * methods are user-specific. Access alarms from the build result
+     * or use an `afterBuild` hook to apply actions.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+     */
+    recommendedAlarms?: RestApiAlarmConfig | false;
+}
+/**
+ * Build result properties shared by both {@link RestApiBuilderResult}
+ * and {@link SpecRestApiBuilderResult}.
+ *
+ * @typeParam T - The concrete REST API type (`RestApi` or `SpecRestApi`).
+ */
+export interface RestApiBuilderResultBase<T extends RestApiBase> {
+    /** The REST API construct created by the builder. */
+    api: T;
+    /**
+     * The CloudWatch log group created for access logging, or `undefined` if
+     * access logging was disabled or the user provided their own destination.
+     */
+    accessLogGroup?: LogGroup;
+    /**
+     * CloudWatch alarms created for the API, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via `addAlarm()`. Access individual alarms by key
+     * (e.g., `result.alarms.serverError`).
+     *
+     * No alarm actions are configured — apply them via the result or an
+     * `afterBuild` hook.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+     */
+    alarms: Record<string, Alarm>;
+}
+//# sourceMappingURL=builder-common.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder-common.d.ts","sourceRoot":"","sources":["../src/builder-common.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAAC;CAChD;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,WAAW;IAC7D,qDAAqD;IACrD,GAAG,EAAE,CAAC,CAAC;IAEP;;;OAGG;IACH,cAAc,CAAC,EAAE,QAAQ,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B"}

package/dist/builder-common.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=builder-common.js.map

package/dist/builder-common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-common.js","sourceRoot":"","sources":["../src/builder-common.ts"],"names":[],"mappings":""}

package/dist/defaults.d.ts

@@ -1,8 +1,22 @@
+import { type StageOptions } from "aws-cdk-lib/aws-apigateway";
 import type { RestApiBuilderProps } from "./rest-api-builder.js";
+import type { SpecRestApiBuilderProps } from "./spec-rest-api-builder.js";
+/**
+ * Secure, AWS-recommended deploy-stage defaults shared by all API Gateway
+ * builders. Each property can be individually overridden via the builder's
+ * fluent API.
+ */
+export declare const DEPLOY_OPTIONS_DEFAULTS: StageOptions;
 /**
  * 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>;
+/**
+ * Secure, AWS-recommended defaults applied to every spec-driven REST API
+ * built with {@link createSpecRestApiBuilder}. Each property can be
+ * individually overridden via the builder's fluent API.
+ */
+export declare const SPEC_REST_API_DEFAULTS: Partial<SpecRestApiBuilderProps>;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,YAmBrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,mBAAmB,CAU1D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,OAAO,CAAC,uBAAuB,CAQnE,CAAC"}

package/dist/defaults.js

@@ -1,4 +1,27 @@
 import { MethodLoggingLevel } from "aws-cdk-lib/aws-apigateway";
+/**
+ * Secure, AWS-recommended deploy-stage defaults shared by all API Gateway
+ * builders. Each property can be individually overridden via the builder's
+ * fluent API.
+ */
+export const DEPLOY_OPTIONS_DEFAULTS = {
+    /**
+     * 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,
+};
 /**
  * Secure, AWS-recommended defaults applied to every REST API built with
  * {@link createRestApiBuilder}. Each property can be individually overridden
@@ -12,23 +35,19 @@ export const REST_API_DEFAULTS = {
      * @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,
-    },
+    deployOptions: DEPLOY_OPTIONS_DEFAULTS,
+};
+/**
+ * Secure, AWS-recommended defaults applied to every spec-driven REST API
+ * built with {@link createSpecRestApiBuilder}. Each property can be
+ * individually overridden via the builder's fluent API.
+ */
+export const SPEC_REST_API_DEFAULTS = {
+    /**
+     * Automatically create an access log group with structured JSON output.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-logging.html
+     */
+    accessLogging: true,
+    deployOptions: DEPLOY_OPTIONS_DEFAULTS,
 };
 //# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -1 +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"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAqB,MAAM,4BAA4B,CAAC;AAInF;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAiB;IACnD;;;OAGG;IACH,cAAc,EAAE,IAAI;IAEpB;;;OAGG;IACH,YAAY,EAAE,kBAAkB,CAAC,IAAI;IAErC;;;;OAIG;IACH,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAiC;IAC7D;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB,aAAa,EAAE,uBAAuB;CACvC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAqC;IACtE;;;OAGG;IACH,aAAa,EAAE,IAAI;IAEnB,aAAa,EAAE,uBAAuB;CACvC,CAAC"}

package/dist/deploy-options.d.ts

@@ -0,0 +1,17 @@
+import { type StageOptions } from "aws-cdk-lib/aws-apigateway";
+import { type LogGroup } from "aws-cdk-lib/aws-logs";
+import { type IConstruct } from "constructs";
+interface AccessLoggingResult {
+    accessLogGroup?: LogGroup;
+    deployOptions: StageOptions;
+}
+/**
+ * Resolves access logging configuration and merges deploy options with
+ * the provided defaults. Shared by {@link RestApiBuilder} and
+ * {@link SpecRestApiBuilder}.
+ *
+ * @internal
+ */
+export declare function resolveDeployOptions(scope: IConstruct, id: string, accessLogging: boolean | undefined, defaults: StageOptions, userDeployOptions: StageOptions): AccessLoggingResult;
+export {};
+//# sourceMappingURL=deploy-options.d.ts.map

package/dist/deploy-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-options.d.ts","sourceRoot":"","sources":["../src/deploy-options.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,UAAU,mBAAmB;IAC3B,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC1B,aAAa,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,OAAO,GAAG,SAAS,EAClC,QAAQ,EAAE,YAAY,EACtB,iBAAiB,EAAE,YAAY,GAC9B,mBAAmB,CAsBrB"}

package/dist/deploy-options.js

@@ -0,0 +1,30 @@
+import { AccessLogFormat, LogGroupLogDestination, } from "aws-cdk-lib/aws-apigateway";
+import { createLogGroupBuilder } from "@composurecdk/logs";
+/**
+ * Resolves access logging configuration and merges deploy options with
+ * the provided defaults. Shared by {@link RestApiBuilder} and
+ * {@link SpecRestApiBuilder}.
+ *
+ * @internal
+ */
+export function resolveDeployOptions(scope, id, accessLogging, defaults, userDeployOptions) {
+    const autoAccessLog = (accessLogging ?? true) && !userDeployOptions.accessLogDestination;
+    let accessLogGroup;
+    let accessLogProps = {};
+    if (autoAccessLog) {
+        accessLogGroup = createLogGroupBuilder().build(scope, `${id}AccessLogs`).logGroup;
+        accessLogProps = {
+            accessLogDestination: new LogGroupLogDestination(accessLogGroup),
+            accessLogFormat: AccessLogFormat.jsonWithStandardFields(),
+        };
+    }
+    return {
+        accessLogGroup,
+        deployOptions: {
+            ...defaults,
+            ...accessLogProps,
+            ...userDeployOptions,
+        },
+    };
+}
+//# sourceMappingURL=deploy-options.js.map

package/dist/deploy-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-options.js","sourceRoot":"","sources":["../src/deploy-options.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,sBAAsB,GAEvB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAO3D;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAiB,EACjB,EAAU,EACV,aAAkC,EAClC,QAAsB,EACtB,iBAA+B;IAE/B,MAAM,aAAa,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,oBAAoB,CAAC;IAEzF,IAAI,cAAoC,CAAC;IACzC,IAAI,cAAc,GAAG,EAAE,CAAC;IAExB,IAAI,aAAa,EAAE,CAAC;QAClB,cAAc,GAAG,qBAAqB,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC;QAClF,cAAc,GAAG;YACf,oBAAoB,EAAE,IAAI,sBAAsB,CAAC,cAAc,CAAC;YAChE,eAAe,EAAE,eAAe,CAAC,sBAAsB,EAAE;SAC1D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,cAAc;QACd,aAAa,EAAE;YACb,GAAG,QAAQ;YACX,GAAG,cAAc;YACjB,GAAG,iBAAiB;SACrB;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export { createRestApiBuilder, type RestApiBuilderResult, type IRestApiBuilder, } from "./rest-api-builder.js";
-export { REST_API_DEFAULTS } from "./defaults.js";
+export { createSpecRestApiBuilder, type SpecRestApiBuilderResult, type ISpecRestApiBuilder, } from "./spec-rest-api-builder.js";
+export { REST_API_DEFAULTS, SPEC_REST_API_DEFAULTS } from "./defaults.js";
+export { type RestApiAlarmConfig } from "./alarm-config.js";
+export { REST_API_ALARM_DEFAULTS } from "./alarm-defaults.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
 export { createRestApiBuilder, } from "./rest-api-builder.js";
-export { REST_API_DEFAULTS } from "./defaults.js";
+export { createSpecRestApiBuilder, } from "./spec-rest-api-builder.js";
+export { REST_API_DEFAULTS, SPEC_REST_API_DEFAULTS } from "./defaults.js";
+export { REST_API_ALARM_DEFAULTS } from "./alarm-defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,GAGzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,26 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { RestApiBase } from "aws-cdk-lib/aws-apigateway";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { RestApiAlarmConfig } from "./alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an API Gateway REST API.
+ */
+export declare function resolveRestApiAlarmDefinitions(api: RestApiBase, config: RestApiAlarmConfig | undefined): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an API Gateway REST API,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param api - The REST API to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+ */
+export declare function createRestApiAlarms(scope: IConstruct, id: string, api: RestApiBase, config: RestApiAlarmConfig | false | undefined, customAlarms?: AlarmDefinitionBuilder<RestApiBase>[]): Record<string, Alarm>;
+//# sourceMappingURL=rest-api-alarms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api-alarms.d.ts","sourceRoot":"","sources":["../src/rest-api-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAuB5D;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,kBAAkB,GAAG,SAAS,GACrC,eAAe,EAAE,CAgDnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,kBAAkB,GAAG,KAAK,GAAG,SAAS,EAC9C,YAAY,GAAE,sBAAsB,CAAC,WAAW,CAAC,EAAO,GACvD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/rest-api-alarms.js

@@ -0,0 +1,95 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { REST_API_ALARM_DEFAULTS } from "./alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Creates an API Gateway metric with the correct namespace and
+ * dimensions (ApiName + Stage).
+ */
+function apiMetric(api, metricName, statistic) {
+    return new Metric({
+        namespace: "AWS/ApiGateway",
+        metricName,
+        dimensionsMap: {
+            ApiName: api.restApiName,
+            Stage: api.deploymentStage.stageName,
+        },
+        statistic,
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an API Gateway REST API.
+ */
+export function resolveRestApiAlarmDefinitions(api, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.clientError !== false) {
+        const cfg = resolveAlarmConfig(config?.clientError, REST_API_ALARM_DEFAULTS.clientError);
+        definitions.push({
+            key: "clientError",
+            metric: apiMetric(api, "4XXError", Stats.AVERAGE),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `REST API client error rate is elevated. Threshold: > ${String(cfg.threshold * 100)}% of requests in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.serverError !== false) {
+        const cfg = resolveAlarmConfig(config?.serverError, REST_API_ALARM_DEFAULTS.serverError);
+        definitions.push({
+            key: "serverError",
+            metric: apiMetric(api, "5XXError", Stats.AVERAGE),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `REST API server error rate is elevated. Threshold: > ${String(cfg.threshold * 100)}% of requests in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.latency !== false) {
+        const cfg = resolveAlarmConfig(config?.latency, REST_API_ALARM_DEFAULTS.latency);
+        definitions.push({
+            key: "latency",
+            metric: apiMetric(api, "Latency", Stats.percentile(90)),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `REST API p90 latency is elevated. Threshold: >= ${String(cfg.threshold)}ms in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an API Gateway REST API,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param api - The REST API to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ApiGateway
+ */
+export function createRestApiAlarms(scope, id, api, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? REST_API_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveRestApiAlarmDefinitions(api, config);
+    const custom = customAlarms.map((b) => b.resolve(api));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=rest-api-alarms.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api-alarms.js","sourceRoot":"","sources":["../src/rest-api-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAc,kBAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAI3F,OAAO,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1C,MAAM,mBAAmB,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC;AAE1E;;;GAGG;AACH,SAAS,SAAS,CAAC,GAAgB,EAAE,UAAkB,EAAE,SAAiB;IACxE,OAAO,IAAI,MAAM,CAAC;QAChB,SAAS,EAAE,gBAAgB;QAC3B,UAAU;QACV,aAAa,EAAE;YACb,OAAO,EAAE,GAAG,CAAC,WAAW;YACxB,KAAK,EAAE,GAAG,CAAC,eAAe,CAAC,SAAS;SACrC;QACD,SAAS;QACT,MAAM,EAAE,aAAa;KACtB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,GAAgB,EAChB,MAAsC;IAEtC,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,WAAW,GAAsB,EAAE,CAAC;IAE1C,IAAI,MAAM,EAAE,WAAW,KAAK,KAAK,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;QACzF,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,aAAa;YAClB,MAAM,EAAE,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC;YACjD,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,kBAAkB,CAAC,sBAAsB;YAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EAAE,wDAAwD,MAAM,CAAC,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,oBAAoB,mBAAmB,GAAG;SAC3I,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAAM,EAAE,WAAW,KAAK,KAAK,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;QACzF,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,aAAa;YAClB,MAAM,EAAE,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC;YACjD,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,kBAAkB,CAAC,sBAAsB;YAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EAAE,wDAAwD,MAAM,CAAC,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,oBAAoB,mBAAmB,GAAG;SAC3I,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC;QACjF,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,SAAS;YACd,MAAM,EAAE,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACvD,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,kBAAkB,CAAC,kCAAkC;YACzE,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EAAE,mDAAmD,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,mBAAmB,GAAG;SACrH,CAAC,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAiB,EACjB,EAAU,EACV,GAAgB,EAChB,MAA8C,EAC9C,eAAsD,EAAE;IAExD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,uBAAuB,CAAC,OAAO,CAAC;IACnE,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,MAAM,WAAW,GAAG,8BAA8B,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAEvD,OAAO,YAAY,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}

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

@@ -1,43 +1,21 @@
-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 Integration, type MethodOptions, RestApi, type RestApiBase, type RestApiProps } from "aws-cdk-lib/aws-apigateway";
 import { type IConstruct } from "constructs";
 import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { RestApiBuilderPropsBase, RestApiBuilderResultBase } from "./builder-common.js";
 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;
+export interface RestApiBuilderProps extends RestApiProps, RestApiBuilderPropsBase {
 }
 /**
  * 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;
-}
+export type RestApiBuilderResult = RestApiBuilderResultBase<RestApi>;
 /**
  * A fluent builder for configuring and creating an API Gateway REST API.
  *
@@ -68,6 +46,8 @@ export type IRestApiBuilder = IBuilder<RestApiBuilderProps, RestApiBuilder>;
 declare class RestApiBuilder implements Lifecycle<RestApiBuilderResult> {
     props: Partial<RestApiBuilderProps>;
     private readonly root;
+    private readonly customAlarms;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<RestApiBase>) => AlarmDefinitionBuilder<RestApiBase>): this;
     /**
      * Adds an HTTP method to the API root resource (`/`).
      *

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

@@ -1 +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"}
+{"version":3,"file":"rest-api-builder.d.ts","sourceRoot":"","sources":["../src/rest-api-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,OAAO,EACP,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAG7F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY,EAAE,uBAAuB;CAAG;AAErF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;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;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6C;IAE1E,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,WAAW,CAAC,KAAK,sBAAsB,CAAC,WAAW,CAAC,GAC7F,IAAI;IAKP;;;;;;;;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;CAoB7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,CAEtD"}

package/dist/rest-api-builder.js

@@ -1,11 +1,18 @@
-import { AccessLogFormat, LogGroupLogDestination, RestApi, } from "aws-cdk-lib/aws-apigateway";
+import { RestApi, } from "aws-cdk-lib/aws-apigateway";
 import { Builder } from "@composurecdk/core";
-import { createLogGroupBuilder } from "@composurecdk/logs";
-import { ResourceBuilder } from "./resource-builder.js";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import { REST_API_DEFAULTS } from "./defaults.js";
+import { resolveDeployOptions } from "./deploy-options.js";
+import { ResourceBuilder } from "./resource-builder.js";
+import { createRestApiAlarms } from "./rest-api-alarms.js";
 class RestApiBuilder {
     props = {};
     root = new ResourceBuilder();
+    customAlarms = [];
+    addAlarm(key, configure) {
+        this.customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
     /**
      * Adds an HTTP method to the API root resource (`/`).
      *
@@ -31,29 +38,15 @@ class RestApiBuilder {
         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 = {
+        const { accessLogging, recommendedAlarms: alarmConfig, ...restApiProps } = this.props;
+        const { accessLogGroup, deployOptions } = resolveDeployOptions(scope, id, accessLogging, REST_API_DEFAULTS.deployOptions ?? {}, restApiProps.deployOptions ?? {});
+        const api = new RestApi(scope, id, {
             ...restApiProps,
-            deployOptions: {
-                ...REST_API_DEFAULTS.deployOptions,
-                ...accessLogProps,
-                ...userDeployOptions,
-            },
-        };
-        const api = new RestApi(scope, id, mergedProps);
+            deployOptions,
+        });
         this.root.applyTo(api.root, context ?? {});
-        return { api, accessLogGroup };
+        const alarms = createRestApiAlarms(scope, id, api, alarmConfig, this.customAlarms);
+        return { api, accessLogGroup, alarms };
     }
 }
 /**

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

@@ -1 +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"}
+{"version":3,"file":"rest-api-builder.js","sourceRoot":"","sources":["../src/rest-api-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,OAAO,GAGR,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,OAAO,EAAkD,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AA2C3D,MAAM,cAAc;IAClB,KAAK,GAAiC,EAAE,CAAC;IACxB,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;IAC7B,YAAY,GAA0C,EAAE,CAAC;IAE1E,QAAQ,CACN,GAAW,EACX,SAA8F;QAE9F,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAc,GAAG,CAAC,CAAC,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;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,iBAAiB,EAAE,WAAW,EAAE,GAAG,YAAY,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACtF,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,oBAAoB,CAC5D,KAAK,EACL,EAAE,EACF,aAAa,EACb,iBAAiB,CAAC,aAAa,IAAI,EAAE,EACrC,YAAY,CAAC,aAAa,IAAI,EAAE,CACjC,CAAC;QAEF,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE;YACjC,GAAG,YAAY;YACf,aAAa;SACE,CAAC,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QAE3C,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAEnF,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAsC,cAAc,CAAC,CAAC;AACtE,CAAC"}

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

@@ -0,0 +1,87 @@
+import { type RestApiBase, SpecRestApi, type SpecRestApiProps } from "aws-cdk-lib/aws-apigateway";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { RestApiBuilderPropsBase, RestApiBuilderResultBase } from "./builder-common.js";
+/**
+ * Configuration properties for the spec-driven REST API builder.
+ *
+ * Extends the CDK {@link SpecRestApiProps} with additional builder-specific
+ * options.
+ */
+export interface SpecRestApiBuilderProps extends SpecRestApiProps, RestApiBuilderPropsBase {
+}
+/**
+ * The build output of a {@link ISpecRestApiBuilder}. Contains the CDK
+ * constructs created during {@link Lifecycle.build}, keyed by role.
+ */
+export type SpecRestApiBuilderResult = RestApiBuilderResultBase<SpecRestApi>;
+/**
+ * A fluent builder for configuring and creating an API Gateway REST API from
+ * an OpenAPI specification.
+ *
+ * Configuration properties from CDK {@link SpecRestApiProps} are exposed as
+ * overloaded getter/setter methods via the builder proxy. The API structure
+ * is defined entirely by the OpenAPI specification provided via
+ * {@link apiDefinition}.
+ *
+ * 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 {@link SpecRestApi} with the configured properties and returns a
+ * {@link SpecRestApiBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const api = createSpecRestApiBuilder()
+ *   .restApiName("PetStore")
+ *   .apiDefinition(ApiDefinition.fromAsset("openapi/petstore.yaml"));
+ * ```
+ */
+export type ISpecRestApiBuilder = IBuilder<SpecRestApiBuilderProps, SpecRestApiBuilder>;
+declare class SpecRestApiBuilder implements Lifecycle<SpecRestApiBuilderResult> {
+    props: Partial<SpecRestApiBuilderProps>;
+    private readonly customAlarms;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<RestApiBase>) => AlarmDefinitionBuilder<RestApiBase>): this;
+    build(scope: IConstruct, id: string): SpecRestApiBuilderResult;
+}
+/**
+ * Creates a new {@link ISpecRestApiBuilder} for configuring an API Gateway
+ * REST API from an OpenAPI specification.
+ *
+ * This is the entry point for defining a spec-driven REST API component. The
+ * returned builder exposes every {@link SpecRestApiProps} property as a fluent
+ * setter/getter. It implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * The API structure — resources, methods, and integrations — is defined
+ * entirely by the OpenAPI specification passed to {@link apiDefinition}.
+ * Use CDK's {@link ApiDefinition} static methods to load the spec from an
+ * inline object, a local file, or an S3 bucket.
+ *
+ * @returns A fluent builder for a spec-driven API Gateway REST API.
+ *
+ * @example
+ * ```ts
+ * // From a local OpenAPI file
+ * const api = createSpecRestApiBuilder()
+ *   .restApiName("PetStore")
+ *   .apiDefinition(ApiDefinition.fromAsset("openapi/petstore.yaml"));
+ *
+ * // From an inline definition
+ * const api = createSpecRestApiBuilder()
+ *   .restApiName("PetStore")
+ *   .apiDefinition(ApiDefinition.fromInline({
+ *     openapi: "3.0.2",
+ *     info: { title: "PetStore", version: "1.0" },
+ *     paths: { "/pets": { get: { ... } } },
+ *   }));
+ *
+ * // Compose into a system
+ * const system = compose(
+ *   { api },
+ *   { api: [] },
+ * );
+ * ```
+ */
+export declare function createSpecRestApiBuilder(): ISpecRestApiBuilder;
+export {};
+//# sourceMappingURL=spec-rest-api-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec-rest-api-builder.d.ts","sourceRoot":"","sources":["../src/spec-rest-api-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAK7F;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB,EAAE,uBAAuB;CAAG;AAE7F;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,CAAC;AAExF,cAAM,kBAAmB,YAAW,SAAS,CAAC,wBAAwB,CAAC;IACrE,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAM;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6C;IAE1E,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,WAAW,CAAC,KAAK,sBAAsB,CAAC,WAAW,CAAC,GAC7F,IAAI;IAKP,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,wBAAwB;CAmB/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,IAAI,mBAAmB,CAE9D"}

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

@@ -0,0 +1,66 @@
+import { SpecRestApi } from "aws-cdk-lib/aws-apigateway";
+import { Builder } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { SPEC_REST_API_DEFAULTS } from "./defaults.js";
+import { resolveDeployOptions } from "./deploy-options.js";
+import { createRestApiAlarms } from "./rest-api-alarms.js";
+class SpecRestApiBuilder {
+    props = {};
+    customAlarms = [];
+    addAlarm(key, configure) {
+        this.customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    build(scope, id) {
+        const { accessLogging, recommendedAlarms: alarmConfig, ...specRestApiProps } = this.props;
+        const { accessLogGroup, deployOptions } = resolveDeployOptions(scope, id, accessLogging, SPEC_REST_API_DEFAULTS.deployOptions ?? {}, specRestApiProps.deployOptions ?? {});
+        const api = new SpecRestApi(scope, id, {
+            ...specRestApiProps,
+            deployOptions,
+        });
+        const alarms = createRestApiAlarms(scope, id, api, alarmConfig, this.customAlarms);
+        return { api, accessLogGroup, alarms };
+    }
+}
+/**
+ * Creates a new {@link ISpecRestApiBuilder} for configuring an API Gateway
+ * REST API from an OpenAPI specification.
+ *
+ * This is the entry point for defining a spec-driven REST API component. The
+ * returned builder exposes every {@link SpecRestApiProps} property as a fluent
+ * setter/getter. It implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * The API structure — resources, methods, and integrations — is defined
+ * entirely by the OpenAPI specification passed to {@link apiDefinition}.
+ * Use CDK's {@link ApiDefinition} static methods to load the spec from an
+ * inline object, a local file, or an S3 bucket.
+ *
+ * @returns A fluent builder for a spec-driven API Gateway REST API.
+ *
+ * @example
+ * ```ts
+ * // From a local OpenAPI file
+ * const api = createSpecRestApiBuilder()
+ *   .restApiName("PetStore")
+ *   .apiDefinition(ApiDefinition.fromAsset("openapi/petstore.yaml"));
+ *
+ * // From an inline definition
+ * const api = createSpecRestApiBuilder()
+ *   .restApiName("PetStore")
+ *   .apiDefinition(ApiDefinition.fromInline({
+ *     openapi: "3.0.2",
+ *     info: { title: "PetStore", version: "1.0" },
+ *     paths: { "/pets": { get: { ... } } },
+ *   }));
+ *
+ * // Compose into a system
+ * const system = compose(
+ *   { api },
+ *   { api: [] },
+ * );
+ * ```
+ */
+export function createSpecRestApiBuilder() {
+    return Builder(SpecRestApiBuilder);
+}
+//# sourceMappingURL=spec-rest-api-builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec-rest-api-builder.js","sourceRoot":"","sources":["../src/spec-rest-api-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,WAAW,EAAyB,MAAM,4BAA4B,CAAC;AAElG,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAuC3D,MAAM,kBAAkB;IACtB,KAAK,GAAqC,EAAE,CAAC;IAC5B,YAAY,GAA0C,EAAE,CAAC;IAE1E,QAAQ,CACN,GAAW,EACX,SAA8F;QAE9F,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAc,GAAG,CAAC,CAAC,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW,EAAE,GAAG,gBAAgB,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAC1F,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,oBAAoB,CAC5D,KAAK,EACL,EAAE,EACF,aAAa,EACb,sBAAsB,CAAC,aAAa,IAAI,EAAE,EAC1C,gBAAgB,CAAC,aAAa,IAAI,EAAE,CACrC,CAAC;QAEF,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE;YACrC,GAAG,gBAAgB;YACnB,aAAa;SACM,CAAC,CAAC;QAEvB,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAEnF,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,OAAO,CAA8C,kBAAkB,CAAC,CAAC;AAClF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/apigateway",
-  "version": "0.1.3",
+  "version": "0.3.2",
   "description": "Composable API Gateway REST API builder with well-architected defaults",
   "repository": {
     "type": "git",
@@ -35,16 +35,17 @@
   },
   "type": "module",
   "peerDependencies": {
-    "@composurecdk/core": "^0.1.0",
-    "@composurecdk/logs": "^0.1.0",
+    "@composurecdk/cloudwatch": "^0.3.0",
+    "@composurecdk/core": "^0.3.0",
+    "@composurecdk/logs": "^0.3.0",
     "aws-cdk-lib": "^2.0.0",
     "constructs": "^10.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "aws-cdk-lib": "^2.245.0",
+    "@types/node": "^25.6.0",
+    "aws-cdk-lib": "^2.250.0",
     "constructs": "^10.6.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
   }
 }