@api-client/core 0.18.24 → 0.18.26

package/src/modeling/Semantics.ts

@@ -182,6 +182,12 @@ export enum SemanticType {
    * Annotates a field as derived from other fields.
    */
   Derived = 'Semantic#Derived',
+  /**
+   * Annotates a field that should automatically receive the client's IP address.
+   * The runtime automatically populates this field with the request's IP address
+   * when creating or updating records, providing audit trail and geolocation capabilities.
+   */
+  ClientIPAddress = 'Semantic#ClientIPAddress',
 
   //
   // Association-Level Semantics
@@ -270,6 +276,251 @@ export enum SemanticCategory {
   Computed = 'Computed Values',
 }
 
+/**
+ * Defines when a semantic should execute in relation to database operations.
+ */
+export enum SemanticTiming {
+  /**
+   * Execute before the database operation (validation, preprocessing)
+   */
+  Before = 'Before',
+  /**
+   * Execute after the database operation (cleanup, notifications, derived values)
+   */
+  After = 'After',
+  /**
+   * Execute both before and after the operation
+   */
+  Both = 'Both',
+  /**
+   * No automatic execution (manual/on-demand only)
+   */
+  None = 'None',
+}
+
+/**
+ * Defines which database operations can trigger a semantic.
+ */
+export enum SemanticOperation {
+  Create = 'Create',
+  Read = 'Read',
+  Update = 'Update',
+  Delete = 'Delete',
+  /**
+   * Special operation for list/query operations
+   */
+  List = 'List',
+}
+
+/**
+ * Defines the execution mode for a semantic.
+ */
+export enum SemanticExecutionMode {
+  /**
+   * Execute synchronously as part of the main operation
+   */
+  Synchronous = 'Synchronous',
+  /**
+   * Execute asynchronously after the main operation
+   */
+  Asynchronous = 'Asynchronous',
+  /**
+   * Execute in background/queue (fire and forget)
+   */
+  Background = 'Background',
+}
+
+/**
+ * Defines validation strategies for semantics.
+ */
+export enum SemanticValidationStrategy {
+  /**
+   * Fail the operation if semantic validation fails
+   */
+  Strict = 'Strict',
+  /**
+   * Log warnings but continue operation
+   */
+  Warning = 'Warning',
+  /**
+   * Skip validation entirely
+   */
+  Skip = 'Skip',
+}
+
+/**
+ * Defines caching strategies for computed semantics.
+ */
+export enum SemanticCacheStrategy {
+  /**
+   * No caching - always compute
+   */
+  None = 'None',
+  /**
+   * Cache until dependent fields change
+   */
+  Dependency = 'Dependency',
+  /**
+   * Cache with TTL expiration
+   */
+  TimeToLive = 'TimeToLive',
+  /**
+   * Cache until manually invalidated
+   */
+  Manual = 'Manual',
+}
+
+/**
+ * Configuration for when and how a semantic should execute at runtime.
+ */
+export interface SemanticRuntimeConfig {
+  /**
+   * When the semantic should execute relative to the database operation.
+   */
+  timing: SemanticTiming
+  /**
+   * Which database operations should trigger this semantic.
+   */
+  operations: SemanticOperation[]
+  /**
+   * Priority order for execution when multiple semantics apply.
+   * Lower numbers execute first. Default is 100.
+   */
+  priority?: number
+  /**
+   * Whether this semantic can be disabled at the entity/property level.
+   */
+  canDisable?: boolean
+  /**
+   * How the semantic should execute (sync/async/background).
+   * Default is Synchronous.
+   * @default Synchronous
+   */
+  executionMode?: SemanticExecutionMode
+  /**
+   * Validation strategy when semantic processing fails.
+   * Default is Strict.
+   * @default Strict
+   */
+  validationStrategy?: SemanticValidationStrategy
+  /**
+   * Maximum execution time in milliseconds before timeout.
+   * Default is 5000ms for sync, 30000ms for async.
+   * @default 5000 for sync, 30000 for async
+   */
+  timeoutMs?: number
+  /**
+   * Number of retry attempts on failure.
+   * Default is 0 (no retries).
+   * @default 0
+   */
+  retryAttempts?: number
+  /**
+   * Dependencies on other semantics that must execute first.
+   * Uses semantic IDs.
+   */
+  dependencies?: SemanticType[]
+  /**
+   * Fields that this semantic depends on for computation.
+   * Used for cache invalidation and optimization.
+   */
+  dependentFields?: string[]
+  /**
+   * Caching strategy for computed/derived values.
+   */
+  cacheStrategy?: SemanticCacheStrategy
+  /**
+   * Cache TTL in seconds (only used with TimeToLive strategy).
+   */
+  cacheTtlSeconds?: number
+  /**
+   * Whether this semantic should run in transactions.
+   * Default is true.
+   */
+  transactional?: boolean
+  /**
+   * Rate limiting configuration for expensive operations.
+   */
+  rateLimit?: SemanticRateLimit
+  /**
+   * Conditional execution based on data or context.
+   */
+  conditions?: SemanticCondition[]
+  /**
+   * Audit and logging configuration.
+   */
+  audit?: SemanticAudit
+}
+
+export interface SemanticRateLimit {
+  /**
+   * Maximum executions per time window.
+   */
+  maxExecutions: number
+  /**
+   * Time window in seconds.
+   */
+  windowSeconds: number
+  /**
+   * Strategy when rate limit is exceeded.
+   */
+  strategy: 'queue' | 'drop' | 'error'
+}
+
+export interface SemanticCondition {
+  /**
+   * JEXL expression that must evaluate to true for execution.
+   * Has access to entity data, user context, and semantic field references.
+   *
+   * Available context variables:
+   * - `entity`: The entity data being processed
+   * - `user`: Current user context (if authenticated)
+   * - `operation`: The current operation (Create, Update, etc.)
+   * - `semantics`: Object with semantic field accessors
+   *
+   * Semantic field references use dot notation:
+   * - `semantics.CreatedTimestamp` - field with CreatedTimestamp semantic
+   * - `semantics.Password` - field with Password semantic
+   * - `semantics.User` - entity with User semantic (for associations)
+   *
+   * @example
+   * // Only set timestamp if not already provided
+   * "semantics.CreatedTimestamp == null"
+   *
+   * @example
+   * // Only apply to authenticated users
+   * "user != null && user.authenticated == true"
+   *
+   * @example
+   * // Only hash password if it's a plain text (not already hashed)
+   * "entity[semantics.Password] != null && !entity[semantics.Password].startsWith('$')"
+   *
+   * @example
+   * // Only generate slug if title exists
+   * "entity[semantics.Title] != null && entity[semantics.Title].length > 0"
+   */
+  expression: string
+  /**
+   * Description of when this semantic should run.
+   */
+  description: string
+}
+
+export interface SemanticAudit {
+  /**
+   * Whether to log semantic execution.
+   */
+  logExecution: boolean
+  /**
+   * Whether to log input/output data.
+   */
+  logData: boolean
+  /**
+   * Retention period for audit logs in days.
+   */
+  retentionDays: number
+}
+
 /**
  * A base interface for all Data Semantics, containing common properties.
  * A semantic is an annotation applied to a Data Entity, Property, or Association
@@ -302,6 +553,10 @@ interface BaseDataSemantic {
    * This is used to determine if the semantic requires additional setup or configuration.
    */
   hasConfig: boolean
+  /**
+   * Runtime execution configuration for this semantic.
+   */
+  runtime: SemanticRuntimeConfig
 }
 
 /**
@@ -369,6 +624,10 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'System users and accounts',
     category: SemanticCategory.Identity,
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
   },
   [SemanticType.Password]: {
     id: SemanticType.Password,
@@ -378,6 +637,19 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Identity,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 10, // High priority for security
+      canDisable: false, // Security semantics cannot be disabled
+      timeoutMs: 2000, // Allow time for hashing
+      conditions: [
+        {
+          expression: 'entity[semantics.Password] != null && entity[semantics.Password].length > 0',
+          description: 'Only process when password field has a value',
+        },
+      ],
+    },
   },
   [SemanticType.UserRole]: {
     id: SemanticType.UserRole,
@@ -387,6 +659,17 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Identity,
     applicableDataTypes: ['string'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [
+        SemanticOperation.Create,
+        SemanticOperation.Read,
+        SemanticOperation.Update,
+        SemanticOperation.Delete,
+        SemanticOperation.List,
+      ],
+      priority: 20,
+    },
   },
   [SemanticType.ResourceOwnerIdentifier]: {
     id: SemanticType.ResourceOwnerIdentifier,
@@ -395,6 +678,18 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Links record to owner user',
     category: SemanticCategory.Identity,
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [
+        SemanticOperation.Create,
+        SemanticOperation.Read,
+        SemanticOperation.Update,
+        SemanticOperation.Delete,
+        SemanticOperation.List,
+      ],
+      priority: 5, // Very high priority for access control
+      canDisable: false,
+    },
   },
 
   //
@@ -409,6 +704,18 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create],
+      priority: 90,
+      timeoutMs: 100, // Very fast operation
+      conditions: [
+        {
+          expression: 'entity[semantics.CreatedTimestamp] == null',
+          description: 'Only set timestamp if not already provided',
+        },
+      ],
+    },
   },
   [SemanticType.UpdatedTimestamp]: {
     id: SemanticType.UpdatedTimestamp,
@@ -418,6 +725,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Update],
+      priority: 90,
+    },
   },
   [SemanticType.DeletedTimestamp]: {
     id: SemanticType.DeletedTimestamp,
@@ -427,6 +739,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Delete],
+      priority: 80,
+    },
   },
   [SemanticType.DeletedFlag]: {
     id: SemanticType.DeletedFlag,
@@ -436,6 +753,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['boolean'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Delete, SemanticOperation.Read, SemanticOperation.List],
+      priority: 80,
+    },
   },
   [SemanticType.Version]: {
     id: SemanticType.Version,
@@ -445,6 +767,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['number'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Update],
+      priority: 85,
+    },
   },
 
   //
@@ -459,6 +786,10 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
   },
   [SemanticType.Description]: {
     id: SemanticType.Description,
@@ -468,6 +799,10 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
   },
   [SemanticType.Summary]: {
     id: SemanticType.Summary,
@@ -477,6 +812,10 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
   },
   [SemanticType.Markdown]: {
     id: SemanticType.Markdown,
@@ -486,6 +825,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 50, // Process before storage
+    },
   },
   [SemanticType.HTML]: {
     id: SemanticType.HTML,
@@ -495,6 +839,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 50, // Process before storage for sanitization
+    },
   },
   [SemanticType.ImageURL]: {
     id: SemanticType.ImageURL,
@@ -504,6 +853,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 60, // Validate URLs before storage
+    },
   },
   [SemanticType.FileURL]: {
     id: SemanticType.FileURL,
@@ -513,6 +867,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
     hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 60, // Validate URLs before storage
+    },
   },
 
   //
@@ -527,6 +886,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Both,
+      operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Read, SemanticOperation.List],
+      priority: 30, // Validate state transitions before, filter by state after
+    },
   },
   [SemanticType.Currency]: {
     id: SemanticType.Currency,
@@ -536,6 +900,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Business,
     applicableDataTypes: ['number', 'string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 70, // Validate currency format and precision
+    },
   },
   [SemanticType.SKU]: {
     id: SemanticType.SKU,
@@ -545,6 +914,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 25, // High priority for uniqueness validation
+    },
   },
 
   //
@@ -559,6 +933,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 40, // Validate email format
+    },
   },
   [SemanticType.Phone]: {
     id: SemanticType.Phone,
@@ -568,6 +947,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 40, // Validate phone format
+    },
   },
   [SemanticType.URL]: {
     id: SemanticType.URL,
@@ -577,6 +961,32 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 40, // Validate URL format
+    },
+  },
+  [SemanticType.ClientIPAddress]: {
+    id: SemanticType.ClientIPAddress,
+    displayName: 'Client IP Address',
+    scope: SemanticScope.Property,
+    description: 'Automatically populated client IP address',
+    category: SemanticCategory.Contact,
+    applicableDataTypes: ['string'],
+    hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 95, // Low priority, populate after other validations
+      timeoutMs: 100, // Very fast operation
+      conditions: [
+        {
+          expression: 'entity[semantics.ClientIPAddress] == null',
+          description: 'Only set IP address if not already provided',
+        },
+      ],
+    },
   },
 
   //
@@ -591,6 +1001,23 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Organization,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Before,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 30, // Generate slug from title, validate uniqueness
+      timeoutMs: 1000,
+      conditions: [
+        {
+          expression: 'entity[semantics.PublicUniqueName] == null || entity[semantics.PublicUniqueName].length == 0',
+          description: 'Only generate slug if not already provided',
+        },
+        // Let's not guess which field is marked as slug source in the `PublicUniqueName` configuration.
+        // {
+        //   expression: 'entity[semantics.Title] != null && entity[semantics.Title].length > 0',
+        //   description: 'Only generate slug if title field exists and has content',
+        // },
+      ],
+    },
   },
   [SemanticType.Tags]: {
     id: SemanticType.Tags,
@@ -599,6 +1026,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Enable tagging functionality',
     category: SemanticCategory.Organization,
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.After,
+      operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Delete],
+      priority: 200, // Process after main operation
+    },
   },
   [SemanticType.Categories]: {
     id: SemanticType.Categories,
@@ -607,6 +1039,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Enable categorization functionality',
     category: SemanticCategory.Organization,
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.After,
+      operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Delete],
+      priority: 200, // Process after main operation
+    },
   },
 
   //
@@ -621,6 +1058,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Location,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Both,
+      operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Read, SemanticOperation.List],
+      priority: 60, // Validate coordinates before, enable spatial queries after
+    },
   },
 
   //
@@ -636,6 +1078,11 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Computed,
     applicableDataTypes: ['string', 'number', 'boolean', 'date', 'datetime', 'time', 'binary'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.Both,
+      operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Read],
+      priority: 150, // Calculate after other validations, recalculate on read if needed
+    },
   },
   [SemanticType.Derived]: {
     id: SemanticType.Derived,
@@ -645,9 +1092,55 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     category: SemanticCategory.Computed,
     applicableDataTypes: ['string'],
     hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.After,
+      operations: [SemanticOperation.Create, SemanticOperation.Update],
+      priority: 180, // Derive after all other processing
+    },
   },
 }
 
+/**
+ * Get all semantics that should run for a specific operation and timing
+ */
+export function getSemanticsForOperation(
+  semantics: AppliedDataSemantic[],
+  operation: SemanticOperation,
+  timing: SemanticTiming
+): AppliedDataSemantic[] {
+  return semantics
+    .filter((semantic) => {
+      const definition = DataSemantics[semantic.id]
+      if (!definition?.runtime) {
+        return false
+      }
+
+      const { timing: semanticTiming, operations } = definition.runtime
+
+      // Check if timing matches
+      const timingMatches = semanticTiming === timing || semanticTiming === SemanticTiming.Both
+
+      // Check if operation is included
+      const operationMatches = operations.includes(operation)
+
+      return timingMatches && operationMatches
+    })
+    .sort((a, b) => {
+      // Sort by priority (lower number = higher priority)
+      const priorityA = DataSemantics[a.id]?.runtime?.priority ?? 100
+      const priorityB = DataSemantics[b.id]?.runtime?.priority ?? 100
+      return priorityA - priorityB
+    })
+}
+
+/**
+ * Check if a specific semantic can be disabled at runtime
+ */
+export function canSemanticBeDisabled(semanticType: SemanticType): boolean {
+  const definition = DataSemantics[semanticType]
+  return definition?.runtime?.canDisable !== false // Default to true if not specified
+}
+
 export function getSemanticsByCategory(): Record<SemanticCategory, DataSemantic[]>
 export function getSemanticsByCategory(scope: SemanticScope.Entity): Record<SemanticCategory, EntitySemantic[]>
 export function getSemanticsByCategory(scope: SemanticScope.Property): Record<SemanticCategory, PropertySemantic[]>

package/src/modeling/definitions/Email.ts

@@ -79,7 +79,7 @@ export const createEmailSemantic = (config: EmailConfig = {}): AppliedEmailSeman
  * Default configuration for Email semantic.
  */
 export const DEFAULT_EMAIL_CONFIG: EmailConfig = {
-  requireVerification: false,
+  requireVerification: true,
   allowSubaddressing: true,
   allowInternational: true,
 }