@maykonpaulo/maestro-core 0.3.0-rc.0 → 0.4.0

package/dist/index.d.ts

@@ -632,14 +632,150 @@ interface RelationSchema {
     display?: RelationDisplayConfig;
 }
 
+type OperationalRisk = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+
+interface RiskClassificationInput {
+    operation: string;
+    resource?: ResourceRef;
+    metadata?: Metadata;
+}
+interface RiskClassifier {
+    classify(input: RiskClassificationInput): OperationalRisk;
+}
+
+declare class MetadataRiskClassifier implements RiskClassifier {
+    private readonly operationRiskMap;
+    private readonly defaultRisk;
+    constructor(operationRiskMap?: Record<string, OperationalRisk>, defaultRisk?: OperationalRisk);
+    classify(input: RiskClassificationInput): OperationalRisk;
+}
+
+interface EnumOptionDeclaration {
+    value: string | number;
+    label: string;
+}
+interface FieldDeclaration {
+    type: FieldType;
+    label?: string;
+    required?: boolean;
+    readonly?: boolean;
+    primary?: boolean;
+    sensitive?: boolean;
+    visible?: boolean;
+    searchable?: boolean;
+    sortable?: boolean;
+    filterable?: boolean;
+    exportable?: boolean;
+    description?: string;
+    /** Options for enum fields. Only valid when type is 'enum'. */
+    enumOptions?: EnumOptionDeclaration[];
+    /** Target entity identifier for relation fields. Only valid when type is 'relation'. */
+    relationEntity?: string;
+}
+interface ConfirmationDeclaration {
+    required: boolean;
+    approvers?: number;
+}
+interface OperationDeclaration {
+    label: string;
+    description?: string;
+    scope?: OperationScope;
+    risk?: OperationalRisk;
+    audit?: boolean;
+    confirmation?: ConfirmationDeclaration;
+    permission?: string;
+}
+interface RelationDeclaration {
+    /** Explicit relation identifier. Derived as `${fromEntity}.${toEntity}` when absent. */
+    id?: string;
+    type: RelationType;
+    /** Field in the declaring entity that holds the foreign key or join key. */
+    fromField: string;
+    /** Identifier of the target entity. Cross-entity references are validated at startup. */
+    toEntity: string;
+    /** Field in the target entity that the relation points to. */
+    toField: string;
+    /** Human-readable label. Defaults to capitalizeFirst(toEntity) when absent. */
+    label?: string;
+    display?: {
+        tab?: boolean;
+        label?: string;
+    };
+}
+interface EntityDeclaration {
+    entity: string;
+    /** Human-readable singular label (e.g. "User"). */
+    label?: string;
+    /** Human-readable plural label (e.g. "Users"). Defaults to `label` when absent. */
+    pluralLabel?: string;
+    description?: string;
+    fields: Record<string, FieldDeclaration>;
+    /** Capability overrides merged over DEFAULT_CAPABILITIES at startup. */
+    capabilities?: Partial<EntityCapabilities>;
+    operations?: Record<string, OperationDeclaration>;
+    /** Relationships from this entity to other entities. Cross-entity refs are validated at startup. */
+    relationships?: RelationDeclaration[];
+}
+
+interface ConsumerListConfig {
+    fields?: string[];
+}
+interface ConsumerDetailConfig {
+    fields?: string[];
+}
+interface ConsumerFormConfig {
+    fields?: string[];
+}
+interface ConsumerFormsConfig {
+    create?: ConsumerFormConfig;
+    update?: ConsumerFormConfig;
+    clone?: ConsumerFormConfig;
+}
+interface ConsumerActionsConfig {
+    row?: string[];
+    bulk?: string[];
+    global?: string[];
+}
+interface ConsumerDeclaration {
+    consumer: string;
+    entity: string;
+    list?: ConsumerListConfig;
+    detail?: ConsumerDetailConfig;
+    forms?: ConsumerFormsConfig;
+    actions?: ConsumerActionsConfig;
+}
+
+interface DeclarativeConfig {
+    entities: EntityDeclaration[];
+    consumers?: ConsumerDeclaration[];
+    /**
+     * Datasource ID to use for all declared entities that don't specify one.
+     * Required when more than one datasource is configured in the engine.
+     * When only one datasource is configured, it is used automatically.
+     */
+    defaultDatasource?: string;
+}
+
 interface MaestroConfig {
     datasources: Record<string, DatasourceProvider>;
-    entities: EntitySchema[];
+    /**
+     * Entities defined using the low-level EntitySchema format.
+     * Can be combined with `declarations.entities` or used alone.
+     * Required when `declarations` is not provided.
+     */
+    entities?: EntitySchema[];
     relations?: RelationSchema[];
     operations?: OperationDef[];
     policies?: RbacPolicy;
     audit?: AuditRepository;
     logger?: Logger;
+    /**
+     * Declarative entity and consumer definitions.
+     * Entities declared here are compiled to EntitySchema and merged with `entities`.
+     * Operations declared here are registered as stubs; provide real implementations in `operations`.
+     * Required when `entities` is not provided.
+     */
+    declarations?: DeclarativeConfig;
 }
 
 interface SchemaValidationError {
@@ -668,14 +804,49 @@ interface ExportResult {
     mimeType: string;
 }
 
+interface ConsumerProjectionFields {
+    list: FieldMetadata[];
+    detail: FieldMetadata[];
+    create: FieldMetadata[];
+    update: FieldMetadata[];
+    clone: FieldMetadata[];
+}
+interface ConsumerProjectionOperations {
+    row: OperationMetadata[];
+    bulk: OperationMetadata[];
+    global: OperationMetadata[];
+}
+/**
+ * A resolved, runtime projection of a ConsumerDeclaration against a compiled EntityMetadata.
+ * Contains FieldMetadata and OperationMetadata objects — not raw names — ready for consumption
+ * by UI, API, or CLI layers.
+ */
+interface ResolvedConsumerProjection {
+    consumer: string;
+    entity: string;
+    fields: ConsumerProjectionFields;
+    operations: ConsumerProjectionOperations;
+}
+
 declare class MaestroEngine {
     private readonly metadata;
     private readonly datasources;
     private readonly operations;
     private readonly audit?;
     private readonly rbac;
-    constructor(metadata: MaestroMetadata, datasources: DatasourceRegistry, operations: OperationRegistry, audit?: AuditRecorder | undefined);
+    private readonly consumerMap;
+    constructor(metadata: MaestroMetadata, datasources: DatasourceRegistry, operations: OperationRegistry, audit?: AuditRecorder | undefined, consumers?: ResolvedConsumerProjection[]);
     getMetadata(): MaestroMetadata;
+    /**
+     * Returns the resolved consumer projection for the given consumer ID, or undefined if not found.
+     * Each call returns an independent copy — mutations to the returned object do not affect internal state.
+     * Consumer projections are only available when declarations.consumers were provided to createMaestro().
+     */
+    getConsumer(consumerId: string): ResolvedConsumerProjection | undefined;
+    /**
+     * Returns the IDs of all registered consumer projections.
+     */
+    listConsumers(): string[];
     list(entityId: string, query: QueryInput, actor: Actor): Promise<ListResult<Record<string, unknown>>>;
     findById(entityId: string, id: string, actor: Actor): Promise<Record<string, unknown> | null>;
     create(entityId: string, data: Record<string, unknown>, actor: Actor): Promise<Record<string, unknown>>;
@@ -1019,24 +1190,6 @@ interface CorrelationContext {
     correlationId: CorrelationId;
 }
 
-type OperationalRisk = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
-
-interface RiskClassificationInput {
-    operation: string;
-    resource?: ResourceRef;
-    metadata?: Metadata;
-}
-interface RiskClassifier {
-    classify(input: RiskClassificationInput): OperationalRisk;
-}
-
-declare class MetadataRiskClassifier implements RiskClassifier {
-    private readonly operationRiskMap;
-    private readonly defaultRisk;
-    constructor(operationRiskMap?: Record<string, OperationalRisk>, defaultRisk?: OperationalRisk);
-    classify(input: RiskClassificationInput): OperationalRisk;
-}
-
 type AuthorizationDecision = 'ALLOW' | 'DENY' | 'REQUIRES_CONFIRMATION';
 
 interface AuthorizationContext {
@@ -1173,6 +1326,35 @@ declare class InMemoryConfirmationRepository implements ConfirmationRepository {
     listPending(): Promise<ConfirmationRequest[]>;
 }
 
+interface DeclarativeCompilationResult {
+    valid: boolean;
+    errors: SchemaValidationError[];
+    entities: EntitySchema[];
+    /** Operation stubs for declared operations. Real implementations in config.operations override these. */
+    operations: OperationDef[];
+    /** Validated consumer declarations ready for resolution after metadata is built. */
+    consumers: ConsumerDeclaration[];
+    /** Relation schemas derived from RelationDeclaration[]. Cross-entity refs validated at startup. */
+    relations: RelationSchema[];
+}
+interface CompileDeclarationsOptions {
+    datasourceIds: string[];
+    /**
+     * Datasource to assign to all declared entities.
+     * Resolved by the caller: either declarations.defaultDatasource or the single available datasource.
+     */
+    defaultDatasource?: string;
+}
+declare function compileDeclarations(config: DeclarativeConfig, options: CompileDeclarationsOptions): DeclarativeCompilationResult;
+/**
+ * Resolves validated ConsumerDeclarations against the fully-built MaestroMetadata.
+ * Must be called after MetadataEngine.normalize() has produced the final EntityMetadata[].
+ */
+declare function resolveConsumerProjections(consumers: ConsumerDeclaration[], metadata: MaestroMetadata): ResolvedConsumerProjection[];
+
+declare function validateEntityDeclaration(input: unknown): SchemaValidationResult;
+declare function validateConsumerDeclaration(input: unknown, entity?: EntityDeclaration): SchemaValidationResult;
+
 declare const GOVERNANCE_EVENT_TYPES: {
     readonly OPERATION_EXECUTED: "governance.operation.executed";
     readonly AUTHORIZATION_DENIED: "governance.authorization.denied";
@@ -1246,4 +1428,4 @@ declare class DefaultGovernanceApi implements GovernanceApi {
     getPolicyViolations(filter?: PolicyViolationFilter): Promise<PolicyViolation[]>;
 }
 
-export { type Actor, type ActorType, type AuditEvent, type AuditFilter, type AuditLevel, type AuditRecordedPayload, AuditRecorder, type AuditRepository, type AuditTimeline, type AuthorizationContext, type AuthorizationDecision, type AuthorizationDeniedPayload, type AuthorizationProvider, type AuthorizationResult, type ConfigProvider, type ConfirmationApproval, type ConfirmationApprovedPayload, ConfirmationEngine, type ConfirmationRejectedPayload, type ConfirmationRepository, type ConfirmationRequest, type ConfirmationRequestedPayload, type ConfirmationStatus, ConsoleLogger, ConsoleStructuredLogger, type ContextAction, type ContextActionCondition, type ContextActionStyle, ContextualAuthorizationEngine, type CorrelationContext, type CorrelationId, type CreateMaestroFromIntrospectionOptions, CsvExportProvider, type CursorPagination, DEFAULT_CAPABILITIES, type DatasourceDeleteContext, type DatasourceFindContext, type DatasourceProvider, type DatasourceQueryContext, DatasourceRegistry, type DatasourceUpdateContext, type DatasourceWriteContext, DefaultGovernanceApi, type DiffChange, type DiffChangeKind, DiffEngine, type DiffEngineOptions, type DiffSummary, type DomainEvent, type EntityCapabilities, type EntityDiffChange, type EntityDiffChangeKind, type EntityExportConfig, type EntityIntrospectionSchema, type EntityLabelConfig, type EntityMetadata, type EntitySchema, type EntitySourceConfig, type EnumOption, ErrorCode, type EventBus, type EventHandler, type ExportConfig, type ExportFormat, type ExportOptions, type ExportProvider, type ExportResult, type FeatureFlag, type FeatureFlagProvider, type FieldDetailConfig, type FieldDiffChange, type FieldDiffChangeKind, type FieldFormConfig, type FieldIntrospectionSchema, type FieldListConfig, type FieldMetadata, type FieldSchema, type FieldSchemaDetailConfig, type FieldSchemaEnumOption, type FieldSchemaFormConfig, type FieldSchemaListConfig, type FieldType, type FileSystemReader, type FilterDescriptor, type FilterOperator, GOVERNANCE_EVENT_TYPES, type GeneratedConfig, type GovernanceApi, type GovernanceEventBus, type GovernanceEventType, type ImpactLevel, InMemoryAuditRepository, InMemoryConfigProvider, InMemoryConfirmationRepository, InMemoryDatasourceProvider, InMemoryEventBus, InMemoryFeatureFlagProvider, InMemoryGovernanceEventBus, InMemoryPolicyProvider, InMemorySnapshotRepository, type IndexIntrospectionSchema, type IntrospectionDiff, type IntrospectionProvider, type IntrospectionReport, type IntrospectionReportChange, type IntrospectionReportStats, type IntrospectionResult, IntrospectionRuntime, type IntrospectionRuntimeResult, type IntrospectionRuntimeRunOptions, type IntrospectionSnapshot, type ListResult, type LoadedConfig, type LogEntry, type LogLevel, type Logger, type MaestroActorResolver, type MaestroConfig, MaestroEngine, MaestroError, type MaestroFileLoaderOptions, type MaestroHttpHandler, type MaestroHttpHandlers, type MaestroHttpOptions, type MaestroHttpRequest, type MaestroHttpResponse, type MaestroMetadata, type MaestroRequestContext, type MergeIntrospectionOptions, type MergeStrategy, type Metadata, MetadataEngine, MetadataRiskClassifier, type MetadataValue, type OffsetPagination, type OperationContext, type OperationDef, type OperationExecutedPayload, type OperationLogStatus, type OperationMetadata, OperationRegistry, type OperationResult, type OperationScope, type OperationalRisk, type PagePagination, type PaginationInput, type Permission, type PolicyContext, type PolicyDecision, PolicyEngine, type PolicyEvaluationResult, type PolicyProvider, type PolicyRule, type PolicyRuleResult, type PolicyTriggeredPayload, type PolicyViolation, type PolicyViolationFilter, type QueryInput, RbacEngine, type RbacPolicy, type RecordAuditInput, type RelationDiffChange, type RelationDiffChangeKind, type RelationDisplayConfig, type RelationEndpoint, type RelationIntrospectionSchema, type RelationMetadata, type RelationSchema, type RelationType, ReportGenerator, type RequestConfirmationInput, type ResourceRef, type RiskClassificationInput, type RiskClassifier, type Role, type SchemaValidationError, type SchemaValidationResult, type SearchConfig, type SearchInput, type SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, tableNameToEntityId, tableNameToLabel, validateMaestroConfig };
+export { type Actor, type ActorType, type AuditEvent, type AuditFilter, type AuditLevel, type AuditRecordedPayload, AuditRecorder, type AuditRepository, type AuditTimeline, type AuthorizationContext, type AuthorizationDecision, type AuthorizationDeniedPayload, type AuthorizationProvider, type AuthorizationResult, type CompileDeclarationsOptions, type ConfigProvider, type ConfirmationApproval, type ConfirmationApprovedPayload, type ConfirmationDeclaration, ConfirmationEngine, type ConfirmationRejectedPayload, type ConfirmationRepository, type ConfirmationRequest, type ConfirmationRequestedPayload, type ConfirmationStatus, ConsoleLogger, ConsoleStructuredLogger, type ConsumerActionsConfig, type ConsumerDeclaration, type ConsumerDetailConfig, type ConsumerFormConfig, type ConsumerFormsConfig, type ConsumerListConfig, type ConsumerProjectionFields, type ConsumerProjectionOperations, type ContextAction, type ContextActionCondition, type ContextActionStyle, ContextualAuthorizationEngine, type CorrelationContext, type CorrelationId, type CreateMaestroFromIntrospectionOptions, CsvExportProvider, type CursorPagination, DEFAULT_CAPABILITIES, type DatasourceDeleteContext, type DatasourceFindContext, type DatasourceProvider, type DatasourceQueryContext, DatasourceRegistry, type DatasourceUpdateContext, type DatasourceWriteContext, type DeclarativeCompilationResult, type DeclarativeConfig, DefaultGovernanceApi, type DiffChange, type DiffChangeKind, DiffEngine, type DiffEngineOptions, type DiffSummary, type DomainEvent, type EntityCapabilities, type EntityDeclaration, type EntityDiffChange, type EntityDiffChangeKind, type EntityExportConfig, type EntityIntrospectionSchema, type EntityLabelConfig, type EntityMetadata, type EntitySchema, type EntitySourceConfig, type EnumOption, type EnumOptionDeclaration, ErrorCode, type EventBus, type EventHandler, type ExportConfig, type ExportFormat, type ExportOptions, type ExportProvider, type ExportResult, type FeatureFlag, type FeatureFlagProvider, type FieldDeclaration, type FieldDetailConfig, type FieldDiffChange, type FieldDiffChangeKind, type FieldFormConfig, type FieldIntrospectionSchema, type FieldListConfig, type FieldMetadata, type FieldSchema, type FieldSchemaDetailConfig, type FieldSchemaEnumOption, type FieldSchemaFormConfig, type FieldSchemaListConfig, type FieldType, type FileSystemReader, type FilterDescriptor, type FilterOperator, GOVERNANCE_EVENT_TYPES, type GeneratedConfig, type GovernanceApi, type GovernanceEventBus, type GovernanceEventType, type ImpactLevel, InMemoryAuditRepository, InMemoryConfigProvider, InMemoryConfirmationRepository, InMemoryDatasourceProvider, InMemoryEventBus, InMemoryFeatureFlagProvider, InMemoryGovernanceEventBus, InMemoryPolicyProvider, InMemorySnapshotRepository, type IndexIntrospectionSchema, type IntrospectionDiff, type IntrospectionProvider, type IntrospectionReport, type IntrospectionReportChange, type IntrospectionReportStats, type IntrospectionResult, IntrospectionRuntime, type IntrospectionRuntimeResult, type IntrospectionRuntimeRunOptions, type IntrospectionSnapshot, type ListResult, type LoadedConfig, type LogEntry, type LogLevel, type Logger, type MaestroActorResolver, type MaestroConfig, MaestroEngine, MaestroError, type MaestroFileLoaderOptions, type MaestroHttpHandler, type MaestroHttpHandlers, type MaestroHttpOptions, type MaestroHttpRequest, type MaestroHttpResponse, type MaestroMetadata, type MaestroRequestContext, type MergeIntrospectionOptions, type MergeStrategy, type Metadata, MetadataEngine, MetadataRiskClassifier, type MetadataValue, type OffsetPagination, type OperationContext, type OperationDeclaration, type OperationDef, type OperationExecutedPayload, type OperationLogStatus, type OperationMetadata, OperationRegistry, type OperationResult, type OperationScope, type OperationalRisk, type PagePagination, type PaginationInput, type Permission, type PolicyContext, type PolicyDecision, PolicyEngine, type PolicyEvaluationResult, type PolicyProvider, type PolicyRule, type PolicyRuleResult, type PolicyTriggeredPayload, type PolicyViolation, type PolicyViolationFilter, type QueryInput, RbacEngine, type RbacPolicy, type RecordAuditInput, type RelationDeclaration, type RelationDiffChange, type RelationDiffChangeKind, type RelationDisplayConfig, type RelationEndpoint, type RelationIntrospectionSchema, type RelationMetadata, type RelationSchema, type RelationType, ReportGenerator, type RequestConfirmationInput, type ResolvedConsumerProjection, type ResourceRef, type RiskClassificationInput, type RiskClassifier, type Role, type SchemaValidationError, type SchemaValidationResult, type SearchConfig, type SearchInput, type SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, compileDeclarations, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, resolveConsumerProjections, tableNameToEntityId, tableNameToLabel, validateConsumerDeclaration, validateEntityDeclaration, validateMaestroConfig };