@quiltdata/benchling-webhook 0.6.3-20251104T170954Z → 0.7.1-20251106T100426Z

package/dist/lib/types/config.d.ts

@@ -1,252 +1,404 @@
 /**
- * Comprehensive Type Definitions for XDG Configuration System
+ * Type Definitions for v0.7.0 Configuration Architecture
  *
- * This module defines all TypeScript types and interfaces for the
- * XDG-compliant configuration management system.
+ * BREAKING CHANGE: Complete rewrite with NO backward compatibility.
+ * This module defines the new unified configuration system for multi-environment deployments.
  *
  * @module types/config
+ * @version 0.7.0
  */
 /**
  * Configuration profile identifier
  * Profiles allow multiple named configurations (e.g., "default", "dev", "prod")
+ *
+ * @example "default"
+ * @example "dev"
+ * @example "prod"
  */
 export type ProfileName = string;
 /**
- * Configuration type identifier
- */
-export type ConfigType = "user" | "derived" | "deploy" | "complete";
-/**
- * User Configuration
+ * Profile Configuration (Single Source of Truth)
+ *
+ * This is the primary configuration interface for v0.7.0, replacing the previous
+ * three-tier system (user/derived/deploy). All configuration is now unified in
+ * a single structured format.
  *
- * User-provided settings that define the core configuration.
- * This is the primary configuration file edited by users.
+ * @example
+ * ```json
+ * {
+ *   "quilt": {
+ *     "stackArn": "arn:aws:cloudformation:...",
+ *     "catalog": "https://quilt.example.com",
+ *     "bucket": "my-quilt-bucket",
+ *     "database": "quilt_catalog",
+ *     "queueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/quilt-queue",
+ *     "region": "us-east-1"
+ *   },
+ *   "benchling": {
+ *     "tenant": "my-tenant",
+ *     "clientId": "client_123",
+ *     "secretArn": "arn:aws:secretsmanager:...",
+ *     "appDefinitionId": "app_456"
+ *   },
+ *   "packages": {
+ *     "bucket": "benchling-packages",
+ *     "prefix": "benchling",
+ *     "metadataKey": "experiment_id"
+ *   },
+ *   "deployment": {
+ *     "region": "us-east-1",
+ *     "imageTag": "latest"
+ *   },
+ *   "_metadata": {
+ *     "version": "0.7.0",
+ *     "createdAt": "2025-11-04T10:00:00Z",
+ *     "updatedAt": "2025-11-04T10:00:00Z",
+ *     "source": "wizard"
+ *   }
+ * }
+ * ```
  */
-export interface UserConfig {
+export interface ProfileConfig {
     /**
-     * Quilt catalog URL (e.g., "https://quilt.example.com")
+     * Quilt catalog and infrastructure configuration
      */
-    quiltCatalog?: string;
+    quilt: QuiltConfig;
     /**
-     * Quilt user bucket name for package storage
+     * Benchling tenant and OAuth configuration
      */
-    quiltUserBucket?: string;
+    benchling: BenchlingConfig;
     /**
-     * Quilt database (Athena/Glue) identifier
+     * Package storage and metadata configuration
      */
-    quiltDatabase?: string;
+    packages: PackageConfig;
     /**
-     * Quilt CloudFormation stack ARN
+     * AWS deployment configuration (CDK)
      */
-    quiltStackArn?: string;
+    deployment: DeploymentConfig;
     /**
-     * AWS region for Quilt resources
+     * Optional logging configuration
      */
-    quiltRegion?: string;
+    logging?: LoggingConfig;
     /**
-     * Benchling tenant identifier
+     * Optional security configuration (webhook verification, IP allowlist)
      */
-    benchlingTenant?: string;
+    security?: SecurityConfig;
     /**
-     * Benchling OAuth client ID
+     * Configuration metadata (provenance, versioning, timestamps)
      */
-    benchlingClientId?: string;
+    _metadata: ConfigMetadata;
     /**
-     * Benchling OAuth client secret (stored in Secrets Manager in production)
+     * Optional profile inheritance (for profile hierarchies)
+     *
+     * When present, this profile inherits configuration from the specified base profile.
+     * Values in this profile override inherited values via deep merge.
+     *
+     * @example "_inherits": "default"
      */
-    benchlingClientSecret?: string;
+    _inherits?: string;
+}
+/**
+ * Quilt Catalog Configuration
+ *
+ * Configuration for Quilt data catalog integration, including CloudFormation stack
+ * and SQS queue for package creation.
+ */
+export interface QuiltConfig {
     /**
-     * Benchling app definition ID
+     * Quilt CloudFormation stack ARN
+     *
+     * @example "arn:aws:cloudformation:us-east-1:123456789012:stack/quilt-stack/..."
      */
-    benchlingAppDefinitionId?: string;
+    stackArn: string;
     /**
-     * S3 bucket for Benchling package storage
+     * Quilt catalog domain (without protocol)
+     *
+     * @example "quilt.example.com"
      */
-    benchlingPkgBucket?: string;
+    catalog: string;
     /**
-     * Benchling test entry ID (optional, for validation)
+     * Athena/Glue database name for catalog metadata
+     *
+     * @example "quilt_catalog"
      */
-    benchlingTestEntry?: string;
+    database: string;
     /**
-     * AWS Secrets Manager secret ARN for Benchling credentials
+     * SQS queue URL for package creation jobs
+     *
+     * @example "https://sqs.us-east-1.amazonaws.com/123456789012/quilt-package-queue"
      */
-    benchlingSecretArn?: string;
+    queueUrl: string;
     /**
-     * AWS account ID for CDK deployment
+     * AWS region for Quilt resources
+     *
+     * @example "us-east-1"
      */
-    cdkAccount?: string;
+    region: string;
+}
+/**
+ * Benchling Configuration
+ *
+ * OAuth credentials and tenant information for Benchling API integration.
+ */
+export interface BenchlingConfig {
     /**
-     * AWS region for CDK deployment
+     * Benchling tenant identifier (subdomain)
+     *
+     * @example "my-company"
      */
-    cdkRegion?: string;
+    tenant: string;
     /**
-     * AWS profile to use for deployment operations
+     * OAuth client ID
+     *
+     * @example "client_abc123"
      */
-    awsProfile?: string;
+    clientId: string;
     /**
-     * SQS queue ARN for package creation
+     * OAuth client secret (optional, for local dev only)
+     *
+     * For production, use `secretArn` instead to reference AWS Secrets Manager.
+     *
+     * @example "secret_xyz789"
      */
-    queueArn?: string;
+    clientSecret?: string;
     /**
-     * S3 key prefix for Benchling packages
+     * AWS Secrets Manager ARN for OAuth credentials (production)
+     *
+     * @example "arn:aws:secretsmanager:us-east-1:123456789012:secret:benchling-..."
      */
-    pkgPrefix?: string;
+    secretArn?: string;
     /**
-     * Package metadata key (e.g., "experiment_id")
+     * Benchling app definition ID
+     *
+     * @example "app_def_456"
      */
-    pkgKey?: string;
+    appDefinitionId: string;
     /**
-     * Logging level (DEBUG, INFO, WARNING, ERROR)
+     * Test entry ID for validation (optional)
+     *
+     * @example "etr_abc123"
      */
-    logLevel?: string;
+    testEntryId?: string;
+}
+/**
+ * Package Configuration
+ *
+ * S3 storage and metadata settings for Benchling packages.
+ */
+export interface PackageConfig {
     /**
-     * Comma-separated IP allowlist for webhook access
+     * S3 bucket for package storage
+     *
+     * @example "benchling-packages"
      */
-    webhookAllowList?: string;
+    bucket: string;
     /**
-     * Enable webhook signature verification
+     * S3 key prefix for packages
+     *
+     * @example "benchling"
+     * @default "benchling"
      */
-    enableWebhookVerification?: string;
+    prefix: string;
     /**
-     * Create ECR repository flag
+     * Metadata key for package organization
+     *
+     * @example "experiment_id"
+     * @default "experiment_id"
      */
-    createEcrRepository?: string;
+    metadataKey: string;
+}
+/**
+ * Deployment Configuration
+ *
+ * AWS infrastructure settings for CDK deployment.
+ */
+export interface DeploymentConfig {
     /**
-     * ECR repository name
+     * AWS region for deployment
+     *
+     * @example "us-east-1"
      */
-    ecrRepositoryName?: string;
+    region: string;
     /**
-     * Docker image tag
+     * AWS account ID (optional, auto-detected if not provided)
+     *
+     * @example "123456789012"
      */
-    imageTag?: string;
+    account?: string;
     /**
-     * Configuration metadata (optional)
+     * ECR repository name (optional, default: "benchling-webhook")
+     *
+     * @example "my-custom-repo"
      */
-    _metadata?: ConfigMetadata;
+    ecrRepository?: string;
+    /**
+     * Docker image tag
+     *
+     * @example "latest"
+     * @example "0.7.0"
+     * @default "latest"
+     */
+    imageTag?: string;
 }
 /**
- * Derived Configuration
+ * Logging Configuration
  *
- * Configuration values inferred from CLI tools (e.g., quilt3 config)
- * or computed from user configuration.
+ * Python logging level for Flask application.
  */
-export interface DerivedConfig extends UserConfig {
+export interface LoggingConfig {
     /**
-     * Catalog URL inferred from quilt3 CLI
+     * Python logging level
+     *
+     * @default "INFO"
      */
-    catalogUrl?: string;
-    /**
-     * Metadata tracking inference source and timestamp
-     */
-    _metadata?: ConfigMetadata & {
-        inferredAt?: string;
-        inferredFrom?: string;
-    };
+    level: "DEBUG" | "INFO" | "WARNING" | "ERROR";
 }
 /**
- * Deployment Configuration
+ * Security Configuration
  *
- * Configuration artifacts generated during deployment.
- * Contains deployment-specific values like webhook URLs and stack ARNs.
+ * Webhook security settings including IP allowlist and signature verification.
  */
-export interface DeploymentConfig extends DerivedConfig {
-    /**
-     * Deployed webhook endpoint URL
-     */
-    webhookEndpoint?: string;
-    /**
-     * Deployed webhook URL (alias for webhookEndpoint)
-     */
-    webhookUrl?: string;
-    /**
-     * CloudFormation stack ARN
-     */
-    stackArn?: string;
+export interface SecurityConfig {
     /**
-     * Deployment timestamp
+     * Comma-separated list of allowed IP addresses/CIDR blocks
+     *
+     * Empty string means no IP filtering.
+     *
+     * @example "192.168.1.0/24,10.0.0.0/8"
+     * @default ""
      */
-    deploymentTimestamp?: string;
-    /**
-     * ISO timestamp of deployment
-     */
-    deployedAt?: string;
+    webhookAllowList?: string;
     /**
-     * Metadata tracking deployment details
+     * Enable webhook signature verification
+     *
+     * @default true
      */
-    _metadata?: ConfigMetadata & {
-        deployedAt?: string;
-        deployedBy?: string;
-        stackName?: string;
-    };
+    enableVerification?: boolean;
 }
 /**
  * Configuration Metadata
  *
- * Tracks configuration provenance, timestamps, and versioning.
+ * Provenance tracking for configuration files.
  */
 export interface ConfigMetadata {
     /**
-     * ISO timestamp when configuration was saved
+     * Configuration schema version
+     *
+     * @example "0.7.0"
+     */
+    version: string;
+    /**
+     * ISO 8601 timestamp when configuration was created
+     *
+     * @example "2025-11-04T10:00:00Z"
      */
-    savedAt?: string;
+    createdAt: string;
     /**
-     * Source of configuration (e.g., "cli", "wizard", "manual")
+     * ISO 8601 timestamp when configuration was last updated
+     *
+     * @example "2025-11-04T15:30:00Z"
      */
-    source?: string;
+    updatedAt: string;
     /**
-     * Configuration version
+     * Source of configuration
+     *
+     * - "wizard": Created via interactive setup wizard
+     * - "manual": Hand-edited by user
+     * - "cli": Created via CLI command
      */
-    version?: string;
+    source: "wizard" | "manual" | "cli";
     /**
-     * Additional metadata fields
+     * Additional metadata fields (extensible)
      */
     [key: string]: string | undefined;
 }
 /**
- * Complete Configuration
+ * Deployment History
  *
- * Merged configuration from all sources (user + derived + deploy).
+ * Tracks all deployments for a profile, with active deployment pointers per stage.
  */
-export type CompleteConfig = DeploymentConfig;
-/**
- * Configuration Set
- *
- * Collection of configurations for merging operations.
- */
-export interface ConfigSet {
-    user?: UserConfig;
-    derived?: DerivedConfig;
-    deploy?: DeploymentConfig;
+export interface DeploymentHistory {
+    /**
+     * Active deployments by stage name
+     *
+     * Maps stage name (e.g., "dev", "prod") to the currently active deployment.
+     *
+     * @example
+     * ```json
+     * {
+     *   "dev": { "stage": "dev", "endpoint": "https://...", "imageTag": "latest", ... },
+     *   "prod": { "stage": "prod", "endpoint": "https://...", "imageTag": "0.7.0", ... }
+     * }
+     * ```
+     */
+    active: Record<string, DeploymentRecord>;
+    /**
+     * Complete deployment history (newest first)
+     *
+     * All past deployments for this profile, ordered by timestamp descending.
+     */
+    history: DeploymentRecord[];
 }
 /**
- * Configuration Profile
+ * Deployment Record
  *
- * Named configuration with metadata for profile management.
+ * A single deployment event with full metadata for debugging and rollback.
  */
-export interface ConfigProfile {
+export interface DeploymentRecord {
     /**
-     * Profile name (e.g., "default", "dev", "prod")
+     * API Gateway stage name
+     *
+     * @example "dev"
+     * @example "prod"
      */
-    name: ProfileName;
+    stage: string;
     /**
-     * User configuration for this profile
+     * ISO 8601 deployment timestamp
+     *
+     * @example "2025-11-04T10:30:00Z"
      */
-    user?: UserConfig;
+    timestamp: string;
     /**
-     * Derived configuration for this profile
+     * Docker image tag deployed
+     *
+     * @example "latest"
+     * @example "0.7.0"
      */
-    derived?: DerivedConfig;
+    imageTag: string;
     /**
-     * Deployment configuration for this profile
+     * Deployed webhook endpoint URL
+     *
+     * @example "https://abc123.execute-api.us-east-1.amazonaws.com/dev"
      */
-    deploy?: DeploymentConfig;
+    endpoint: string;
     /**
-     * Profile metadata
+     * CloudFormation stack name
+     *
+     * @example "BenchlingWebhookStack"
      */
-    metadata?: {
-        createdAt?: string;
-        updatedAt?: string;
-        description?: string;
-    };
+    stackName: string;
+    /**
+     * AWS region
+     *
+     * @example "us-east-1"
+     */
+    region: string;
+    /**
+     * User who triggered deployment (optional)
+     *
+     * @example "ernest@example.com"
+     */
+    deployedBy?: string;
+    /**
+     * Git commit hash (optional)
+     *
+     * @example "abc123f"
+     */
+    commit?: string;
+    /**
+     * Additional metadata (extensible)
+     */
+    [key: string]: string | undefined;
 }
 /**
  * Configuration Validation Result
@@ -259,7 +411,7 @@ export interface ValidationResult {
      */
     isValid: boolean;
     /**
-     * Validation errors (if any)
+     * Validation errors (fatal issues that prevent deployment)
      */
     errors: string[];
     /**
@@ -272,23 +424,31 @@ export interface ValidationResult {
     details?: Record<string, unknown>;
 }
 /**
- * XDG Configuration Paths
+ * Migration Report
  *
- * File paths for XDG-compliant configuration storage.
+ * Result of migrating from legacy configuration format.
  */
-export interface XDGConfigPaths {
+export interface MigrationReport {
     /**
-     * Path to user configuration file
+     * Whether migration completed successfully
      */
-    userConfig: string;
+    success: boolean;
     /**
-     * Path to derived configuration file
+     * Profiles that were successfully migrated
      */
-    derivedConfig: string;
+    profilesMigrated: string[];
     /**
-     * Path to deployment configuration file
+     * Migration errors
      */
-    deployConfig: string;
+    errors: string[];
+    /**
+     * Migration warnings (non-fatal issues)
+     */
+    warnings?: string[];
+    /**
+     * Additional migration details
+     */
+    details?: Record<string, unknown>;
 }
 /**
  * Profile Management Options
@@ -308,91 +468,237 @@ export interface ProfileOptions {
     createIfMissing?: boolean;
 }
 /**
- * Configuration Read Options
- */
-export interface ConfigReadOptions {
-    /**
-     * Configuration type to read
-     */
-    type: ConfigType;
-    /**
-     * Profile name (defaults to "default")
-     */
-    profile?: ProfileName;
-    /**
-     * Throw error if file doesn't exist
-     */
-    throwIfMissing?: boolean;
-    /**
-     * Validate schema after reading
-     */
-    validate?: boolean;
-}
-/**
- * Configuration Write Options
- */
-export interface ConfigWriteOptions {
-    /**
-     * Configuration type to write
-     */
-    type: ConfigType;
-    /**
-     * Profile name (defaults to "default")
-     */
-    profile?: ProfileName;
-    /**
-     * Create backup before writing
-     */
-    backup?: boolean;
-    /**
-     * Validate schema before writing
-     */
-    validate?: boolean;
-    /**
-     * Add metadata to configuration
-     */
-    addMetadata?: boolean;
-}
-/**
- * AWS Profile Configuration
+ * JSON Schema for ProfileConfig validation
  *
- * Integration with AWS credentials and profiles.
+ * This schema can be used with ajv or other JSON Schema validators.
  */
-export interface AWSProfileConfig {
-    /**
-     * AWS profile name from ~/.aws/credentials
-     */
-    profileName: string;
-    /**
-     * AWS region
-     */
-    region?: string;
-    /**
-     * AWS account ID
-     */
-    accountId?: string;
-}
+export declare const ProfileConfigSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "ProfileConfig";
+    readonly description: "Benchling Webhook Profile Configuration (v0.7.0)";
+    readonly type: "object";
+    readonly required: readonly ["quilt", "benchling", "packages", "deployment", "_metadata"];
+    readonly properties: {
+        readonly quilt: {
+            readonly type: "object";
+            readonly required: readonly ["stackArn", "catalog", "database", "queueUrl", "region"];
+            readonly properties: {
+                readonly stackArn: {
+                    readonly type: "string";
+                    readonly pattern: "^arn:aws:cloudformation:";
+                };
+                readonly catalog: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly database: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly queueUrl: {
+                    readonly type: "string";
+                    readonly pattern: "^https://sqs\\.[a-z0-9-]+\\.amazonaws\\.com/\\d{12}/.+";
+                };
+                readonly region: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z]{2}-[a-z]+-[0-9]$";
+                };
+            };
+        };
+        readonly benchling: {
+            readonly type: "object";
+            readonly required: readonly ["tenant", "clientId", "appDefinitionId"];
+            readonly properties: {
+                readonly tenant: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly clientId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly clientSecret: {
+                    readonly type: "string";
+                };
+                readonly secretArn: {
+                    readonly type: "string";
+                    readonly pattern: "^arn:aws:secretsmanager:";
+                };
+                readonly appDefinitionId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly testEntryId: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly packages: {
+            readonly type: "object";
+            readonly required: readonly ["bucket", "prefix", "metadataKey"];
+            readonly properties: {
+                readonly bucket: {
+                    readonly type: "string";
+                    readonly minLength: 3;
+                };
+                readonly prefix: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly metadataKey: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly deployment: {
+            readonly type: "object";
+            readonly required: readonly ["region"];
+            readonly properties: {
+                readonly region: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z]{2}-[a-z]+-[0-9]$";
+                };
+                readonly account: {
+                    readonly type: "string";
+                    readonly pattern: "^[0-9]{12}$";
+                };
+                readonly ecrRepository: {
+                    readonly type: "string";
+                };
+                readonly imageTag: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly logging: {
+            readonly type: "object";
+            readonly properties: {
+                readonly level: {
+                    readonly type: "string";
+                    readonly enum: readonly ["DEBUG", "INFO", "WARNING", "ERROR"];
+                };
+            };
+        };
+        readonly security: {
+            readonly type: "object";
+            readonly properties: {
+                readonly webhookAllowList: {
+                    readonly type: "string";
+                };
+                readonly enableVerification: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly _metadata: {
+            readonly type: "object";
+            readonly required: readonly ["version", "createdAt", "updatedAt", "source"];
+            readonly properties: {
+                readonly version: {
+                    readonly type: "string";
+                };
+                readonly createdAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                };
+                readonly updatedAt: {
+                    readonly type: "string";
+                    readonly format: "date-time";
+                };
+                readonly source: {
+                    readonly type: "string";
+                    readonly enum: readonly ["wizard", "manual", "cli"];
+                };
+            };
+        };
+        readonly _inherits: {
+            readonly type: "string";
+        };
+    };
+    readonly additionalProperties: false;
+};
 /**
- * Quilt CLI Configuration
- *
- * Configuration inferred from quilt3 CLI.
+ * JSON Schema for DeploymentHistory validation
  */
-export interface QuiltCLIConfig {
-    /**
-     * Catalog URL from quilt3 config
-     */
-    catalog?: string;
-    /**
-     * Default bucket from quilt3 config
-     */
-    defaultBucket?: string;
-    /**
-     * AWS region from quilt3 config
-     */
-    region?: string;
-    /**
-     * Registry URL from quilt3 config
-     */
-    registryUrl?: string;
-}
+export declare const DeploymentHistorySchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "DeploymentHistory";
+    readonly description: "Deployment tracking for a profile";
+    readonly type: "object";
+    readonly required: readonly ["active", "history"];
+    readonly properties: {
+        readonly active: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "object";
+                readonly required: readonly ["stage", "timestamp", "imageTag", "endpoint", "stackName", "region"];
+                readonly properties: {
+                    readonly stage: {
+                        readonly type: "string";
+                    };
+                    readonly timestamp: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly imageTag: {
+                        readonly type: "string";
+                    };
+                    readonly endpoint: {
+                        readonly type: "string";
+                        readonly format: "uri";
+                    };
+                    readonly stackName: {
+                        readonly type: "string";
+                    };
+                    readonly region: {
+                        readonly type: "string";
+                    };
+                    readonly deployedBy: {
+                        readonly type: "string";
+                    };
+                    readonly commit: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly history: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["stage", "timestamp", "imageTag", "endpoint", "stackName", "region"];
+                readonly properties: {
+                    readonly stage: {
+                        readonly type: "string";
+                    };
+                    readonly timestamp: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly imageTag: {
+                        readonly type: "string";
+                    };
+                    readonly endpoint: {
+                        readonly type: "string";
+                        readonly format: "uri";
+                    };
+                    readonly stackName: {
+                        readonly type: "string";
+                    };
+                    readonly region: {
+                        readonly type: "string";
+                    };
+                    readonly deployedBy: {
+                        readonly type: "string";
+                    };
+                    readonly commit: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+    readonly additionalProperties: false;
+};
 //# sourceMappingURL=config.d.ts.map