@api-client/core 0.17.5 → 0.17.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.17.5",
+  "version": "0.17.7",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -88,7 +88,7 @@
     "@esm-bundle/chai": "^4.3.4-fix.0",
     "@metrichor/jmespath": "^0.3.1",
     "@pawel-up/data-mock": "^0.4.0",
-    "@pawel-up/jexl": "^3.0.0",
+    "@pawel-up/jexl": "^4.0.1",
     "@xmldom/xmldom": "^0.9.7",
     "amf-json-ld-lib": "^0.0.15",
     "chalk": "^5.4.1",

package/src/modeling/Semantics.ts

@@ -50,11 +50,12 @@ export enum SemanticType {
    */
   DeletedFlag = 'Semantic#DeletedFlag',
   /**
-   * Designates a Data Property as a unique public identifier for a resource (the slug).
+   * Designates a Data Property as a public identifier for a resource (the slug).
    * This is often used in URLs to provide a user-friendly way to access the resource.
    * For example, a blog post might have a public unique name like "my-first-post".
-   * A URL-friendly text field. The runtime automatically generates a unique, URL-safe string from another field (like a title or name). The user needs to specify which field is used to generate
-   * the slug.
+   * The runtime automatically generates a URL-safe string from another field (like a title).
+   * By default, slugs are generated to be unique, but the configuration allows for duplicates
+   * in scenarios where uniqueness is handled by a combination of fields (e.g., year and slug).
    */
   PublicUniqueName = 'Semantic#PublicUniqueName',
   /**
@@ -149,7 +150,10 @@ export enum SemanticType {
   /**
    * Annotates a field as a monetary value with currency support and precision control.
    * Can store simple decimal amounts or complex objects with amount and currency.
-   * Enforces proper decimal handling to avoid floating-point errors.
+   *
+   * As a semantic, it provides flexibility by annotating a base `number` or `string` type,
+   * allowing for different storage strategies (e.g., decimal, integer cents, or a JSON object)
+   * while maintaining a consistent API for currency operations.
    */
   Currency = 'Semantic#Currency',
   /**
@@ -623,13 +627,14 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
   // Computed Values
   //
 
+  // Calculated field can be added to any data type as we can compute any value.
   [SemanticType.Calculated]: {
     id: SemanticType.Calculated,
     displayName: 'Calculated',
     scope: SemanticScope.Property,
     description: 'Auto-calculated field value',
     category: SemanticCategory.Computed,
-    applicableDataTypes: ['string'],
+    applicableDataTypes: ['string', 'number', 'boolean', 'date', 'datetime', 'time', 'binary'],
     hasConfig: true,
   },
   [SemanticType.Derived]: {

package/src/modeling/definitions/Email.ts

@@ -15,9 +15,9 @@ export interface EmailConfig {
    */
   requireVerification?: boolean
   /**
-   * Method to use for verification: 'email', 'sms', or 'none'.
+   * Method to use for verification: 'email' or 'sms'.
    */
-  verificationMethod?: 'email' | 'sms' | 'none'
+  verificationMethod?: 'email' | 'sms'
   /**
    * Whether to allow subaddressing (user+tag@domain.com).
    */

package/src/modeling/definitions/GeospatialCoordinates.ts

@@ -97,12 +97,16 @@ export interface GeospatialCoordinatesConfig {
   /**
    * The spatial reference system (SRS) for the coordinates.
    * Defaults to WGS84 (EPSG:4326) if not specified.
+   *
+   * Note: If `format` is set to `GeoJSON`, this value is automatically locked to `WGS84`
+   * as per the GeoJSON specification (RFC 7946).
    */
   spatialReferenceSystem?: GeospatialSpatialReferenceSystem
 
   /**
    * The default distance unit for spatial queries.
    * Defaults to 'meters' if not specified.
+   * Only applicable when `enableDistanceQueries` is true.
    */
   defaultDistanceUnit?: GeospatialDistanceUnit
 
@@ -120,7 +124,8 @@ export interface GeospatialCoordinatesConfig {
 
   /**
    * Custom validation rules for coordinate bounds.
-   * If not specified, uses standard latitude (-90 to 90) and longitude (-180 to 180) bounds.
+   * Values are in decimal degrees.
+   * If not specified, uses standard latitude (-90.0 to 90.0) and longitude (-180.0 to 180.0) bounds.
    */
   validationBounds?: {
     /**
@@ -144,35 +149,55 @@ export interface GeospatialCoordinatesConfig {
   /**
    * Whether to enable automatic PostGIS integration when using PostgreSQL.
    * Defaults to true if not specified.
+   *
+   * This is an advanced setting. For UIs targeting non-technical users,
+   * it is safe to hide this option and keep it enabled. The backend should
+   * gracefully handle cases where the database is not PostgreSQL.
    */
   enablePostGISIntegration?: boolean
 
   /**
    * The PostGIS geometry type to use for storage.
    * Defaults to 'POINT' if not specified.
+   * This choice fundamentally defines the shape of the data and the types of queries that can be performed.
+   *
+   * - **POINT**: For single locations (e.g., a store, a user's location).
+   * - **LINESTRING**: For paths or routes (e.g., a delivery route, a hiking trail).
+   * - **POLYGON**: For defined areas (e.g., a delivery zone, a sales territory, a city boundary).
+   * - **MULTI***: For collections of the above types (e.g., all stores in a chain as a MULTIPOINT).
    */
   postGISGeometryType?: 'POINT' | 'LINESTRING' | 'POLYGON' | 'MULTIPOINT' | 'MULTILINESTRING' | 'MULTIPOLYGON'
 
   /**
    * Whether to enable distance-based query endpoints.
+   * This is not mutually exclusive with other query types and is useful for all geometry types.
    * Defaults to true if not specified.
+   *
+   * - For **POINT**: Finds points within a certain radius.
+   * - For **POLYGON**: Finds polygons that are within a certain distance of a point
+   *   (e.g., "find all parks within 5 miles").
+   * - For **LINESTRING**: Finds paths/routes within a certain distance of a point
+   *   (e.g., "find all subway lines near me").
    */
   enableDistanceQueries?: boolean
 
   /**
    * Maximum distance allowed in distance queries (in the default distance unit).
    * Defaults to 100000 (100km) if not specified.
+   * Only applicable when `enableDistanceQueries` is true.
    */
   maxQueryDistance?: number
 
   /**
    * Whether to enable bounding box query endpoints.
+   * This is not mutually exclusive with other query types.
    * Defaults to true if not specified.
    */
   enableBoundingBoxQueries?: boolean
 
   /**
    * Whether to enable polygon intersection query endpoints.
+   * This is not mutually exclusive with other query types.
    * Defaults to false if not specified.
    */
   enablePolygonQueries?: boolean
@@ -180,12 +205,26 @@ export interface GeospatialCoordinatesConfig {
   /**
    * Custom API endpoint prefix for geospatial queries.
    * Defaults to '/nearby' if not specified.
+   * Only applicable if `enableDistanceQueries`, `enableBoundingBoxQueries`,
+   * or `enablePolygonQueries` is true.
+   *
+   * The generated endpoints would be:
+   * - **Distance Query**: `GET {apiEndpointPrefix}`
+   * - **Bounding Box Query**: `GET {apiEndpointPrefix}/bbox`
+   * - **Polygon Query**: `POST {apiEndpointPrefix}/polygon`
    */
   apiEndpointPrefix?: string
 
   /**
    * Whether to include elevation data in coordinates (3D coordinates).
    * Defaults to false if not specified.
+   * When true, a third value for elevation is expected in the coordinate data.
+   *
+   * - **LatLon**: `"40.7128,-74.0060,10"` (latitude, longitude, elevation)
+   * - **PostGIS/WKT**: `"POINT Z (-74.0060 40.7128 10)"`
+   * - **GeoJSON**: `{"type": "Point", "coordinates": [-74.0060, 40.7128, 10]}`
+   *
+   * The unit for elevation is determined by `defaultDistanceUnit`.
    */
   includeElevation?: boolean
 
@@ -198,6 +237,12 @@ export interface GeospatialCoordinatesConfig {
   /**
    * Whether to enable reverse geocoding capabilities.
    * Defaults to false if not specified.
+   *
+   * When enabled, the system can convert geographic coordinates (e.g., `40.7128, -74.0060`)
+   * into a human-readable address (e.g., "New York, NY, USA").
+   *
+   * This often requires integration with an external geocoding service and may have
+   * associated costs or usage limits.
    */
   enableReverseGeocoding?: boolean
 

package/src/modeling/definitions/Phone.ts

@@ -15,18 +15,17 @@ export interface PhoneConfig {
 
   /**
    * Whether the phone number must include a country code.
-   * Defaults to true for E.164 format.
+   * Defaults to true for international format.
    */
   requireCountryCode?: boolean
 
   /**
    * Format for phone number validation and display.
-   * - 'E.164': International format with + prefix (e.g., +1234567890)
    * - 'national': Country-specific format without country code
-   * - 'international': International format with country code
+   * - 'international': E.164 international format with + prefix (e.g., +1234567890)
    * - 'custom': Use customFormat pattern
    */
-  format?: 'E.164' | 'national' | 'international' | 'custom'
+  format?: 'national' | 'international' | 'custom'
 
   /**
    * Custom format pattern for phone number validation.
@@ -51,9 +50,8 @@ export interface PhoneConfig {
    * Method to use for phone verification.
    * - 'sms': Send verification code via SMS
    * - 'call': Make verification call
-   * - 'none': No verification required
    */
-  verificationMethod?: 'sms' | 'call' | 'none'
+  verificationMethod?: 'sms' | 'call'
 
   /**
    * Custom metadata for the phone field.
@@ -105,11 +103,11 @@ export const createPhoneSemantic = (config: PhoneConfig = {}): AppliedPhoneSeman
 
 /**
  * Default configuration for Phone semantic.
- * Uses E.164 format with country code required and SMS verification.
+ * Uses international format with country code required and SMS verification.
  */
 export const DEFAULT_PHONE_CONFIG: PhoneConfig = {
   requireCountryCode: true,
-  format: 'E.164',
+  format: 'international',
   allowExtension: false,
   requireVerification: false,
   verificationMethod: 'sms',

package/src/modeling/definitions/PublicUniqueName.ts

@@ -7,7 +7,7 @@ import { SemanticType } from '../Semantics.js'
  */
 export interface PublicUniqueNameConfig {
   /**
-   * The source field to generate the slug from (e.g., 'title').
+   * The key of the source field to generate the slug from.
    * Default to the field that is annotated with the Title semantic.
    */
   sourceField?: string
@@ -15,10 +15,6 @@ export interface PublicUniqueNameConfig {
    * Separator character to use in the slug (default: '-').
    */
   separator?: string
-  /**
-   * Maximum length of the slug (default: 64).
-   */
-  maxLength?: number
   /**
    * Whether the slug is case sensitive (default: false).
    */
@@ -27,10 +23,6 @@ export interface PublicUniqueNameConfig {
    * Whether to allow Unicode characters in the slug (default: false).
    */
   allowUnicode?: boolean
-  /**
-   * Name of a custom generator function to use for slug creation.
-   */
-  customGenerator?: string
   /**
    * Whether to allow duplicate slugs (default: false).
    */
@@ -91,7 +83,6 @@ export const createPublicUniqueNameSemantic = (
  */
 export const DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG: PublicUniqueNameConfig = {
   separator: '-',
-  maxLength: 64,
   caseSensitive: false,
   allowUnicode: false,
   allowDuplicates: false,

package/src/modeling/definitions/SKU.ts

@@ -60,9 +60,12 @@ export interface SKUConfig {
   autoGenerate?: boolean
 
   /**
-   * Field name to use as source for auto-generation.
+   * Field key to use as source for auto-generation.
    * Only used when autoGenerate is true.
    * If not specified, uses random generation.
+   *
+   * The kay can be any field that provides a meaningful value for the SKU. It can also be a key of
+   * a property in one of the parent entities.
    */
   autoGenerateSource?: string
 

package/src/modeling/definitions/URL.ts

@@ -6,12 +6,9 @@ import { SemanticType } from '../Semantics.js'
  * Controls validation, allowed protocols, and formatting.
  */
 export interface URLConfig {
-  /**
-   * List of allowed protocols (e.g., ['http', 'https']).
-   */
-  allowedProtocols?: string[]
   /**
    * Whether to require HTTPS protocol (default: false).
+   * When not set, both HTTP and HTTPS are allowed.
    */
   requireHttps?: boolean
   /**
@@ -85,7 +82,6 @@ export const createURLSemantic = (config: URLConfig = {}): AppliedURLSemantic =>
  * Default configuration for URL semantic.
  */
 export const DEFAULT_URL_CONFIG: URLConfig = {
-  allowedProtocols: ['http', 'https'],
   requireHttps: false,
   allowQueryParams: true,
   allowFragments: true,

package/tests/unit/modeling/definitions/derived.spec.ts

@@ -10,8 +10,7 @@ test.group('Derived Semantic Configuration', () => {
   test('should create semantic with custom config', ({ assert }) => {
     const config: DerivedConfig = {
       sourceFields: ['firstName', 'lastName'],
-      derivationRule: 'concat',
-      updateOnChange: true,
+      transformation: 'concat',
       allowManualOverride: true,
       recalculateOnUpdate: false,
     }

package/tests/unit/modeling/definitions/url.spec.ts

@@ -16,7 +16,6 @@ test.group('URL Semantic Configuration', () => {
 
   test('should create semantic with custom config', ({ assert }) => {
     const config: URLConfig = {
-      allowedProtocols: ['https'],
       allowedDomains: ['example.com'],
       requireHTTPS: true,
     }

package/tests/unit/modeling/semantic-configs.spec.ts

@@ -287,7 +287,7 @@ test.group('Semantic Configurations', () => {
   test('Phone: should create semantic with custom config', ({ assert }) => {
     const config: PhoneConfig = {
       allowedCountries: ['US', 'CA'],
-      format: 'E.164',
+      format: 'international',
       requireVerification: true,
     }
     const semantic = createPhoneSemantic(config)
@@ -308,7 +308,6 @@ test.group('Semantic Configurations', () => {
 
   test('URL: should create semantic with custom config', ({ assert }) => {
     const config: URLConfig = {
-      allowedProtocols: ['https'],
       allowedDomains: ['example.com'],
       requireHTTPS: true,
     }