@api-client/core 0.14.2 → 0.14.4

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.14.2",
+  "version": "0.14.4",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -135,7 +135,7 @@
     "oauth2-mock-server": "^8.0.0",
     "playwright": "^1.50.1",
     "prettier": "^3.5.1",
-    "sinon": "^20.0.0",
+    "sinon": "^21.0.0",
     "ts-lit-plugin": "^2.0.2",
     "ts-node-maintained": "^10.9.5",
     "typescript": "^5.5.2",
@@ -157,7 +157,6 @@
     "test:coverage": "wireit",
     "test:node": "node --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts",
     "test:node:coverage": "c8 --reporter lcov --reporter text node --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts",
-    "test:node:watch": "node --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts --watch",
     "build:api-models": "node data/model.js",
     "copy:assets": "cp -f ./oauth-popup.html ./build/oauth-popup.html",
     "start": "echo \"Use the npm run dev instead\"",

package/src/events/BaseEvents.ts

@@ -439,6 +439,10 @@ export interface ContextListOptions {
    * Some specific list operations might use this directly if not part of the main path.
    */
   oid?: string
+  /**
+   * Optional user id to filter results by the user
+   */
+  uid?: string
   /**
    * A structured filter object for advanced querying.
    */

package/src/modeling/ApiFile.ts

@@ -0,0 +1,53 @@
+import { File, type IFile } from '../models/store/File.js'
+import { ApiFileKind } from '../models/kinds.js'
+import { ApiModel, ApiModelSchema } from './ApiModel.js'
+
+export interface IApiFile extends IFile {
+  kind: typeof ApiFileKind
+}
+
+/**
+ * Used by the store. A file definition for the ApiModel.
+ */
+export class ApiFile extends File {
+  override kind = ApiFileKind
+
+  static override fromName(name: string): ApiFile {
+    return super.fromName(name, ApiFileKind) as ApiFile
+  }
+
+  /**
+   * Creates the file definition for a DomainNamespace contents.
+   *
+   * @param input The data namespace instance or schema.
+   */
+  static fromApiModel(input: ApiModel | ApiModelSchema): ApiFile {
+    let final: ApiModelSchema
+    if (typeof (input as ApiModel).toJSON === 'function') {
+      final = (input as ApiModel).toJSON()
+    } else {
+      final = input as ApiModelSchema
+    }
+    return new ApiFile({ key: final.key, info: final.info })
+  }
+
+  constructor(state: Partial<IApiFile> = {}) {
+    super({ ...state, kind: ApiFileKind })
+  }
+
+  static isApiFile(input: unknown): boolean {
+    const typed = input as IApiFile
+    if (!input || typed.kind !== ApiFileKind) {
+      return false
+    }
+    return true
+  }
+
+  override toJSON(): IApiFile {
+    const result: IApiFile = {
+      ...super.toJSON(),
+      kind: ApiFileKind,
+    }
+    return result
+  }
+}

package/src/modeling/ApiModel.ts

@@ -0,0 +1,327 @@
+import { nanoid } from '../nanoid.js'
+import { ApiModelKind } from '../models/kinds.js'
+import { type IThing, Thing } from '../models/Thing.js'
+import type {
+  AccessRule,
+  AuthenticationConfiguration,
+  AuthorizationConfiguration,
+  ExposedEntity,
+  ForeignDomainDependency,
+  RateLimitingConfiguration,
+  SessionConfiguration,
+} from './types.js'
+import { DataDomain, type DataDomainSchema } from './DataDomain.js'
+
+export interface ApiModelSchema {
+  /**
+   * The data domain kind recognizable by the ecosystem.
+   */
+  kind: typeof ApiModelKind
+  /**
+   * The unique key of the data domain schema.
+   * This is a stable identifier that does not change across versions.
+   */
+  key: string
+  /**
+   * Contains the name, display name, description, and the version of the data domain schema.
+   */
+  info: IThing
+
+  /**
+   * The designated Data Entity that represents a "User".
+   * This entity must be marked with the "User" semantic in the Data Modeler.
+   *
+   * This property is required to publish the API.
+   */
+  userKey?: string
+
+  /**
+   * Reference to the stable, version-controlled data definition from the
+   * Data Catalog. When not set, the model cannot be published.
+   */
+  domain?: ForeignDomainDependency
+
+  /**
+   * Configuration for how users prove their identity.
+   * The API model is invalid if this is not set.
+   */
+  authentication?: AuthenticationConfiguration
+
+  /**
+   * Configuration for what authenticated users are allowed to do.
+   * The API model is invalid if this is not set.
+   */
+  authorization?: AuthorizationConfiguration
+
+  /**
+   * Configuration for the transport and payload of the user session.
+   * The API model is invalid if this is not set.
+   */
+  session?: SessionConfiguration
+  /**
+   * The specific subset of Data Entities to be exposed by this API.
+   * These are the entities that are included in the data domain schema.
+   */
+  exposes: ExposedEntity[]
+
+  /**
+   * Optional array of access rules that define the access control policies
+   * for the API. These rules are used to enforce security and permissions
+   * on the exposed entities.
+   *
+   * These rules apply to all exposed entities and actions. An API action
+   * can declare its own access rules, which will override these.
+   */
+  accessRule?: AccessRule[]
+  /**
+   * Optional configuration for API-wide rate limiting and throttling.
+   * Defines rules to protect the API from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+}
+
+export class ApiModel extends EventTarget {
+  /**
+   * The data domain kind recognizable by the ecosystem.
+   */
+  kind: typeof ApiModelKind
+  /**
+   * The unique key of the data domain schema.
+   * This is a stable identifier that does not change across versions.
+   */
+  key: string
+
+  /**
+   * The description of the domain property.
+   */
+  info: Thing
+  /**
+   * The designated Data Entity that represents a "User".
+   * This entity must be marked with the "User" semantic in the Data Modeler.
+   *
+   * This property is required to publish the API.
+   */
+  userKey?: string
+
+  /**
+   * Reference to the stable, version-controlled data definition from the
+   * Data Catalog. When not set, the model cannot be published.
+   */
+  domain?: ForeignDomainDependency
+
+  /**
+   * Configuration for how users prove their identity.
+   * The API model is invalid if this is not set.
+   */
+  authentication?: AuthenticationConfiguration
+
+  /**
+   * Configuration for what authenticated users are allowed to do.
+   * The API model is invalid if this is not set.
+   */
+  authorization?: AuthorizationConfiguration
+
+  /**
+   * Configuration for the transport and payload of the user session.
+   * The API model is invalid if this is not set.
+   */
+  session?: SessionConfiguration
+  /**
+   * The specific subset of Data Entities to be exposed by this API.
+   * These are the entities that are included in the data domain schema.
+   */
+  exposes: ExposedEntity[]
+  /**
+   * Optional array of access rules that define the access control policies
+   * for the API. These rules are used to enforce security and permissions
+   * on the exposed entities.
+   *
+   * These rules apply to all exposed entities and actions. An API action
+   * can declare its own access rules, which will override these.
+   */
+  accessRule?: AccessRule[]
+  /**
+   * Optional configuration for API-wide rate limiting and throttling.
+   * Defines rules to protect the API from overuse.
+   */
+  rateLimiting?: RateLimitingConfiguration
+
+  /**
+   * When the initializing flag is set to true,
+   * the domain is not notified of changes.
+   */
+  #initializing = true
+
+  /**
+   * When the notifying flag is set to true,
+   * the domain is pending a notification.
+   * No other notifications will be sent until
+   * the current notification is sent.
+   */
+  #notifying = false
+
+  /**
+   * A reference to the published data domain.
+   */
+  dataDomain?: DataDomain
+
+  static createSchema(input: Partial<ApiModelSchema> = {}): ApiModelSchema {
+    const { key = nanoid(), exposes = [] } = input
+    const info = Thing.fromJSON(input.info, { name: 'Unnamed API' }).toJSON()
+    const result: ApiModelSchema = {
+      kind: ApiModelKind,
+      key,
+      info,
+      exposes,
+    }
+    if (input.userKey) {
+      result.userKey = input.userKey
+    }
+    if (input.domain) {
+      result.domain = input.domain
+    }
+    if (input.authentication) {
+      result.authentication = input.authentication
+    }
+    if (input.authorization) {
+      result.authorization = input.authorization
+    }
+    if (input.session) {
+      result.session = input.session
+    }
+    if (input.accessRule) {
+      result.accessRule = input.accessRule
+    }
+    if (input.rateLimiting) {
+      result.rateLimiting = input.rateLimiting
+    }
+    return result
+  }
+
+  constructor(state?: Partial<ApiModelSchema>, domain?: DataDomainSchema) {
+    super()
+    const init = ApiModel.createSchema(state)
+    this.kind = init.kind
+    this.key = init.key
+    this.info = new Thing(init.info)
+    this.userKey = init.userKey
+    if (init.domain) {
+      this.domain = structuredClone(init.domain)
+    }
+    if (init.authentication) {
+      this.authentication = structuredClone(init.authentication)
+    }
+    if (init.authorization) {
+      this.authorization = structuredClone(init.authorization)
+    }
+    if (init.session) {
+      this.session = structuredClone(init.session)
+    }
+    if (Array.isArray(init.exposes)) {
+      this.exposes = structuredClone(init.exposes)
+    } else {
+      this.exposes = []
+    }
+    if (init.accessRule) {
+      this.accessRule = structuredClone(init.accessRule)
+    }
+    if (init.rateLimiting) {
+      this.rateLimiting = structuredClone(init.rateLimiting)
+    }
+    if (domain) {
+      this.dataDomain = new DataDomain(domain)
+    }
+    this.#initializing = false
+    this.info.addEventListener('change', () => {
+      this.notifyChange()
+    })
+  }
+
+  toJSON(): ApiModelSchema {
+    const result: ApiModelSchema = {
+      kind: this.kind,
+      key: this.key,
+      info: this.info.toJSON(),
+      exposes: structuredClone(this.exposes),
+    }
+    if (this.userKey) {
+      result.userKey = this.userKey
+    }
+    if (this.domain) {
+      result.domain = structuredClone(this.domain)
+    }
+    if (this.authentication) {
+      result.authentication = structuredClone(this.authentication)
+    }
+    if (this.authorization) {
+      result.authorization = structuredClone(this.authorization)
+    }
+    if (this.session) {
+      result.session = structuredClone(this.session)
+    }
+    if (this.accessRule) {
+      result.accessRule = structuredClone(this.accessRule)
+    }
+    if (this.rateLimiting) {
+      result.rateLimiting = structuredClone(this.rateLimiting)
+    }
+    return result
+  }
+
+  /**
+   * This function is used internally by all domain elements to notify that something has changed.
+   * Since we want to notify listeners after the operation commits, we use microtask
+   * to ensure that the event is dispatched after the current operation.
+   */
+  notifyChange() {
+    if (this.#notifying || this.#initializing) {
+      return
+    }
+    this.#notifying = true
+    queueMicrotask(() => {
+      this.#notifying = false
+      const event = new Event('change')
+      this.dispatchEvent(event)
+    })
+  }
+
+  /**
+   * Exposes a new entity in the API model.
+   * If the entity already exists, it returns the existing one.
+   * @param entityKey The key of the entity to expose.
+   * @returns The exposed entity.
+   */
+  exposeEntity(entityKey: string): ExposedEntity {
+    const existing = this.exposes.find((e) => e.key === entityKey)
+    if (existing) {
+      return existing
+    }
+    const newEntity: ExposedEntity = {
+      key: entityKey,
+      actions: [],
+    }
+    this.exposes.push(newEntity)
+    this.notifyChange()
+    return newEntity
+  }
+
+  /**
+   * Removes an entity from the API model.
+   * @param entityKey The key of the entity to remove.
+   */
+  removeEntity(entityKey: string): void {
+    const index = this.exposes.findIndex((e) => e.key === entityKey)
+    if (index !== -1) {
+      this.exposes.splice(index, 1)
+      this.notifyChange()
+    }
+  }
+  /**
+   * Returns the exposed entity by its key.
+   * @param entityKey The key of the entity to find.
+   * @returns The exposed entity or undefined if not found.
+   */
+  getExposedEntity(entityKey: string): ExposedEntity | undefined {
+    return this.exposes.find((e) => e.key === entityKey)
+  }
+}

package/src/modeling/DataDomain.ts

@@ -134,7 +134,7 @@ export class DataDomain extends EventTarget {
   /**
    * The description of the domain property.
    */
-  accessor info: Thing
+  info: Thing
 
   /**
    * When the initializing flag is set to true,

package/src/modeling/DomainEntity.ts

@@ -165,7 +165,7 @@ export class DomainEntity extends DomainElement {
    */
   static createSchema(input: Partial<DomainEntitySchema> = {}): DomainEntitySchema {
     const { key = nanoid(), tags, semantics, fields, deprecated } = input
-    const info = Thing.fromJSON(input.info, { name: 'New entity' }).toJSON()
+    const info = Thing.fromJSON(input.info, { name: 'new_entity' }).toJSON()
     const result: DomainEntitySchema = {
       kind: DomainEntityKind,
       key,

package/src/modeling/DomainFile.ts

@@ -1,6 +1,4 @@
-import { nanoid } from '../nanoid.js'
 import { File, type IFile } from '../models/store/File.js'
-import { Thing } from '../models/Thing.js'
 import type { DataDomain, DataDomainSchema } from './DataDomain.js'
 import { DomainFileKind } from '../models/kinds.js'
 
@@ -30,46 +28,11 @@ export class DomainFile extends File {
     } else {
       final = input as DataDomainSchema
     }
-    const init: IDomainFile = {
-      kind: DomainFileKind,
-      key: final.key,
-      info: { ...final.info },
-      lastModified: { user: '', time: 0, byMe: false },
-      parents: [],
-      permissionIds: [],
-      permissions: [],
-    }
-    return new DomainFile(init)
+    return new DomainFile({ key: final.key, info: final.info })
   }
 
-  constructor(input?: string | IDomainFile) {
-    super()
-    let init: IDomainFile
-    if (typeof input === 'string') {
-      init = JSON.parse(input)
-    } else if (typeof input === 'object') {
-      init = input
-    } else {
-      init = {
-        kind: DomainFileKind,
-        key: nanoid(),
-        info: Thing.fromName('').toJSON(),
-        parents: [],
-        permissionIds: [],
-        permissions: [],
-        lastModified: { user: '', time: 0, byMe: false },
-      }
-    }
-    this.new(init)
-  }
-
-  override new(init: IDomainFile): this {
-    if (!DomainFile.isDomainFile(init)) {
-      throw new Error(`Not a data file.`)
-    }
-    super.new(init)
-    this.kind = DomainFileKind
-    return this
+  constructor(state: Partial<IDomainFile> = {}) {
+    super({ ...state, kind: DomainFileKind })
   }
 
   static isDomainFile(input: unknown): boolean {

package/src/modeling/Semantics.ts

@@ -10,14 +10,44 @@ export enum SemanticType {
   /**
    * Designates a Data Entity that represents users of the system.
    */
-  User = 'https://apinow.app/semantics/entities/#User',
+  User = 'Semantic#User',
 
   // Property-Level Semantics
-  CreatedTimestamp = 'https://apinow.app/semantics/properties/#CreatedTimestamp',
-  UpdatedTimestamp = 'https://apinow.app/semantics/properties/#UpdatedTimestamp',
-  DeletedTimestamp = 'https://apinow.app/semantics/properties/#DeletedTimestamp',
-  DeletedFlag = 'https://apinow.app/semantics/properties/#DeletedFlag',
-  PublicUniqueName = 'https://apinow.app/semantics/properties/#PublicUniqueName',
+  /**
+   * Annotates the field as the user password.
+   * The runtime should treat this field with special care,
+   * ensuring it is encrypted and not exposed in API responses.
+   */
+  Password = 'Semantic#Password',
+  /**
+   * Designates a Data Property as the `createdAt` timestamp of an entity.
+   * This is used to track when the entity was first created.
+   */
+  CreatedTimestamp = 'Semantic#CreatedTimestamp',
+  /**
+   * Designates a Data Property as the `updatedAt` timestamp of an entity.
+   * This is used to track when the entity was last modified.
+   */
+  UpdatedTimestamp = 'Semantic#UpdatedTimestamp',
+  /**
+   * Designates a Data Property as the `deletedAt` timestamp of an entity.
+   * This is used to track when the entity was soft-deleted.
+   * Soft-deletion means the entity is not physically removed from the database,
+   * but marked as deleted for logical deletion purposes.
+   */
+  DeletedTimestamp = 'Semantic#DeletedTimestamp',
+  /**
+   * Designates a Data Property as a boolean flag indicating whether the entity is deleted.
+   * This is used for soft-deletion, where the entity is not physically removed from the database,
+   * but marked as deleted.
+   */
+  DeletedFlag = 'Semantic#DeletedFlag',
+  /**
+   * Designates a Data Property as a unique public identifier for a resource.
+   * 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".
+   */
+  PublicUniqueName = 'Semantic#PublicUniqueName',
   /**
    * Designates a Data Property as the `role` of a user within the system.
    * This is used to define the user's permissions and access levels.
@@ -25,17 +55,34 @@ export enum SemanticType {
    * compared to a user with the role of "guest".
    * Roles are defined on the entity as enums, or as a string property with a controlled vocabulary.
    */
-  UserRole = 'https://apinow.app/semantics/entities/#UserRole',
+  UserRole = 'Semantic#UserRole',
   // Association-Level Semantics
-  ResourceOwnerIdentifier = 'https://apinow.app/semantics/associations/#ResourceOwnerIdentifier',
+  /**
+   * 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.
+   * For example, a blog post might have a resource owner identifier that points to the user who created it.
+   */
+  ResourceOwnerIdentifier = 'Semantic#ResourceOwnerIdentifier',
 }
 
 /**
  * Defines the scope at which a semantic can be applied.
  */
 export enum SemanticScope {
+  /**
+   * The semantic applies to an entire Data Entity.
+   * This is used for semantics that provide context or constraints at the entity level.
+   */
   Entity = 'Entity',
+  /**
+   * The semantic applies to a single Data Property.
+   * This is used for semantics that provide context or constraints at the property level.
+   */
   Property = 'Property',
+  /**
+   * The semantic applies to an Association between Data Entities.
+   * This is used for semantics that provide context or constraints at the association level.
+   */
   Association = 'Association',
 }
 
@@ -127,6 +174,14 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
   },
 
   // Property-Level Definitions
+  [SemanticType.Password]: {
+    id: SemanticType.Password,
+    displayName: 'User Password',
+    scope: SemanticScope.Property,
+    description:
+      'Annotates the field as the user password. The runtime should treat this field with special care, ensuring it is encrypted and not exposed in API responses.',
+    applicableDataTypes: ['string'],
+  },
   [SemanticType.CreatedTimestamp]: {
     id: SemanticType.CreatedTimestamp,
     displayName: 'Creation Timestamp',

package/src/modeling/amf/ShapeGenerator.ts

@@ -107,7 +107,7 @@ export class ShapeGenerator {
    * const amfShape = generator.entity(myDomainEntity);
    * ```
    */
-  entity(input: DomainEntity, visited: Set<string> = new Set<string>()): IApiNodeShape | IApiRecursiveShape {
+  entity(input: DomainEntity, visited = new Set<string>()): IApiNodeShape | IApiRecursiveShape {
     if (visited.has(input.key)) {
       // create a recursive shape.
       return this.createRecursiveShape(input)