apimo.js 1.0.1

package/dist/src/core/api.d.ts

@@ -0,0 +1,389 @@
+import type { CatalogName } from '../consts/catalogs';
+import type { ApiCulture } from '../consts/languages';
+import type { CatalogDefinition, CatalogEntry, CatalogTransformer } from '../schemas/common';
+import type { ApiCacheAdapter, CatalogEntryName } from '../services/storage/types';
+import type { DeepPartial } from '../types';
+import type { ApiSearchParams } from '../utils/url';
+import Bottleneck from 'bottleneck';
+import { z } from 'zod';
+/**
+ * ApiConfig
+ * ---
+ *
+ * The general config, used to create an API wrapper. It exports major endpoints as methods.
+ * Internally, it's a simple wrapper to node:fetch with a neater syntax.
+ */
+export interface AdditionalConfig {
+    baseUrl: string;
+    culture: ApiCulture;
+    catalogs: {
+        cache: {
+            active: boolean;
+            adapter: ApiCacheAdapter;
+        };
+        transform: {
+            active: boolean;
+            transformFn?: CatalogTransformer;
+        };
+    };
+}
+export declare const DEFAULT_BASE_URL = "https://api.apimo.pro";
+export declare const DEFAULT_ADDITIONAL_CONFIG: AdditionalConfig;
+export declare class Api {
+    private readonly provider;
+    private readonly token;
+    readonly config: AdditionalConfig;
+    readonly cache: ApiCacheAdapter;
+    readonly limiter: Bottleneck;
+    constructor(provider: string, token: string, config?: DeepPartial<AdditionalConfig>);
+    /**
+     * An override of fetch that adds the required Authorization header to every request.
+     */
+    fetch(...parameters: Parameters<typeof fetch>): Promise<Response>;
+    get<S extends z.Schema>(path: string[], schema: S, options?: Partial<ApiSearchParams>): Promise<z.infer<S>>;
+    fetchCatalogs(): Promise<CatalogDefinition[]>;
+    populateCache(catalogName: CatalogName, culture: ApiCulture): Promise<void>;
+    populateCache(catalogName: CatalogName, culture: ApiCulture, id: number): Promise<CatalogEntryName | null>;
+    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;
+        agencies: {
+            id: number;
+            name: string;
+            active: boolean;
+            created_at: Date;
+            updated_at: Date;
+            email: string;
+            phone: string;
+            fax: string | null;
+            city: {
+                id: number;
+                name: string;
+                zipcode: string;
+            };
+            picture: string;
+            partners: {
+                name: string | null;
+                type: number;
+                partner: number | null;
+                reference: string;
+                amount: number;
+                currency: string;
+            }[];
+            stories: unknown[];
+            rates: {
+                id: number;
+                category: string | CatalogEntryName | null;
+                range_min: number | null;
+                range_max: number | null;
+                commission_price: number | null;
+                commission_rate: number | null;
+                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;
+            users: {
+                id: number;
+                agency: number;
+                active: boolean;
+                created_at: Date;
+                updated_at: Date;
+                firstname: string;
+                lastname: string;
+                language: string;
+                group: string | CatalogEntryName | null;
+                email: string;
+                phone: string | null;
+                mobile: string;
+                fax: string | null;
+                birthday_at: Date;
+                timezone: string | null;
+                picture: string | null;
+                username?: string | undefined;
+                password?: string | undefined;
+                spoken_languages?: string[] | undefined;
+                city?: {
+                    id: number;
+                    name: string;
+                } | null | undefined;
+                partners?: unknown[] | undefined;
+                stories?: unknown[] | undefined;
+                rates?: unknown;
+            }[];
+            sectors: unknown[];
+            parameters: string;
+            subscription: string;
+            brand?: unknown;
+            district?: unknown;
+        }[];
+        total_items: number;
+    }>;
+    fetchProperties(agencyId: number, options?: Pick<ApiSearchParams, 'culture' | 'limit' | 'offset' | 'timestamp' | 'step' | 'status' | 'group'>): Promise<{
+        timestamp: number;
+        total_items: 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)[];
+            user: {
+                id: number;
+                agency: number;
+                active: boolean;
+                created_at: Date;
+                updated_at: Date;
+                firstname: string;
+                lastname: string;
+                language: string;
+                group: string | CatalogEntryName | null;
+                email: string;
+                phone: string | null;
+                mobile: string;
+                fax: string | null;
+                birthday_at: Date;
+                timezone: string | null;
+                picture: string | null;
+                username?: string | undefined;
+                password?: string | undefined;
+                spoken_languages?: string[] | undefined;
+                city?: {
+                    id: number;
+                    name: string;
+                } | null | undefined;
+                partners?: unknown[] | undefined;
+                stories?: unknown[] | undefined;
+                rates?: unknown;
+            };
+            parent: number | null;
+            subtype: string | CatalogEntryName | null;
+            agreement: {
+                type: string | CatalogEntryName | null;
+                reference: string;
+                start_at: Date;
+                end_at: Date;
+            } | null;
+            block_name: string | null;
+            lot_reference: string | null;
+            cadastre_reference: string | null;
+            stairs_reference: string | null;
+            publish_address: boolean;
+            radius: number;
+            altitude: number;
+            plot: {
+                net_floor: number;
+                land_type: string | CatalogEntryName | null;
+                width: number;
+                serviced_plot: boolean;
+                height?: number | undefined;
+            };
+            rooms: number;
+            bedrooms: number;
+            sleeps: number;
+            price: {
+                fees: number;
+                value: number;
+                currency: string;
+                max: number;
+                period: string | CatalogEntryName | null;
+                hide: boolean;
+                inventory: number | null;
+                deposit: number | null;
+                commission: number | null;
+                tenant: number | null;
+                vat: boolean | null;
+                unit?: unknown;
+                transfer_tax?: unknown;
+                contribution?: unknown;
+                pension?: unknown;
+            };
+            residence: {
+                fees: number;
+                id: number;
+                type: string | CatalogEntryName | null;
+                period: string | CatalogEntryName | null;
+                lots: number;
+            } | null;
+            view: {
+                type: string | CatalogEntryName | null;
+                landscape: (string | CatalogEntryName | null)[];
+            } | null;
+            construction: {
+                construction_step: string | CatalogEntryName | null;
+                construction_year: number;
+                renovation_year: number;
+                renovation_cost: number;
+                type?: (string | CatalogEntryName | null)[] | undefined;
+            };
+            heating: {
+                type: string | CatalogEntryName | null;
+                device: string | CatalogEntryName | null;
+                devices: (string | CatalogEntryName | null)[] | null;
+                access: string | CatalogEntryName | null;
+                types: (string | CatalogEntryName | null)[] | null;
+            };
+            water: {
+                hot_device: string | CatalogEntryName | null;
+                hot_access: string | CatalogEntryName | null;
+                waste: string | CatalogEntryName | null;
+            };
+            condition: string | CatalogEntryName | null;
+            standing: string | CatalogEntryName | null;
+            style: {
+                name: string | null;
+            };
+            twinned: number | null;
+            facades: number;
+            availability: string | CatalogEntryName | null;
+            delivered_at: Date | null;
+            activities: (string | CatalogEntryName | null)[];
+            services: (string | CatalogEntryName | null)[];
+            proximities: (string | CatalogEntryName | null)[];
+            tags_customized: unknown[];
+            pictures: {
+                id: number;
+                url: string;
+                rank: number;
+                width_max: number;
+                height_max: number;
+                internet: boolean;
+                print: boolean;
+                panorama: boolean;
+                child: number;
+                comments: {
+                    language: string;
+                    comment: string;
+                    title?: string | null | undefined;
+                    subtitle?: string | null | undefined;
+                    hook?: unknown;
+                    comment_full?: string | null | undefined;
+                }[];
+                reference?: unknown;
+            }[];
+            medias: unknown[];
+            documents: unknown[];
+            areas: {
+                number: number;
+                type: string | CatalogEntryName | null;
+                comments: {
+                    language: string;
+                    comment: string;
+                    title?: string | null | undefined;
+                    subtitle?: string | null | undefined;
+                    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: {
+                    name: unknown[];
+                    type?: unknown;
+                    rank?: unknown;
+                };
+            }[];
+            regulations: {
+                value: number[];
+                type: string | CatalogEntryName | null;
+                date: Date | null;
+                graph: string | null;
+            }[];
+            financial: unknown[];
+            exchanges: unknown[];
+            logs: unknown[];
+            referrals: unknown[];
+            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;
+        }[];
+    }>;
+    private getLocalizedCatalogTransformer;
+    private catalogTransformer;
+}

package/dist/src/core/api.js

@@ -0,0 +1,157 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import Bottleneck from 'bottleneck';
+import { merge } from 'merge-anything';
+import { z } from 'zod';
+import { getAgencySchema } from '../schemas/agency';
+import { CatalogDefinitionSchema, CatalogEntrySchema } from '../schemas/common';
+import { getPropertySchema } from '../schemas/property';
+import { DummyCache } from '../services/storage/dummy.cache';
+import { MemoryCache } from '../services/storage/memory.cache';
+import { CacheExpiredError } from '../services/storage/types';
+import { makeApiUrl } from '../utils/url';
+export const DEFAULT_BASE_URL = 'https://api.apimo.pro';
+export const DEFAULT_ADDITIONAL_CONFIG = {
+    baseUrl: DEFAULT_BASE_URL,
+    culture: 'en',
+    catalogs: {
+        cache: {
+            active: true,
+            adapter: new MemoryCache(),
+        },
+        transform: {
+            active: true,
+        },
+    },
+};
+export class Api {
+    constructor(
+    // The site identifier, in a string of numbers format. You can request yours by contacting Apimo.net customer service.
+    provider, 
+    // The secret token for API authentication
+    token, 
+    // Additional config, to tweak how the API is handled
+    config = DEFAULT_ADDITIONAL_CONFIG) {
+        this.provider = provider;
+        this.token = token;
+        this.config = merge(DEFAULT_ADDITIONAL_CONFIG, config);
+        this.cache = this.config.catalogs.cache.active ? this.config.catalogs.cache.adapter : new DummyCache();
+        this.limiter = new Bottleneck({
+            reservoir: 10,
+            reservoirRefreshAmount: 10,
+            reservoirRefreshInterval: 1000,
+        });
+    }
+    /**
+     * An override of fetch that adds the required Authorization header to every request.
+     */
+    fetch(...parameters) {
+        const [input, init] = parameters;
+        const extendedInit = Object.assign(Object.assign({}, init), { headers: Object.assign({ Authorization: `Basic ${btoa(`${this.provider}:${this.token}`)}` }, init === null || init === void 0 ? void 0 : init.headers) });
+        return this.limiter.schedule(() => fetch(input, extendedInit));
+    }
+    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());
+            }
+            return schema.parseAsync(yield response.json());
+        });
+    }
+    fetchCatalogs() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.get(['catalogs'], z.array(CatalogDefinitionSchema));
+        });
+    }
+    populateCache(catalogName, culture, id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const catalog = yield this.fetchCatalog(catalogName, { culture });
+            yield this.cache.setEntries(catalogName, culture, catalog);
+            if (id !== undefined) {
+                const queriedKey = catalog.find(({ id: entryId }) => entryId === id);
+                return queriedKey
+                    ? {
+                        name: queriedKey.name,
+                        namePlural: queriedKey.name_plurial,
+                    }
+                    : null;
+            }
+        });
+    }
+    getCatalogEntries(catalogName, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            try {
+                return yield this.cache.getEntries(catalogName, (_a = options === null || options === void 0 ? void 0 : options.culture) !== null && _a !== void 0 ? _a : this.config.culture);
+            }
+            catch (e) {
+                if (e instanceof CacheExpiredError) {
+                    yield this.populateCache(catalogName, (_b = options === null || options === void 0 ? void 0 : options.culture) !== null && _b !== void 0 ? _b : this.config.culture);
+                    return this.cache.getEntries(catalogName, (_c = options === null || options === void 0 ? void 0 : options.culture) !== null && _c !== void 0 ? _c : this.config.culture);
+                }
+                else {
+                    throw e;
+                }
+            }
+        });
+    }
+    fetchCatalog(catalogName, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.get(['catalogs', catalogName], z.array(CatalogEntrySchema), options);
+        });
+    }
+    fetchAgencies(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            return this.get(['agencies'], z.object({
+                total_items: z.number(),
+                agencies: getAgencySchema(this.getLocalizedCatalogTransformer((_a = options === null || options === void 0 ? void 0 : options.culture) !== null && _a !== void 0 ? _a : this.config.culture), this.config).array(),
+                timestamp: z.number(),
+            }));
+        });
+    }
+    fetchProperties(agencyId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            return this.get(['agencies', agencyId.toString(), 'properties'], z.object({
+                total_items: z.number(),
+                timestamp: z.number(),
+                properties: getPropertySchema(this.getLocalizedCatalogTransformer((_a = options === null || options === void 0 ? void 0 : options.culture) !== null && _a !== void 0 ? _a : this.config.culture)).array(),
+            }), options);
+        });
+    }
+    getLocalizedCatalogTransformer(culture) {
+        return (catalogName, id) => __awaiter(this, void 0, void 0, function* () {
+            if (!this.config.catalogs.transform.active) {
+                return `${catalogName}.${id}`;
+            }
+            if (this.config.catalogs.transform.transformFn) {
+                return this.config.catalogs.transform.transformFn(catalogName, culture, id);
+            }
+            return this.catalogTransformer(catalogName, culture, id);
+        });
+    }
+    catalogTransformer(catalogName, culture, id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield this.cache.getEntry(catalogName, culture, id);
+            }
+            catch (e) {
+                if (e instanceof CacheExpiredError) {
+                    return yield this.populateCache(catalogName, culture, id);
+                }
+                else {
+                    throw e;
+                }
+            }
+        });
+    }
+}

package/dist/src/core/api.test.d.ts

@@ -0,0 +1 @@
+export {};