@api-client/core 0.18.25 → 0.18.27

package/build/src/modeling/Semantics.d.ts

@@ -14,6 +14,13 @@ export declare enum SemanticType {
      * ensuring it is encrypted and not exposed in API responses.
      */
     Password = "Semantic#Password",
+    /**
+     * Annotates the field as the username for user authentication.
+     * This identifies which field should be used for login purposes.
+     * Can be applied to dedicated username fields or email fields that serve as usernames.
+     * The runtime uses this for authentication, password reset, and user lookup operations.
+     */
+    Username = "Semantic#Username",
     /**
      * Designates a Data Property as the `createdAt` timestamp of an entity.
      * This is used to track when the entity was first created.
@@ -163,6 +170,12 @@ export declare 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",
     /**
      * Designates an association that links a resource to a "User" entity instance.
      * This is used to indicate ownership of the resource for access control purposes.
@@ -277,6 +290,61 @@ export declare enum SemanticOperation {
      */
     List = "List"
 }
+/**
+ * Defines the execution mode for a semantic.
+ */
+export declare 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 declare 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 declare 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.
  */
@@ -298,6 +366,131 @@ export interface SemanticRuntimeConfig {
      * 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.

package/build/src/modeling/Semantics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Semantics.d.ts","sourceRoot":"","sources":["../../../src/modeling/Semantics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Semantics.d.ts","sourceRoot":"","sources":["../../../src/modeling/Semantics.ts"],"names":[],"mappings":"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"}

package/build/src/modeling/Semantics.js

@@ -20,6 +20,13 @@ export var SemanticType;
      * ensuring it is encrypted and not exposed in API responses.
      */
     SemanticType["Password"] = "Semantic#Password";
+    /**
+     * Annotates the field as the username for user authentication.
+     * This identifies which field should be used for login purposes.
+     * Can be applied to dedicated username fields or email fields that serve as usernames.
+     * The runtime uses this for authentication, password reset, and user lookup operations.
+     */
+    SemanticType["Username"] = "Semantic#Username";
     /**
      * Designates a Data Property as the `createdAt` timestamp of an entity.
      * This is used to track when the entity was first created.
@@ -169,6 +176,12 @@ export var SemanticType;
      * Annotates a field as derived from other fields.
      */
     SemanticType["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.
+     */
+    SemanticType["ClientIPAddress"] = "Semantic#ClientIPAddress";
     //
     // Association-Level Semantics
     //
@@ -290,6 +303,64 @@ export var SemanticOperation;
      */
     SemanticOperation["List"] = "List";
 })(SemanticOperation || (SemanticOperation = {}));
+/**
+ * Defines the execution mode for a semantic.
+ */
+export var SemanticExecutionMode;
+(function (SemanticExecutionMode) {
+    /**
+     * Execute synchronously as part of the main operation
+     */
+    SemanticExecutionMode["Synchronous"] = "Synchronous";
+    /**
+     * Execute asynchronously after the main operation
+     */
+    SemanticExecutionMode["Asynchronous"] = "Asynchronous";
+    /**
+     * Execute in background/queue (fire and forget)
+     */
+    SemanticExecutionMode["Background"] = "Background";
+})(SemanticExecutionMode || (SemanticExecutionMode = {}));
+/**
+ * Defines validation strategies for semantics.
+ */
+export var SemanticValidationStrategy;
+(function (SemanticValidationStrategy) {
+    /**
+     * Fail the operation if semantic validation fails
+     */
+    SemanticValidationStrategy["Strict"] = "Strict";
+    /**
+     * Log warnings but continue operation
+     */
+    SemanticValidationStrategy["Warning"] = "Warning";
+    /**
+     * Skip validation entirely
+     */
+    SemanticValidationStrategy["Skip"] = "Skip";
+})(SemanticValidationStrategy || (SemanticValidationStrategy = {}));
+/**
+ * Defines caching strategies for computed semantics.
+ */
+export var SemanticCacheStrategy;
+(function (SemanticCacheStrategy) {
+    /**
+     * No caching - always compute
+     */
+    SemanticCacheStrategy["None"] = "None";
+    /**
+     * Cache until dependent fields change
+     */
+    SemanticCacheStrategy["Dependency"] = "Dependency";
+    /**
+     * Cache with TTL expiration
+     */
+    SemanticCacheStrategy["TimeToLive"] = "TimeToLive";
+    /**
+     * Cache until manually invalidated
+     */
+    SemanticCacheStrategy["Manual"] = "Manual";
+})(SemanticCacheStrategy || (SemanticCacheStrategy = {}));
 /**
  * A type guard to check if a semantic is an EntitySemantic.
  */
@@ -335,6 +406,29 @@ export const DataSemantics = {
             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.Username]: {
+        id: SemanticType.Username,
+        displayName: 'Username',
+        scope: SemanticScope.Property,
+        description: 'User authentication identifier',
+        category: SemanticCategory.Identity,
+        applicableDataTypes: ['string'],
+        hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Read],
+            priority: 15, // High priority for authentication
+            canDisable: false, // Security semantics cannot be disabled
+            timeoutMs: 100, // Fast operation
         },
     },
     [SemanticType.UserRole]: {
@@ -392,6 +486,13 @@ export const DataSemantics = {
             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]: {
@@ -638,6 +739,27 @@ export const DataSemantics = {
             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',
+                },
+            ],
+        },
+    },
     //
     // Classification & Organization
     //
@@ -653,6 +775,18 @@ export const DataSemantics = {
             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]: {