@api-client/core 0.18.2 → 0.18.4

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

@@ -42065,6 +42065,9 @@
 "@id": "#191"
 },
 {
+"@id": "#206"
+},
+{
 "@id": "#194"
 },
 {
@@ -42077,9 +42080,6 @@
 "@id": "#203"
 },
 {
-"@id": "#206"
-},
-{
 "@id": "#209"
 }
 ],
@@ -43457,7 +43457,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
+"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43478,7 +43478,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43499,7 +43499,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43520,7 +43520,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
+"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43541,7 +43541,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
+"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44761,27 +44761,27 @@
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(10,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#199",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#205/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#205",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#208/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#208",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(10,0)]"
 },
 {
 "@id": "#223/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.2",
+  "version": "0.18.4",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -87,12 +87,14 @@
     "@api-client/json": "^0.2.0",
     "@esm-bundle/chai": "^4.3.4-fix.0",
     "@metrichor/jmespath": "^0.3.1",
+    "@pawel-up/csv": "^0.2.0",
     "@pawel-up/data-mock": "^0.4.0",
     "@pawel-up/jexl": "^4.0.1",
     "@xmldom/xmldom": "^0.9.7",
     "amf-json-ld-lib": "^0.0.15",
     "chalk": "^5.4.1",
     "console-table-printer": "^2.11.2",
+    "isomorphic-dompurify": "^2.26.0",
     "nanoid": "^5.1.5",
     "ws": "^8.12.0",
     "xpath": "^0.0.34"
@@ -111,6 +113,7 @@
     "@types/cors": "^2.8.12",
     "@types/express-ntlm": "^2.3.3",
     "@types/jsdom": "^21.1.7",
+    "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
     "@types/node": "^24.0.1",
     "@types/sinon": "^17.0.1",
@@ -131,11 +134,11 @@
     "get-port": "^7.0.0",
     "globals": "^16.0.0",
     "husky": "^9.0.11",
-    "jsdom": "^26.0.0",
     "lint-staged": "^16.0.0",
     "nock": "^14.0.1",
     "oauth2-mock-server": "^8.0.0",
     "prettier": "^3.5.1",
+    "schema-org-json-schemas": "^2.1.4",
     "sinon": "^21.0.0",
     "ts-lit-plugin": "^2.0.2",
     "ts-node-maintained": "^10.9.5",

package/src/modeling/ApiModel.ts

@@ -3,6 +3,7 @@ import { ApiModelKind, DataDomainKind } from '../models/kinds.js'
 import { type IThing, Thing } from '../models/Thing.js'
 import type {
   AccessRule,
+  AssociationTarget,
   AuthenticationConfiguration,
   AuthorizationConfiguration,
   ExposedEntity,
@@ -64,11 +65,11 @@ export interface ApiModelSchema extends DependentModelSchema {
 
   /**
    * The designated Data Entity that represents a "User".
-   * This entity must be marked with the "User" semantic in the Data Modeler.
+   * This entity should be marked with the "User" semantic in the Data Modeler.
    *
    * This property is required to publish the API.
    */
-  userKey?: string
+  user?: AssociationTarget
 
   /**
    * Configuration for how users prove their identity.
@@ -142,7 +143,7 @@ export class ApiModel extends DependentModel {
    *
    * This property is required to publish the API.
    */
-  userKey?: string
+  user?: AssociationTarget
 
   /**
    * Configuration for how users prove their identity.
@@ -232,8 +233,8 @@ export class ApiModel extends DependentModel {
       info,
       exposes,
     }
-    if (input.userKey) {
-      result.userKey = input.userKey
+    if (input.user) {
+      result.user = { ...input.user }
     }
     if (input.dependencyList) {
       result.dependencyList = structuredClone(input.dependencyList)
@@ -279,7 +280,7 @@ export class ApiModel extends DependentModel {
     this.kind = init.kind
     this.key = init.key
     this.info = new Thing(init.info)
-    this.userKey = init.userKey
+    this.user = init.user
     if (init.authentication) {
       this.authentication = structuredClone(init.authentication)
     }
@@ -322,8 +323,8 @@ export class ApiModel extends DependentModel {
       info: this.info.toJSON(),
       exposes: structuredClone(this.exposes),
     }
-    if (this.userKey) {
-      result.userKey = this.userKey
+    if (this.user) {
+      result.user = { ...this.user }
     }
     if (this.dependencyList.length > 0) {
       result.dependencyList = structuredClone(this.dependencyList)
@@ -414,14 +415,14 @@ export class ApiModel extends DependentModel {
 
   /**
    * Clears the API model for a new entity change.
-   * This method resets the dependencies, exposes, userKey,
+   * This method resets the dependencies, exposes, user,
    * authentication, authorization, and session properties.
    */
   cleanForEntityChange(): void {
     this.dependencies.clear()
     this.dependencyList = []
     this.exposes = []
-    this.userKey = undefined
+    this.user = undefined
     if (this.session) {
       this.session.properties = []
     }

package/src/modeling/helpers/database.ts

@@ -0,0 +1,48 @@
+import DOMPurify from 'isomorphic-dompurify'
+import { snakeCase } from '@pawel-up/jexl/string.js'
+
+export function sanitizeInput(input: string): string {
+  return DOMPurify.isSupported ? DOMPurify.sanitize(input) : input
+}
+
+/**
+ * Converts a string into a sanitized, database column friendly name.
+ * - Sanitizes the input using DOMPurify.
+ * - Converts to lowercase.
+ * - Replaces spaces and multiple underscores with a single underscore.
+ * - Removes any characters that are not alphanumeric or underscore.
+ *
+ * @param inputName The string to format.
+ * @returns A database column friendly name.
+ */
+export function toDatabaseColumnName(inputName: string, defaultName = 'untitled_column'): string {
+  // 1. Sanitize
+  let name = sanitizeInput(inputName)
+
+  // 2. Convert to lowercase
+  name = snakeCase(name)
+
+  // 3. Replace spaces and multiple hyphens/underscores with a single underscore
+  name = name.replace(/[\s-]+/g, '_')
+
+  // 4. Remove any characters that are not alphanumeric or underscore
+  name = name.replace(/[^a-z0-9_]/g, '')
+
+  // 5. Ensure it doesn't start or end with an underscore (optional, but good practice)
+  name = name.replace(/^_+|_+$/g, '')
+
+  return name || defaultName
+}
+/**
+ * Converts a string into a sanitized, database table friendly name.
+ * - Sanitizes the input using DOMPurify.
+ * - Converts to lowercase.
+ * - Replaces spaces and multiple underscores with a single underscore.
+ * - Removes any characters that are not alphanumeric or underscore.
+ *
+ * @param inputName The string to format.
+ * @returns A database table friendly name.
+ */
+export function toDatabaseTableName(inputName: string, defaultName = 'untitled_table'): string {
+  return toDatabaseColumnName(inputName, defaultName)
+}

package/src/modeling/importers/CsvImporter.ts

@@ -0,0 +1,88 @@
+import { type CSVOptions, CSVParser, type ParseResult } from '@pawel-up/csv'
+import type { DataDomain } from '../DataDomain.js'
+import { sanitizeInput, toDatabaseColumnName, toDatabaseTableName } from '../helpers/database.js'
+import type { DomainPropertySchema } from '../DomainProperty.js'
+
+export type { CSVOptions, ParseResult }
+
+/**
+ * Imports CSV data into a DataDomain.
+ *
+ * This class parses CSV files and translates the column definitions into DomainProperty instances
+ * within a specified DomainModel and DomainEntity.
+ */
+export class CsvImporter {
+  private parser: CSVParser
+  private domain: DataDomain
+
+  /**
+   * Creates an instance of CsvImporter.
+   * @param domain The DataDomain to which the imported data will be added.
+   * @param options Optional CSV parsing options.
+   */
+  constructor(domain: DataDomain, options?: CSVOptions) {
+    this.parser = new CSVParser(options)
+    this.domain = domain
+  }
+
+  /**
+   * Parses a CSV file or string to extract its structure and data.
+   * This is a wrapper around the underlying CSV parser.
+   * @param csv The CSV content to parse, as a File object or a string.
+   * @returns A promise that resolves with the parsed result.
+   */
+  public parse(csv: File | string): Promise<ParseResult> {
+    return this.parser.parse(csv)
+  }
+
+  /**
+   * Imports the parsed CSV data structure into the domain as a new model and entity.
+   * It creates a `DomainEntity` where each column from the CSV is represented as a `DomainProperty`.
+   * The first row of data is used to provide an example value for each property.
+   * @param data The result from the `parse` method, containing the CSV structure and values.
+   * @param modelName The name to be used for the created `DomainModel` and `DomainEntity`.
+   * @returns A promise that resolves when the import is complete.
+   */
+  public async import(data: ParseResult, modelName: string): Promise<void> {
+    const name = toDatabaseTableName(modelName, 'imported_cvs_data')
+    const model = this.domain.addModel({ info: { name } })
+    const entity = model.addEntity({ info: { name } })
+    const sanitizedInputName = sanitizeInput(modelName)
+    if (name !== sanitizedInputName) {
+      model.info.displayName = sanitizedInputName
+      entity.info.displayName = sanitizedInputName
+    }
+    for (const row of data.format) {
+      const { index, name, type, format } = row
+      const columnName = toDatabaseColumnName(name, `column_${index}`)
+      const schema: Partial<DomainPropertySchema> = {
+        info: { name: columnName },
+        type,
+      }
+      if (format) {
+        schema.bindings = [
+          {
+            type: 'web',
+            schema: {
+              format: format === 'integer' ? 'int64' : 'double',
+            },
+          },
+        ]
+      }
+      const exampleRow = data.values[0]
+      if (Array.isArray(exampleRow) && exampleRow[index]) {
+        const value = exampleRow[index]
+        if (value !== undefined && value !== null) {
+          schema.schema = {
+            examples: [sanitizeInput(String(value))],
+          }
+        }
+      }
+      const prop = entity.addProperty(schema)
+      const sn = sanitizeInput(name)
+      if (sn !== columnName) {
+        prop.info.displayName = sn
+      }
+    }
+  }
+}

package/src/modeling/importers/ImporterException.ts

@@ -0,0 +1,10 @@
+import { Exception } from '../../exceptions/exception.js'
+
+/**
+ * An exception thrown during the JSON Schema import process when an
+ * unrecoverable error occurs.
+ */
+export class ImporterException extends Exception {
+  static override code = 'E_IMPORTER_FAILURE'
+  static override status = 400 // Bad Request, as it's likely due to invalid input schemas
+}