@api-client/core 0.19.18 → 0.19.20

package/src/modeling/types.ts

@@ -223,41 +223,35 @@ export interface ProblemDetails {
 }
 
 /**
- * The set of supported filter operators for the List action.
+ * The set of supported filter operators for the List and search action.
  * These are used in query parameters, e.g., ?price[gte]=100
  *
  * - eq: Equal
- * - nq: Not Equal
+ * - neq: Not Equal
+ * - in: Value is one of the elements in the provided array
+ * - nin: Value is not one of the elements in the provided array
  * - lt: Less Than
  * - lte: Less Than or Equal
  * - gt: Greater Than
  * - gte: Greater Than or Equal
- * - ex: Checks if the field exists
- * - re: Regular expression match
- * - bf: Date before a specific value
- * - af: Date after a specific value
- * - cn: String contains substring / Array contains element
- * - st: String starts with
- * - end: String ends with
- * - in: Value is one of the elements in the provided array
- * - nin: Value is not one of the elements in the provided array
+ * - exists: Checks if the field exists
+ *
+ * Search filters only:
+ * - contains: String contains substring / Array contains element (Substring Match)
+ * - match: Lexical Match, multi-word queries against long text.
  */
 export type ResourceFilterOperator =
   | 'eq' // Equal
-  | 'nq' // Not equal
+  | 'neq' // Not equal
+  | 'in' // Value is one of the elements in the provided array
+  | 'nin' // Value is not one of the elements in the provided array
   | 'lt' // Less than
   | 'lte' // Less than or equal
   | 'gt' // Greater than
   | 'gte' // Greater than or equal
-  | 'ex' // Checks if the field exists
-  | 're' // Regular expression match
-  | 'bf' // Date before a specific value
-  | 'af' // Date after a specific value
-  | 'cn' // String contains substring / Array contains element
-  | 'st' // String starts with
-  | 'end' // String ends with
-  | 'in' // Value is one of the elements in the provided array
-  | 'nin' // Value is not one of the elements in the provided array
+  | 'exists' // Checks if the field exists
+  | 'contains' // String contains substring / Array contains element (Substring Match)
+  | 'match' // Lexical Match, multi-word queries against long text.
 
 /**
  * The session transport configuration interface.
@@ -384,6 +378,8 @@ export interface RolesBasedAccessControl extends AuthorizationConfiguration {
   roleKey: string
 }
 
+export type AuthorizationStrategy = RolesBasedAccessControl
+
 /**
  * Configures the strategy for authenticating end-users.
  * An API can only support one authentication strategy at a time.
@@ -412,6 +408,8 @@ export interface UsernamePasswordConfiguration extends AuthenticationConfigurati
   passwordKey?: string
 }
 
+export type AuthenticationStrategy = UsernamePasswordConfiguration
+
 /**
  * Represents a Data Entity from the Data Domain that the API will expose and operate upon.
  */
@@ -492,6 +490,10 @@ export interface ExposedEntitySchema {
    * When true, generation for this exposure hit configured limits
    */
   truncated?: boolean
+  /**
+   * Pagination contract for this exposure.
+   */
+  paginationContract?: PaginationContract
 }
 
 /**
@@ -542,7 +544,13 @@ export interface PaginationStrategy {
    * The default page size for the pagination strategy.
    * This is the number of items returned per page when no specific page size is requested.
    */
-  pageSize?: number
+  defaultLimit?: number
+  /**
+   * The maximum page size for the pagination strategy.
+   * This is the maximum number of items that can be returned per page.
+   * The API runtime defined the upper limit to prevent abuse.
+   */
+  maxLimit?: number
 }
 
 /**
@@ -559,6 +567,31 @@ export interface OffsetPaginationStrategy extends PaginationStrategy {
   kind: 'offset'
 }
 
+/**
+ * Represents the contract for pagination. Defines which fields can be used for filtering, sorting,
+ * and searching.
+ */
+export interface PaginationContract {
+  /**
+   * The list of fields (property keys) that can be used for filtering.
+   */
+  filterableFields: string[]
+  /**
+   * The list of fields (property keys) that can be used for sorting.
+   */
+  sortableFields: string[]
+  /**
+   * The list of fields (property keys) that can be used for searching.
+   * Note that these properties must be of type string or array of strings.
+   */
+  searchableFields: string[]
+  /**
+   * The default sort order for the pagination strategy.
+   * This is the sort order that will be used when no sort order is specified.
+   */
+  defaultSort?: { field: string; direction: 'asc' | 'desc' }[]
+}
+
 export type DomainImpactKinds =
   | typeof DomainNamespaceKind
   | typeof DomainEntityKind

package/src/modeling/validation/api_model_rules.ts

@@ -348,49 +348,62 @@ export function validateApiModelMetadata(model: ApiModel): ApiModelValidationIte
   return issues
 }
 
-export function validateAction(action: Action, parent: ExposedEntity, apiModelKey: string): ApiModelValidationItem[] {
+export function validateApiPagination(model: ApiModel): ApiModelValidationItem[] {
   const issues: ApiModelValidationItem[] = []
   const context: ApiModelValidationContext = {
-    apiModelKey,
-    kind: 'Action',
-    key: action.kind, // Actions lack nanoids, kind represents its type
-    parentExposedEntityKey: parent.key,
+    apiModelKey: model.key,
+    kind: ApiModelKind,
+    key: model.key,
   }
-
-  if (ListAction.isListAction(action)) {
-    if (!action.pagination || !action.pagination.kind) {
+  // We only need pagination when the API contains at least one List or Search action
+  let validate = false
+  for (const exposure of model.exposes.values()) {
+    if (exposure.actions.some((action) => ListAction.isListAction(action) || SearchAction.isSearchAction(action))) {
+      validate = true
+      break
+    }
+  }
+  if (!validate) {
+    return issues
+  }
+  if (!model.pagination || !model.pagination.kind) {
+    issues.push({
+      code: createCode('API', 'MISSING_PAGINATION'),
+      message: 'The API must have a defined pagination strategy when it exposes List or Search actions.',
+      suggestion: 'Configure how results are loaded (e.g. by page or by a continuous cursor).',
+      severity: 'error',
+      context: { ...context, property: 'pagination' },
+    })
+  } else {
+    if (model.pagination.defaultLimit === undefined) {
       issues.push({
-        code: createCode('ACTION', 'LIST_MISSING_PAGINATION'),
-        message: 'A List action must have a defined pagination strategy.',
-        suggestion: 'Configure how results are loaded (e.g. by page or by a continuous cursor).',
-        severity: 'error',
-        context: { ...context, property: 'pagination' },
+        code: createCode('API', 'MISSING_PAGINATION_DEFAULT_LIMIT'),
+        message: "The API doesn't have a defined default page limit when it exposes List or Search actions.",
+        suggestion: 'Set a default page limit for the pagination otherwise the API will use its default limit.',
+        severity: 'info',
+        context: { ...context, property: 'pagination.defaultLimit' },
       })
     }
-    if (
-      (!action.filterableFields || action.filterableFields.length === 0) &&
-      (!action.sortableFields || action.sortableFields.length === 0)
-    ) {
+    if (model.pagination.maxLimit === undefined) {
       issues.push({
-        code: createCode('ACTION', 'LIST_MISSING_FILTERS'),
-        message: 'Listing all elements without filters or sorting could be overwhelming for large tables.',
-        suggestion: 'Select a few important fields to allow sorting and searching by.',
-        severity: 'warning',
-        context,
+        code: createCode('API', 'MISSING_PAGINATION_MAX_LIMIT'),
+        message: "The API doesn't have a defined page size max limit when it exposes List or Search actions.",
+        suggestion: 'Set a max page size limit for the pagination otherwise the API will use its default max limit.',
+        severity: 'info',
+        context: { ...context, property: 'pagination.maxLimit' },
       })
     }
   }
+  return issues
+}
 
-  if (SearchAction.isSearchAction(action)) {
-    if (!action.fields || action.fields.length === 0) {
-      issues.push({
-        code: createCode('ACTION', 'SEARCH_MISSING_FIELDS'),
-        message: 'A Search action needs to know which fields to look in.',
-        suggestion: 'Select the properties (like names or emails) that the search will run on.',
-        severity: 'error',
-        context: { ...context, property: 'fields' },
-      })
-    }
+export function validateAction(action: Action, parent: ExposedEntity, apiModelKey: string): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey,
+    kind: 'Action',
+    key: action.kind, // Actions lack nanoids, kind represents its type
+    parentExposedEntityKey: parent.key,
   }
 
   if (DeleteAction.isDeleteAction(action)) {
@@ -573,9 +586,14 @@ export function validateExposedEntity(entity: ExposedEntity, apiModel: ApiModel)
       context: { ...context, property: 'actions' },
     })
   } else {
+    let hasSearch = false
+    let hasList = false
     for (const action of entity.actions) {
       issues.push(...validateAction(action, entity, apiModel.key))
 
+      if (SearchAction.isSearchAction(action)) hasSearch = true
+      if (ListAction.isListAction(action)) hasList = true
+
       // Check inheritance of access rules
       // For a rule to exist, it might be on the action, the exposure, any parent, or the apiModel.
       let hasAuth = false
@@ -605,6 +623,59 @@ export function validateExposedEntity(entity: ExposedEntity, apiModel: ApiModel)
         })
       }
     }
+
+    if (hasList || hasSearch) {
+      const contract = entity.paginationContract
+      if (!contract) {
+        issues.push({
+          code: createCode('EXPOSURE', 'MISSING_PAGINATION_CONTRACT'),
+          message: 'The List or Search action needs a pagination contract.',
+          suggestion: 'Add a pagination contract to the exposed entity.',
+          severity: 'error',
+          context,
+        })
+      } else {
+        if (hasList) {
+          if (!contract.filterableFields || contract.filterableFields.length === 0) {
+            issues.push({
+              code: createCode('EXPOSURE', 'LIST_MISSING_FILTERS'),
+              message: 'Listing all elements without filters could be overwhelming for large tables.',
+              suggestion: 'Select a few important fields to allow filtering.',
+              severity: 'warning',
+              context,
+            })
+          }
+          if (!contract.sortableFields || contract.sortableFields.length === 0) {
+            issues.push({
+              code: createCode('EXPOSURE', 'LIST_MISSING_SORTING'),
+              message: 'Listing all elements without sorting could be overwhelming for large tables.',
+              suggestion: 'Select a few important fields to allow sorting.',
+              severity: 'warning',
+              context,
+            })
+          }
+        }
+        if (hasSearch) {
+          // Search and technically be used for filtering.
+          const all: string[] = []
+          if (Array.isArray(contract.searchableFields)) {
+            all.push(...contract.searchableFields)
+          }
+          if (Array.isArray(contract.filterableFields)) {
+            all.push(...contract.filterableFields)
+          }
+          if (!all.length) {
+            issues.push({
+              code: createCode('EXPOSURE', 'SEARCH_MISSING_FIELDS'),
+              message: 'Search action needs to know which fields to look in.',
+              suggestion: 'Select a few important fields to allow searching or full-text search.',
+              severity: 'warning',
+              context,
+            })
+          }
+        }
+      }
+    }
   }
 
   return issues

package/src/models/ProjectRequest.ts

@@ -315,10 +315,6 @@ export class ProjectRequest extends Request implements ProjectDefinitionProperty
     if (!environment) {
       return undefined
     }
-    let parent = this.getParent()
-    if (parent === project) {
-      parent = undefined
-    }
     return project.findEnvironment(environment)
   }
 

package/src/models/store/Organization.ts

@@ -4,6 +4,20 @@ import { OrganizationKind } from '../kinds.js'
 
 export type UserOrganizationGrantType = 'owner' | 'manager' | 'editor' | 'viewer'
 
+/**
+ * The response of the organization slug validation.
+ */
+export interface OrganizationSlugValidateResponse {
+  /**
+   * Whether the slug is valid.
+   */
+  valid: boolean
+  /**
+   * The reason why the slug is invalid.
+   */
+  reason?: string
+}
+
 /**
  * In the system the user identity represents registration information associated with a specific identity provider.
  * This association allows the user to use different identity providers that map to the same user, as long as the

package/src/models/transformers/ArcDexieTransformer.ts

@@ -235,10 +235,6 @@ export class ArcDexieTransformer extends BaseTransformer {
 
   parseSavedItem(item: DexieRequest): RequestProcessItem {
     const requestName = item.name || item._name
-    let keyName = requestName
-    if (keyName && keyName[0] === '_') {
-      keyName = keyName.substr(1)
-    }
     const obj: ExportArcSavedRequest = {
       name: requestName || '',
       method: item.method,

package/src/models/transformers/ImportUtils.ts

@@ -118,7 +118,7 @@ export function prepareImportObject(data: Record<string, unknown> | string): unk
       data = JSON.parse(data)
     } catch (e) {
       const err = e as Error
-      throw new Error(`Unable to read the file. Not a JSON: ${err.message}`)
+      throw new Error(`Unable to read the file. Not a JSON: ${err.message}`, { cause: e })
     }
   }
   return data

package/src/models/transformers/PostmanBackupTransformer.ts

@@ -213,11 +213,6 @@ export class PostmanBackupTransformer extends PostmanTransformer {
     let headers = request.headers || ''
     headers = this.ensureVariablesSyntax(headers) as string
 
-    let createdTime = Number(request.time)
-    if (Number.isNaN(createdTime)) {
-      createdTime = Date.now()
-    }
-
     const created = current.addRequest(url)
     created.info.name = name
     if (request.description) {

package/src/runtime/constants.ts

@@ -0,0 +1,9 @@
+// This is shared in the web and node.
+
+export const OFFSET_PAGINATION_DEFAULT_LIMIT = 20
+export const OFFSET_PAGINATION_MAX_LIMIT = 100
+export const OFFSET_PAGINATION_MIN_LIMIT = 1
+
+export const CURSOR_PAGINATION_DEFAULT_LIMIT = 20
+export const CURSOR_PAGINATION_MAX_LIMIT = 100
+export const CURSOR_PAGINATION_MIN_LIMIT = 1

package/src/runtime/http-engine/ntlm/Des.ts

@@ -128,6 +128,7 @@ export class Des {
       cbcleft =
         (iv!.charCodeAt(m++) << 24) | (iv!.charCodeAt(m++) << 16) | (iv!.charCodeAt(m++) << 8) | iv!.charCodeAt(m++)
       cbcright =
+        // eslint-disable-next-line no-useless-assignment
         (iv!.charCodeAt(m++) << 24) | (iv!.charCodeAt(m++) << 16) | (iv!.charCodeAt(m++) << 8) | iv!.charCodeAt(m++)
       m = 0
     }

package/src/runtime/variables/EvalFunctions.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-extraneous-class */
 import { find, store } from './Cache.js'
 
 // eslint-disable-next-line no-restricted-globals

package/src/sdk/OrganizationsSdk.ts

@@ -8,7 +8,11 @@ import {
 } from './SdkBase.js'
 import { RouteBuilder } from './RouteBuilder.js'
 import type { ContextListOptions, ContextListResult } from '../events/BaseEvents.js'
-import type { OrganizationSchema, UserOrganizationGrantType } from '../models/store/Organization.js'
+import type {
+  OrganizationSchema,
+  UserOrganizationGrantType,
+  OrganizationSlugValidateResponse,
+} from '../models/store/Organization.js'
 import type { InvitationSchema } from '../models/store/Invitation.js'
 import type { PatchInfo } from '../patch/types.js'
 import type { UserSchema } from '../models/store/User.js'
@@ -520,4 +524,80 @@ export class OrganizationsSdk extends SdkBase {
       }
     },
   }
+
+  slugs = {
+    /**
+     * Generates a slug for the organization.
+     * @param name The name of the organization.
+     * @param request Optional request options.
+     * @returns A promise that resolves to the generated slug.
+     */
+    generate: async (name: string, request: SdkOptions = {}): Promise<string> => {
+      const { token } = request
+      const url = this.sdk.getUrl(RouteBuilder.orgSlugGenerate()).toString()
+      const body = {
+        name,
+      }
+      const result = await this.sdk.http.post(url, {
+        body: JSON.stringify(body),
+        token,
+      })
+      this.inspectCommonStatusCodes(result)
+      const E_PREFIX = 'Unable to generate the slug. '
+      if (result.status !== 200) {
+        this.logInvalidResponse(result)
+        throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+      }
+      if (!result.body) {
+        throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
+      }
+      let data: { slug: string }
+      try {
+        data = JSON.parse(result.body)
+      } catch {
+        throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
+      }
+      if (!data.slug) {
+        throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
+      }
+      return data.slug
+    },
+
+    /**
+     * Validates a slug for the organization.
+     * @param slug The slug to validate.
+     * @param request Optional request options.
+     * @returns A promise that resolves to the validation result.
+     */
+    validate: async (slug: string, request: SdkOptions = {}): Promise<OrganizationSlugValidateResponse> => {
+      const { token } = request
+      const url = this.sdk.getUrl(RouteBuilder.orgSlugValidate()).toString()
+      const body = {
+        slug,
+      }
+      const result = await this.sdk.http.post(url, {
+        body: JSON.stringify(body),
+        token,
+      })
+      this.inspectCommonStatusCodes(result)
+      const E_PREFIX = 'Unable to validate the slug. '
+      if (result.status !== 200) {
+        this.logInvalidResponse(result)
+        throw this.createApiError(`${E_PREFIX}${E_RESPONSE_STATUS}${result.status}`, result.body)
+      }
+      if (!result.body) {
+        throw new Exception(`${E_PREFIX}${E_RESPONSE_NO_VALUE}`, { code: 'E_RESPONSE_NO_VALUE', status: result.status })
+      }
+      let data: OrganizationSlugValidateResponse
+      try {
+        data = JSON.parse(result.body)
+      } catch {
+        throw new Exception(`${E_PREFIX}${E_INVALID_JSON}`, { code: 'E_INVALID_JSON', status: result.status })
+      }
+      if (typeof data.valid !== 'boolean') {
+        throw new Exception(`${E_PREFIX}${E_RESPONSE_UNKNOWN}`, { code: 'E_RESPONSE_UNKNOWN', status: result.status })
+      }
+      return data
+    },
+  }
 }

package/src/sdk/RouteBuilder.ts

@@ -326,4 +326,12 @@ export class RouteBuilder {
   static aiMessage(oid: string, sid: string, mid: string): string {
     return `${RouteBuilder.aiMessages(oid, sid)}/${mid}`
   }
+
+  static orgSlugGenerate(): string {
+    return `/v1/orgs/slugs/generate`
+  }
+
+  static orgSlugValidate(): string {
+    return `/v1/orgs/slugs/validate`
+  }
 }

package/src/sdk/SdkMock.ts

@@ -591,6 +591,56 @@ export class SdkMock {
         )
       },
     },
+
+    slugs: {
+      /**
+       * Mocks the `slugs.validate()` method.
+       * @param options Optional response customization.
+       */
+      validate: async (init?: MockResult, options?: InterceptOptions): Promise<void> => {
+        const { mock } = this
+        const respond = this.createDefaultResponse(
+          200,
+          { 'content-type': 'application/json' },
+          () => JSON.stringify(this.gen.organization.organizationSlugValidateResponse()),
+          init
+        )
+        await mock.add(
+          {
+            match: {
+              uri: RouteBuilder.orgSlugValidate(),
+              methods: ['POST'],
+            },
+            respond,
+          },
+          options
+        )
+      },
+
+      /**
+       * Mocks the `slugs.generate()` method.
+       * @param options Optional response customization.
+       */
+      generate: async (init?: MockResult, options?: InterceptOptions): Promise<void> => {
+        const { mock } = this
+        const respond = this.createDefaultResponse(
+          200,
+          { 'content-type': 'application/json' },
+          () => JSON.stringify(this.gen.organization.organizationSlugGenerateResponse()),
+          init
+        )
+        await mock.add(
+          {
+            match: {
+              uri: RouteBuilder.orgSlugGenerate(),
+              methods: ['POST'],
+            },
+            respond,
+          },
+          options
+        )
+      },
+    },
   }
 
   /**

package/tests/test-utils.ts

@@ -111,11 +111,15 @@ export const TestUtils = {
       if (expectedMessage) {
         if (typeof expectedMessage === 'string') {
           if (!typedError.message.includes(expectedMessage)) {
-            throw new Error(`Expected error message to include "${expectedMessage}", got "${typedError.message}"`)
+            throw new Error(`Expected error message to include "${expectedMessage}", got "${typedError.message}"`, {
+              cause: error,
+            })
           }
         } else if (expectedMessage instanceof RegExp) {
           if (!expectedMessage.test(typedError.message)) {
-            throw new Error(`Expected error message to match ${expectedMessage}, got "${typedError.message}"`)
+            throw new Error(`Expected error message to match ${expectedMessage}, got "${typedError.message}"`, {
+              cause: error,
+            })
           }
         }
       }