@resistdesign/voltra 3.0.0-alpha.5 → 3.0.0-alpha.51

package/iac/packs/auth.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Optional logical ids for resources generated by {@link addAuth}.
+ */
+export type UserManagementIds = {
+    userPool?: string;
+    userPoolClient?: string;
+    identityPool?: string;
+    authRole?: string;
+    unauthRole?: string;
+    roleAttachment?: string;
+    domain?: string;
+    domainRecord?: string;
+    baseDomainRecord?: string;
+};
+/**
+ * Configuration for the auth pack.
+ */
+export type AddAuthConfigBase = {
+    /**
+     * Base id for Cognito resources.
+     */
+    userManagementId: string;
+    /**
+     * IAM role name for authenticated users.
+     */
+    authRoleName: string;
+    /**
+     * IAM role name for unauthenticated users.
+     */
+    unauthRoleName: string;
+    /**
+     * API Gateway REST API id for authenticated access.
+     */
+    apiCloudFunctionGatewayId: string;
+    /**
+     * API Gateway stage name for authenticated access.
+     */
+    apiStageName: string;
+    /**
+     * Resource id for the admin group.
+     */
+    adminGroupId: string;
+    /**
+     * Cognito group name for admins.
+     */
+    userManagementAdminGroupName: string;
+    /**
+     * Optional explicit logical ids for generated user-management resources.
+     *
+     * @example
+     * ```ts
+     * userManagementIds: {
+     *   userPool: "MyUserPool",
+     *   userPoolClient: "MyUserPoolClient",
+     * }
+     * ```
+     */
+    userManagementIds?: UserManagementIds;
+};
+/**
+ * Configuration for adding auth resources including a user pool domain with
+ * callback and logout URLs.
+ */
+export type AddAuthConfigWithUserPoolDomain = AddAuthConfigBase & {
+    /**
+     * Enable Cognito Hosted UI/OAuth redirect mode by creating a custom user pool
+     * domain plus Route53 records.
+     *
+     * When enabled, the generated user pool client uses OAuth flows (`code`,
+     * `implicit`) and supports callback/logout URL configuration.
+     *
+     * Defaults to `true`. Set `false` to opt out of Hosted UI resources and use
+     * SDK/API-based sign-in flows only.
+     */
+    enableUserPoolDomain?: true;
+    /**
+     * Parameter name for the Route53 hosted zone id that owns `domainName`.
+     */
+    hostedZoneIdParameterName: string;
+    /**
+     * Parameter name for the base domain used for the auth subdomain.
+     */
+    domainNameParameterName: string;
+    /**
+     * ACM certificate resource id (in `us-east-1`) for the Cognito custom
+     * domain.
+     */
+    sslCertificateId: string;
+    /**
+     * CloudFront distribution resource id used as the base-domain alias target.
+     */
+    mainCDNCloudFrontId: string;
+    /**
+     * OAuth callback URLs for Hosted UI/federated redirect flows.
+     */
+    callbackUrls: any[];
+    /**
+     * OAuth logout redirect URLs for Hosted UI sign-out.
+     */
+    logoutUrls: any[];
+    /**
+     * Supported identity providers for Hosted UI/OAuth flows.
+     */
+    supportedIdentityProviders?: any[];
+};
+/**
+ * Configuration for adding auth resources without a user pool domain.
+ */
+export type AddAuthConfigWithoutUserPoolDomain = AddAuthConfigBase & {
+    /**
+     * Disable Cognito Hosted UI/OAuth redirect configuration.
+     */
+    enableUserPoolDomain: false;
+    hostedZoneIdParameterName?: never;
+    domainNameParameterName?: never;
+    sslCertificateId?: never;
+    mainCDNCloudFrontId?: never;
+    callbackUrls?: never;
+    logoutUrls?: never;
+    supportedIdentityProviders?: never;
+};
+/**
+ * Configuration for {@link addAuth}.
+ */
+export type AddAuthConfig = AddAuthConfigWithUserPoolDomain | AddAuthConfigWithoutUserPoolDomain;
+/**
+ * Add auth resources including user management and an admin group.
+ *
+ * @group Resource Packs
+ */
+export declare const addAuth: import("..").ResourcePackApplier<AddAuthConfig>;

package/iac/packs/build/utils.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Require at least one key from the provided type.
+ *
+ * @typeParam T - Base object type.
+ * @typeParam U - Helper mapped type.
+ */
+export type AtLeastOne<T, U = {
+    [K in keyof T]: Pick<T, K>;
+}> = Partial<T> & U[keyof U];
+/**
+ * Helper functions for generating CLI commands in build specs.
+ */
+export declare const COMMAND_HELPERS: {
+    updateFunction: ({ cloudFunctionArn, codeZipFilePath, }: {
+        cloudFunctionArn: string;
+        codeZipFilePath: string;
+    }) => string;
+    copyDirectoryToS3: ({ s3Domain, directoryPath, }: {
+        s3Domain: string;
+        directoryPath: string;
+    }) => string;
+    cloudFrontInvalidation: ({ cloudFrontDistributionId, pathsToInvalidate, }: {
+        cloudFrontDistributionId: string;
+        pathsToInvalidate?: string[];
+    }) => string;
+    addNPMTokenWithNPMRC: ({ npmToken }: {
+        npmToken: string;
+    }) => string;
+};
+/**
+ * Linux user name string.
+ */
+export type LinuxUserNameString = string;
+/**
+ * Flag value for yes/no configuration fields.
+ */
+export type YesOrNo = "yes" | "no";
+/**
+ * BuildSpec environment configuration.
+ */
+export interface Env {
+    /**
+     * Shell to use for command execution.
+     */
+    shell?: "bash" | "/bin/sh" | "powershell.exe" | "cmd.exe" | string;
+    /**
+     * Environment variables to expose.
+     */
+    variables?: Record<string, string>;
+    /**
+     * SSM parameter store references.
+     */
+    "parameter-store"?: Record<string, string>;
+    /**
+     * Exported variable names.
+     */
+    "exported-variables"?: string[];
+    /**
+     * Secrets Manager references.
+     */
+    "secrets-manager"?: Record<string, `${string}:${string}:${string}:${string}`>;
+    /**
+     * Whether to enable git credential helper.
+     */
+    "git-credential-helper"?: YesOrNo;
+}
+/**
+ * BuildSpec proxy configuration.
+ */
+export interface Proxy {
+    /**
+     * Whether to upload build artifacts via proxy.
+     */
+    "upload-artifacts"?: YesOrNo;
+    /**
+     * Whether to proxy logs.
+     */
+    logs?: YesOrNo;
+}
+/**
+ * BuildSpec batch build configuration.
+ */
+export interface Batch {
+    /**
+     * Whether to fail fast for batch builds.
+     */
+    "fast-fail"?: boolean;
+    /**
+     * Batch build list config.
+     */
+    "build-list"?: any;
+    /**
+     * Batch build matrix config.
+     */
+    "build-matrix"?: any;
+    /**
+     * Batch build graph config.
+     */
+    "build-graph"?: any;
+    [key: string]: any;
+}
+/**
+ * BuildSpec phase configuration.
+ */
+export interface Phase {
+    /**
+     * Runtime versions for this phase.
+     */
+    "runtime-versions"?: Record<string, any>;
+    /**
+     * User to run commands as.
+     */
+    "run-as"?: LinuxUserNameString;
+    /**
+     * Behavior when a command fails.
+     */
+    "on-failure"?: "ABORT" | "CONTINUE";
+    /**
+     * Commands to run during the phase.
+     */
+    commands: string[];
+    /**
+     * Commands to always run at the end of the phase.
+     */
+    finally?: string[];
+}
+/**
+ * BuildSpec phase collection (at least one phase required).
+ */
+export type PhaseConfig = AtLeastOne<{
+    install: Phase;
+    pre_build: Phase;
+    build: Phase;
+    post_build: Phase;
+}>;
+/**
+ * Report group configuration for build reports.
+ */
+export interface ReportGroupNameOrArn {
+    /**
+     * Report files to include.
+     */
+    files?: string[];
+    /**
+     * Base directory for report files.
+     */
+    "base-directory"?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Report file format.
+     */
+    "file-format"?: string;
+}
+/**
+ * Reports configuration for BuildSpec.
+ */
+export interface Reports {
+    /**
+     * Report group name or ARN.
+     */
+    "report-group-name-or-arn"?: ReportGroupNameOrArn;
+}
+/**
+ * Artifact identifier configuration.
+ */
+export interface ArtifactIdentifier {
+    /**
+     * Artifact file list.
+     */
+    files?: string[];
+    /**
+     * Artifact name.
+     */
+    name?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Base directory for artifact files.
+     */
+    "base-directory"?: string;
+}
+/**
+ * Secondary artifacts configuration.
+ */
+export interface SecondaryArtifacts {
+    /**
+     * Artifact identifier for secondary artifacts.
+     */
+    artifactIdentifier?: ArtifactIdentifier;
+}
+/**
+ * Artifacts configuration for BuildSpec.
+ */
+export interface Artifacts {
+    /**
+     * Artifact file list.
+     */
+    files?: string[];
+    /**
+     * Artifact name.
+     */
+    name?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Base directory for artifact files.
+     */
+    "base-directory"?: string;
+    /**
+     * Paths to exclude from artifacts.
+     */
+    "exclude-paths"?: string;
+    /**
+     * Whether to enable symlinks in artifacts.
+     */
+    "enable-symlinks"?: string;
+    /**
+     * S3 prefix for artifact upload.
+     */
+    "s3-prefix"?: string;
+    /**
+     * Secondary artifacts configuration.
+     */
+    "secondary-artifacts"?: SecondaryArtifacts;
+}
+/**
+ * Cache configuration for BuildSpec.
+ */
+export interface Cache {
+    /**
+     * Cache paths to persist between builds.
+     */
+    paths?: string[];
+}
+/**
+ * BuildSpec configuration object.
+ */
+export interface BuildSpec {
+    /**
+     * Build spec version.
+     */
+    version?: number;
+    /**
+     * User to run build commands as.
+     */
+    "run-as"?: LinuxUserNameString;
+    /**
+     * Environment configuration.
+     */
+    env?: Env;
+    /**
+     * Proxy configuration.
+     */
+    proxy?: Proxy;
+    /**
+     * Batch build configuration.
+     */
+    batch?: Batch;
+    /**
+     * Build phases configuration.
+     */
+    phases: PhaseConfig;
+    /**
+     * Reports configuration.
+     */
+    reports?: Reports;
+    /**
+     * Artifacts configuration.
+     */
+    artifacts?: Artifacts;
+    /**
+     * Cache configuration.
+     */
+    cache?: Cache;
+}
+/**
+ * Create a build spec YAML string for a build pipeline (CI/CD).
+ *
+ * @param config - Build spec configuration.
+ * @returns YAML string for the build spec.
+ */
+export declare const createBuildSpec: ({ version, phases }: BuildSpec) => string;

package/iac/packs/build.d.ts

@@ -0,0 +1,92 @@
+import { AWS } from "../types/IaCTypes";
+/**
+ * Default repository provider for CodePipeline source actions.
+ */
+export declare const DEFAULT_BUILD_PIPELINE_REPO_PROVIDER = "GitHub";
+/**
+ * Source repository configuration for the build pipeline.
+ */
+export type BuildPipelineRepoConfig = {
+    /**
+     * CodePipeline provider (e.g., GitHub).
+     */
+    provider?: any;
+    /**
+     * Repository owner/organization.
+     */
+    owner: any;
+    /**
+     * Repository name.
+     */
+    repo: any;
+    /**
+     * Repository branch name.
+     */
+    branch: any;
+    /**
+     * OAuth token for source access.
+     */
+    oauthToken: any;
+};
+/**
+ * Helper for custom CodeBuild string literals.
+ */
+export type CustomCodeBuildString<T extends string> = T & {
+    __custom?: never;
+};
+/**
+ * Allowed CodeBuild environment types.
+ */
+export type CodeBuildEnvironmentType = "ARM_CONTAINER" | "LINUX_CONTAINER" | "LINUX_GPU_CONTAINER" | "WINDOWS_SERVER_2019_CONTAINER" | "WINDOWS_SERVER_2022_CONTAINER" | "LINUX_EC2" | "ARM_EC2" | "WINDOWS_EC2" | "MAC_ARM" | CustomCodeBuildString<string>;
+/**
+ * Allowed CodeBuild compute types.
+ */
+export type CodeBuildComputeType = "BUILD_GENERAL1_SMALL" | "BUILD_GENERAL1_MEDIUM" | "BUILD_GENERAL1_LARGE" | "BUILD_GENERAL1_2XLARGE" | "BUILD_GENERAL1_XLARGE" | CustomCodeBuildString<string>;
+/**
+ * Configuration for the build pipeline pack.
+ */
+export type AddBuildPipelineConfig = {
+    /**
+     * Base id for created resources.
+     */
+    id: string;
+    /**
+     * Build spec YAML or JSON.
+     */
+    buildSpec: any;
+    /**
+     * Optional resource dependencies.
+     */
+    dependsOn?: string | string[];
+    /**
+     * CodeBuild environment variables.
+     */
+    environmentVariables?: AWS.CodeBuild.Project.EnvironmentVariable[];
+    /**
+     * Build timeout in minutes.
+     */
+    timeoutInMinutes?: number;
+    /**
+     * CodeBuild environment type.
+     */
+    environmentType?: CodeBuildEnvironmentType;
+    /**
+     * CodeBuild compute type.
+     */
+    environmentComputeType?: CodeBuildComputeType;
+    /**
+     * CodeBuild image to run.
+     */
+    environmentImage?: string;
+    /**
+     * Repository configuration for source stage.
+     */
+    repoConfig: BuildPipelineRepoConfig;
+};
+/**
+ * Add a build pipeline with full permissions.
+ *
+ * @param config - Build pipeline configuration.
+ * @group Resource Packs
+ */
+export declare const addBuildPipeline: import("..").ResourcePackApplier<AddBuildPipelineConfig>;

package/iac/packs/cdn.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Configuration for the CDN pack.
+ */
+export type AddCDNConfig = {
+    /**
+     * CloudFront distribution id.
+     */
+    id: string;
+    /**
+     * Route53 hosted zone id for the domain.
+     */
+    hostedZoneId: any;
+    /**
+     * Domain name to serve.
+     */
+    domainName: any;
+    /**
+     * ACM certificate ARN for the domain.
+     */
+    certificateArn: any;
+    /**
+     * S3 file storage resource id.
+     */
+    fileStorageId: string;
+};
+/**
+ * Add a global cache of static files (a CDN) for things like your front-end, website, etc.
+ * Includes a DNS record for the domain.
+ *
+ * @param config - CDN configuration.
+ * @group Resource Packs
+ * */
+export declare const addCDN: import("..").ResourcePackApplier<AddCDNConfig>;

package/iac/packs/cloud-function.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @packageDocumentation
+ *
+ * Lambda pack that provisions a basic function with an IAM role and optional
+ * environment settings.
+ */
+import { AWS } from "../types/IaCTypes";
+/**
+ * Default inline function code for placeholder Lambda resources.
+ */
+export declare const PLACEHOLDER_FUNCTION_CODE: AWS.Lambda.Function.Code;
+/**
+ * Supported Lambda runtimes for cloud functions.
+ */
+export type CloudFunctionRuntime = "nodejs14.x" | "nodejs16.x" | "nodejs18.x" | "nodejs20.x" | "nodejs22.x" | "nodejs24.x" | "nodejs26.x" | "python3.8" | "python3.9" | "python3.10" | "python3.11" | "python3.12" | "python3.13" | "python3.14" | "python3.15" | "java11" | "java17" | "java21" | "java25" | "dotnet6" | "dotnet8" | "dotnet10" | "go1.x" | "ruby2.7" | "ruby3.2" | "ruby3.3" | "ruby3.4" | "ruby3.5" | "provided" | "provided.al2" | "provided.al2023";
+/**
+ * Configuration for the cloud function pack.
+ */
+export type AddCloudFunctionConfig = {
+    /**
+     * Base id for the function resources.
+     */
+    id: string;
+    /**
+     * Lambda function code.
+     */
+    code?: AWS.Lambda.Function.Code;
+    /**
+     * Lambda environment configuration.
+     */
+    environment?: AWS.Lambda.Function.Environment;
+    /**
+     * Function handler entrypoint.
+     */
+    handler?: any;
+    /**
+     * Lambda runtime.
+     */
+    runtime?: CloudFunctionRuntime;
+    /**
+     * Function timeout in seconds.
+     */
+    timeout?: any;
+    /**
+     * IAM policy statements to attach to the role.
+     */
+    policies?: AWS.IAM.Role.Policy[];
+    /**
+     * Lambda function memory size in MB.
+     *
+     * You can configure memory between 128 MB and 10,240 MB in 1-MB increments.
+     *
+     * @default 128
+     */
+    memorySize?: number;
+};
+/**
+ * Add a serverless cloud function to run part or all of your API (back-end) without always running servers.
+ *
+ * @param config - Cloud function configuration.
+ * */
+/**
+ * Add a cloud function resource with IAM role and configuration.
+ *
+ * @group Resource Packs
+ */
+export declare const addCloudFunction: import("..").ResourcePackApplier<AddCloudFunctionConfig>;

package/iac/packs/database.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The configuration for adding a database to a stack.
+ * */
+export type AddDatabaseConfig = {
+    /**
+     * The id of the database table in a stack.
+     * */
+    tableId: string;
+    /**
+     * The name of the database table.
+     * */
+    tableName?: string;
+    /**
+     * The keys for the database table.
+     * */
+    keys: Record<string, "HASH" | "RANGE">;
+    /**
+     * Specific attributes for the database table.
+     * */
+    attributes: Record<string, "S" | "N" | "B" | "BOOL" | "NULL" | "M" | "L" | "SS" | "NS" | "BS">;
+    /**
+     * The billing mode for the database table.
+     * */
+    billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
+};
+/**
+ * Add a highly available key-value database with global scale performance.
+ *
+ * @param config - Database configuration.
+ * @group Resource Packs
+ * */
+export declare const addDatabase: import("..").ResourcePackApplier<AddDatabaseConfig>;

package/iac/packs/dns.d.ts

@@ -0,0 +1,34 @@
+import { CloudFormationPrimitiveValue } from "../types/IaCTypes";
+/**
+ * Configuration for the DNS record pack.
+ */
+export type AddDNSConfig = {
+    /**
+     * Resource id for the DNS record.
+     */
+    id: string;
+    /**
+     * Hosted zone id for the domain.
+     */
+    hostedZoneId: CloudFormationPrimitiveValue<string>;
+    /**
+     * Fully qualified domain name.
+     */
+    domainName: CloudFormationPrimitiveValue<string>;
+    /**
+     * Resource records for the DNS entry.
+     */
+    resourceRecords: CloudFormationPrimitiveValue<string>[];
+    /**
+     * DNS record type.
+     */
+    recordType?: CloudFormationPrimitiveValue<string>;
+};
+/**
+ * Add DNS parameters for reference in other resources.
+ * Optionally includes a front-end live development subdomain.
+ *
+ * @param config - DNS configuration.
+ * @group Resource Packs
+ * */
+export declare const addDNS: import("..").ResourcePackApplier<AddDNSConfig>;