@jaypie/constructs 1.2.9 → 1.2.11

package/dist/cjs/JaypieCertificate.d.ts

@@ -0,0 +1,117 @@
+import { RemovalPolicy, Stack } from "aws-cdk-lib";
+import * as acm from "aws-cdk-lib/aws-certificatemanager";
+import * as route53 from "aws-cdk-lib/aws-route53";
+import { Construct } from "constructs";
+export interface JaypieCertificateProps {
+    /**
+     * Import certificate from a provider stack instead of creating one.
+     * When true, imports the certificate ARN via CloudFormation export.
+     * @default false
+     */
+    consumer?: boolean;
+    /**
+     * The domain name for the certificate.
+     * @default Derived from CDK_ENV_API_HOST_NAME or CDK_ENV_API_SUBDOMAIN + CDK_ENV_API_HOSTED_ZONE
+     */
+    domainName?: string;
+    /**
+     * Export name override for cross-stack sharing.
+     * Only used when provider is true.
+     * @default Generated from environment and domain
+     */
+    export?: string;
+    /**
+     * Construct ID override. When not provided, ID is auto-generated from domain.
+     * Use this to align with certificates created by other constructs.
+     * @default Auto-generated as "JaypieCert-{sanitized-domain}"
+     */
+    id?: string;
+    /**
+     * Export certificate ARN for other stacks to import.
+     * When true, creates a CloudFormation export that consumer stacks can import.
+     * @default false
+     */
+    provider?: boolean;
+    /**
+     * Role tag for tagging the certificate.
+     * @default CDK.ROLE.API
+     */
+    roleTag?: string;
+    /**
+     * The hosted zone for DNS validation.
+     * @default CDK_ENV_API_HOSTED_ZONE || CDK_ENV_HOSTED_ZONE
+     */
+    zone?: string | route53.IHostedZone;
+}
+/**
+ * A standalone certificate construct that can be shared across constructs.
+ *
+ * Key feature: Uses the same `resolveCertificate()` helper as JaypieDistribution,
+ * JaypieApiGateway, etc. This means:
+ * - Certificates are created at the stack level and cached by domain
+ * - You can "take over" a certificate from another construct by using the same domain
+ * - Swapping between JaypieDistribution and JaypieApiGateway won't recreate certs
+ *
+ * Supports flexible constructor signatures:
+ * - `new JaypieCertificate(scope)` - uses environment defaults
+ * - `new JaypieCertificate(scope, props)` - ID auto-generated from domain
+ * - `new JaypieCertificate(scope, id, props)` - explicit ID
+ *
+ * @example
+ * // Minimal - uses environment variables for domain/zone
+ * const cert = new JaypieCertificate(this);
+ *
+ * @example
+ * // With options - ID auto-generated as "JaypieCert-api-example-com"
+ * const cert = new JaypieCertificate(this, {
+ *   domainName: "api.example.com",
+ *   zone: "example.com",
+ * });
+ *
+ * @example
+ * // Explicit ID - useful when you need a specific construct ID
+ * const cert = new JaypieCertificate(this, "MyApiCert", {
+ *   domainName: "api.example.com",
+ *   zone: "example.com",
+ * });
+ *
+ * @example
+ * // Take over from JaypieDistribution (uses same ID format)
+ * // After removing JaypieDistribution with certificate: true
+ * const cert = new JaypieCertificate(this, {
+ *   domainName: "api.example.com",
+ *   zone: "example.com",
+ * });
+ *
+ * @example
+ * // Optional: Provider/consumer pattern for cross-stack sharing
+ * // In sandbox stack (explicitly export):
+ * new JaypieCertificate(this, { provider: true });
+ *
+ * // In personal build (explicitly import):
+ * new JaypieCertificate(this, { consumer: true });
+ */
+export declare class JaypieCertificate extends Construct implements acm.ICertificate {
+    readonly certificate: acm.ICertificate;
+    readonly certificateArn: string;
+    readonly domainName: string;
+    /**
+     * Create a certificate with environment defaults.
+     */
+    constructor(scope: Construct);
+    /**
+     * Create a certificate with options (ID auto-generated from domain).
+     */
+    constructor(scope: Construct, props: JaypieCertificateProps);
+    /**
+     * Create a certificate with explicit ID.
+     */
+    constructor(scope: Construct, id: string, props?: JaypieCertificateProps);
+    get stack(): Stack;
+    get env(): {
+        account: string;
+        region: string;
+    };
+    applyRemovalPolicy(policy: RemovalPolicy): void;
+    metricDaysToExpiry(props?: import("aws-cdk-lib/aws-cloudwatch").MetricOptions): import("aws-cdk-lib/aws-cloudwatch").Metric;
+}

package/dist/cjs/__tests__/JaypieCertificate.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/__tests__/resolveCertificate.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/helpers/index.d.ts

@@ -4,6 +4,7 @@ export { constructStackName } from "./constructStackName";
 export { constructTagger } from "./constructTagger";
 export { envHostname } from "./envHostname";
 export { extendDatadogRole, ExtendDatadogRoleOptions, } from "./extendDatadogRole";
+export { clearAllCertificateCaches, clearCertificateCache, resolveCertificate, ResolveCertificateOptions, } from "./resolveCertificate";
 export { isEnv, isProductionEnv, isSandboxEnv } from "./isEnv";
 export { isValidHostname } from "./isValidHostname";
 export { isValidSubdomain } from "./isValidSubdomain";

package/dist/cjs/helpers/resolveCertificate.d.ts

@@ -0,0 +1,63 @@
+import { Stack } from "aws-cdk-lib";
+import * as acm from "aws-cdk-lib/aws-certificatemanager";
+import * as route53 from "aws-cdk-lib/aws-route53";
+import { Construct } from "constructs";
+export interface ResolveCertificateOptions {
+    /** Certificate input - true creates at stack level, false skips, ICertificate uses as-is, string imports from ARN */
+    certificate?: boolean | acm.ICertificate | string;
+    /** Domain name for the certificate (required if certificate is true) */
+    domainName: string;
+    /** Construct ID name prefix (defaults to "Certificate") */
+    name?: string;
+    /** Role tag for tagging (defaults to CDK.ROLE.API) */
+    roleTag?: string;
+    /** Hosted zone for DNS validation (required if certificate is true) */
+    zone: route53.IHostedZone;
+}
+/**
+ * Resolves a certificate based on input type.
+ *
+ * Key behavior: When certificate is `true`, the certificate is created at the
+ * STACK level (not construct level) and cached by domain name. This allows
+ * swapping between constructs (e.g., JaypieDistribution to JaypieApiGateway)
+ * without recreating the certificate.
+ *
+ * @param scope - The construct scope (used to find the stack)
+ * @param options - Certificate resolution options
+ * @returns The resolved certificate, or undefined if certificate is false
+ *
+ * @example
+ * // Create or get cached certificate at stack level
+ * const cert = resolveCertificate(this, {
+ *   certificate: true,
+ *   domainName: "api.example.com",
+ *   zone: hostedZone,
+ * });
+ *
+ * @example
+ * // Use existing certificate
+ * const cert = resolveCertificate(this, {
+ *   certificate: existingCert,
+ *   domainName: "api.example.com",
+ *   zone: hostedZone,
+ * });
+ *
+ * @example
+ * // Import certificate from ARN
+ * const cert = resolveCertificate(this, {
+ *   certificate: "arn:aws:acm:us-east-1:123456789:certificate/abc-123",
+ *   domainName: "api.example.com",
+ *   zone: hostedZone,
+ * });
+ */
+export declare function resolveCertificate(scope: Construct, options: ResolveCertificateOptions): acm.ICertificate | undefined;
+/**
+ * Clears the certificate cache for a specific stack.
+ * Primarily useful for testing.
+ */
+export declare function clearCertificateCache(stack: Stack): void;
+/**
+ * Clears all certificate caches.
+ * Primarily useful for testing.
+ */
+export declare function clearAllCertificateCaches(): void;