@api-client/core 0.20.8 → 0.20.10

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.20.8",
+  "version": "0.20.10",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/src/mocking/ModelingMock.ts

@@ -10,6 +10,9 @@ import { DataCatalog } from './lib/DataCatalog.js'
 import { Permission } from './lib/Permission.js'
 import { Ai } from './lib/Ai.js'
 import { Deployment } from './lib/Deployment.js'
+import type { MockListResult } from '../sdk/SdkMock.js'
+import { ResourceResponse } from '../sdk/SdkBase.js'
+import { ContextListResult } from '../events/BaseEvents.js'
 
 export class ModelingMock {
   faker: Faker = faker
@@ -24,4 +27,55 @@ export class ModelingMock {
   permission = new Permission()
   ai = new Ai()
   deployments = new Deployment()
+
+  /**
+   * Wraps a single resource in a standard API resource response structure and serializes it to a JSON string.
+   *
+   * @param resource - The resource object to wrap.
+   * @returns A JSON string representation of the wrapped resource.
+   */
+  public wrapResource<T extends object>(resource: T): string {
+    const wrapper: ResourceResponse<T> = {
+      data: resource,
+    }
+    return JSON.stringify(wrapper)
+  }
+
+  /**
+   * Wraps a list of items in a standard API list response structure, including an optional pagination cursor,
+   * and serializes it to a JSON string.
+   *
+   * @param items - The array of items to wrap.
+   * @param init - Optional configuration for the mock list result, such as cursor settings.
+   * @returns A JSON string representation of the wrapped list.
+   */
+  public wrapList<T extends object>(items: (T | undefined)[], init?: MockListResult): string {
+    const obj: ContextListResult<T | undefined> = {
+      data: items,
+      cursor: this.createCursorOption(init),
+    }
+    return JSON.stringify(obj)
+  }
+
+  /**
+   * Generates or determines the pagination cursor based on the provided mock initialization options.
+   * If a cursor is explicitly provided, it is returned. If explicitly disabled, it returns undefined.
+   * Otherwise, it randomly generates a mock JWT string to simulate a cursor.
+   *
+   * @param init - Configuration object detailing cursor behavior.
+   * @returns The cursor string or undefined if no cursor should be present.
+   */
+  protected createCursorOption(init: MockListResult = {}): string | undefined {
+    if (init.cursor === false) {
+      return undefined
+    }
+    if (typeof init.cursor === 'string') {
+      return init.cursor
+    }
+    const hasCursor = init.cursor === true ? true : this.faker.datatype.boolean()
+    if (!hasCursor) {
+      return undefined
+    }
+    return this.faker.internet.jwt()
+  }
 }

package/src/modeling/RuntimeApiModel.ts

@@ -11,12 +11,55 @@ import { SemanticType } from './Semantics.js'
 import { AccessRule, AccessRuleExecutionPhase } from './rules/AccessRule.js'
 import { Exception } from '../exceptions/exception.js'
 
+/**
+ * Describes a mapped parameter for a route.
+ */
+export interface RouteParam {
+  /**
+   * The name of the parameter in the path (e.g. "userId")
+   * This can be anything as the user can freely change the param names.
+   */
+  paramName: string
+  /**
+   * The "key" of the exposed entity this parameter belongs to.
+   */
+  exposedEntityKey: string
+  /**
+   * The "name" of the exposed entity this parameter belongs to.
+   */
+  exposedEntityName: string
+  /**
+   * The primary key's property name of the exposed entity (e.g., "id").
+   */
+  propertyName: string
+  /**
+   * The name of the association that connects the parent entity to its child (e.g., "comments")
+   * If its missing it means that there's no association, so there's no sub-endpoint in the path
+   * (e.g., `/users/123` - It's a single root endpoint - it doesn't have any sub-endpoints.)
+   */
+  associationName?: string
+}
+
 /**
  * Identifies a specific exposed entity and its action kind.
  */
 export interface RouteLookup {
+  /**
+   * The "key" of the exposed entity that is being accessed.
+   */
   exposedEntityKey: string
+  /**
+   * The "name" of the exposed entity that is being accessed.
+   */
+  exposedEntityName: string
+  /**
+   * The "kind" of the action that is being performed.
+   */
   actionKind: ActionKind
+  /**
+   * Information about each path parameter in this route.
+   */
+  params: RouteParam[]
 }
 
 /**
@@ -44,6 +87,7 @@ export interface RuntimeResolvedAction {
   entity: DomainEntity
   action: Action
   params: Record<string, string>
+  lookup: RouteLookup
 }
 
 export type RuleEvaluator = (rule: AccessRule) => Promise<boolean | undefined> | boolean | undefined
@@ -429,6 +473,7 @@ export class RuntimeApiModel extends ApiModel {
       entity,
       action,
       params,
+      lookup: def.lookup,
     }
   }
 

package/src/modeling/generators/RuntimeModelGenerator.ts

@@ -1,6 +1,7 @@
 import { type ActionKind, type UpdateAction } from '../actions/index.js'
 import { ApiModel, type ApiModelSchema } from '../ApiModel.js'
-import { type RouteDefinition, type RuntimeApiModelSchema } from '../RuntimeApiModel.js'
+import { ExposedEntity } from '../ExposedEntity.js'
+import { RouteParam, type RouteDefinition, type RuntimeApiModelSchema } from '../RuntimeApiModel.js'
 
 /**
  * A class that takes the API model and generates a runtime-optimized API model.
@@ -34,27 +35,27 @@ export class RuntimeModelGenerator {
       for (const action of expose.actions) {
         switch (action.kind) {
           case 'list':
-            if (colPath) this.addRoute('GET', colPath, expose.key, action.kind)
+            if (colPath) this.addRoute('GET', colPath, expose, action.kind)
             break
           case 'create':
-            if (colPath) this.addRoute('POST', colPath, expose.key, action.kind)
+            if (colPath) this.addRoute('POST', colPath, expose, action.kind)
             break
           case 'search':
-            if (colPath) this.addRoute('POST', `${colPath}/search`, expose.key, action.kind)
+            if (colPath) this.addRoute('POST', `${colPath}/search`, expose, action.kind)
             break
           case 'read':
-            if (resPath) this.addRoute('GET', resPath, expose.key, action.kind)
+            if (resPath) this.addRoute('GET', resPath, expose, action.kind)
             break
           case 'update':
             if (resPath) {
               const updateAction = action as UpdateAction
               for (const method of updateAction.allowedMethods) {
-                this.addRoute(method, resPath, expose.key, action.kind)
+                this.addRoute(method, resPath, expose, action.kind)
               }
             }
             break
           case 'delete':
-            if (resPath) this.addRoute('DELETE', resPath, expose.key, action.kind)
+            if (resPath) this.addRoute('DELETE', resPath, expose, action.kind)
             break
         }
       }
@@ -66,14 +67,65 @@ export class RuntimeModelGenerator {
     }
   }
 
-  private addRoute(method: string, path: string, exposedEntityKey: string, actionKind: ActionKind): void {
+  private addRoute(method: string, path: string, expose: ExposedEntity, actionKind: ActionKind): void {
     const upperMethod = method.toUpperCase()
     if (!this.#routingMap[upperMethod]) {
       this.#routingMap[upperMethod] = []
     }
+
+    const domainEntity = this.#apiModel.domain?.findEntity(expose.entity.key, expose.entity.domain)
+    if (!domainEntity) throw new Error(`Entity ${expose.key} not found, this should never happen`)
+
+    const params: RouteParam[] = []
+    let current: ExposedEntity | undefined
+    let previous: ExposedEntity | undefined = undefined
+    if (['list', 'create', 'search'].includes(actionKind)) {
+      // when starting with a collection, ignore self and start with parent (if any).
+      // A collection won't have any path params anyway, so we can skip it.
+      current = expose.parent ? this.#apiModel.exposes.get(expose.parent.key) : undefined
+      // setting the previous to the current so the associations are captured.
+      previous = expose
+    } else {
+      current = expose
+    }
+
+    while (current) {
+      const match = current.resourcePath.match(/\{([^}]+)\}/)
+      if (match) {
+        const entity = this.#apiModel.domain?.findEntity(current.entity.key, current.entity.domain)
+        if (!entity) throw new Error(`Entity ${current.entity.key} not found, this should never happen`)
+        const pkName = entity.primaryKey()?.info.name
+        if (!pkName) throw new Error(`Entity ${current.entity.key} has no primary key, this should never happen`)
+
+        let associationName: string | undefined
+        if (previous && previous.parent && previous.parent.key === current.key) {
+          for (const assoc of entity.withInheritedAssociations()) {
+            if (previous.parent?.association.key === assoc.key) {
+              associationName = assoc.info.name
+              break
+            }
+          }
+        }
+
+        params.push({
+          paramName: match[1],
+          exposedEntityKey: current.key,
+          exposedEntityName: entity.info.name as string,
+          propertyName: pkName,
+          ...(associationName ? { associationName } : {}),
+        })
+      }
+      previous = current
+      current = current.parent ? this.#apiModel.exposes.get(current.parent.key) : undefined
+    }
     this.#routingMap[upperMethod].push({
       path,
-      lookup: { exposedEntityKey, actionKind },
+      lookup: {
+        exposedEntityKey: expose.key,
+        exposedEntityName: domainEntity.info.name as string,
+        actionKind,
+        params,
+      },
     })
   }
 }