apimo.js 1.0.4 → 1.0.5

package/dist/core/api.d.ts

@@ -26,6 +26,27 @@ export interface AdditionalConfig {
             transformFn?: CatalogTransformer;
         };
     };
+    retry: {
+        /**
+         * Maximum total number of attempts (1 = no retries, 2 = one retry, etc.).
+         * @default 3
+         */
+        attempts: number;
+        /**
+         * Delay in milliseconds before the first retry.
+         * Subsequent delays are calculated according to the `backoff` strategy.
+         * @default 200
+         */
+        initialDelayMs: number;
+        /**
+         * Back-off strategy applied between attempts.
+         * - `exponential` — delay doubles on every retry (200 → 400 → 800 …)
+         * - `linear`      — delay increases by `initialDelayMs` each time (200 → 400 → 600 …)
+         * - `fixed`       — the same delay is used for every retry
+         * @default 'exponential'
+         */
+        backoff: 'exponential' | 'linear' | 'fixed';
+    };
 }
 export declare const DEFAULT_BASE_URL = "https://api.apimo.pro";
 export declare const DEFAULT_ADDITIONAL_CONFIG: AdditionalConfig;
@@ -47,31 +68,42 @@ export declare class Apimo {
     getCatalogEntries(catalogName: CatalogName, options?: Pick<ApiSearchParams, 'culture'>): Promise<CatalogEntry[]>;
     fetchCatalog(catalogName: CatalogName, options?: Pick<ApiSearchParams, 'culture'>): Promise<CatalogEntry[]>;
     fetchAgencies(options?: Pick<ApiSearchParams, 'culture' | 'limit' | 'offset'>): Promise<{
-        timestamp: number;
+        total_items: number;
         agencies: {
             id: number;
-            name: string;
+            reference: number;
             active: boolean;
-            created_at: Date;
-            updated_at: Date;
-            email: string;
-            phone: string;
-            fax: string | null;
+            name: string;
+            company: {
+                id: number;
+                name: string;
+            };
+            brand: unknown;
+            networks: unknown[];
+            address: string;
+            address_more: string | null;
             city: {
                 id: number;
                 name: string;
                 zipcode: string;
             };
+            district: unknown;
+            country: string;
+            region: string;
+            latitude: number;
+            longitude: number;
+            email: string;
+            phone: string;
+            fax: string | null;
+            url: string;
+            logo: string;
+            logo_svg: string | null;
             picture: string;
-            partners: {
-                name: string | null;
-                type: number;
-                partner: number | null;
-                reference: string;
-                amount: number;
-                currency: string;
-            }[];
-            stories: unknown[];
+            currency: string;
+            timetable: string;
+            created_at: Date;
+            updated_at: Date;
+            providers: string;
             rates: {
                 id: number;
                 category: string | CatalogEntryName | null;
@@ -82,24 +114,15 @@ export declare class Apimo {
                 comment: string;
                 url: string | null;
             }[];
-            url: string;
-            reference: number;
-            currency: string;
-            company: {
-                id: number;
-                name: string;
-            };
-            networks: unknown[];
-            address: string;
-            address_more: string | null;
-            country: string;
-            region: string;
-            latitude: number;
-            longitude: number;
-            logo: string;
-            logo_svg: string | null;
-            timetable: string;
-            providers: string;
+            partners: {
+                type: number;
+                partner: number | null;
+                name: string | null;
+                reference: string;
+                amount: number;
+                currency: string;
+            }[];
+            stories: unknown[];
             users: {
                 id: number;
                 agency: number;
@@ -117,6 +140,7 @@ export declare class Apimo {
                 birthday_at: Date;
                 timezone: string | null;
                 picture: string | null;
+                rates: unknown;
                 username?: string | undefined;
                 password?: string | undefined;
                 spoken_languages?: string[] | undefined;
@@ -126,75 +150,22 @@ export declare class Apimo {
                 } | null | undefined;
                 partners?: unknown[] | undefined;
                 stories?: unknown[] | undefined;
-                rates?: unknown;
             }[];
             sectors: unknown[];
             parameters: string;
             subscription: string;
-            brand?: unknown;
-            district?: unknown;
         }[];
-        total_items: number;
+        timestamp: number;
     }>;
     fetchProperties(agencyId: number, options?: Pick<ApiSearchParams, 'culture' | 'limit' | 'offset' | 'timestamp' | 'step' | 'status' | 'group'>): Promise<{
-        timestamp: number;
         total_items: number;
+        timestamp: number;
         properties: {
-            tags: (string | CatalogEntryName | null)[];
             id: number;
-            name: string | null;
-            options: unknown[];
-            type: string | CatalogEntryName | null;
-            length: number | null;
-            status: string | CatalogEntryName | null;
-            agency: number;
-            created_at: Date;
-            updated_at: Date;
-            city: {
-                id: number;
-                name: string;
-                zipcode: string;
-            };
-            rates: unknown[];
-            step: string | CatalogEntryName | null;
-            category: string | CatalogEntryName | null;
-            url: string | null;
             reference: number;
-            address: string | null;
-            address_more: string | null;
-            district: {
-                id: number;
-                name: string;
-            } | null;
-            country: string;
-            region: {
-                id: number;
-                name: string;
-            };
-            latitude: number;
-            longitude: number;
-            height: number | null;
-            comments: {
-                language: string;
-                comment: string;
-                title?: string | null | undefined;
-                subtitle?: string | null | undefined;
-                hook?: unknown;
-                comment_full?: string | null | undefined;
-            }[];
-            area: {
-                value: number;
-                unit: string | CatalogEntryName | null;
-                total: number;
-                weighted: number;
-            };
-            floor: {
-                value: number;
-                type: string | CatalogEntryName | null;
-                levels: number;
-                floors: number;
-            };
-            orientations: (string | CatalogEntryName | null)[];
+            agency: number;
+            brand: unknown;
+            sector: unknown;
             user: {
                 id: number;
                 agency: number;
@@ -212,6 +183,7 @@ export declare class Apimo {
                 birthday_at: Date;
                 timezone: string | null;
                 picture: string | null;
+                rates: unknown;
                 username?: string | undefined;
                 password?: string | undefined;
                 spoken_languages?: string[] | undefined;
@@ -221,9 +193,14 @@ export declare class Apimo {
                 } | null | undefined;
                 partners?: unknown[] | undefined;
                 stories?: unknown[] | undefined;
-                rates?: unknown;
             };
+            step: string | CatalogEntryName | null;
+            status: string | CatalogEntryName | null;
             parent: number | null;
+            ranking: unknown;
+            category: string | CatalogEntryName | null;
+            name: string | null;
+            type: string | CatalogEntryName | null;
             subtype: string | CatalogEntryName | null;
             agreement: {
                 type: string | CatalogEntryName | null;
@@ -235,9 +212,38 @@ export declare class Apimo {
             lot_reference: string | null;
             cadastre_reference: string | null;
             stairs_reference: string | null;
+            address: string | null;
+            address_more: string | null;
             publish_address: boolean;
+            country: string;
+            region: {
+                id: number;
+                name: string;
+            };
+            city: {
+                id: number;
+                name: string;
+                zipcode: string;
+            };
+            original_city: unknown;
+            district: {
+                id: number;
+                name: string;
+            } | null;
+            original_district: unknown;
+            location: unknown;
+            longitude: number;
+            latitude: number;
             radius: number;
             altitude: number;
+            referral: unknown;
+            subreferral: unknown;
+            area: {
+                unit: string | CatalogEntryName | null;
+                value: number;
+                total: number;
+                weighted: number;
+            };
             plot: {
                 net_floor: number;
                 land_type: string | CatalogEntryName | null;
@@ -249,26 +255,29 @@ export declare class Apimo {
             bedrooms: number;
             sleeps: number;
             price: {
-                fees: number;
                 value: number;
-                currency: string;
                 max: number;
+                fees: number;
+                unit: unknown;
                 period: string | CatalogEntryName | null;
                 hide: boolean;
                 inventory: number | null;
                 deposit: number | null;
+                currency: string;
                 commission: number | null;
+                transfer_tax: unknown;
+                contribution: unknown;
+                pension: unknown;
                 tenant: number | null;
                 vat: boolean | null;
-                unit?: unknown;
-                transfer_tax?: unknown;
-                contribution?: unknown;
-                pension?: unknown;
             };
+            rates: unknown[];
+            owner: unknown;
+            visit: unknown;
             residence: {
-                fees: number;
                 id: number;
                 type: string | CatalogEntryName | null;
+                fees: number;
                 period: string | CatalogEntryName | null;
                 lots: number;
             } | null;
@@ -277,17 +286,23 @@ export declare class Apimo {
                 landscape: (string | CatalogEntryName | null)[];
             } | null;
             construction: {
-                construction_step: string | CatalogEntryName | null;
                 construction_year: number;
                 renovation_year: number;
                 renovation_cost: number;
+                construction_step: string | CatalogEntryName | null;
                 type?: (string | CatalogEntryName | null)[] | undefined;
             };
-            heating: {
+            floor: {
                 type: string | CatalogEntryName | null;
+                value: number;
+                levels: number;
+                floors: number;
+            };
+            heating: {
                 device: string | CatalogEntryName | null;
                 devices: (string | CatalogEntryName | null)[] | null;
                 access: string | CatalogEntryName | null;
+                type: string | CatalogEntryName | null;
                 types: (string | CatalogEntryName | null)[] | null;
             };
             water: {
@@ -302,22 +317,29 @@ export declare class Apimo {
             };
             twinned: number | null;
             facades: number;
+            length: number | null;
+            height: number | null;
+            url: string | null;
             availability: string | CatalogEntryName | null;
+            available_at: unknown;
             delivered_at: Date | null;
             activities: (string | CatalogEntryName | null)[];
+            orientations: (string | CatalogEntryName | null)[];
             services: (string | CatalogEntryName | null)[];
             proximities: (string | CatalogEntryName | null)[];
+            tags: (string | CatalogEntryName | null)[];
             tags_customized: unknown[];
             pictures: {
                 id: number;
-                url: string;
                 rank: number;
+                url: string;
                 width_max: number;
                 height_max: number;
                 internet: boolean;
                 print: boolean;
                 panorama: boolean;
                 child: number;
+                reference: unknown;
                 comments: {
                     language: string;
                     comment: string;
@@ -326,13 +348,28 @@ export declare class Apimo {
                     hook?: unknown;
                     comment_full?: string | null | undefined;
                 }[];
-                reference?: unknown;
             }[];
             medias: unknown[];
             documents: unknown[];
+            comments: {
+                language: string;
+                comment: string;
+                title?: string | null | undefined;
+                subtitle?: string | null | undefined;
+                hook?: unknown;
+                comment_full?: string | null | undefined;
+            }[];
             areas: {
-                number: number;
                 type: string | CatalogEntryName | null;
+                number: number;
+                area: number;
+                flooring: string | CatalogEntryName | null;
+                ceiling_height: number | null;
+                floor: {
+                    type: string | CatalogEntryName | null;
+                    value: number;
+                };
+                orientations: (string | CatalogEntryName | null)[];
                 comments: {
                     language: string;
                     comment: string;
@@ -341,49 +378,36 @@ export declare class Apimo {
                     hook?: unknown;
                     comment_full?: string | null | undefined;
                 }[];
-                area: number;
-                flooring: string | CatalogEntryName | null;
-                ceiling_height: number | null;
-                floor: {
-                    value: number;
-                    type: string | CatalogEntryName | null;
-                };
-                orientations: (string | CatalogEntryName | null)[];
                 lot: {
+                    type: unknown;
+                    rank: unknown;
                     name: unknown[];
-                    type?: unknown;
-                    rank?: unknown;
                 };
             }[];
             regulations: {
-                value: number[];
                 type: string | CatalogEntryName | null;
+                value: number[];
                 date: Date | null;
                 graph: string | null;
             }[];
             financial: unknown[];
             exchanges: unknown[];
+            options: unknown[];
+            filling_rate: unknown;
+            private_comment: unknown;
+            interagency_comment: unknown;
+            status_comment: unknown;
             logs: unknown[];
             referrals: unknown[];
+            created_at: Date;
+            updated_at: Date;
             created_by: number;
             updated_by: number;
-            referral?: unknown;
-            brand?: unknown;
-            sector?: unknown;
-            ranking?: unknown;
-            original_city?: unknown;
-            original_district?: unknown;
-            location?: unknown;
-            subreferral?: unknown;
-            owner?: unknown;
-            visit?: unknown;
-            available_at?: unknown;
-            filling_rate?: unknown;
-            private_comment?: unknown;
-            interagency_comment?: unknown;
-            status_comment?: unknown;
         }[];
     }>;
+    /** Calculates the delay before the next retry attempt (1-based attempt index). */
+    private retryDelayMs;
+    private sleep;
     private getLocalizedCatalogTransformer;
     private catalogTransformer;
 }

package/dist/core/api.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import Bottleneck from 'bottleneck';
 import { merge } from 'merge-anything';
 import { z } from 'zod';
+import { ApiConfigurationError, ApiResponseValidationError, ApiRetryExhaustedError, isRetryable, throwForStatus, } from '../errors';
 import { getAgencySchema } from '../schemas/agency';
 import { CatalogDefinitionSchema, CatalogEntrySchema } from '../schemas/common';
 import { getPropertySchema } from '../schemas/property';
@@ -30,6 +31,11 @@ export const DEFAULT_ADDITIONAL_CONFIG = {
             active: true,
         },
     },
+    retry: {
+        attempts: 3,
+        initialDelayMs: 200,
+        backoff: 'exponential',
+    },
 };
 export class Apimo {
     constructor(
@@ -41,7 +47,23 @@ export class Apimo {
     config = DEFAULT_ADDITIONAL_CONFIG) {
         this.provider = provider;
         this.token = token;
+        if (!provider || provider.trim() === '') {
+            throw new ApiConfigurationError('provider must be a non-empty string.');
+        }
+        if (!token || token.trim() === '') {
+            throw new ApiConfigurationError('token must be a non-empty string.');
+        }
         this.config = merge(DEFAULT_ADDITIONAL_CONFIG, config);
+        if (!this.config.baseUrl || this.config.baseUrl.trim() === '') {
+            throw new ApiConfigurationError('baseUrl must be a non-empty string.');
+        }
+        try {
+            // eslint-disable-next-line no-new
+            new URL(this.config.baseUrl);
+        }
+        catch (_a) {
+            throw new ApiConfigurationError(`baseUrl "${this.config.baseUrl}" is not a valid URL.`);
+        }
         this.cache = this.config.catalogs.cache.active ? this.config.catalogs.cache.adapter : new DummyCache();
         this.limiter = new Bottleneck({
             reservoir: 10,
@@ -59,11 +81,43 @@ export class Apimo {
     }
     get(path, schema, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const response = yield this.fetch(makeApiUrl(path, this.config, Object.assign({ culture: this.config.culture }, options)));
-            if (!response.ok) {
-                throw new Error(yield response.json());
+            const url = makeApiUrl(path, this.config, Object.assign({ culture: this.config.culture }, options));
+            const { attempts, initialDelayMs, backoff } = this.config.retry;
+            let lastError;
+            for (let attempt = 1; attempt <= attempts; attempt++) {
+                try {
+                    const response = yield this.fetch(url);
+                    if (!response.ok) {
+                        let responseBody;
+                        try {
+                            responseBody = yield response.json();
+                        }
+                        catch (_a) {
+                            // The body wasn't JSON — leave responseBody as undefined
+                        }
+                        throwForStatus(response.status, url.toString(), responseBody);
+                    }
+                    const json = yield response.json();
+                    const result = yield schema.safeParseAsync(json);
+                    if (!result.success) {
+                        throw new ApiResponseValidationError(url.toString(), result.error);
+                    }
+                    return result.data;
+                }
+                catch (error) {
+                    lastError = error;
+                    const hasMoreAttempts = attempt < attempts;
+                    if (!isRetryable(error)) {
+                        // Non-transient errors (4xx, schema failures, etc.) — propagate immediately
+                        throw error;
+                    }
+                    if (!hasMoreAttempts) {
+                        break;
+                    }
+                    yield this.sleep(this.retryDelayMs(attempt, initialDelayMs, backoff));
+                }
             }
-            return schema.parseAsync(yield response.json());
+            throw new ApiRetryExhaustedError(attempts, lastError);
         });
     }
     fetchCatalogs() {
@@ -128,6 +182,17 @@ export class Apimo {
             }), options);
         });
     }
+    /** Calculates the delay before the next retry attempt (1-based attempt index). */
+    retryDelayMs(attempt, initialDelayMs, backoff) {
+        switch (backoff) {
+            case 'exponential': return initialDelayMs * Math.pow(2, (attempt - 1));
+            case 'linear': return initialDelayMs * attempt;
+            case 'fixed': return initialDelayMs;
+        }
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
     getLocalizedCatalogTransformer(culture) {
         return (catalogName, id) => __awaiter(this, void 0, void 0, function* () {
             if (!this.config.catalogs.transform.active) {