@api-client/core 0.15.1 → 0.16.0

package/src/modeling/definitions/Derived.ts

@@ -0,0 +1,76 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Derived semantic.
+ * Controls source fields, transformation, and recalculation behavior.
+ *
+ * Use Derived when you need to combine, format, or transform existing field values
+ */
+export interface DerivedConfig {
+  /**
+   * List of source field names this value is derived from.
+   */
+  sourceFields: string[]
+  /**
+   * Name of a transformation function to apply to the source fields.
+   */
+  transformation?: string
+  /**
+   * Whether to recalculate the value on update (default: true).
+   */
+  recalculateOnUpdate?: boolean
+  /**
+   * Whether to allow manual override of the derived value.
+   */
+  allowManualOverride?: boolean
+  /**
+   * Custom metadata for the derived field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Derived semantic.
+ */
+export interface AppliedDerivedSemantic extends AppliedDataSemantic {
+  id: SemanticType.Derived
+  config?: DerivedConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Derived semantic.
+ */
+export const isDerivedSemantic = (semantic: AppliedDataSemantic): semantic is AppliedDerivedSemantic => {
+  return semantic.id === SemanticType.Derived
+}
+
+/**
+ * Helper function to create a Derived semantic with configuration.
+ */
+export const createDerivedSemantic = (config: DerivedConfig): AppliedDerivedSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_DERIVED_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Derived,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Derived semantic.
+ */
+export const DEFAULT_DERIVED_CONFIG: Partial<DerivedConfig> = {
+  recalculateOnUpdate: true,
+  allowManualOverride: false,
+}

package/src/modeling/definitions/Description.ts

@@ -0,0 +1,55 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Description semantic.
+ * Controls length, formatting, and markdown support.
+ */
+export interface DescriptionConfig {
+  /**
+   * Custom metadata for the description field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Description semantic.
+ */
+export interface AppliedDescriptionSemantic extends AppliedDataSemantic {
+  id: SemanticType.Description
+  config?: DescriptionConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Description semantic.
+ */
+export const isDescriptionSemantic = (semantic: AppliedDataSemantic): semantic is AppliedDescriptionSemantic => {
+  return semantic.id === SemanticType.Description
+}
+
+/**
+ * Helper function to create a Description semantic with configuration.
+ */
+export const createDescriptionSemantic = (config: DescriptionConfig = {}): AppliedDescriptionSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_DESCRIPTION_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Description,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Description semantic.
+ */
+export const DEFAULT_DESCRIPTION_CONFIG: DescriptionConfig = {}

package/src/modeling/definitions/Email.ts

@@ -0,0 +1,90 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Email semantic.
+ * Controls validation, allowed domains, and verification.
+ */
+export interface EmailConfig {
+  /**
+   * List of allowed email domains (e.g., ['example.com']).
+   */
+  allowedDomains?: string[]
+  /**
+   * Whether email verification is required.
+   */
+  requireVerification?: boolean
+  /**
+   * Method to use for verification: 'email', 'sms', or 'none'.
+   */
+  verificationMethod?: 'email' | 'sms' | 'none'
+  /**
+   * Whether to allow subaddressing (user+tag@domain.com).
+   */
+  allowSubaddressing?: boolean
+  /**
+   * Whether to allow internationalized email addresses.
+   *
+   * - When true (default): Allows email addresses with non-ASCII characters in the domain part,
+   *   like user@münchen.de or user@café.com
+   * - When false: Only allows ASCII characters in the domain part, like user@example.com
+   *
+   * Why it exists:
+   * - Internationalization: Many countries have domain names with native characters (like German umlauts,
+   *   French accents, etc.)
+   * - RFC 6531: The standard for internationalized email addresses
+   * - Validation flexibility: Some systems may need to restrict to ASCII-only domains for compatibility reasons
+   */
+  allowInternational?: boolean
+  /**
+   * Custom metadata for the email field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Email semantic.
+ */
+export interface AppliedEmailSemantic extends AppliedDataSemantic {
+  id: SemanticType.Email
+  config?: EmailConfig
+}
+
+/**
+ * Type guard to check if a semantic is an Email semantic.
+ */
+export const isEmailSemantic = (semantic: AppliedDataSemantic): semantic is AppliedEmailSemantic => {
+  return semantic.id === SemanticType.Email
+}
+
+/**
+ * Helper function to create an Email semantic with configuration.
+ */
+export const createEmailSemantic = (config: EmailConfig = {}): AppliedEmailSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_EMAIL_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Email,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Email semantic.
+ */
+export const DEFAULT_EMAIL_CONFIG: EmailConfig = {
+  requireVerification: false,
+  verificationMethod: 'email',
+  allowSubaddressing: true,
+  allowInternational: true,
+}

package/src/modeling/definitions/GeospatialCoordinates.ts

@@ -0,0 +1,274 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Supported coordinate formats for geospatial data.
+ */
+export enum GeospatialCoordinateFormat {
+  /**
+   * Latitude, Longitude format: "40.7128,-74.0060"
+   */
+  LatLon = 'lat,lon',
+  /**
+   * Longitude, Latitude format: "-74.0060,40.7128"
+   */
+  LonLat = 'lon,lat',
+  /**
+   * PostGIS POINT format: "POINT(-74.0060 40.7128)"
+   */
+  PostGIS = 'postgis',
+  /**
+   * Degree format with cardinal directions: "40.7128°N, 74.0060°W"
+   */
+  Degree = 'degree',
+  /**
+   * Well-Known Text (WKT) format: "POINT(-74.0060 40.7128)"
+   */
+  WKT = 'wkt',
+  /**
+   * GeoJSON format: {"type": "Point", "coordinates": [-74.0060, 40.7128]}
+   */
+  GeoJSON = 'geojson',
+}
+
+/**
+ * Supported distance units for spatial queries.
+ */
+export enum GeospatialDistanceUnit {
+  /**
+   * Meters (SI unit)
+   */
+  Meters = 'meters',
+  /**
+   * Kilometers
+   */
+  Kilometers = 'kilometers',
+  /**
+   * Miles (imperial)
+   */
+  Miles = 'miles',
+  /**
+   * Feet (imperial)
+   */
+  Feet = 'feet',
+  /**
+   * Yards (imperial)
+   */
+  Yards = 'yards',
+  /**
+   * Nautical miles
+   */
+  NauticalMiles = 'nautical_miles',
+}
+
+/**
+ * Supported spatial reference systems.
+ */
+export enum GeospatialSpatialReferenceSystem {
+  /**
+   * WGS84 (World Geodetic System 1984) - Most common for GPS coordinates
+   */
+  WGS84 = 'EPSG:4326',
+  /**
+   * Web Mercator - Common for web mapping
+   */
+  WebMercator = 'EPSG:3857',
+  /**
+   * NAD83 (North American Datum 1983)
+   */
+  NAD83 = 'EPSG:4269',
+  /**
+   * NAD27 (North American Datum 1927)
+   */
+  NAD27 = 'EPSG:4267',
+}
+
+/**
+ * Configuration options for the GeospatialCoordinates semantic.
+ * These options control how the runtime handles geospatial data and queries.
+ */
+export interface GeospatialCoordinatesConfig {
+  /**
+   * The coordinate format expected for input/output.
+   * Defaults to 'lat,lon' if not specified.
+   */
+  format?: GeospatialCoordinateFormat
+
+  /**
+   * The spatial reference system (SRS) for the coordinates.
+   * Defaults to WGS84 (EPSG:4326) if not specified.
+   */
+  spatialReferenceSystem?: GeospatialSpatialReferenceSystem
+
+  /**
+   * The default distance unit for spatial queries.
+   * Defaults to 'meters' if not specified.
+   */
+  defaultDistanceUnit?: GeospatialDistanceUnit
+
+  /**
+   * Whether to enable automatic spatial indexing.
+   * Defaults to true if not specified.
+   */
+  enableSpatialIndexing?: boolean
+
+  /**
+   * Whether to enable automatic coordinate validation.
+   * Defaults to true if not specified.
+   */
+  enableValidation?: boolean
+
+  /**
+   * Custom validation rules for coordinate bounds.
+   * If not specified, uses standard latitude (-90 to 90) and longitude (-180 to 180) bounds.
+   */
+  validationBounds?: {
+    /**
+     * Minimum latitude value
+     */
+    minLatitude?: number
+    /**
+     * Maximum latitude value
+     */
+    maxLatitude?: number
+    /**
+     * Minimum longitude value
+     */
+    minLongitude?: number
+    /**
+     * Maximum longitude value
+     */
+    maxLongitude?: number
+  }
+
+  /**
+   * Whether to enable automatic PostGIS integration when using PostgreSQL.
+   * Defaults to true if not specified.
+   */
+  enablePostGISIntegration?: boolean
+
+  /**
+   * The PostGIS geometry type to use for storage.
+   * Defaults to 'POINT' if not specified.
+   */
+  postGISGeometryType?: 'POINT' | 'LINESTRING' | 'POLYGON' | 'MULTIPOINT' | 'MULTILINESTRING' | 'MULTIPOLYGON'
+
+  /**
+   * Whether to enable distance-based query endpoints.
+   * Defaults to true if not specified.
+   */
+  enableDistanceQueries?: boolean
+
+  /**
+   * Maximum distance allowed in distance queries (in the default distance unit).
+   * Defaults to 100000 (100km) if not specified.
+   */
+  maxQueryDistance?: number
+
+  /**
+   * Whether to enable bounding box query endpoints.
+   * Defaults to true if not specified.
+   */
+  enableBoundingBoxQueries?: boolean
+
+  /**
+   * Whether to enable polygon intersection query endpoints.
+   * Defaults to false if not specified.
+   */
+  enablePolygonQueries?: boolean
+
+  /**
+   * Custom API endpoint prefix for geospatial queries.
+   * Defaults to '/nearby' if not specified.
+   */
+  apiEndpointPrefix?: string
+
+  /**
+   * Whether to include elevation data in coordinates (3D coordinates).
+   * Defaults to false if not specified.
+   */
+  includeElevation?: boolean
+
+  /**
+   * Precision for coordinate storage (number of decimal places).
+   * Defaults to 6 if not specified.
+   */
+  coordinatePrecision?: number
+
+  /**
+   * Whether to enable reverse geocoding capabilities.
+   * Defaults to false if not specified.
+   */
+  enableReverseGeocoding?: boolean
+
+  /**
+   * Custom metadata for the geospatial field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for GeospatialCoordinates semantic.
+ */
+export interface AppliedGeospatialCoordinatesSemantic extends AppliedDataSemantic {
+  id: SemanticType.GeospatialCoordinates
+  config?: GeospatialCoordinatesConfig
+}
+
+/**
+ * Type guard to check if a semantic is a GeospatialCoordinates semantic.
+ */
+export const isGeospatialCoordinatesSemantic = (
+  semantic: AppliedDataSemantic
+): semantic is AppliedGeospatialCoordinatesSemantic => {
+  return semantic.id === SemanticType.GeospatialCoordinates
+}
+
+/**
+ * Helper function to create a GeospatialCoordinates semantic with configuration.
+ */
+export const createGeospatialCoordinatesSemantic = (
+  config: GeospatialCoordinatesConfig = {}
+): AppliedGeospatialCoordinatesSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_GEOSPATIAL_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+  if (config.validationBounds) {
+    mergedConfig.validationBounds = { ...config.validationBounds }
+  }
+
+  return {
+    id: SemanticType.GeospatialCoordinates,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for GeospatialCoordinates semantic.
+ */
+export const DEFAULT_GEOSPATIAL_CONFIG: GeospatialCoordinatesConfig = {
+  format: GeospatialCoordinateFormat.LatLon,
+  spatialReferenceSystem: GeospatialSpatialReferenceSystem.WGS84,
+  defaultDistanceUnit: GeospatialDistanceUnit.Meters,
+  enableSpatialIndexing: true,
+  enableValidation: true,
+  enablePostGISIntegration: true,
+  postGISGeometryType: 'POINT',
+  enableDistanceQueries: true,
+  maxQueryDistance: 100000,
+  enableBoundingBoxQueries: true,
+  enablePolygonQueries: false,
+  apiEndpointPrefix: '/nearby',
+  includeElevation: false,
+  coordinatePrecision: 6,
+  enableReverseGeocoding: false,
+}

package/src/modeling/definitions/HTML.ts

@@ -0,0 +1,121 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the HTML semantic.
+ * Controls rendering, sanitization, and allowed HTML features.
+ */
+export interface HTMLConfig {
+  /**
+   * List of allowed HTML tags in the content.
+   */
+  allowedTags?: string[]
+  /**
+   * Maximum length of the HTML content.
+   */
+  maxLength?: number
+  /**
+   * Render mode: 'html', 'text', or 'both'.
+   */
+  renderMode?: 'html' | 'text' | 'both'
+  /**
+   * Sanitization level: 'strict', 'moderate', or 'none'.
+   */
+  sanitizeLevel?: 'strict' | 'moderate' | 'none'
+  /**
+   * Whether to allow images in HTML.
+   */
+  allowImages?: boolean
+  /**
+   * Whether to allow links in HTML.
+   */
+  allowLinks?: boolean
+  /**
+   * Whether to allow tables in HTML.
+   */
+  allowTables?: boolean
+  /**
+   * Whether to allow forms in HTML.
+   */
+  allowForms?: boolean
+  /**
+   * Whether to allow scripts in HTML.
+   */
+  allowScripts?: boolean
+  /**
+   * Whether to allow iframes in HTML.
+   */
+  allowIframes?: boolean
+  /**
+   * Whether to allow embedded content (video, audio, etc.).
+   */
+  allowEmbedded?: boolean
+  /**
+   * Whether to allow CSS styles in HTML.
+   */
+  allowStyles?: boolean
+  /**
+   * Whether to allow data attributes in HTML.
+   */
+  allowDataAttributes?: boolean
+  /**
+   * Custom metadata for the HTML field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for HTML semantic.
+ */
+export interface AppliedHTMLSemantic extends AppliedDataSemantic {
+  id: SemanticType.HTML
+  config?: HTMLConfig
+}
+
+/**
+ * Type guard to check if a semantic is an HTML semantic.
+ */
+export const isHTMLSemantic = (semantic: AppliedDataSemantic): semantic is AppliedHTMLSemantic => {
+  return semantic.id === SemanticType.HTML
+}
+
+/**
+ * Helper function to create an HTML semantic with configuration.
+ */
+export const createHTMLSemantic = (config: HTMLConfig = {}): AppliedHTMLSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_HTML_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.HTML,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for HTML semantic.
+ */
+export const DEFAULT_HTML_CONFIG: HTMLConfig = {
+  allowedTags: ['b', 'i', 'em', 'strong', 'a', 'ul', 'ol', 'li', 'p', 'br', 'pre', 'code', 'div', 'span'],
+  maxLength: 10000,
+  renderMode: 'html',
+  sanitizeLevel: 'strict',
+  allowImages: true,
+  allowLinks: true,
+  allowTables: true,
+  allowForms: false,
+  allowScripts: false,
+  allowIframes: false,
+  allowEmbedded: false,
+  allowStyles: false,
+  allowDataAttributes: false,
+}