@composurecdk/apigateway 0.7.0 → 0.8.1

package/dist/commonjs/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/commonjs/alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=alarm-config.js.map

package/dist/{alarm-config.js.map → commonjs/alarm-config.js.map}

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

package/dist/commonjs/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,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,oBAAoB;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd,WAAW,EAAE,mBAAmB,CAAC;IACjC,WAAW,EAAE,mBAAmB,CAAC;IACjC,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,oBAsCrC,CAAC"}

package/dist/commonjs/alarm-defaults.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REST_API_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("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
+ */
+exports.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: aws_cloudwatch_1.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: aws_cloudwatch_1.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: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=alarm-defaults.js.map

package/dist/commonjs/alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAU9D;;;;GAIG;AACU,QAAA,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,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,WAAW,EAAE;QACX,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,OAAO,EAAE;QACP,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/commonjs/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/commonjs/builder-common.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=builder-common.js.map

package/dist/{builder-common.js.map → commonjs/builder-common.js.map}

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

package/dist/commonjs/defaults.d.ts.map

@@ -0,0 +1 @@
+{"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/commonjs/defaults.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEC_REST_API_DEFAULTS = exports.REST_API_DEFAULTS = exports.DEPLOY_OPTIONS_DEFAULTS = void 0;
+const aws_apigateway_1 = require("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.
+ */
+exports.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: aws_apigateway_1.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
+ * via the builder's fluent API.
+ */
+exports.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: exports.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.
+ */
+exports.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: exports.DEPLOY_OPTIONS_DEFAULTS,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/commonjs/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":";;;AAAA,+DAAmF;AAInF;;;;GAIG;AACU,QAAA,uBAAuB,GAAiB;IACnD;;;OAGG;IACH,cAAc,EAAE,IAAI;IAEpB;;;OAGG;IACH,YAAY,EAAE,mCAAkB,CAAC,IAAI;IAErC;;;;OAIG;IACH,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF;;;;GAIG;AACU,QAAA,iBAAiB,GAAiC;IAC7D;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB,aAAa,EAAE,+BAAuB;CACvC,CAAC;AAEF;;;;GAIG;AACU,QAAA,sBAAsB,GAAqC;IACtE;;;OAGG;IACH,aAAa,EAAE,IAAI;IAEnB,aAAa,EAAE,+BAAuB;CACvC,CAAC"}

package/dist/commonjs/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/commonjs/deploy-options.js

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

package/dist/commonjs/deploy-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-options.js","sourceRoot":"","sources":["../../src/deploy-options.ts"],"names":[],"mappings":";;AAqBA,oDA4BC;AAjDD,+DAIoC;AAGpC,6CAA2D;AAO3D;;;;;;GAMG;AACH,SAAgB,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,IAAA,4BAAqB,GAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC;QAClF,cAAc,GAAG;YACf,oBAAoB,EAAE,IAAI,uCAAsB,CAAC,cAAc,CAAC;YAChE,eAAe,EAAE,gCAAe,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/commonjs/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,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,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/commonjs/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REST_API_ALARM_DEFAULTS = exports.SPEC_REST_API_DEFAULTS = exports.REST_API_DEFAULTS = exports.createSpecRestApiBuilder = exports.createRestApiBuilder = void 0;
+var rest_api_builder_js_1 = require("./rest-api-builder.js");
+Object.defineProperty(exports, "createRestApiBuilder", { enumerable: true, get: function () { return rest_api_builder_js_1.createRestApiBuilder; } });
+var spec_rest_api_builder_js_1 = require("./spec-rest-api-builder.js");
+Object.defineProperty(exports, "createSpecRestApiBuilder", { enumerable: true, get: function () { return spec_rest_api_builder_js_1.createSpecRestApiBuilder; } });
+var defaults_js_1 = require("./defaults.js");
+Object.defineProperty(exports, "REST_API_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.REST_API_DEFAULTS; } });
+Object.defineProperty(exports, "SPEC_REST_API_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.SPEC_REST_API_DEFAULTS; } });
+var alarm_defaults_js_1 = require("./alarm-defaults.js");
+Object.defineProperty(exports, "REST_API_ALARM_DEFAULTS", { enumerable: true, get: function () { return alarm_defaults_js_1.REST_API_ALARM_DEFAULTS; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAK+B;AAJ7B,2HAAA,oBAAoB,OAAA;AAMtB,uEAKoC;AAJlC,oIAAA,wBAAwB,OAAA;AAK1B,6CAA0E;AAAjE,gHAAA,iBAAiB,OAAA;AAAE,qHAAA,sBAAsB,OAAA;AAElD,yDAA8D;AAArD,4HAAA,uBAAuB,OAAA"}

package/dist/commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/commonjs/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;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAOvC,gBAAgB;IAChB,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,IAAI;CAczE"}

package/dist/commonjs/resource-builder.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceBuilder = void 0;
+const core_1 = require("@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)
+ *     )
+ *   );
+ * ```
+ */
+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;
+    }
+    /**
+     * Copies this builder's resource tree onto `target`. Used by
+     * `RestApiBuilder.[COPY_STATE]` per ADR-0005's containers-fresh,
+     * elements-shared rule: the `methods` array and `children` Map are
+     * reconstructed on `target`, but `MethodDefinition` and child
+     * `ResourceDefinition` entries are shared by reference. Sharing the
+     * child entries is safe because the public API (`addResource`)
+     * replaces a child wholesale rather than mutating it in place.
+     *
+     * @internal
+     */
+    copyInto(target) {
+        target.definition.methods.push(...this.definition.methods);
+        for (const [pathPart, childDef] of this.definition.children) {
+            target.definition.children.set(pathPart, childDef);
+        }
+    }
+    /** @internal */
+    applyTo(resource, context = {}) {
+        for (const method of this.definition.methods) {
+            const integration = method.integration !== undefined ? (0, core_1.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);
+        }
+    }
+}
+exports.ResourceBuilder = ResourceBuilder;
+//# sourceMappingURL=resource-builder.js.map

package/dist/commonjs/resource-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-builder.js","sourceRoot":"","sources":["../../src/resource-builder.ts"],"names":[],"mappings":";;;AACA,6CAA8D;AAa9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,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;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAuB;QAC9B,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC3D,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;YAC5D,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACrD,CAAC;IACH,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,IAAA,cAAO,EAAC,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;AAvED,0CAuEC"}

package/dist/commonjs/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,CAmDnB;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/commonjs/rest-api-alarms.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRestApiAlarmDefinitions = resolveRestApiAlarmDefinitions;
+exports.createRestApiAlarms = createRestApiAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const alarm_defaults_js_1 = require("./alarm-defaults.js");
+const METRIC_PERIOD = aws_cdk_lib_1.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 aws_cloudwatch_1.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.
+ */
+function resolveRestApiAlarmDefinitions(api, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.clientError !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.clientError, alarm_defaults_js_1.REST_API_ALARM_DEFAULTS.clientError);
+        definitions.push({
+            key: "clientError",
+            alarmName: cfg.alarmName,
+            metric: apiMetric(api, "4XXError", aws_cloudwatch_1.Stats.AVERAGE),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.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 = (0, cloudwatch_1.resolveAlarmConfig)(config?.serverError, alarm_defaults_js_1.REST_API_ALARM_DEFAULTS.serverError);
+        definitions.push({
+            key: "serverError",
+            alarmName: cfg.alarmName,
+            metric: apiMetric(api, "5XXError", aws_cloudwatch_1.Stats.AVERAGE),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.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 = (0, cloudwatch_1.resolveAlarmConfig)(config?.latency, alarm_defaults_js_1.REST_API_ALARM_DEFAULTS.latency);
+        definitions.push({
+            key: "latency",
+            alarmName: cfg.alarmName,
+            metric: apiMetric(api, "Latency", aws_cloudwatch_1.Stats.percentile(90)),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.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
+ */
+function createRestApiAlarms(scope, id, api, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? alarm_defaults_js_1.REST_API_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveRestApiAlarmDefinitions(api, config);
+    const custom = customAlarms.map((b) => b.resolve(api));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=rest-api-alarms.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api-alarms.js","sourceRoot":"","sources":["../../src/rest-api-alarms.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/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,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,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,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,cAAc,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;AAElF,cAAM,cAAe,YAAW,SAAS,CAAC,oBAAoB,CAAC;;IAC7D,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAM;IAIzC,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;;;;;;;;OAQG;IACH,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAK1C,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/commonjs/rest-api-builder.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRestApiBuilder = createRestApiBuilder;
+const aws_apigateway_1 = require("aws-cdk-lib/aws-apigateway");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const defaults_js_1 = require("./defaults.js");
+const deploy_options_js_1 = require("./deploy-options.js");
+const resource_builder_js_1 = require("./resource-builder.js");
+const rest_api_alarms_js_1 = require("./rest-api-alarms.js");
+class RestApiBuilder {
+    props = {};
+    #root = new resource_builder_js_1.ResourceBuilder();
+    #customAlarms = [];
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Copies non-`props` state onto a freshly cloned builder. The resource
+     * tree is deep-cloned via `ResourceBuilder.copyInto` so mutations on
+     * either side after `.copy()` do not leak; the alarm-builder array is
+     * spread into a fresh container with elements shared by reference per
+     * ADR-0005's shallow-clone stance.
+     *
+     * @internal
+     */
+    [core_1.COPY_STATE](target) {
+        this.#root.copyInto(target.#root);
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id, context) {
+        const { accessLogging, recommendedAlarms: alarmConfig, ...restApiProps } = this.props;
+        const { accessLogGroup, deployOptions } = (0, deploy_options_js_1.resolveDeployOptions)(scope, id, accessLogging, defaults_js_1.REST_API_DEFAULTS.deployOptions ?? {}, restApiProps.deployOptions ?? {});
+        const api = new aws_apigateway_1.RestApi(scope, id, {
+            ...restApiProps,
+            deployOptions,
+        });
+        this.#root.applyTo(api.root, context ?? {});
+        const alarms = (0, rest_api_alarms_js_1.createRestApiAlarms)(scope, id, api, alarmConfig, this.#customAlarms);
+        return { api, accessLogGroup, alarms };
+    }
+}
+/**
+ * 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: [] },
+ * );
+ * ```
+ */
+function createRestApiBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(RestApiBuilder);
+}
+//# sourceMappingURL=rest-api-builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rest-api-builder.js","sourceRoot":"","sources":["../../src/rest-api-builder.ts"],"names":[],"mappings":";;AA0KA,oDAEC;AA5KD,+DAMoC;AAEpC,6CAAiF;AACjF,iEAAkF;AAClF,yDAAkE;AAElE,+CAAkD;AAClD,2DAA2D;AAC3D,+DAAwD;AACxD,6DAA2D;AA2C3D,MAAM,cAAc;IAClB,KAAK,GAAiC,EAAE,CAAC;IAChC,KAAK,GAAG,IAAI,qCAAe,EAAE,CAAC;IAC9B,aAAa,GAA0C,EAAE,CAAC;IAEnE,QAAQ,CACN,GAAW,EACX,SAA8F;QAE9F,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,mCAAsB,CAAc,GAAG,CAAC,CAAC,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CACP,UAAkB,EAClB,WAAqC,EACrC,OAAuB;QAEvB,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,QAAgB,EAAE,SAA+C;QAC3E,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,CAAC,iBAAU,CAAC,CAAC,MAAsB;QACjC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IACnD,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,IAAA,wCAAoB,EAC5D,KAAK,EACL,EAAE,EACF,aAAa,EACb,+BAAiB,CAAC,aAAa,IAAI,EAAE,EACrC,YAAY,CAAC,aAAa,IAAI,EAAE,CACjC,CAAC;QAEF,MAAM,GAAG,GAAG,IAAI,wBAAO,CAAC,KAAK,EAAE,EAAE,EAAE;YACjC,GAAG,YAAY;YACf,aAAa;SACd,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QAE5C,MAAM,MAAM,GAAG,IAAA,wCAAmB,EAAC,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAEpF,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,SAAgB,oBAAoB;IAClC,OAAO,IAAA,8BAAa,EAAsC,cAAc,CAAC,CAAC;AAC5E,CAAC"}

package/dist/commonjs/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,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,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,cAAc,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,CAAC;AAE9F,cAAM,kBAAmB,YAAW,SAAS,CAAC,wBAAwB,CAAC;;IACrE,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAM;IAG7C,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,WAAW,CAAC,KAAK,sBAAsB,CAAC,WAAW,CAAC,GAC7F,IAAI;IAKP,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAI9C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,wBAAwB;CAmB/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,IAAI,mBAAmB,CAE9D"}

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

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpecRestApiBuilder = createSpecRestApiBuilder;
+const aws_apigateway_1 = require("aws-cdk-lib/aws-apigateway");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const defaults_js_1 = require("./defaults.js");
+const deploy_options_js_1 = require("./deploy-options.js");
+const rest_api_alarms_js_1 = require("./rest-api-alarms.js");
+class SpecRestApiBuilder {
+    props = {};
+    #customAlarms = [];
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id) {
+        const { accessLogging, recommendedAlarms: alarmConfig, ...specRestApiProps } = this.props;
+        const { accessLogGroup, deployOptions } = (0, deploy_options_js_1.resolveDeployOptions)(scope, id, accessLogging, defaults_js_1.SPEC_REST_API_DEFAULTS.deployOptions ?? {}, specRestApiProps.deployOptions ?? {});
+        const api = new aws_apigateway_1.SpecRestApi(scope, id, {
+            ...specRestApiProps,
+            deployOptions,
+        });
+        const alarms = (0, rest_api_alarms_js_1.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: [] },
+ * );
+ * ```
+ */
+function createSpecRestApiBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(SpecRestApiBuilder);
+}
+//# sourceMappingURL=spec-rest-api-builder.js.map

package/dist/commonjs/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":";;AA2HA,4DAEC;AA7HD,+DAAkG;AAElG,6CAAgE;AAChE,iEAAkF;AAClF,yDAAkE;AAElE,+CAAuD;AACvD,2DAA2D;AAC3D,6DAA2D;AAuC3D,MAAM,kBAAkB;IACtB,KAAK,GAAqC,EAAE,CAAC;IACpC,aAAa,GAA0C,EAAE,CAAC;IAEnE,QAAQ,CACN,GAAW,EACX,SAA8F;QAE9F,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,mCAAsB,CAAc,GAAG,CAAC,CAAC,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,iBAAU,CAAC,CAAC,MAA0B;QACrC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IACnD,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,IAAA,wCAAoB,EAC5D,KAAK,EACL,EAAE,EACF,aAAa,EACb,oCAAsB,CAAC,aAAa,IAAI,EAAE,EAC1C,gBAAgB,CAAC,aAAa,IAAI,EAAE,CACrC,CAAC;QAEF,MAAM,GAAG,GAAG,IAAI,4BAAW,CAAC,KAAK,EAAE,EAAE,EAAE;YACrC,GAAG,gBAAgB;YACnB,aAAa;SACM,CAAC,CAAC;QAEvB,MAAM,MAAM,GAAG,IAAA,wCAAmB,EAAC,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAEpF,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAgB,wBAAwB;IACtC,OAAO,IAAA,8BAAa,EAA8C,kBAAkB,CAAC,CAAC;AACxF,CAAC"}