@intellegens/cornerstone-client 0.0.0-experimental-upgrade-20260302-1

package/src/data/api/dto/read/ReadSelectedSearchDefinitionBuilder.ts

@@ -0,0 +1,348 @@
+import { ReadSelectedCollectionOperator, ReadSelectedComparisonOperator, ReadSelectedLogicalOperator, ReadSelectedPropertyType } from '@data';
+import { ReadSelectedSearchDefinitionDto } from './ReadSelectedSearchDefinitionDto';
+import { ReadSelectedSearchPropertyDefinitionDto } from './ReadSelectedSearchPropertyDefinitionDto';
+import { ReadSelectedNestedCriteriaDto } from './ReadSelectedNestedCriteriaDto';
+import { ReadSelectedNestedCollectionCriteriaDto } from './ReadSelectedNestedCollectionCriteriaDto';
+
+/**
+ * Builder class for constructing ReadSelectedSearchDefinitionDto with a fluent API.
+ *
+ * @example
+ * // Simple AND search with property criteria
+ * const search = SearchBuilder.and<User>()
+ *   .whereString('name', ReadSelectedComparisonOperator.IContains, 'John')
+ *   .whereNumber('age', ReadSelectedComparisonOperator.GreaterThan, 18)
+ *   .build();
+ *
+ * @example
+ * // OR search with nested criteria (specify nested type for intellisense)
+ * const search = SearchBuilder.or<User>()
+ *   .whereString('status', ReadSelectedComparisonOperator.Equal, 'active')
+ *   .nested<Address>('address', nested =>
+ *     nested.whereString('city', ReadSelectedComparisonOperator.Equal, 'NYC')
+ *   )
+ *   .build();
+ *
+ * @example
+ * // Complex nested search with collection criteria
+ * const search = SearchBuilder.and<Order>()
+ *   .whereString('status', ReadSelectedComparisonOperator.Equal, 'pending')
+ *   .any<OrderItem>('items', itemSearch =>
+ *     itemSearch.whereNumber('quantity', ReadSelectedComparisonOperator.GreaterThan, 5)
+ *   )
+ *   .group(sub => sub.or()
+ *     .whereString('priority', ReadSelectedComparisonOperator.Equal, 'high')
+ *     .whereString('priority', ReadSelectedComparisonOperator.Equal, 'urgent')
+ *   )
+ *   .build();
+ */
+export class SearchBuilder<T> {
+  private _logicalOperator: ReadSelectedLogicalOperator;
+  private _searches: ReadSelectedSearchDefinitionDto<T>[] = [];
+  private _propertyCriteria: ReadSelectedSearchPropertyDefinitionDto<T, keyof T>[] = [];
+  private _nestedCriteria: ReadSelectedNestedCriteriaDto<T, keyof T>[] = [];
+  private _nestedCollectionCriteria: ReadSelectedNestedCollectionCriteriaDto<T, keyof T>[] = [];
+
+  private constructor(logicalOperator: ReadSelectedLogicalOperator) {
+    this._logicalOperator = logicalOperator;
+  }
+
+  /**
+   * Creates a new builder with AND logical operator.
+   * All criteria added to this builder will be combined with AND.
+   */
+  static and<T>(): SearchBuilder<T> {
+    return new SearchBuilder<T>(ReadSelectedLogicalOperator.And);
+  }
+
+  /**
+   * Creates a new builder with OR logical operator.
+   * All criteria added to this builder will be combined with OR.
+   */
+  static or<T>(): SearchBuilder<T> {
+    return new SearchBuilder<T>(ReadSelectedLogicalOperator.Or);
+  }
+
+  /**
+   * Sets the logical operator to AND.
+   */
+  and(): this {
+    this._logicalOperator = ReadSelectedLogicalOperator.And;
+    return this;
+  }
+
+  /**
+   * Sets the logical operator to OR.
+   */
+  or(): this {
+    this._logicalOperator = ReadSelectedLogicalOperator.Or;
+    return this;
+  }
+
+  /**
+   * Adds a property comparison criterion.
+   *
+   * @param propertyName - The property to compare
+   * @param comparisonOperator - The comparison operator to use
+   * @param value - The value to compare against
+   * @param valueType - The type of the value
+   */
+  where<K extends keyof T>(propertyName: K, comparisonOperator: ReadSelectedComparisonOperator, value: unknown, valueType: ReadSelectedPropertyType): this {
+    this._propertyCriteria.push({
+      propertyName: this.toPascalCase(propertyName),
+      comparisonOperator,
+      value,
+      valueType,
+    } as ReadSelectedSearchPropertyDefinitionDto<T, keyof T>);
+    return this;
+  }
+
+  /**
+   * Adds a string property comparison with common string operations.
+   */
+  whereString<K extends keyof T>(
+    propertyName: K,
+    comparisonOperator:
+      | ReadSelectedComparisonOperator.Equal
+      | ReadSelectedComparisonOperator.NotEqual
+      | ReadSelectedComparisonOperator.Contains
+      | ReadSelectedComparisonOperator.StartsWith
+      | ReadSelectedComparisonOperator.EndsWith
+      | ReadSelectedComparisonOperator.IContains
+      | ReadSelectedComparisonOperator.IStartsWith
+      | ReadSelectedComparisonOperator.IEndsWith
+      | ReadSelectedComparisonOperator.IEqual
+      | ReadSelectedComparisonOperator.INotEqual,
+    value: string,
+  ): this {
+    return this.where(propertyName, comparisonOperator, value, ReadSelectedPropertyType.String);
+  }
+
+  /**
+   * Adds a number property comparison.
+   */
+  whereNumber<K extends keyof T>(
+    propertyName: K,
+    comparisonOperator:
+      | ReadSelectedComparisonOperator.Equal
+      | ReadSelectedComparisonOperator.NotEqual
+      | ReadSelectedComparisonOperator.LessThan
+      | ReadSelectedComparisonOperator.LessOrEqual
+      | ReadSelectedComparisonOperator.GreaterThan
+      | ReadSelectedComparisonOperator.GreaterOrEqual,
+    value: number,
+    valueType:
+      | ReadSelectedPropertyType.Int
+      | ReadSelectedPropertyType.Short
+      | ReadSelectedPropertyType.Long
+      | ReadSelectedPropertyType.Decimal
+      | ReadSelectedPropertyType.Double
+      | ReadSelectedPropertyType.Float = ReadSelectedPropertyType.Int,
+  ): this {
+    return this.where(propertyName, comparisonOperator, value, valueType);
+  }
+
+  /**
+   * Adds a boolean property comparison.
+   */
+  whereBool<K extends keyof T>(
+    propertyName: K,
+    comparisonOperator: ReadSelectedComparisonOperator.Equal | ReadSelectedComparisonOperator.NotEqual,
+    value: boolean,
+  ): this {
+    return this.where(propertyName, comparisonOperator, value, ReadSelectedPropertyType.Bool);
+  }
+
+  /**
+   * Adds a date/time property comparison.
+   */
+  whereDate<K extends keyof T>(
+    propertyName: K,
+    comparisonOperator:
+      | ReadSelectedComparisonOperator.Equal
+      | ReadSelectedComparisonOperator.NotEqual
+      | ReadSelectedComparisonOperator.LessThan
+      | ReadSelectedComparisonOperator.LessOrEqual
+      | ReadSelectedComparisonOperator.GreaterThan
+      | ReadSelectedComparisonOperator.GreaterOrEqual,
+    value: string | Date,
+    valueType:
+      | ReadSelectedPropertyType.DateTime
+      | ReadSelectedPropertyType.DateTimeOffset
+      | ReadSelectedPropertyType.DateOnly
+      | ReadSelectedPropertyType.TimeOnly
+      | ReadSelectedPropertyType.TimeSpan = ReadSelectedPropertyType.DateTime,
+  ): this {
+    const stringValue = value instanceof Date ? value.toISOString() : value;
+    return this.where(propertyName, comparisonOperator, stringValue, valueType);
+  }
+
+  /**
+   * Adds an isNull check for a property.
+   */
+  whereNull<K extends keyof T>(propertyName: K): this {
+    this._propertyCriteria.push({
+      propertyName: this.toPascalCase(propertyName),
+      comparisonOperator: ReadSelectedComparisonOperator.IsNull,
+      value: null,
+      valueType: ReadSelectedPropertyType.String,
+    } as unknown as ReadSelectedSearchPropertyDefinitionDto<T, keyof T>);
+    return this;
+  }
+
+  /**
+   * Adds an isNotNull check for a property.
+   */
+  whereNotNull<K extends keyof T>(propertyName: K): this {
+    this._propertyCriteria.push({
+      propertyName: this.toPascalCase(propertyName),
+      comparisonOperator: ReadSelectedComparisonOperator.IsNotNull,
+      value: null,
+      valueType: ReadSelectedPropertyType.String,
+    } as unknown as ReadSelectedSearchPropertyDefinitionDto<T, keyof T>);
+    return this;
+  }
+
+  /**
+   * Adds criteria for a nested object property (navigation property).
+   *
+   * @param propertyName - The navigation property name
+   * @param builderFn - A function that receives a new builder for the nested type
+   *
+   * @example
+   * // With explicit type for proper intellisense
+   * SearchBuilder.and<VehicleDto>()
+   *   .nested<PersonDto>('driver', nested =>
+   *     nested.whereString('name', ReadSelectedComparisonOperator.Contains, 'Alice')
+   *   )
+   *   .build();
+   */
+  nested<TNested, K extends keyof T = keyof T>(propertyName: K, builderFn: (builder: SearchBuilder<TNested>) => SearchBuilder<TNested>): this {
+    const nestedBuilder = SearchBuilder.and<TNested>();
+    const configuredBuilder = builderFn(nestedBuilder);
+    this._nestedCriteria.push({
+      propertyName: this.toPascalCase(propertyName),
+      criteria: configuredBuilder.build(),
+    } as ReadSelectedNestedCriteriaDto<T, keyof T>);
+    return this;
+  }
+
+  /**
+   * Adds criteria for a collection property with Any quantifier.
+   * Matches if at least one element in the collection satisfies the criteria.
+   *
+   * @param propertyName - The collection property name
+   * @param builderFn - A function that receives a new builder for the collection element type
+   *
+   * @example
+   * // With explicit type for proper intellisense
+   * SearchBuilder.and<VehicleDto>()
+   *   .any<PersonDto>('passengers', passengers =>
+   *     passengers.whereString('name', ReadSelectedComparisonOperator.Contains, 'Bob')
+   *   )
+   *   .build();
+   */
+  any<TElement, K extends keyof T = keyof T>(propertyName: K, builderFn: (builder: SearchBuilder<TElement>) => SearchBuilder<TElement>): this {
+    const nestedBuilder = SearchBuilder.and<TElement>();
+    const configuredBuilder = builderFn(nestedBuilder);
+    this._nestedCollectionCriteria.push({
+      propertyName: this.toPascalCase(propertyName),
+      collectionOperator: ReadSelectedCollectionOperator.Any,
+      criteria: configuredBuilder.build(),
+    } as ReadSelectedNestedCollectionCriteriaDto<T, keyof T>);
+    return this;
+  }
+
+  /**
+   * Adds criteria for a collection property with All quantifier.
+   * Matches if all elements in the collection satisfy the criteria.
+   *
+   * @param propertyName - The collection property name
+   * @param builderFn - A function that receives a new builder for the collection element type
+   *
+   * @example
+   * // With explicit type for proper intellisense
+   * SearchBuilder.and<VehicleDto>()
+   *   .all<PersonDto>('passengers', passengers =>
+   *     passengers.whereNumber('age', ReadSelectedComparisonOperator.GreaterThan, 18)
+   *   )
+   *   .build();
+   */
+  all<TElement, K extends keyof T = keyof T>(propertyName: K, builderFn: (builder: SearchBuilder<TElement>) => SearchBuilder<TElement>): this {
+    const nestedBuilder = SearchBuilder.and<TElement>();
+    const configuredBuilder = builderFn(nestedBuilder);
+    this._nestedCollectionCriteria.push({
+      propertyName: this.toPascalCase(propertyName),
+      collectionOperator: ReadSelectedCollectionOperator.All,
+      criteria: configuredBuilder.build(),
+    } as ReadSelectedNestedCollectionCriteriaDto<T, keyof T>);
+    return this;
+  }
+
+  /**
+   * Adds a nested search group. Use this for complex logical groupings.
+   *
+   * @param builderFn - A function that receives a new builder for creating the nested search
+   *
+   * @example
+   * // (name contains 'John') AND ((age > 18) OR (status = 'verified'))
+   * SearchBuilder.and<User>()
+   *   .whereString('name', ReadSelectedComparisonOperator.IContains, 'John')
+   *   .group(sub => sub.or()
+   *     .whereNumber('age', ReadSelectedComparisonOperator.GreaterThan, 18)
+   *     .whereString('status', ReadSelectedComparisonOperator.Equal, 'verified')
+   *   )
+   *   .build();
+   */
+  group(builderFn: (builder: SearchBuilder<T>) => SearchBuilder<T>): this {
+    const nestedBuilder = SearchBuilder.and<T>();
+    const configuredBuilder = builderFn(nestedBuilder);
+    this._searches.push(configuredBuilder.build());
+    return this;
+  }
+
+  /**
+   * Adds an existing search definition as a nested search.
+   *
+   * @param search - An existing ReadSelectedSearchDefinitionDto
+   */
+  addSearch(search: ReadSelectedSearchDefinitionDto<T>): this {
+    this._searches.push(search);
+    return this;
+  }
+
+  /**
+   * Builds and returns the ReadSelectedSearchDefinitionDto.
+   */
+  build(): ReadSelectedSearchDefinitionDto<T> {
+    const result: ReadSelectedSearchDefinitionDto<T> = {
+      logicalOperator: this._logicalOperator,
+    };
+
+    if (this._searches.length > 0) {
+      result.searches = this._searches;
+    }
+
+    if (this._propertyCriteria.length > 0) {
+      result.propertyCriteria = this._propertyCriteria;
+    }
+
+    if (this._nestedCriteria.length > 0) {
+      result.nestedCriteria = this._nestedCriteria;
+    }
+
+    if (this._nestedCollectionCriteria.length > 0) {
+      result.nestedCollectionCriteria = this._nestedCollectionCriteria;
+    }
+
+    return result;
+  }
+
+  private toPascalCase(str: string | number | symbol): string {
+    if (typeof str !== 'string') {
+      return str.toString();
+    }
+
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}

package/src/data/api/dto/read/ReadSelectedSearchDefinitionDto.ts

@@ -0,0 +1,43 @@
+import {
+    ReadSelectedLogicalOperator,
+    ReadSelectedNestedCollectionCriteriaDto,
+    ReadSelectedNestedCriteriaDto,
+    ReadSelectedSearchPropertyDefinitionDto,
+} from '@data';
+
+/**
+ * Defines the search criteria for a controller using a recursive structure.
+ *
+ * This DTO supports complex search queries with:
+ * - Logical operators (AND/OR) to combine multiple criteria
+ * - Direct property value comparisons via `propertyCriteria`
+ * - Nested searches via `searches` for recursive query composition
+ * - Navigation into nested objects via `nestedCriteria`
+ * - Collection quantifier queries (Any/All) via `nestedCollectionCriteria`
+ */
+export type ReadSelectedSearchDefinitionDto<T> = {
+    /**
+     * The logical operator to combine all criteria at this level.
+     */
+    logicalOperator: ReadSelectedLogicalOperator;
+
+    /**
+     * Recursive nested search definitions combined with the logical operator.
+     */
+    searches?: ReadSelectedSearchDefinitionDto<T>[];
+
+    /**
+     * Direct property value comparison criteria.
+     */
+    propertyCriteria?: ReadSelectedSearchPropertyDefinitionDto<T, keyof T>[];
+
+    /**
+     * Criteria for searching within nested object properties.
+     */
+    nestedCriteria?: ReadSelectedNestedCriteriaDto<T, keyof T>[];
+
+    /**
+     * Criteria for searching within collection properties using Any/All quantifiers.
+     */
+    nestedCollectionCriteria?: ReadSelectedNestedCollectionCriteriaDto<T, keyof T>[];
+};

package/src/data/api/dto/read/ReadSelectedSearchPropertyDefinitionDto.ts

@@ -0,0 +1,186 @@
+import {ReadSelectedComparisonOperator, ReadSelectedPropertyType} from '@data';
+
+/**
+ * Defines a direct property value comparison criteria for searching.
+ *
+ * This DTO represents a leaf-level search criterion that compares a single property
+ * against a value using a comparison operator. For nested property searches, use
+ * `ReadSelectedNestedCriteriaDto` or `ReadSelectedNestedCollectionCriteriaDto`.
+ */
+export type ReadSelectedSearchPropertyDefinitionDto<T, TPropertyName extends keyof T> =
+    Partial_ReadSelectedSearchPropertyDefinition_IndependentProperties<T, TPropertyName>
+    &
+    Partial_ReadSelectedSearchPropertyDefinition_TypedValueProperty
+    &
+    Partial_ReadSelectedSearchPropertyDefinition_TypedComparisonOperators;
+
+/**
+ * Defines independent properties
+ */
+type Partial_ReadSelectedSearchPropertyDefinition_IndependentProperties<T, TPropertyName extends keyof T> = {
+    /**
+     * The name of the property to compare.
+     *
+     * This must be a direct property on the target type, not a nested property path.
+     * Use nested criteria DTOs for navigation.
+     */
+    propertyName: TPropertyName;
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator: ReadSelectedComparisonOperator;
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType;
+    /**
+     * The value to compare against.
+     */
+    value: unknown;
+};
+
+/**
+ * Defines the dependence between the .valueType and the type of the .value properties
+ */
+type Partial_ReadSelectedSearchPropertyDefinition_TypedValueProperty =
+// Boolean
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.Bool;
+    /**
+     * The value to use for the search.
+     */
+    value: boolean;
+}
+    // Number
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.Int
+        | ReadSelectedPropertyType.Short
+        | ReadSelectedPropertyType.Long
+        | ReadSelectedPropertyType.Decimal
+        | ReadSelectedPropertyType.Double
+        | ReadSelectedPropertyType.Float;
+    /**
+     * The value to use for the search.
+     */
+    value: number;
+}
+    // String
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.String;
+    /**
+     * The value to use for the search.
+     */
+    value: string;
+}
+    // Temporal
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.DateTime
+        | ReadSelectedPropertyType.DateTimeOffset
+        | ReadSelectedPropertyType.TimeSpan
+        | ReadSelectedPropertyType.DateOnly
+        | ReadSelectedPropertyType.TimeOnly;
+    /**
+     * The value to use for the search.
+     */
+    value: string;
+};
+
+/**
+ * Defines the dependence between the .valueType and the type of the .comparisonOperator properties
+ */
+type Partial_ReadSelectedSearchPropertyDefinition_TypedComparisonOperators =
+// Boolean
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.Bool;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator: ReadSelectedComparisonOperator.Equal | ReadSelectedComparisonOperator.NotEqual;
+}
+    // Number
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.Int
+        | ReadSelectedPropertyType.Short
+        | ReadSelectedPropertyType.Long
+        | ReadSelectedPropertyType.Decimal
+        | ReadSelectedPropertyType.Double
+        | ReadSelectedPropertyType.Float;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator:
+        | ReadSelectedComparisonOperator.Equal
+        | ReadSelectedComparisonOperator.NotEqual
+        | ReadSelectedComparisonOperator.LessThan
+        | ReadSelectedComparisonOperator.LessOrEqual
+        | ReadSelectedComparisonOperator.GreaterThan
+        | ReadSelectedComparisonOperator.GreaterOrEqual;
+}
+    // String
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.String;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator:
+        | ReadSelectedComparisonOperator.Equal
+        | ReadSelectedComparisonOperator.NotEqual
+        | ReadSelectedComparisonOperator.Contains
+        | ReadSelectedComparisonOperator.StartsWith
+        | ReadSelectedComparisonOperator.EndsWith
+        | ReadSelectedComparisonOperator.IContains
+        | ReadSelectedComparisonOperator.IStartsWith
+        | ReadSelectedComparisonOperator.IEndsWith
+        | ReadSelectedComparisonOperator.IEqual
+        | ReadSelectedComparisonOperator.INotEqual;
+}
+    // Temporal
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.DateTime
+        | ReadSelectedPropertyType.DateTimeOffset
+        | ReadSelectedPropertyType.TimeSpan
+        | ReadSelectedPropertyType.DateOnly
+        | ReadSelectedPropertyType.TimeOnly;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator:
+        | ReadSelectedComparisonOperator.Equal
+        | ReadSelectedComparisonOperator.NotEqual
+        | ReadSelectedComparisonOperator.LessThan
+        | ReadSelectedComparisonOperator.LessOrEqual
+        | ReadSelectedComparisonOperator.GreaterThan
+        | ReadSelectedComparisonOperator.GreaterOrEqual;
+};

package/src/data/api/dto/read/index.ts

@@ -0,0 +1,10 @@
+export * from './ReadMetadataDto';
+export * from './ReadSelectedSearchPropertyDefinitionDto';
+export * from './ReadSelectedNestedCriteriaDto';
+export * from './ReadSelectedNestedCollectionCriteriaDto';
+export * from './ReadSelectedOrderingDefinitionDto';
+export * from './ReadSelectedOrderingPropertyDefinitionDto';
+export * from './ReadSelectedPaginationDefinitionDto';
+export * from './ReadSelectedDefinitionDto';
+export * from './ReadSelectedSearchDefinitionDto';
+export * from './ReadSelectedSearchDefinitionBuilder';

package/src/data/api/dto/response/ApiErrorDto.ts

@@ -0,0 +1,21 @@
+import {EmptyMetadataDto, ErrorCode, ValidationFailedMetadataDto} from '@data';
+
+/**
+ * Default, empty metadata.
+ */
+export type ApiErrorDto<TMetadata extends ApiErrorMetadataDto = ApiErrorMetadataDto> = {
+  message: string;
+    details?: string;
+    traceId?: string;
+    timestamp?: string;
+} & TMetadata;
+
+export type ApiErrorMetadataDto =
+    | {
+    code: ErrorCode.ValidationFailed;
+    metadata: ValidationFailedMetadataDto;
+}
+    | {
+    code: Omit<number, ErrorCode.ValidationFailed>;
+    metadata: EmptyMetadataDto;
+};

package/src/data/api/dto/response/ApiErrorResponseDto.ts

@@ -0,0 +1,13 @@
+import {ApiErrorDto, ApiErrorMetadataDto} from '@data';
+
+/**
+ * Represents an API response containing an error and empty metadata.
+ */
+export type ApiErrorResponseDto<TErrorMetadata extends ApiErrorMetadataDto = ApiErrorMetadataDto> = {
+    ok: false;
+
+    /**
+     * The error object containing information about the error
+     */
+    error: ApiErrorDto<TErrorMetadata>;
+};

package/src/data/api/dto/response/ApiResponseDto.ts

@@ -0,0 +1,7 @@
+import {ApiErrorMetadataDto, ApiErrorResponseDto, ApiSuccessResponseDto} from '@/data';
+import {Result} from '@utils/result';
+
+export type ApiResponseDto<T, TMetadata extends object, TErrorMetadata extends ApiErrorMetadataDto = ApiErrorMetadataDto> = Result<
+    ApiSuccessResponseDto<T, TMetadata>,
+    ApiErrorResponseDto<TErrorMetadata>
+>;

package/src/data/api/dto/response/ApiSuccessResponseDto.ts

@@ -0,0 +1,13 @@
+/**
+ * Represents a successful API response containing a result and metadata.
+ *
+ * @template T The type of result
+ * @template TMetadata The type of metadata
+ * @property {T} result - The result returned
+ * @property {TMetadata} metadata - Metadata about the result
+ */
+export type ApiSuccessResponseDto<T, TMetadata> = {
+  ok: true;
+  result: T;
+  metadata: TMetadata;
+};

package/src/data/api/dto/response/MetadataDto.ts

@@ -0,0 +1,24 @@
+declare const __brand: unique symbol;
+
+/**
+ * Utility type for creating branded types that are nominally different but structurally identical.
+ * This enables compile-time type safety for values that would otherwise have the same runtime structure.
+ *
+ * @template T - The brand identifier string literal type
+ *
+ * @example
+ * ```typescript
+ * type UserId = Brand<'userId'>;
+ * type OrderId = Brand<'orderId'>;
+ *
+ * const userId: UserId = { [__brand]: 'userId' } as UserId;
+ * const orderId: OrderId = userId; // Type error! Different brands
+ * ```
+ */
+export type Brand<T extends string> = { [__brand]: T };
+
+/**
+ * Default, empty metadata.
+ */
+export type EmptyMetadataDto = Brand<'emptyMetadata'>;
+export type ValidationFailedMetadataDto = Brand<'validationFailedMetadata'>;

package/src/data/api/dto/response/index.ts

@@ -0,0 +1,5 @@
+export * from './ApiResponseDto';
+export * from './ApiSuccessResponseDto';
+export * from './ApiErrorDto';
+export * from './MetadataDto';
+export * from './ApiErrorResponseDto';

package/src/data/api/enum/index.ts

@@ -0,0 +1,2 @@
+export * from './response';
+export * from './read';