@api-client/core 0.18.54 → 0.18.56

package/data/models/example-generator-api.json

@@ -42813,10 +42813,10 @@
 "@id": "#210"
 },
 {
-"@id": "#216"
+"@id": "#213"
 },
 {
-"@id": "#213"
+"@id": "#216"
 },
 {
 "@id": "#219"
@@ -44253,7 +44253,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44274,7 +44274,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
+"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -45121,12 +45121,12 @@
 {
 "@id": "#215/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#215",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#218/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#218",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#221/source-map/lexical/element_0",

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.18.54",
+  "version": "0.18.56",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/Semantics.ts

@@ -15,6 +15,10 @@ export enum SemanticType {
    * Designates a Data Entity that represents users of the system.
    */
   User = 'Semantic#User',
+  /**
+   * Designates a Data Entity that represents a physical address.
+   */
+  Address = 'Semantic#Address',
 
   //
   // Property-Level Semantics
@@ -197,10 +201,33 @@ export enum 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.
    */
   ClientIPAddress = 'Semantic#ClientIPAddress',
+  /**
+   * Designates a Data Property as the street address (e.g., "123 Main St").
+   */
+  StreetAddress = 'Semantic#StreetAddress',
+  /**
+   * This is a single semantic used for any additional lines (Unit, Suite, Apartment, Floor).
+   */
+  StreetAddressSupplemental = 'Semantic#StreetAddressSupplemental',
+  /**
+   * Designates a Data Property as the city or locality.
+   */
+  City = 'Semantic#City',
+  /**
+   * Designates a Data Property as the postal or zip code.
+   */
+  PostalCode = 'Semantic#PostalCode',
+  /**
+   * Designates a Data Property as the country.
+   */
+  Country = 'Semantic#Country',
+  /**
+   * Designates a Data Property as the state, province, or region.
+   */
+  Region = 'Semantic#Region',
 
   //
   // Association-Level Semantics
@@ -271,10 +298,6 @@ export enum SemanticCategory {
    * Business-specific data like pricing, inventory, status
    */
   Business = 'Business Data',
-  /**
-   * Contact information and communication
-   */
-  Contact = 'Contact Information',
   /**
    * Organization, categorization, and tagging
    */
@@ -283,6 +306,10 @@ export enum SemanticCategory {
    * Location and geographical data
    */
   Location = 'Location & Geography',
+  /**
+   * Contact information and communication
+   */
+  Contact = 'Contact Information',
   /**
    * Calculated and derived values
    */
@@ -792,6 +819,106 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
       priority: 80,
     },
   },
+
+  //
+  // Contact & Address
+  //
+
+  [SemanticType.Address]: {
+    id: SemanticType.Address,
+    displayName: 'Address Entity',
+    scope: SemanticScope.Entity,
+    description: 'Physical address entity',
+    category: SemanticCategory.Contact,
+    // For now, the Address won't have configuration, but future-wise:
+    //  - autoGeocode (boolean): If true, the runtime automatically generates latitude and longitude for the record whenever the address properties change.
+    //  - validationProvider (enum): Options like None, GoogleMaps, or Loqate. This determines if the API returns an error for non-existent addresses.
+    //  - strictness (enum): Lax (accept anything) vs. Strict (reject if not deliverable).
+    hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
+  },
+  [SemanticType.StreetAddress]: {
+    id: SemanticType.StreetAddress,
+    displayName: 'Street Address',
+    scope: SemanticScope.Property,
+    description: 'Street address line',
+    category: SemanticCategory.Contact,
+    applicableDataTypes: ['string'],
+    hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
+  },
+  [SemanticType.StreetAddressSupplemental]: {
+    id: SemanticType.StreetAddressSupplemental,
+    displayName: 'Street Address Supplemental',
+    scope: SemanticScope.Property,
+    description: 'Supplemental street address line (e.g., Unit, Suite, Apartment, Floor)',
+    category: SemanticCategory.Contact,
+    applicableDataTypes: ['string'],
+    hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
+  },
+  [SemanticType.City]: {
+    id: SemanticType.City,
+    displayName: 'City',
+    scope: SemanticScope.Property,
+    description: 'City or locality',
+    category: SemanticCategory.Contact,
+    applicableDataTypes: ['string'],
+    hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
+  },
+  [SemanticType.PostalCode]: {
+    id: SemanticType.PostalCode,
+    displayName: 'Postal Code',
+    scope: SemanticScope.Property,
+    description: 'Postal or zip code',
+    category: SemanticCategory.Contact,
+    applicableDataTypes: ['string'],
+    hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
+  },
+  [SemanticType.Country]: {
+    id: SemanticType.Country,
+    displayName: 'Country',
+    scope: SemanticScope.Property,
+    description: 'Country name or code',
+    category: SemanticCategory.Contact,
+    applicableDataTypes: ['string'],
+    hasConfig: true,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
+  },
+  [SemanticType.Region]: {
+    id: SemanticType.Region,
+    displayName: 'Region',
+    scope: SemanticScope.Property,
+    description: 'State, province, or region',
+    category: SemanticCategory.Contact,
+    applicableDataTypes: ['string'],
+    hasConfig: false,
+    runtime: {
+      timing: SemanticTiming.None,
+      operations: [],
+    },
+  },
+
   [SemanticType.Version]: {
     id: SemanticType.Version,
     displayName: 'Version Number',

package/src/modeling/definitions/Country.ts

@@ -0,0 +1,62 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+export type CountryFormat = 'ISO_3166_Alpha_2' | 'ISO_3166_Alpha_3' | 'Name'
+
+export interface CountryConfig {
+  /**
+   * The format of the country code.
+   *
+   * @default 'Name'
+   */
+  format?: CountryFormat
+
+  /**
+   * The list of allowed countries.
+   */
+  allowedCountries?: string[]
+
+  /**
+   * The list of disallowed countries.
+   */
+  disallowedCountries?: string[]
+  /**
+   * Custom metadata for the country field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Country semantic.
+ */
+export interface AppliedCountrySemantic extends AppliedDataSemantic {
+  id: SemanticType.Country
+  config?: CountryConfig
+}
+
+export const isCountrySemantic = (semantic: AppliedDataSemantic): semantic is AppliedCountrySemantic => {
+  return semantic.id === SemanticType.Country
+}
+
+export const createCountrySemantic = (config: CountryConfig = {}): AppliedCountrySemantic => {
+  const mergedConfig = {
+    ...DEFAULT_COUNTRY_CONFIG,
+    ...config,
+  }
+  // Merge metadata separately
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+  return {
+    id: SemanticType.Country,
+    config: mergedConfig,
+  }
+}
+
+export const DEFAULT_COUNTRY_CONFIG: CountryConfig = {
+  format: 'ISO_3166_Alpha_2',
+}

package/src/modeling/definitions/PostalCode.ts

@@ -0,0 +1,70 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+/**
+ * Validation Logic Flow:
+ *
+ * When the API receives a POST or PATCH request, the following sequence occurs:
+ * 1. Semantic Trigger: The Runtime identifies a property with the PostalCode semantic and config.validate: true.
+ * 2. Country Lookup: The Runtime identifies the sibling property tagged with `SemanticType.Country`.
+ * 3. Regex Retrieval: The Runtime retrieves the appropriate regex pattern based on the country code.
+ * 4. Validation: The Runtime validates the postal code against the retrieved regex pattern.
+ * 5. Error Handling: If the validation fails, the Runtime returns a 400 Bad Request error with a descriptive message.
+ *   - Example: "Invalid postal code format for country: [CountryCode]."
+ *
+ * Validation libraries:
+ * - https://www.npmjs.com/package/postcode-validator (MIT)
+ * - https://github.com/sashiksu/postal-code-checker (MIT)
+ */
+export interface PostalCodeConfig {
+  /**
+   * Enables regex-based validation based on the value in the sibling property
+   * tagged with `SemanticType.Country`.
+   */
+  validate?: boolean
+
+  /**
+   * The list of allowed postal codes.
+   */
+  allowedPostalCodes?: string[]
+
+  /**
+   * The list of disallowed postal codes.
+   */
+  disallowedPostalCodes?: string[]
+  /**
+   * Custom metadata for the postal code field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+export interface AppliedPostalCodeSemantic extends AppliedDataSemantic {
+  id: SemanticType.PostalCode
+  config?: PostalCodeConfig
+}
+
+export const DEFAULT_POSTAL_CODE_CONFIG: PostalCodeConfig = {
+  validate: false,
+}
+
+export const isPostalCodeSemantic = (semantic: AppliedDataSemantic): semantic is AppliedPostalCodeSemantic => {
+  return semantic.id === SemanticType.PostalCode
+}
+
+export const createPostalCodeSemantic = (config: PostalCodeConfig = {}): AppliedPostalCodeSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_POSTAL_CODE_CONFIG,
+    ...config,
+  }
+  // Merge metadata separately
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+  return {
+    id: SemanticType.PostalCode,
+    config: mergedConfig,
+  }
+}

package/src/modeling/helpers/Intelisense.ts

@@ -12,6 +12,8 @@ import { createDescriptionSemantic } from '../definitions/Description.js'
 import { CURRENCY_PRESETS } from '../definitions/Currency.js'
 import { createStatusSemantic } from '../definitions/Status.js'
 import { SKU_PRESETS } from '../definitions/SKU.js'
+import { createCountrySemantic, DEFAULT_COUNTRY_CONFIG } from '../definitions/Country.js'
+import { createPostalCodeSemantic, DEFAULT_POSTAL_CODE_CONFIG } from '../definitions/PostalCode.js'
 
 /**
  * Adds a field to the given entity that is automatically generated by the system.
@@ -83,6 +85,16 @@ export function addAutoField(entity: DomainEntity, autoField: string): DomainEle
       return addExpiresAtField(entity)
     case 'unit-price':
       return addUnitPriceField(entity)
+    case 'street-address':
+      return addStreetAddressField(entity)
+    case 'city':
+      return addCityField(entity)
+    case 'postal-code':
+      return addPostalCodeField(entity)
+    case 'country':
+      return addCountryField(entity)
+    case 'region':
+      return addRegionField(entity)
     default:
       throw new Error(`Unsupported auto field: ${autoField}`)
   }
@@ -1362,3 +1374,86 @@ function findExpiresAtField(entity: DomainEntity, direct = false): DomainPropert
     direct
   )
 }
+
+export function addStreetAddressField(entity: DomainEntity, info: Partial<IThing> = {}): DomainProperty {
+  const existing = findStreetAddressField(entity, true)
+  if (existing) return existing
+  const prop = entity.addProperty({
+    info: { name: 'street_address', displayName: 'Street Address', ...info },
+    type: 'string',
+    required: true,
+  })
+  prop.addSemantic({ id: SemanticType.StreetAddress })
+  return prop
+}
+
+function findStreetAddressField(entity: DomainEntity, direct = false): DomainProperty | undefined {
+  return findPropertyField(entity, (property) => property.hasSemantic(SemanticType.StreetAddress), direct)
+}
+
+export function addCityField(entity: DomainEntity, info: Partial<IThing> = {}): DomainProperty {
+  const existing = findCityField(entity, true)
+  if (existing) return existing
+  const prop = entity.addProperty({
+    info: { name: 'city', displayName: 'City', ...info },
+    type: 'string',
+    required: true,
+    index: true,
+  })
+  prop.addSemantic({ id: SemanticType.City })
+  return prop
+}
+
+function findCityField(entity: DomainEntity, direct = false): DomainProperty | undefined {
+  return findPropertyField(entity, (property) => property.hasSemantic(SemanticType.City), direct)
+}
+
+export function addPostalCodeField(entity: DomainEntity, info: Partial<IThing> = {}): DomainProperty {
+  const existing = findPostalCodeField(entity, true)
+  if (existing) return existing
+  const prop = entity.addProperty({
+    info: { name: 'postal_code', displayName: 'Postal Code', ...info },
+    type: 'string',
+    required: true,
+    index: true,
+  })
+  prop.addSemantic(createPostalCodeSemantic(DEFAULT_POSTAL_CODE_CONFIG))
+  return prop
+}
+
+function findPostalCodeField(entity: DomainEntity, direct = false): DomainProperty | undefined {
+  return findPropertyField(entity, (property) => property.hasSemantic(SemanticType.PostalCode), direct)
+}
+
+export function addCountryField(entity: DomainEntity, info: Partial<IThing> = {}): DomainProperty {
+  const existing = findCountryField(entity, true)
+  if (existing) return existing
+  const prop = entity.addProperty({
+    info: { name: 'country', displayName: 'Country', ...info },
+    type: 'string',
+    required: true,
+    index: true,
+  })
+  prop.addSemantic(createCountrySemantic(DEFAULT_COUNTRY_CONFIG))
+  return prop
+}
+
+function findCountryField(entity: DomainEntity, direct = false): DomainProperty | undefined {
+  return findPropertyField(entity, (property) => property.hasSemantic(SemanticType.Country), direct)
+}
+
+export function addRegionField(entity: DomainEntity, info: Partial<IThing> = {}): DomainProperty {
+  const existing = findRegionField(entity, true)
+  if (existing) return existing
+  const prop = entity.addProperty({
+    info: { name: 'region', displayName: 'Region', ...info },
+    type: 'string',
+    index: true,
+  })
+  prop.addSemantic({ id: SemanticType.Region })
+  return prop
+}
+
+function findRegionField(entity: DomainEntity, direct = false): DomainProperty | undefined {
+  return findPropertyField(entity, (property) => property.hasSemantic(SemanticType.Region), direct)
+}

package/src/modeling/templates/verticals/business-services/ecommerce-domain.ts

@@ -25,7 +25,9 @@
 import { DataDomain } from '../../../DataDomain.js'
 import { SemanticType } from '../../../Semantics.js'
 import { createCalculatedSemantic } from '../../../definitions/Calculated.js'
+import { createCountrySemantic, DEFAULT_COUNTRY_CONFIG } from '../../../definitions/Country.js'
 import { createCurrencySemantic } from '../../../definitions/Currency.js'
+import { createPostalCodeSemantic, DEFAULT_POSTAL_CODE_CONFIG } from '../../../definitions/PostalCode.js'
 import { createSummarySemantic } from '../../../definitions/Summary.js'
 import {
   addAvatarUrlField,
@@ -200,6 +202,7 @@ export default function createEcommerceDomain(options: CreateTemplateOptions = {
       displayName: 'Address',
       description: 'Physical address information',
     },
+    semantics: [{ id: SemanticType.Address }],
   })
 
   addIdField(addressEntity, { displayName: 'Address ID', description: 'Unique identifier for the address' })
@@ -221,6 +224,7 @@ export default function createEcommerceDomain(options: CreateTemplateOptions = {
     },
     type: 'string',
     required: true,
+    semantics: [{ id: SemanticType.StreetAddress }],
   })
 
   addressEntity.addProperty({
@@ -231,6 +235,7 @@ export default function createEcommerceDomain(options: CreateTemplateOptions = {
     },
     type: 'string',
     required: false,
+    semantics: [{ id: SemanticType.StreetAddressSupplemental }],
   })
 
   addressEntity.addProperty({
@@ -241,30 +246,35 @@ export default function createEcommerceDomain(options: CreateTemplateOptions = {
     },
     type: 'string',
     required: false,
+    semantics: [{ id: SemanticType.StreetAddressSupplemental }],
   })
 
   addressEntity.addProperty({
     info: { name: 'city', displayName: 'City', description: 'City name' },
     type: 'string',
     required: true,
+    semantics: [{ id: SemanticType.City }],
   })
 
   addressEntity.addProperty({
     info: { name: 'state', displayName: 'State/Province', description: 'State or province' },
     type: 'string',
     required: true,
+    semantics: [{ id: SemanticType.Region }],
   })
 
   addressEntity.addProperty({
     info: { name: 'postal_code', displayName: 'ZIP/Postal Code', description: 'ZIP or postal code' },
     type: 'string',
     required: true,
+    semantics: [createPostalCodeSemantic(DEFAULT_POSTAL_CODE_CONFIG)],
   })
 
   addressEntity.addProperty({
     info: { name: 'country', displayName: 'Country', description: 'Country name' },
     type: 'string',
     required: true,
+    semantics: [createCountrySemantic(DEFAULT_COUNTRY_CONFIG)],
   })
 
   // User-Address Association (One-to-Many)

package/src/modeling/templates/verticals/business-services/financial-services-domain.ts

@@ -25,6 +25,8 @@
 
 import { DataDomain } from '../../../DataDomain.js'
 import { SemanticType } from '../../../Semantics.js'
+import { createCountrySemantic, DEFAULT_COUNTRY_CONFIG } from '../../../definitions/Country.js'
+import { createPostalCodeSemantic, DEFAULT_POSTAL_CODE_CONFIG } from '../../../definitions/PostalCode.js'
 import {
   addIdField,
   addNameField,
@@ -262,24 +264,35 @@ export default function createFinancialServicesDomain(options: CreateTemplateOpt
     info: { name: 'address', displayName: 'Address', description: 'Customer residential address' },
     type: 'string',
     required: true,
+    semantics: [{ id: SemanticType.StreetAddress }],
   })
 
   customerProfileEntity.addProperty({
     info: { name: 'city', displayName: 'City', description: 'Customer city' },
     type: 'string',
     required: true,
+    semantics: [{ id: SemanticType.City }],
   })
 
   customerProfileEntity.addProperty({
-    info: { name: 'state', displayName: 'State', description: 'Customer state' },
+    info: { name: 'state', displayName: 'State/Province', description: 'State or province' },
     type: 'string',
     required: true,
+    semantics: [{ id: SemanticType.Region }],
   })
 
   customerProfileEntity.addProperty({
-    info: { name: 'zip_code', displayName: 'ZIP Code', description: 'Customer ZIP code' },
+    info: { name: 'postal_code', displayName: 'ZIP/Postal Code', description: 'ZIP or postal code' },
     type: 'string',
     required: true,
+    semantics: [createPostalCodeSemantic(DEFAULT_POSTAL_CODE_CONFIG)],
+  })
+
+  customerProfileEntity.addProperty({
+    info: { name: 'country', displayName: 'Country', description: 'Country name' },
+    type: 'string',
+    required: true,
+    semantics: [createCountrySemantic(DEFAULT_COUNTRY_CONFIG)],
   })
 
   customerProfileEntity.addProperty({