@freshpointcz/fresh-core 0.0.18 → 0.0.20

package/dist/index.d.mts

@@ -1,59 +1,288 @@
-import dayjs, { Dayjs } from 'dayjs';
 import { BaseEntity, ColumnOptions, Repository, EntityTarget, EntityManager, ObjectLiteral, EntitySubscriberInterface, InsertEvent, UpdateEvent, SoftRemoveEvent, TransactionCommitEvent, DataSourceOptions } from 'typeorm';
+import dayjs, { Dayjs } from 'dayjs';
 import { Job } from 'node-schedule';
 import * as _eslint_core from '@eslint/core';
 import * as typescript_eslint_dist_compatibility_types from 'typescript-eslint/dist/compatibility-types';
 
+declare const AMOUNT_UNIT: {
+    readonly 1: {
+        readonly symbol: "g";
+        readonly translations: {
+            readonly en: "gram";
+            readonly cs: "gram";
+        };
+    };
+    readonly 2: {
+        readonly symbol: "kg";
+        readonly translations: {
+            readonly en: "kilogram";
+            readonly cs: "kilogram";
+        };
+    };
+    readonly 3: {
+        readonly symbol: "ml";
+        readonly translations: {
+            readonly en: "milliliter";
+            readonly cs: "mililitr";
+        };
+    };
+    readonly 4: {
+        readonly symbol: "l";
+        readonly translations: {
+            readonly en: "liter";
+            readonly cs: "litr";
+        };
+    };
+};
+
+type Status = "ok" | "error" | "not-authorized" | "not-authenticated" | "internal-server-error" | "validation-error";
+
+declare class StatusDto {
+    /**
+     * Call result status
+     */
+    status: Status;
+    /**
+     * UTC Timestamp
+     * @example "2021-12-01T13:23:39.305Z"
+     */
+    timestamp: string;
+    /**
+     * Details (optional)
+     */
+    details?: string;
+    constructor(status: Status, details?: string, timestamp?: string);
+}
+
 /**
- * Static DateUtils class
+ * Pagination parameters used to describe the current page slice of a query.
+ *
+ * Construct this object manually or via {@link getPaginationParams} to ensure
+ * defaults are applied consistently. Pass it into {@link constructTypeormPagination}
+ * when building a TypeORM `findAndCount` call.
+ *
+ * @example
+ * const pagination: PaginationParams = {
+ *   page: 2,
+ *   limit: 25,
+ *   skip: 25, // (page - 1) * limit
+ * };
  */
-declare class DateUtils {
-    /** Holidays 2025-2030 as YYYY-MM-DD strings */
-    static HOLIDAYS_STR: readonly string[];
-    /** Holidays 2025-2030 as UTC timestamps */
-    static HOLIDAYS: readonly number[];
-    static fromISOtoSQLtimestamp(ts?: string): string;
-    static toSQLtimestamp(ts: Dayjs): string;
-    static fromSQLtimestamp(mysqlDate: string): Dayjs;
-    static getSqlTimestampFromNowCzech(): string;
-    static fromISO(isoDate: string): Dayjs;
-    static getDate(ts: string): dayjs.Dayjs;
-    static getNow(): Dayjs;
-    static getNowCzech(): Dayjs;
-    static clone(ts: Dayjs): Dayjs;
-    static getLastSunday(weeksOffset?: number): Dayjs;
-    static dayInWeek(ts?: Dayjs): 1 | 2 | 3 | 4 | 5 | 6 | 7;
-    static isWorkdayDay(ts: Dayjs): boolean;
-    static getDiffInMinutesWithNow(inputTime: Dayjs): number;
-    static isInLastDays(numOfDays: number, timestampInput: string | Dayjs): boolean;
+interface PaginationParams {
+    /** 1-based page number. */
+    page: number;
+    /**
+     * Maximum number of items to return in a single page.
+     *
+     * @remarks Do NOT exceed 1000 — large limits can cause memory pressure and
+     * slow queries. Use {@link listAll} for bulk data retrieval instead.
+     */
+    limit: number;
+    /**
+     * Number of records to skip before returning results.
+     *
+     * @remarks Always derived as `(page - 1) * limit`. Do not set this
+     * independently; keep it in sync with `page` and `limit`.
+     */
+    skip: number;
 }
+/**
+ * Merges caller-supplied pagination overrides with {@link DEFAULT_PAGINATION_PARAMS}.
+ *
+ * Use this at the DAO or service layer to normalize an optional `PaginationParams`
+ * argument before passing it to {@link constructTypeormPagination}.
+ *
+ * @param params - Partial pagination parameters to merge. Any omitted fields
+ *   fall back to the defaults defined in {@link DEFAULT_PAGINATION_PARAMS}.
+ * @returns A complete {@link PaginationParams} object with all fields populated.
+ *
+ * @example
+ * // No args — returns the default params
+ * getPaginationParams();
+ * // → { page: 1, limit: 1000, skip: 0 }
+ *
+ * // Partial override — only limit is customized
+ * getPaginationParams({ page: 3, limit: 50, skip: 100 });
+ * // → { page: 3, limit: 50, skip: 100 }
+ */
+declare function getPaginationParams(params?: Partial<PaginationParams>): PaginationParams;
+/**
+ * Default pagination parameters applied when no overrides are provided.
+ *
+ * - `page`: `1` (first page)
+ * - `limit`: `1000` (fetch-all default; suited for internal batch operations)
+ * - `skip`: `0`
+ *
+ * @remarks
+ * This high default limit is intentional for internal/service-layer usage.
+ * Controller layer endpoints should always supply explicit, lower limits
+ * (e.g. 20–100) to avoid returning unbounded result sets to API consumers.
+ *
+ * @see {@link getPaginationParams} for applying these defaults with optional overrides.
+ */
+declare const DEFAULT_PAGINATION_PARAMS: PaginationParams;
 
-type Deferred<T> = {
-    promise: Promise<T>;
-    resolve: (value: T) => void;
-    reject: (err: any) => void;
+/**
+ * Converts {@link PaginationParams} into the `take`/`skip` shape expected by
+ * TypeORM's `find`, `findAndCount`, and `findOne` options.
+ *
+ * @param params - A fully-populated {@link PaginationParams} object (use
+ *   {@link getPaginationParams} to guarantee all fields are set).
+ * @returns An object with `take` and `skip` keys ready to spread into a TypeORM
+ *   `FindManyOptions`.
+ *
+ * @example
+ * const pagination = getPaginationParams({ page: 2, limit: 25, skip: 25 });
+ *
+ * const [data, total] = await repo.findAndCount({
+ *   where: { isActive: true },
+ *   ...constructTypeormPagination(pagination),
+ * });
+ *
+ * @see {@link https://typeorm.io/find-options | TypeORM Find Options}
+ */
+declare function constructTypeormPagination(params: PaginationParams): {
+    take: number;
+    skip: number;
 };
 /**
- * Deferred promise is like "fake" which is used to manually resolve/reject later on with different promise
- * With resolve and reject outside for easier change of promise
- * is used as placeholder untill real promise is assigned
+ * Parses pagination parameters from a {@link URLSearchParams} instance.
+ *
+ * Intended for use in contexts where query parameters arrive as a raw URL
+ * string (e.g. middleware, edge functions, or fetch-based handlers) rather
+ * than through a framework that deserialises them automatically.
+ *
+ * **Clamping rules applied automatically:**
+ * - `page` is clamped to a minimum of `1`.
+ * - `limit` is clamped between `1` and `100` (inclusive).
+ * - `skip` is derived as `(page - 1) * limit`.
+ *
+ * @param searchParams - A `URLSearchParams` instance, typically obtained from
+ *   `new URL(request.url).searchParams`.
+ * @returns A fully-populated {@link PaginationParams} object.
+ *
+ * @example
+ * const url = new URL("https://api.example.com/items?page=3&limit=50");
+ * const pagination = parsePaginationFromURL(url.searchParams);
+ * // → { page: 3, limit: 50, skip: 100 }
+ *
+ * @example
+ * // Missing params fall back to sensible defaults
+ * const url = new URL("https://api.example.com/items");
+ * const pagination = parsePaginationFromURL(url.searchParams);
+ * // → { page: 1, limit: 20, skip: 0 }
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams | MDN: URLSearchParams}
  */
-declare function createDeferred<T>(): Deferred<T>;
+declare function parsePaginationFromURL(searchParams: URLSearchParams): PaginationParams;
 
 /**
- * Experimental class to maintain just one promise for some process flow.
- * Currently is in singleton design, so can be used only in one proces. (currently: all-product-availability-per-day)
+ * Metadata returned alongside a paginated result set.
+ *
+ * Populated automatically by {@link getPaginationMeta}.
+ *
+ * @example
+ * // Example meta for page 2 of 3, 25 items per page, 70 total items:
+ * const meta: PaginationMeta = {
+ *   total: 70,
+ *   page: 2,
+ *   limit: 25,
+ *   totalPages: 3,
+ * };
  */
-declare class SinglePromiseWaiter<T = any> {
-    private static _instance;
-    static getInstance<T = any>(): SinglePromiseWaiter<any>;
-    private _promise;
-    get promise(): Promise<T> | null;
-    set promise(promise: Promise<T> | null);
-    get hasPromise(): boolean;
+interface PaginationMeta {
+    /** Total number of records across all pages. */
+    total: number;
+    /** Current 1-based page number. */
+    page: number;
+    /** Maximum number of items per page that was requested. */
+    limit: number;
+    /**
+     * Total number of pages available given the current `limit`.
+     *
+     * Computed as `Math.ceil(total / limit)`. Returns `0` when `total` is `0`.
+     */
+    totalPages: number;
 }
+/**
+ * Constructs a {@link PaginationMeta} object from raw query result data.
+ *
+ * Call this after a `findAndCount` (or equivalent) to build the `meta` field
+ * of a {@link PaginatedList} response.
+ *
+ * @param total - Total number of records matching the query (the second element
+ *   returned by TypeORM's `findAndCount`).
+ * @param page - The 1-based page number that was requested.
+ * @param limit - The page size that was requested.
+ * @returns A {@link PaginationMeta} object ready to include in a {@link PaginatedList}.
+ *
+ * @example
+ * const [data, total] = await repo.findAndCount({ take: 25, skip: 25 });
+ *
+ * return {
+ *   data,
+ *   meta: getPaginationMeta(total, 2, 25),
+ *   // → { total: 70, page: 2, limit: 25, totalPages: 3 }
+ * };
+ */
+declare function getPaginationMeta(total: number, page: number, limit: number): PaginationMeta;
 
-declare function isValidCron(expr: string): boolean;
+/**
+ * A generic wrapper for a single page of query results combined with its
+ * pagination metadata.
+ *
+ * Returned by DAO `findMany` methods and exposed directly from API endpoints.
+ *
+ * @typeParam T - The entity or DTO type contained in the `data` array.
+ *
+ * @example
+ * const result: PaginatedList<UserEntity> = {
+ *   data: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }],
+ *   meta: { total: 42, page: 1, limit: 20, totalPages: 3 },
+ * };
+ */
+interface PaginatedList<T> {
+    /** The records for the current page. */
+    data: T[];
+    /** Pagination metadata describing the full result set. */
+    meta: PaginationMeta;
+}
+
+/**
+ * Exhaustively fetches all records by iterating through pages until the last
+ * page is reached.
+ *
+ * Use this utility when you need the full result set for an operation that
+ * does not support streaming (e.g. bulk exports, aggregations, seeding).
+ * For large datasets, prefer a streaming or cursor-based approach where possible.
+ *
+ * @typeParam T - The entity or DTO type returned by `fetchPage`.
+ *
+ * @param fetchPage - An async function that accepts a {@link PaginationParams}
+ *   and returns a {@link PaginatedList}. Typically, a bound DAO method.
+ * @param batchSize - Number of records to fetch per page. Defaults to `1000`.
+ *   Do not exceed `1000` to avoid memory pressure.
+ * @returns A promise resolving to a flat array of all matching records.
+ *
+ * @remarks
+ * - Iteration stops when `page >= meta.totalPages`.
+ * - If the underlying data changes during iteration, results may be inconsistent.
+ *   For consistency guarantees, wrap the call in a database transaction.
+ *
+ * @example
+ * // Fetch all active users without worrying about pagination
+ * const allUsers = await listAll(
+ *   (pagination) => userDao.findMany({ where: { isActive: true }, pagination }),
+ * );
+ *
+ * @example
+ * // Use a smaller batch size to reduce memory footprint
+ * const allOrders = await listAll(
+ *   (pagination) => orderDao.findMany({ pagination }),
+ *   200,
+ * );
+ */
+declare function listAll<T>(fetchPage: (pagination: PaginationParams) => Promise<PaginatedList<T>>, batchSize?: number): Promise<T[]>;
 
 /**
  * Abstract base class implementing a per-subclass Singleton pattern.
@@ -113,56 +342,31 @@ declare abstract class Singleton {
     protected abstract onInit(): void | Promise<void>;
 }
 
-type Status = "ok" | "error" | "not-authorized" | "not-authenticated" | "internal-server-error" | "validation-error";
+type Deferred<T> = {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (err: any) => void;
+};
+/**
+ * Deferred promise is like "fake" which is used to manually resolve/reject later on with different promise
+ * With resolve and reject outside for easier change of promise
+ * is used as placeholder untill real promise is assigned
+ */
+declare function createDeferred<T>(): Deferred<T>;
 
-declare class StatusDto {
-    /**
-     * Call result status
-     */
-    status: Status;
-    /**
-     * UTC Timestamp
-     * @example "2021-12-01T13:23:39.305Z"
-     */
-    timestamp: string;
-    /**
-     * Details (optional)
-     */
-    details?: string;
-    constructor(status: Status, details?: string, timestamp?: string);
+/**
+ * Experimental class to maintain just one promise for some process flow.
+ * Currently is in singleton design, so can be used only in one proces. (currently: all-product-availability-per-day)
+ */
+declare class SinglePromiseWaiter<T = any> {
+    private static _instance;
+    static getInstance<T = any>(): SinglePromiseWaiter<any>;
+    private _promise;
+    get promise(): Promise<T> | null;
+    set promise(promise: Promise<T> | null);
+    get hasPromise(): boolean;
 }
 
-declare const AMOUNT_UNIT: {
-    readonly 1: {
-        readonly symbol: "g";
-        readonly translations: {
-            readonly en: "gram";
-            readonly cs: "gram";
-        };
-    };
-    readonly 2: {
-        readonly symbol: "kg";
-        readonly translations: {
-            readonly en: "kilogram";
-            readonly cs: "kilogram";
-        };
-    };
-    readonly 3: {
-        readonly symbol: "ml";
-        readonly translations: {
-            readonly en: "milliliter";
-            readonly cs: "mililitr";
-        };
-    };
-    readonly 4: {
-        readonly symbol: "l";
-        readonly translations: {
-            readonly en: "liter";
-            readonly cs: "litr";
-        };
-    };
-};
-
 /**
  * Default Entity with needed columns for every basic entity `id`, `uuid`, `created_at`, `updated_at` and `deleted_at`;
  */
@@ -404,6 +608,137 @@ declare class Product extends FreshEntity {
 declare class Subcategory extends FreshEntity {
 }
 
+/**
+ * Formats a number to a database-safe decimal string.
+ * @param num - The number to format
+ * @param precision - Total number of significant digits allowed (e.g., 9)
+ * @param scale - Number of digits after the decimal point (e.g., 2)
+ * @returns string formatted for database insertion of decimal type
+ */
+declare function toDecimal(num: number, precision?: number, scale?: number): string;
+/**
+ * Options for {@link isDecimal}.
+ */
+interface IsDecimalOptions {
+    /**
+     * Restrict accepted JavaScript type.
+     *
+     * - `"number"` — only JS `number` values pass (strings are rejected).
+     * - `"string"` — only JS `string` values pass (numbers are rejected).
+     * - omitted — both `number` and `string` are accepted.
+     *
+     * @example
+     * isDecimal("3.14", { allowedType: "number" }); // false — wrong JS type
+     * isDecimal(3.14,   { allowedType: "number" }); // true
+     * isDecimal(3.14,   { allowedType: "string" }); // false — wrong JS type
+     * isDecimal("3.14", { allowedType: "string" }); // true
+     */
+    allowedType?: "number" | "string";
+    /**
+     * The decimal separator character to accept for string values.
+     * Has no effect on `number` inputs (JS numbers always use `.` internally).
+     *
+     * Defaults to `"."`.
+     *
+     * @example
+     * isDecimal("3,14", { decimalPoint: "," }); // true
+     * isDecimal("3.14", { decimalPoint: "," }); // false — wrong separator
+     */
+    decimalPoint?: "." | ",";
+    /**
+     * Maximum total number of significant digits (integer digits + fractional digits combined).
+     *
+     * @example
+     * isDecimal("12345.67", { precision: 7 }); // true  — 5 + 2 = 7 digits
+     * isDecimal("12345.67", { precision: 6 }); // false — 5 + 2 = 7 > 6
+     */
+    precision?: number;
+    /**
+     * Maximum number of digits allowed after the decimal point.
+     *
+     * @example
+     * isDecimal("3.14",  { scale: 2 }); // true
+     * isDecimal("3.145", { scale: 2 }); // false — 3 fractional digits > 2
+     * isDecimal("3",     { scale: 2 }); // true  — 0 fractional digits ≤ 2
+     */
+    scale?: number;
+}
+/**
+ * Narrows `v` to `number` when `allowedType` is `"number"`.
+ * @param v - Value to test.
+ * @param options - Must include `allowedType: "number"`.
+ */
+declare function isDecimal(v: unknown, options: IsDecimalOptions & {
+    allowedType: "number";
+}): v is number;
+/**
+ * Narrows `v` to `string` when `allowedType` is `"string"`.
+ * @param v - Value to test.
+ * @param options - Must include `allowedType: "string"`.
+ */
+declare function isDecimal(v: unknown, options: IsDecimalOptions & {
+    allowedType: "string";
+}): v is string;
+/**
+ * Returns `true` when `v` is a valid decimal value (number or string).
+ *
+ * Validates that the input represents a finite decimal number. Accepts both
+ * JS `number` primitives and decimal strings. Optionally restricts the accepted
+ * JS type, the decimal separator character, and enforces precision/scale bounds.
+ *
+ * **Type narrowing via overloads:**
+ * When `allowedType` is specified the return type is narrowed accordingly —
+ * `v is number` for `"number"` and `v is string` for `"string"`.
+ *
+ * **Behaviour per input type:**
+ * - `number` — must be finite and non-NaN. Scientific notation (e.g. `1e20`) is
+ *   rejected because it has no standard decimal representation.
+ * - `string` — must match `^-?\d+([.,]\d+)?$` using the configured separator.
+ *   Leading/trailing whitespace is not trimmed; pass `.trim()` yourself if needed.
+ *
+ * @param v - Value to test. Anything other than `number` or `string` returns `false`.
+ * @param options - Optional validation constraints.
+ * @returns `true` when `v` is a valid decimal within the specified constraints.
+ *
+ * @example
+ * // Basic usage — accepts both number and string
+ * isDecimal(3.14);      // true
+ * isDecimal("3.14");    // true
+ * isDecimal("abc");     // false
+ * isDecimal(Infinity);  // false
+ * isDecimal(NaN);       // false
+ * isDecimal(null);      // false
+ *
+ * @example
+ * // Restrict to a single JS type
+ * isDecimal(3.14,   { allowedType: "number" }); // true
+ * isDecimal("3.14", { allowedType: "number" }); // false — string rejected
+ * isDecimal("3.14", { allowedType: "string" }); // true
+ * isDecimal(3.14,   { allowedType: "string" }); // false — number rejected
+ *
+ * @example
+ * // Comma as decimal separator (e.g. European locale strings)
+ * isDecimal("3,14", { decimalPoint: "," }); // true
+ * isDecimal("3.14", { decimalPoint: "," }); // false
+ *
+ * @example
+ * // Precision and scale constraints (matching SQL decimal(9, 2))
+ * isDecimal("1234567.89", { precision: 9, scale: 2 }); // true  — 7+2=9 digits
+ * isDecimal("12345678.9", { precision: 9, scale: 2 }); // false — 8+1=9 but scale violated? no — true, 1≤2
+ * isDecimal("3.145",      { scale: 2 });                // false — 3 fractional digits
+ * isDecimal("3",          { scale: 2 });                // true  — 0 fractional digits
+ *
+ * @example
+ * // Type narrowing in practice
+ * function process(raw: unknown) {
+ *     if (isDecimal(raw, { allowedType: "string" })) {
+ *         raw; // narrowed to string here
+ *         console.log(raw.toUpperCase());
+ *     }
+ * }
+ */
+declare function isDecimal(v: unknown, options?: IsDecimalOptions): v is number | string;
+
 /**
  * Runtime validation for enum values.
  * If a runtime enum object is provided, the value must match one of its values
@@ -503,6 +838,29 @@ declare const TO_BINARY_FLAG: (v: number | boolean | null | undefined) => Binary
  */
 declare function runWithConcurrency<T>(items: T[], concurrency: number, worker: (item: T) => Promise<void>): Promise<void>;
 
+/**
+ * Resolves a path parameter ID string to either a numeric ID or a UUID (any version).
+ *
+ * tsoa always provides path parameters as strings, so this utility determines
+ * the intended type by checking whether the value is purely numeric.
+ *
+ * @param id - Raw path parameter string
+ * @returns Parsed `number` if the value is numeric, otherwise the original `string`.
+ *
+ * @example
+ * resolvePathParameterId("42")                                   // → 42
+ * resolvePathParameterId("550e8400-e29b-41d4-a716-446655440000") // → "550e8400-..."
+ *
+ * // Typical tsoa usage:
+ * \@Get("{id}")
+ * public async getUserById(\@Request() req: ExRequest, \@Path() id: string) {
+ *     const userId = resolvePathParameterId(id); // number | string
+ * }
+ */
+declare function resolvePathParameterId(id: string): string | number;
+
+declare function isValidCron(expr: string): boolean;
+
 type TransformMap<TIn, TOut, K extends keyof TIn & keyof TOut> = Partial<{
     [P in K]: (val: TIn[P]) => TOut[P];
 }>;
@@ -515,34 +873,28 @@ type TransformMap<TIn, TOut, K extends keyof TIn & keyof TOut> = Partial<{
  */
 declare function buildPatch<TOut extends Record<string, any>, TIn extends Record<string, any>, K extends keyof TIn & keyof TOut = keyof TIn & keyof TOut>(data: Partial<TIn>, keys: readonly K[], transforms?: TransformMap<TIn, TOut, K>): Partial<Pick<TOut, K>>;
 
-type Maybe<T> = T | null;
 /**
- * Validates a value that may be `null` or given type
- *
- * WARNING:
- * `undefined` is NOT accepted by this function.
- * If you need `undefined` support, it must be handled
- * before calling this guard or explicitly allowed elsewhere.
- *
- * @typeParam T - The underlying non-nullable type
- * @param v - Value to validate
- * @param inner - Typeguard function for the underlying type `T`
- *
- * @returns `true` if the value is `null` or satisfies the inner typeguard
+ * Static DateUtils class
  */
-declare function isMaybe<T>(v: unknown, inner: (x: unknown) => x is T): v is Maybe<T>;
-
-declare abstract class DataHelper<T> {
-    private _data?;
-    private _dataPromise;
-    protected deviceIds: Promise<number[]>;
-    constructor(startDataRetrieve: boolean | undefined, deviceIds: Promise<number[]>);
-    protected get data(): Maybe<T> | undefined;
-    protected set data(value: Maybe<T>);
-    protected get dataPromise(): Maybe<Promise<Maybe<T>>>;
-    protected set dataPromise(value: Maybe<Promise<Maybe<T>>>);
-    getData(): Promise<Maybe<T>>;
-    abstract startDataRetrieval(): Promise<Maybe<T>>;
+declare class DateUtils {
+    /** Holidays 2025-2030 as YYYY-MM-DD strings */
+    static HOLIDAYS_STR: readonly string[];
+    /** Holidays 2025-2030 as UTC timestamps */
+    static HOLIDAYS: readonly number[];
+    static fromISOtoSQLtimestamp(ts?: string): string;
+    static toSQLtimestamp(ts: Dayjs): string;
+    static fromSQLtimestamp(mysqlDate: string): Dayjs;
+    static getSqlTimestampFromNowCzech(): string;
+    static fromISO(isoDate: string): Dayjs;
+    static getDate(ts: string): dayjs.Dayjs;
+    static getNow(): Dayjs;
+    static getNowCzech(): Dayjs;
+    static clone(ts: Dayjs): Dayjs;
+    static getLastSunday(weeksOffset?: number): Dayjs;
+    static dayInWeek(ts?: Dayjs): 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    static isWorkdayDay(ts: Dayjs): boolean;
+    static getDiffInMinutesWithNow(inputTime: Dayjs): number;
+    static isInLastDays(numOfDays: number, timestampInput: string | Dayjs): boolean;
 }
 
 /**
@@ -635,8 +987,26 @@ declare abstract class FreshJob<T = void> extends Singleton {
     abstract invoke(): T | Promise<T>;
 }
 
+type Maybe<T> = T | null;
+/**
+ * Validates a value that may be `null` or given type
+ *
+ * WARNING:
+ * `undefined` is NOT accepted by this function.
+ * If you need `undefined` support, it must be handled
+ * before calling this guard or explicitly allowed elsewhere.
+ *
+ * @typeParam T - The underlying non-nullable type
+ * @param v - Value to validate
+ * @param inner - Typeguard function for the underlying type `T`
+ *
+ * @returns `true` if the value is `null` or satisfies the inner typeguard
+ */
+declare function isMaybe<T>(v: unknown, inner: (x: unknown) => x is T): v is Maybe<T>;
+
 type CardNumber = `${number}${number}${number}${number}`;
 
+/** @deprecated use {@link FreshError} instead */
 declare class ApiError extends Error {
     private _statusCode;
     get statusCode(): number;
@@ -657,6 +1027,219 @@ declare class BusinessWarning extends Error {
     constructor(code: string, message: string);
 }
 
+/**
+ * Options for {@link FreshError} and its subclasses.
+ */
+interface FreshErrorOptions {
+    /**
+     * The original error that caused this one.
+     * Preserved for error chaining and accessible via `error.cause`.
+     */
+    cause?: unknown;
+}
+/**
+ * Base class for all application HTTP errors.
+ *
+ * Extend this class to create typed, status-specific errors with a hardcoded
+ * HTTP status code and status string. Direct instantiation is allowed but
+ * subclasses are preferred for consistent error identity.
+ *
+ * `error.name` is automatically set to the subclass name, so stack traces
+ * and logs show `UnauthorizedError` instead of the generic `Error`.
+ *
+ * @example
+ * // Without cause
+ * throw new FreshError(HttpStatus.NOT_FOUND, "error", "User not found");
+ *
+ * // With cause — preserves the original error for logging/debugging
+ * try {
+ *     await db.findUser(id);
+ * } catch (err) {
+ *     throw new FreshError(HttpStatus.INTERNAL_SERVER_ERROR, "internal-server-error", "DB query failed", { cause: err });
+ * }
+ */
+declare class FreshError extends Error {
+    /** HTTP status code sent in the response. */
+    readonly statusCode: number;
+    /** Structured response body describing the error. */
+    readonly statusDto: StatusDto;
+    constructor(statusCode: HttpStatus, status: Status, detail?: string, options?: FreshErrorOptions);
+}
+
+/** 400 — The request is malformed or contains invalid parameters. */
+declare class BadRequestError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 401 — Authentication is required or the provided credentials are invalid. */
+declare class UnauthorizedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 402 — Payment is required to access the requested resource. */
+declare class PaymentRequiredError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 403 — The caller is authenticated but lacks permission to access the resource. */
+declare class ForbiddenError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 404 — The requested resource does not exist. */
+declare class NotFoundError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 405 — The HTTP method is not supported for this endpoint. */
+declare class MethodNotAllowedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 406 — The server cannot produce a response matching the client's `Accept` headers. */
+declare class NotAcceptableError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 407 — Authentication with the proxy is required before the request can proceed. */
+declare class ProxyAuthenticationRequiredError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 408 — The server timed out waiting for the client to complete the request. */
+declare class RequestTimeoutError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 409 — The request conflicts with the current state of the resource. */
+declare class ConflictError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 410 — The resource has been permanently removed and will not return. */
+declare class GoneError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 411 — The request must include a `Content-Length` header. */
+declare class LengthRequiredError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 412 — A precondition in the request headers was not met. */
+declare class PreconditionFailedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 413 — The request body exceeds the server's size limit. */
+declare class PayloadTooLargeError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 414 — The request URI is longer than the server is willing to process. */
+declare class UriTooLongError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 415 — The request's `Content-Type` is not supported by the server. */
+declare class UnsupportedMediaTypeError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 416 — The `Range` header in the request cannot be satisfied by the resource. */
+declare class RangeNotSatisfiableError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 417 — The expectation in the `Expect` request header could not be met. */
+declare class ExpectationFailedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 418 — The server refuses to brew coffee because it is, permanently, a teapot. */
+declare class ImATeapotError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 421 — The request was directed at a server that cannot produce a response. */
+declare class MisdirectedRequestError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 422 — The request is well-formed but contains semantic errors. */
+declare class UnprocessableEntityError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 423 — The resource is locked and cannot be accessed. */
+declare class LockedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 424 — The request failed because a dependency it relies on also failed. */
+declare class FailedDependencyError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 425 — The server is unwilling to process a request that may be replayed. */
+declare class TooEarlyError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 426 — The client must switch to a different protocol to proceed. */
+declare class UpgradeRequiredError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 428 — The request must be conditional (e.g. missing `If-Match` header). */
+declare class PreconditionRequiredError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 429 — The client has sent too many requests in a given time window. */
+declare class TooManyRequestsError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 431 — The request headers are too large for the server to process. */
+declare class RequestHeaderFieldsTooLargeError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 451 — The resource is unavailable due to legal restrictions. */
+declare class UnavailableForLegalReasonsError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 500 — The server encountered an unexpected condition. */
+declare class InternalServerError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 501 — The server does not support the functionality required to fulfil the request. */
+declare class NotImplementedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 502 — The upstream server returned an invalid response. */
+declare class BadGatewayError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 503 — The server is temporarily unavailable, usually due to maintenance or overload. */
+declare class ServiceUnavailableError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 504 — The upstream server did not respond in time. */
+declare class GatewayTimeoutError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 505 — The HTTP version used in the request is not supported by the server. */
+declare class HttpVersionNotSupportedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 506 — The server has a configuration error resulting in circular content negotiation. */
+declare class VariantAlsoNegotiatesError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 507 — The server cannot store the representation needed to complete the request. */
+declare class InsufficientStorageError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 508 — The server detected an infinite loop while processing the request. */
+declare class LoopDetectedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 510 — Further extensions to the request are required for the server to fulfil it. */
+declare class NotExtendedError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+/** 511 — The client must authenticate to gain network access (e.g. captive portal). */
+declare class NetworkAuthenticationRequiredError extends FreshError {
+    constructor(detail?: string, options?: FreshErrorOptions);
+}
+
+declare abstract class DataHelper<T> {
+    private _data?;
+    private _dataPromise;
+    protected deviceIds: Promise<number[]>;
+    constructor(startDataRetrieve: boolean | undefined, deviceIds: Promise<number[]>);
+    protected get data(): Maybe<T> | undefined;
+    protected set data(value: Maybe<T>);
+    protected get dataPromise(): Maybe<Promise<Maybe<T>>>;
+    protected set dataPromise(value: Maybe<Promise<Maybe<T>>>);
+    getData(): Promise<Maybe<T>>;
+    abstract startDataRetrieval(): Promise<Maybe<T>>;
+}
+
 declare const FRESH_ESLINT_CONFIG: {
     files: string[];
     ignores: string[];
@@ -734,4 +1317,4 @@ interface HealthCheckResult {
     };
 }
 
-export { AMOUNT_UNIT, ActionCommandCode, ApiError, BaseEntityChangeSubscriber, type BinaryFlag, BusinessWarning, type CardNumber, Category, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, type EntityChangeEvent, FreshDao, FreshEntity, FreshHyperEntity, FreshJob, FreshTranslationBase, type HealthCheckResult, HttpStatus, LanguageCode, Manufacturer, type Maybe, PaymentMethod, PG_DATA_SOURCE_OPTIONS as PgDataSourceOptions, Product, SinglePromiseWaiter, Singleton, type Status, StatusDto, Subcategory, TO_BINARY_FLAG, TimestampColumn, TransactionType, buildPatch, createDeferred, FRESH_ESLINT_CONFIG as freshEslintConfig, hasOwn, isEnumValue, isFlag01, isMaybe, isNumber, isNumberInRange, isObject, isString, isValidCron, runWithConcurrency };
+export { AMOUNT_UNIT, ActionCommandCode, ApiError, BadGatewayError, BadRequestError, BaseEntityChangeSubscriber, type BinaryFlag, BusinessWarning, type CardNumber, Category, ConflictError, DEFAULT_PAGINATION_PARAMS, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, type EntityChangeEvent, ExpectationFailedError, FailedDependencyError, ForbiddenError, FreshDao, FreshEntity, FreshError, type FreshErrorOptions, FreshHyperEntity, FreshJob, FreshTranslationBase, GatewayTimeoutError, GoneError, type HealthCheckResult, HttpStatus, HttpVersionNotSupportedError, ImATeapotError, InsufficientStorageError, InternalServerError, type IsDecimalOptions, LanguageCode, LengthRequiredError, LockedError, LoopDetectedError, Manufacturer, type Maybe, MethodNotAllowedError, MisdirectedRequestError, NetworkAuthenticationRequiredError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, type PaginatedList, type PaginationMeta, type PaginationParams, PayloadTooLargeError, PaymentMethod, PaymentRequiredError, PG_DATA_SOURCE_OPTIONS as PgDataSourceOptions, PreconditionFailedError, PreconditionRequiredError, Product, ProxyAuthenticationRequiredError, RangeNotSatisfiableError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, ServiceUnavailableError, SinglePromiseWaiter, Singleton, type Status, StatusDto, Subcategory, TO_BINARY_FLAG, TimestampColumn, TooEarlyError, TooManyRequestsError, TransactionType, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, VariantAlsoNegotiatesError, buildPatch, constructTypeormPagination, createDeferred, FRESH_ESLINT_CONFIG as freshEslintConfig, getPaginationMeta, getPaginationParams, hasOwn, isDecimal, isEnumValue, isFlag01, isMaybe, isNumber, isNumberInRange, isObject, isString, isValidCron, listAll, parsePaginationFromURL, resolvePathParameterId, runWithConcurrency, toDecimal };