@autofleet/sadot 1.1.3 → 1.1.4-beta

package/src/types/entries/index.ts

@@ -0,0 +1,27 @@
+import type { ValidationError } from 'joi';
+
+export interface CustomFieldEntriesDTO {
+  modelId: string;
+  entityId: string;
+  modelType: string;
+  /**
+   * A collection of custom fields where each key is the name of a CustomFieldDefinition and
+   * each value is the value of that custom field for this specific `modelId`.
+   *
+   * Example:
+   * {
+   *   "vehicleColor": "Red",
+   *   "vehicleType": "premium",
+   *   "isActive": true
+   * }
+   */
+  customFields: Record<string, any>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface EntriesValidationError {
+  value: any,
+  fieldDefinitionName: string,
+  joiValidationError: ValidationError
+}

package/src/types/index.ts

@@ -0,0 +1,52 @@
+import type { IncludeOptions, Transaction } from 'sequelize';
+import type { ModelCtor, Sequelize } from 'sequelize-typescript';
+import type { getUser as GetUserType } from '@autofleet/zehut';
+import type CustomFieldDefinition from '../models/CustomFieldDefinition';
+import type CustomValidator from '../models/CustomValidator';
+
+export type ModelFetcher = (name: string) => any;
+
+export interface TransactionOptions extends Record<string, any> {
+  transaction?: Transaction & {
+    definitionCache?: Map<string, CustomFieldDefinition[]>;
+    validationsCache?: Map<string, CustomValidator[]>;
+  };
+}
+
+export type ModelOptions = {
+  /**
+   * Include options for the model
+   */
+  include?: (entityIds: string[]) => IncludeOptions[];
+  /**
+    * Custom association for the model
+    * @param model - The model to associate with
+   */
+
+  customAssociation?: (model: ModelCtor) => void;
+  /**
+   * Whether to use the entity id  from the instance per scope attribute
+   */
+  useEntityIdFromInclude?: boolean
+  /**
+   * Which attributes to include in the model
+   */
+  attributes?: string[];
+}
+export type Models = {
+  name: string;
+  scopeAttributes: any[];
+  modelOptions?: ModelOptions;
+  creationWebhookHandler?: (instance: any) => any;
+  updateWebhookHandler?: (instance: any) => any;
+  deletionWebhookHandler?: (instance: any) => any;
+}
+
+export type CustomFieldOptions = {
+  models: Models[];
+  databaseConfig: any;
+  getUser: typeof GetUserType;
+  sequelize?: Sequelize;
+  useCustomFieldsEntries?: boolean;
+  useValidators?: boolean;
+};

package/src/types/value/index.ts

@@ -0,0 +1,14 @@
+export interface CustomFieldValueDTO {
+    id?: string;
+    modelId: string;
+    customFieldDefinitionId: string;
+    value: any;
+    createdAt?: Date;
+    updatedAt?: Date;
+    deletedAt?: Date;
+  }
+
+export type ValuesToUpdate = {[name: string]: any };
+export type CreateCustomFieldValue = Omit<CustomFieldValueDTO, 'id'>;
+export type UpdateCustomFieldValue = ValuesToUpdate;
+export type BulkUpdateCustomFieldValue = Partial<CustomFieldValueDTO>[];

package/src/utils/constants/index.ts

@@ -0,0 +1,25 @@
+import { customFields } from '@autofleet/common-types';
+
+const { CUSTOM_FIELDS_FILTER_SCOPE } = customFields;
+
+export const supportedEntities = ['businessModelId', 'fleetId', 'demandSourceId'];
+
+/**
+ * Supported custom field types
+ */
+export enum CustomFieldDefinitionType {
+  NUMBER = 'number',
+  BOOLEAN = 'boolean',
+  DATE = 'date',
+  DATETIME = 'datetime',
+  TEXT = 'text',
+  IMAGE = 'image',
+  SELECT = 'select',
+  STATUS = 'status',
+  FILE = 'file',
+}
+
+export {
+  /** @deprecated Use the value from `@autofleet/common-types` instead */
+  CUSTOM_FIELDS_FILTER_SCOPE,
+};

package/src/utils/db/index.ts

@@ -0,0 +1,21 @@
+import { Sequelize } from 'sequelize-typescript';
+import { QueryTypes } from 'sequelize';
+
+export default (databaseConfig: any): Sequelize => {
+  const ENV_DEV = 'test';
+  const env: string = process.env.NODE_ENV || ENV_DEV;
+  const config = databaseConfig[env];
+  let sequelize: Sequelize;
+  if (config.use_env_variable) {
+    sequelize = new Sequelize(process.env[config.use_env_variable], config);
+  } else {
+    sequelize = new Sequelize(config.database, config.username, config.password, config);
+  }
+  return sequelize;
+};
+
+export const createSequelizeMeta = (sequelize: Sequelize) => sequelize.query(`
+CREATE TABLE IF NOT EXISTS "SequelizeMeta" (
+  name character varying(255) PRIMARY KEY
+);
+`, { type: QueryTypes.SELECT });

package/src/utils/helpers/index.ts

@@ -0,0 +1,66 @@
+/* eslint-disable import/prefer-default-export */
+import { type WhereOptions, Op, type BindOrReplacements } from 'sequelize';
+import { type ModelStatic, Sequelize } from 'sequelize-typescript';
+import { randomInt } from 'node:crypto';
+import { CustomFieldDefinitionType } from '../constants';
+
+/**
+ * Builds a WHERE clause and replacements for free-text search by custom fields.
+ *
+ * This function constructs a WHERE clause and replacement bindings that allow searching
+ * for a given term within custom fields associated with a specific model type and entity ID.
+ * The WHERE clause and replacements are designed to be added to the main query.
+ *
+ * @param {string} searchTerm - The term to search for within custom fields.
+ * @param {ModelStatic} model - The Sequelize model representing the entity type to search for.
+ * @param {string} entityId - The entity ID to filter the custom fields by.
+ * @param {CustomFieldDefinitionType[]} excludedCustomFieldsTypes - An array of custom field types
+ * to exclude from the search
+ *
+ * @returns {CustomFieldsSearchPayload} - An object containing the WHERE clause and replacements
+ * for Sequelize.
+ */
+
+interface CustomFieldsSearchPayload {
+  where: WhereOptions;
+  replacements: BindOrReplacements;
+}
+
+export const generateRandomString = (length = 5): string => {
+  const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+  return Array.from({ length }, () => characters.charAt(randomInt(characters.length))).join('');
+};
+
+export const generateCustomFieldSearchQueryPayload = (
+  searchTerm: string,
+  model: ModelStatic,
+  entityId: string,
+  customFieldsTypesToExclude: CustomFieldDefinitionType[] = [
+    CustomFieldDefinitionType.DATETIME,
+    CustomFieldDefinitionType.DATE,
+  ],
+): CustomFieldsSearchPayload => {
+  const excludedTypesString = customFieldsTypesToExclude.map((type) => `'${type}'`).join(',');
+
+  const subQuery = 'EXISTS ('
+      + ' SELECT 1'
+      + ' FROM "custom_field_values" AS "cv"'
+      + ' INNER JOIN custom_field_definitions AS cd '
+        + ` ON cd.entity_id = '${entityId}'`
+        + ' AND cv.custom_field_definition_id = cd.id'
+        + ` AND cd.model_type = '${model.name}'`
+        + ` ${excludedTypesString ? `AND cd.field_type NOT IN (${excludedTypesString})` : ''}`
+      + ' WHERE'
+        + ' "cv"."deleted_at" IS NULL'
+        + ` AND "cv"."model_id" = "${model.name}"."id"`
+        + ' AND CAST("cv"."value" AS TEXT) ILIKE :searchTerm)';
+
+  return {
+    where: {
+      [Op.or]: [
+        Sequelize.where(Sequelize.literal(subQuery), true),
+      ],
+    },
+    replacements: { searchTerm: `%${searchTerm}%` },
+  };
+};

package/src/utils/init.ts

@@ -0,0 +1,120 @@
+import { DataTypes } from 'sequelize';
+import type { ModelCtor } from 'sequelize-typescript';
+import { customFields } from '@autofleet/common-types';
+import { CUSTOM_FIELDS_SORT_SCOPE } from '@autofleet/common-types/lib/custom-fields';
+import {
+  CustomFieldDefinition,
+  CustomFieldValue,
+} from '../models';
+import {
+  beforeFind,
+  enrichResults,
+  beforeBulkUpdate,
+  beforeUpdate,
+  beforeCreate,
+  beforeBulkCreate,
+} from '../hooks';
+import { customFieldsFilterScope } from '../scopes';
+import logger from './logger';
+import type { CustomFieldOptions, ModelFetcher, Models } from '../types';
+import { customFieldsSortScope } from '../scopes/filter';
+
+const { CUSTOM_FIELDS_FILTER_SCOPE } = customFields;
+
+export const addHooks = (
+  models: Models[],
+  getModel: ModelFetcher,
+  sadotOptions: { useCustomFieldsEntries: boolean } = { useCustomFieldsEntries: false },
+): void => {
+  models.forEach(async ({
+    name, scopeAttributes, modelOptions,
+  }) => {
+    try {
+      const model = getModel(name);
+      if (!model) {
+        logger.warn('sadot - tried to addHooks to a model that does not exist yet', {
+          name,
+          scopeAttributes,
+        });
+        return;
+      }
+      model.rawAttributes.customFields = {
+        type: DataTypes.VIRTUAL,
+      };
+      model.refreshAttributes();
+      // TODO: Uncomment after tests are passed
+      // model.addHook('afterFind', workaround);
+      model.addHook('beforeFind', 'sadot-beforeFind', beforeFind(scopeAttributes));
+      model.addHook('beforeBulkCreate', 'sadot-beforeBulkCreate', beforeBulkCreate);
+      model.addHook('beforeBulkUpdate', 'sadot-beforeBulkUpdate', beforeBulkUpdate);
+      model.addHook('beforeCreate', 'sadot-beforeCreate', beforeCreate(scopeAttributes, modelOptions, sadotOptions));
+      model.addHook('beforeUpdate', 'sadot-beforeUpdate', beforeUpdate(scopeAttributes, modelOptions, sadotOptions));
+      model.addHook('afterFind', 'sadot-afterFind', enrichResults(name, scopeAttributes, 'afterFind', modelOptions, sadotOptions));
+      model.addHook('afterUpdate', 'sadot-afterUpdate', enrichResults(name, scopeAttributes, null, modelOptions, sadotOptions));
+      model.addHook('afterCreate', 'sadot-afterCreate', enrichResults(name, scopeAttributes, null, modelOptions, sadotOptions));
+    } catch (e) {
+      logger.error(`Could not add custom fields hook to model ${name}. `, e);
+    }
+  });
+};
+
+export const removeHooks = (models: Models[], getModel: ModelFetcher): void => {
+  models.forEach(async ({ name }) => {
+    try {
+      const model = getModel(name);
+      if (!model) return;
+      if (model.rawAttributes.customFields) {
+        delete model.rawAttributes.customFields;
+        model.refreshAttributes();
+      }
+      // model.removeHook('afterFind', 'sadot-workaround');
+      model.removeHook('beforeFind', 'sadot-beforeFind');
+      model.removeHook('beforeBulkCreate', 'sadot-beforeBulkCreate');
+      model.removeHook('beforeBulkUpdate', 'sadot-beforeBulkUpdate');
+      model.removeHook('beforeCreate', 'sadot-beforeCreate');
+      model.removeHook('beforeUpdate', 'sadot-beforeUpdate');
+      model.removeHook('afterFind', 'sadot-afterFind');
+      model.removeHook('afterUpdate', 'sadot-afterUpdate');
+    } catch (e) {
+      logger.error(`Could not add custom fields hook to model ${name}. `, e);
+    }
+  });
+};
+
+/**
+ *  Necessary associations for the {@link customFieldsFilterScope} scope
+ */
+const addAssociations = (model: ModelCtor, modelName: string, options: Pick<CustomFieldOptions, 'useCustomFieldsEntries'>): void => {
+  if (options?.useCustomFieldsEntries) return;
+  model.hasMany(CustomFieldValue, { foreignKey: 'modelId', as: 'customFieldValue' });
+  // TBC: maybe can be removed
+  CustomFieldValue.belongsTo(model, { foreignKey: 'modelId', as: modelName });
+};
+
+export const addScopes = (models: Models[], getModel: ModelFetcher, options: Pick<CustomFieldOptions, 'useCustomFieldsEntries'> = { useCustomFieldsEntries: false }): void => {
+  models.forEach(async ({ name, scopeAttributes }) => {
+    try {
+      const model = getModel(name);
+      if (!model) {
+        logger.warn('sadot - tried to addScopes to a model that does not exist yet', {
+          name,
+          scopeAttributes,
+        });
+        return;
+      }
+      // Necessary associations for the filtering scope
+      addAssociations(model, name, options);
+      // Add filter scope
+      model.addScope(CUSTOM_FIELDS_FILTER_SCOPE, customFieldsFilterScope(name, options));
+      model.addScope(CUSTOM_FIELDS_SORT_SCOPE, customFieldsSortScope(name, options));
+    } catch (e) {
+      logger.error(`Could not add custom fields scopes to model ${name}. `, e);
+    }
+  });
+};
+
+export const applyCustomAssociation = (models: Models[]): void => {
+  models.forEach(({ modelOptions }) => {
+    modelOptions?.customAssociation?.(CustomFieldDefinition);
+  });
+};

package/src/utils/logger/index.ts

@@ -0,0 +1,14 @@
+import Logger from '@autofleet/logger';
+
+const logger = Logger();
+
+export async function tryAddingTraceIdMiddleware() {
+  try {
+    const { outbreak } = await import('@autofleet/zehut');
+    logger.addContextMiddleware(() => ({ traceId: outbreak.getCurrentContextTraceId() }));
+  } catch (err) {
+    logger.error('Failed to add traceId middleware', { err });
+  }
+}
+
+export default logger;

package/src/utils/scopeAttributes.ts

@@ -0,0 +1,12 @@
+const mapAttributeToInstance = (scopeAttributes: string[], instance: any) =>
+  scopeAttributes.map((attr) => instance[attr]);
+
+const applyScopeToInstance = (instance: any, scopeAttributes: string[]) => {
+  const uniqueAttributes = Array.from(new Set(scopeAttributes));
+  if (Array.isArray(instance)) {
+    return instance.flatMap((ins) => mapAttributeToInstance(uniqueAttributes, ins));
+  }
+  return mapAttributeToInstance(uniqueAttributes, instance);
+};
+
+export default applyScopeToInstance;

package/src/utils/validations/index.ts

@@ -0,0 +1,46 @@
+import { InvalidEntriesError } from '../../errors';
+import type { CustomFieldDefinition } from '../../models';
+import type { CustomFieldEntriesDTO } from '../../types/entries';
+import type { CustomFieldDefinitionType } from '../constants';
+import { validators } from './validators';
+
+export const validateFieldType = (type: CustomFieldDefinitionType): boolean => Object.keys(validators).includes(type);
+
+export const validateValue = (
+  value: unknown,
+  valueType: CustomFieldDefinitionType,
+  validation?: unknown,
+) => {
+  const validator = validators[valueType];
+  return validator(value, validation);
+  /** TODO: Add validation for required fields
+   * @example
+   * if (validations.required && !value) {
+   *  return false;
+   * }
+   */
+};
+
+export const validateInstanceCustomFieldEntries = (instance: CustomFieldEntriesDTO, definitionsByName: { [defName: string]: CustomFieldDefinition; }) => {
+  const validationErrors = Object.entries(instance.customFields)
+    .map(([customFieldName, value]) => {
+      // Allow NULL values, just like we do in custom_field_values.
+      if (value === null) return null;
+
+      const { validation, fieldType } = definitionsByName[customFieldName];
+      const result = validateValue(value, fieldType, validation);
+      if (result?.error) {
+        return {
+          joiValidationError: result.error,
+          fieldDefinitionName: customFieldName,
+          value,
+        };
+      }
+      return null;
+    })
+    .filter((result) => !!result);
+
+  if (validationErrors?.length) {
+    throw new InvalidEntriesError(instance.modelId, validationErrors);
+  }
+};

package/src/utils/validations/schema/README.md

@@ -0,0 +1,93 @@
+# Schema Validation
+
+This directory contains schema validation utilities for the Sadot library, including:
+
+1. **Custom Fields Schemas** - Schema definitions for custom field validation
+2. **Validator Schemas** - Meta-validation for custom validator JSON schemas
+
+## Custom Fields Schema
+
+`custom-fields.ts` defines JSON Schema validation for custom field definitions, ensuring fields are created with valid configurations.
+
+## Validator Schema Validation
+
+`validator-schema.ts` provides meta-validation for custom validator schemas. It ensures that:
+
+1. The validator schema follows the expected structure
+2. The schema is a valid JSON Schema that can be compiled by AJV
+3. The validation rules defined in the schema are syntactically correct
+
+### Usage
+
+The `validateValidatorSchema` function is used by the custom validator API to validate schemas at creation and update time:
+
+```typescript
+import { validateValidatorSchema } from '../utils/validations/schema/validator-schema';
+
+// Validates a schema, throws BadRequest if invalid
+validateValidatorSchema(schema);
+```
+
+### Schema Structure
+
+Validator schemas must follow this general structure:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "before": {
+      "type": "object",
+      "properties": {
+        // Model properties to validate before update
+      }
+    },
+    "after": {
+      "type": "object", 
+      "properties": {
+        // Model properties to validate after update/create
+      }
+    }
+  }
+}
+```
+
+For create operations, only the `after` section is used. For update operations, both `before` and `after` can be used.
+
+### Conditional Validation
+
+The schema can include conditional validation using JSON Schema's `if/then/else` constructs:
+
+```json
+{
+  "type": "object",
+  "if": {
+    "properties": {
+      "before": {
+        "properties": {
+          "status": { "const": "PENDING" }
+        }
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "after": {
+        "properties": {
+          "status": { "enum": ["APPROVED", "REJECTED"] }
+        }
+      }
+    }
+  }
+}
+```
+
+This example validates that if a model's status was "PENDING", it can only be updated to "APPROVED" or "REJECTED".
+
+### Error Handling
+
+Schema validation errors are thrown as BadRequest errors with descriptive messages indicating:
+
+1. The specific validation error in the schema
+2. The path within the schema where the error occurred
+3. A readable message for API consumers

package/src/utils/validations/schema/custom-fields.ts

@@ -0,0 +1,8 @@
+import Joi from 'joi';
+
+const CustomFieldsSchema = Joi.object().pattern(
+  Joi.string(),
+  Joi.any(),
+);
+
+export { CustomFieldsSchema };

package/src/utils/validations/schema/validator-schema.ts

@@ -0,0 +1,106 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { BadRequest } from '@autofleet/errors';
+import logger from '../../logger';
+
+// Instantiate Ajv for meta-validation
+const metaValidator = new Ajv({
+  allErrors: true,
+  strict: false,
+  strictTypes: false,
+  $data: true, // Enable $data references
+});
+addFormats(metaValidator);
+
+/**
+ * Schema for validating JSON Schema objects in custom validators
+ * This is a meta-schema to ensure that custom validator schemas are valid Ajv schemas
+ */
+const validatorMetaSchema = {
+  type: 'object',
+  properties: {
+    type: { type: 'string', enum: ['object'] },
+    properties: {
+      type: 'object',
+      properties: {
+        before: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', enum: ['object'] },
+            properties: { type: 'object' },
+          },
+        },
+        after: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', enum: ['object'] },
+            properties: { type: 'object' },
+          },
+        },
+      },
+    },
+    required: {
+      type: 'array',
+      items: { type: 'string' },
+    },
+    if: { type: 'object' },
+    then: { type: 'object' },
+    else: { type: 'object' },
+  },
+  required: ['type', 'properties'],
+};
+
+/**
+ * Validates that a given schema is a valid Ajv schema
+ * This function is used to validate schemas passed to custom validators
+ *
+ * @param schema The schema to validate
+ * @returns true if valid, throws an error if invalid
+ */
+export const validateValidatorSchema = (schema: Record<string, unknown>): boolean => {
+  try {
+    // First validate the schema structure
+    const validateMetaSchema = metaValidator.compile(validatorMetaSchema);
+    const isValidStructure = validateMetaSchema(schema);
+
+    if (!isValidStructure) {
+      const errorDetails = validateMetaSchema.errors?.map((err) =>
+        `${(err as unknown as { instancePath: string }).instancePath || ''} ${(err as unknown as { message: string }).message || 'Invalid schema structure'}`).join(', ');
+
+      logger.error('Invalid validator schema structure', {
+        errors: validateMetaSchema.errors,
+        schema,
+      });
+
+      throw new BadRequest(
+        [new Error(`Invalid validator schema structure: ${errorDetails}`)],
+        ['Invalid validator schema structure'],
+      );
+    }
+
+    // Then try to compile the schema with Ajv to verify it's a valid JSON Schema
+    try {
+      metaValidator.compile(schema);
+      return true;
+    } catch (compileError) {
+      logger.error('Failed to compile validator schema', { error: compileError, schema });
+
+      throw new BadRequest(
+        [new Error(`Failed to compile validator schema: ${(compileError as Error).message}`)],
+        ['Invalid validator schema'],
+      );
+    }
+  } catch (error) {
+    if (error instanceof BadRequest) {
+      throw error;
+    }
+
+    logger.error('Error validating validator schema', { error, schema });
+    throw new BadRequest(
+      [new Error(`Error validating validator schema: ${(error as Error).message}`)],
+      ['Invalid validator schema'],
+    );
+  }
+};
+
+export default validateValidatorSchema;

package/src/utils/validations/type.ts

@@ -0,0 +1,20 @@
+import type { ValidationResult } from 'joi';
+import type { CustomFieldDefinitionType } from '../constants';
+
+/**
+ * Validator is a function that validates a custom-field `value`,
+ * against a custom-field definition `validation object`.
+ * @returns `true` if the value is valid, `false` otherwise.
+ */
+export type Validator<Value, DefinitionValidationObject> = (
+   value: Value,
+   validation?: DefinitionValidationObject
+  ) => ValidationResult;
+
+/**
+ * Validators is a map of custom-field types to their respective validators.
+ * The key is the custom-field type, and the value is the validator function.
+ */
+export type Validators = {
+  [K in CustomFieldDefinitionType]: Validator<unknown, unknown>;
+};

package/src/utils/validations/validators/index.ts

@@ -0,0 +1,38 @@
+import Joi from 'joi';
+import { CustomFieldDefinitionType } from '../../constants';
+import type { Validators } from '../type';
+import { validateSelect } from './select.validator';
+import { validateStatus } from './status.validator';
+
+type CustomValidationTypes = Extract<CustomFieldDefinitionType, 'select' | 'status'>;
+/**
+ * Custom field types that must have custom validation.
+ * TODO: remove this after moving to schema-based validation
+ */
+export const CustomValidationTypes = {
+  [CustomFieldDefinitionType.SELECT]: CustomFieldDefinitionType.SELECT,
+  [CustomFieldDefinitionType.STATUS]: CustomFieldDefinitionType.STATUS,
+} as const;
+
+/**
+ * Validators for custom fields
+ */
+export const validators: Validators = {
+  [CustomFieldDefinitionType.SELECT]: validateSelect,
+  [CustomFieldDefinitionType.STATUS]: validateStatus,
+  [CustomFieldDefinitionType.TEXT]: (value) => Joi.string().min(0).validate(value),
+  [CustomFieldDefinitionType.NUMBER]: (value) => Joi.number().strict(true).validate(value),
+  [CustomFieldDefinitionType.BOOLEAN]: (value) => Joi.boolean().strict().validate(value),
+  [CustomFieldDefinitionType.DATE]: (value) => Joi.date().validate(value),
+  [CustomFieldDefinitionType.DATETIME]: (value) => Joi.date().validate(value),
+  [CustomFieldDefinitionType.IMAGE]: (value) => Joi.array().min(1).unique()
+    .items(Joi.string().uri())
+    .validate(value),
+  [CustomFieldDefinitionType.FILE]: (value) => Joi.array().min(1).unique().items(Joi.object({
+    name: Joi.string().required(),
+    type: Joi.string(),
+    size: Joi.string(),
+    addedBy: Joi.string().uuid(),
+  }))
+    .validate(value),
+};