apimo.js 1.0.1 → 1.0.3

package/README.md

@@ -1,91 +1,357 @@
 # Apimo.js
 
-Apimo.js is a Node.js module for interacting with the Apimo API.
+[![npm version](https://badge.fury.io/js/apimo.js.svg)](https://badge.fury.io/js/apimo.js)
+[![CI](https://github.com/Neikow/apimo.js/actions/workflows/ci.yml/badge.svg)](https://github.com/Neikow/apimo.js/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Neikow/apimo.js/branch/main/graph/badge.svg)](https://codecov.io/gh/Neikow/apimo.js)
 
-## Usage
+A comprehensive TypeScript wrapper for the [Apimo API](https://apimo.net/en/api/webservice/) with intelligent caching,
+rate limiting, and automatic catalog transformation for building custom Real Estate websites.
 
-```javascript
-const Apimo = require('apimo.js/dist')
+## Features
+
+- 🚀 **TypeScript-first** - Full type safety with Zod schema validation
+- 📦 **Smart Caching** - Multiple cache adapters (Memory, Filesystem, Dummy) with automatic invalidation
+- 🔄 **Rate Limiting** - Built-in request throttling to respect API limits (1000 requests/day)
+- 🌍 **Multi-language Support** - Automatic catalog transformation for localized content
+- 🏗️ **Property & Agency APIs** - Complete coverage of Apimo's real estate endpoints
+- ⚡ **Optimized Performance** - Intelligent catalog caching reduces API calls by 90%
+
+## Installation
+
+```bash
+npm install apimo.js
+# or
+yarn add apimo.js
+```
+
+## Quick Start
+
+```typescript
+import { Apimo } from 'apimo.js'
 
 const api = new Apimo(
-  '<BRIDGE_ID>',
-  '<API_TOKEN>',
+  'YOUR_BRIDGE_ID', // Get from Apimo support
+  'YOUR_API_TOKEN', // Get from Apimo support
   {
-    debug: true,
-    cultures: [
-      'fr_FR',
-      'en_GB',
-    ],
-    updateIntervals: {
-      properties: 1000 * 60 * 5, // 5 minutes
-      catalogs: 1000 * 60 * 60 * 24, // 24 hours
+    culture: 'en', // Default language
+    catalogs: {
+      cache: {
+        active: true,
+        adapter: new MemoryCache() // or FilesystemCache()
+      }
     }
   }
 )
+
+// Fetch properties with automatic catalog transformation
+const properties = await api.getProperties({
+  limit: 10,
+  offset: 0
+})
+
+// Get a specific property
+const property = await api.getProperty(123)
+
+// Fetch agencies
+const agencies = await api.getAgencies()
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+const api = new Apimo(bridgeId, token, {
+  baseUrl: 'https://api.apimo.pro', // API base URL
+  culture: 'en', // Default language (en, fr)
+  catalogs: {
+    cache: {
+      active: true, // Enable catalog caching
+      adapter: new MemoryCache() // Cache implementation
+    },
+    transform: {
+      active: true, // Enable catalog transformation
+      transformFn: customTransformer // Optional custom transformer
+    }
+  }
+})
+```
+
+### Cache Adapters
+
+#### Memory Cache (Default)
+
+```typescript
+import { MemoryCache } from 'apimo.js'
+
+const api = new Apimo(bridgeId, token, {
+  catalogs: {
+    cache: {
+      adapter: new MemoryCache()
+    }
+  }
+})
 ```
 
-The `BRIDGE_ID` and `API_TOKEN` can be asked on the support page of Apimo.
+#### Filesystem Cache
 
-## API
+```typescript
+import { FilesystemCache } from 'apimo.js'
 
-The API endpoints are described on the [Apimo API documentation](https://apimo.net/en/api/webservice/).
+const api = new Apimo(bridgeId, token, {
+  catalogs: {
+    cache: {
+      adapter: new FilesystemCache('./cache')
+    }
+  }
+})
+```
 
-## Wrapper
+#### Dummy Cache (No Caching)
+
+```typescript
+import { DummyCache } from 'apimo.js'
+
+const api = new Apimo(bridgeId, token, {
+  catalogs: {
+    cache: {
+      adapter: new DummyCache()
+    }
+  }
+})
+```
 
-The wrapper is a set of methods that will help you to interact with the API.
-It can cache requests in order to avoid reaching the API rate limit, which are pretty low (1000 requests per day).
-The data can be set to be updated automatically, given a certain interval.
+## API Reference
 
-## Methods
+### Properties
 
-### `get`
+#### `getProperties(options?)`
 
-Helper method to get a property from the API.
+Fetch a list of properties with optional filtering.
 
-```javascript
-api.get(['properties', 123]).then((property) => {
-  console.log(property) // == Property(id: 123, ...)
+```typescript
+const properties = await api.getProperties({
+  limit: 20,
+  offset: 0,
+  culture: 'fr',
+  // Add property filters as needed
 })
 ```
 
-### `getProperties`
+#### `getProperty(id, options?)`
 
-Get all properties from the API.
+Fetch a specific property by ID.
 
-```javascript
-api.fetchProperties().then((properties) => {
-  console.log(properties) // [Property(...), Property(...), ...]
+```typescript
+const property = await api.getProperty(123, {
+  culture: 'en'
 })
 ```
 
-A `Property` is the data of a property, as stored in the Apimo API, it is described in
-the [Apimo API documentation](https://apimo.net/en/api/webservice/?child=agencies/properties#get-agencies/propertiesagencies-{agency_id}-properties).
+### Agencies
 
-### `getAgencies`
+#### `getAgencies(options?)`
 
-Returns the agencies linked to the bridge.
+Fetch a list of agencies.
 
-```javascript
-api.fetchAgencies().then((agencies) => {
-  console.log(agencies) // [Agency(...), Agency(...), ...]
+```typescript
+const agencies = await api.getAgencies({
+  limit: 10,
+  culture: 'fr'
 })
 ```
 
-An `Agency` is the data of an agency, as stored in the Apimo API, it is described in
-the [Apimo API documentation](https://apimo.net/en/api/webservice/?child=agencies#get-agenciesagencies).
+#### `getAgency(id, options?)`
+
+Fetch a specific agency by ID.
+
+```typescript
+const agency = await api.getAgency(456)
+```
+
+### Catalogs
 
-### `convertDate`
+#### `fetchCatalogs()`
 
-Converts a Apimo date to a `Date` object.
+Get all available catalog definitions.
 
-```javascript
-api.convertDate('2018-01-01').then((date) => {
-  console.log(date) // == Date(2018, 0, 1)
+```typescript
+const catalogs = await api.fetchCatalogs()
+```
+
+#### `fetchCatalog(catalogName, options?)`
+
+Fetch entries for a specific catalog.
+
+```typescript
+const propertyTypes = await api.fetchCatalog('property_type', {
+  culture: 'en'
 })
 ```
 
-## Installation
+#### `getCatalogEntries(catalogName, options?)`
+
+Get catalog entries from cache (populates cache if needed).
+
+```typescript
+const entries = await api.getCatalogEntries('property_category', {
+  culture: 'fr'
+})
+```
+
+### Low-level API
+
+#### `get(path, schema, options?)`
+
+Make a direct API call with schema validation.
+
+```typescript
+import { z } from 'zod'
+
+const customSchema = z.object({
+  id: z.number(),
+  name: z.string()
+})
+
+const result = await api.get(['custom', 'endpoint'], customSchema, {
+  culture: 'en',
+  limit: 10
+})
+```
+
+#### `fetch(...args)`
+
+Direct fetch with automatic authentication headers.
+
+```typescript
+const response = await api.fetch('https://api.apimo.pro/properties')
+```
+
+## Data Transformation
+
+Apimo.js automatically transforms catalog IDs into human-readable names:
+
+```typescript
+// Raw API response
+const rawResponse = {
+  type: 1,
+  category: 2
+}
+
+// Transformed response
+const transformedResponse = {
+  type: 'House',
+  category: 'Sale'
+}
+```
+
+### Custom Transformers
+
+```typescript
+async function customTransformer(catalogName, culture, id) {
+  // Your custom transformation logic
+  return await myCustomCatalogLookup(catalogName, culture, id)
+}
+
+const api = new Apimo(bridgeId, token, {
+  catalogs: {
+    transform: {
+      active: true,
+      transformFn: customTransformer
+    }
+  }
+})
+```
+
+## Rate Limiting
+
+The library includes built-in rate limiting to respect Apimo's API limits:
+
+- **10 requests per second** (configurable)
+- **Automatic queuing** of excess requests
+- **Bottleneck integration** for advanced rate limiting scenarios
+
+## Error Handling
+
+```typescript
+try {
+  const properties = await api.getProperties()
+}
+catch (error) {
+  if (error instanceof CacheExpiredError) {
+    // Handle cache expiration
+  }
+  else {
+    // Handle other API errors
+    console.error('API Error:', error.message)
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import type { Agency, CatalogEntry, Property } from 'apimo.js'
+
+const property: Property = await api.getProperty(123)
+const agency: Agency = await api.getAgency(456)
+```
+
+## Supported Languages
+
+- English (`en`)
+- French (`fr`)
+
+More languages can be added based on Apimo API support.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development
 
 ```bash
-npm install github:Neikow/apimo.js
+# Install dependencies
+yarn install
+
+# Run tests
+yarn test
+
+# Run tests with coverage
+yarn test-coverage
+
+# Run linting
+yarn lint
+
+# Build the package
+yarn build
 ```
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Getting API Credentials
+
+To use this library, you need:
+
+1. **Bridge ID** - Your site identifier (string of numbers)
+2. **API Token** - Secret token for authentication
+
+Contact [Apimo customer service](https://apimo.net/en/contact/) to request your credentials.
+
+## Support
+
+- 📖 [Apimo API Documentation](https://apimo.net/en/api/webservice/)
+- 🐛 [Issue Tracker](https://github.com/Neikow/apimo.js/issues)
+- 💬 [Discussions](https://github.com/Neikow/apimo.js/discussions)
+
+---
+
+Made with ❤️ by [Vitaly Lysen](https://lysen.dev)

package/dist/{src/core → core}/api.d.ts

@@ -29,7 +29,7 @@ export interface AdditionalConfig {
 }
 export declare const DEFAULT_BASE_URL = "https://api.apimo.pro";
 export declare const DEFAULT_ADDITIONAL_CONFIG: AdditionalConfig;
-export declare class Api {
+export declare class Apimo {
     private readonly provider;
     private readonly token;
     readonly config: AdditionalConfig;

package/dist/{src/core → core}/api.js

@@ -31,7 +31,7 @@ export const DEFAULT_ADDITIONAL_CONFIG = {
         },
     },
 };
-export class Api {
+export class Apimo {
     constructor(
     // The site identifier, in a string of numbers format. You can request yours by contacting Apimo.net customer service.
     provider, 

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { CatalogName } from './consts/catalogs';
+export type { ApiCulture } from './consts/languages';
+export { type AdditionalConfig, Apimo, DEFAULT_ADDITIONAL_CONFIG, DEFAULT_BASE_URL } from './core/api';
+export { Apimo as Api } from './core/api';
+export type { CatalogDefinition, CatalogEntry, CatalogTransformer, LocalizedCatalogTransformer } from './schemas/common';
+export { DummyCache } from './services/storage/dummy.cache';
+export { FilesystemCache } from './services/storage/filesystem.cache';
+export { MemoryCache } from './services/storage/memory.cache';
+export { type ApiCacheAdapter, CacheExpiredError, type CatalogEntryName } from './services/storage/types';
+export type { DeepPartial } from './types';
+export type { ApiSearchParams } from './utils/url';

package/dist/index.js

@@ -0,0 +1,10 @@
+// Main exports
+export { Apimo, DEFAULT_ADDITIONAL_CONFIG, DEFAULT_BASE_URL } from './core/api';
+// Backward compatibility - keep Api as alias
+export { Apimo as Api } from './core/api';
+export { DummyCache } from './services/storage/dummy.cache';
+export { FilesystemCache } from './services/storage/filesystem.cache';
+// Cache adapters
+export { MemoryCache } from './services/storage/memory.cache';
+// Cache types and errors
+export { CacheExpiredError } from './services/storage/types';

package/dist/{src/schemas → schemas}/agency.d.ts

@@ -3,7 +3,7 @@ import type { LocalizedCatalogTransformer } from './common';
 import { z } from 'zod';
 export declare function getRateSchema(transformer: LocalizedCatalogTransformer): z.ZodObject<{
     id: z.ZodNumber;
-    category: z.ZodEffects<z.ZodNumber, string | import("../services/storage/types").CatalogEntryName | null, number>;
+    category: z.ZodEffects<z.ZodNumber, string | import("..").CatalogEntryName | null, number>;
     range_min: z.ZodNullable<z.ZodNumber>;
     range_max: z.ZodNullable<z.ZodNumber>;
     commission_price: z.ZodNullable<z.ZodNumber>;
@@ -12,7 +12,7 @@ export declare function getRateSchema(transformer: LocalizedCatalogTransformer):
     url: z.ZodNullable<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     id: number;
-    category: string | import("../services/storage/types").CatalogEntryName | null;
+    category: string | import("..").CatalogEntryName | null;
     range_min: number | null;
     range_max: number | null;
     commission_price: number | null;
@@ -103,7 +103,7 @@ export declare function getAgencySchema(transformer: LocalizedCatalogTransformer
     providers: z.ZodEffects<z.ZodString, string, string>;
     rates: z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
-        category: z.ZodEffects<z.ZodNumber, string | import("../services/storage/types").CatalogEntryName | null, number>;
+        category: z.ZodEffects<z.ZodNumber, string | import("..").CatalogEntryName | null, number>;
         range_min: z.ZodNullable<z.ZodNumber>;
         range_max: z.ZodNullable<z.ZodNumber>;
         commission_price: z.ZodNullable<z.ZodNumber>;
@@ -112,7 +112,7 @@ export declare function getAgencySchema(transformer: LocalizedCatalogTransformer
         url: z.ZodNullable<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         id: number;
-        category: string | import("../services/storage/types").CatalogEntryName | null;
+        category: string | import("..").CatalogEntryName | null;
         range_min: number | null;
         range_max: number | null;
         commission_price: number | null;
@@ -164,7 +164,7 @@ export declare function getAgencySchema(transformer: LocalizedCatalogTransformer
         password: z.ZodOptional<z.ZodString>;
         language: z.ZodString;
         spoken_languages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        group: z.ZodEffects<z.ZodNumber, string | import("../services/storage/types").CatalogEntryName | null, number>;
+        group: z.ZodEffects<z.ZodNumber, string | import("..").CatalogEntryName | null, number>;
         email: z.ZodString;
         phone: z.ZodNullable<z.ZodString>;
         mobile: z.ZodString;
@@ -194,7 +194,7 @@ export declare function getAgencySchema(transformer: LocalizedCatalogTransformer
         firstname: string;
         lastname: string;
         language: string;
-        group: string | import("../services/storage/types").CatalogEntryName | null;
+        group: string | import("..").CatalogEntryName | null;
         email: string;
         phone: string | null;
         mobile: string;
@@ -269,7 +269,7 @@ export declare function getAgencySchema(transformer: LocalizedCatalogTransformer
     stories: unknown[];
     rates: {
         id: number;
-        category: string | import("../services/storage/types").CatalogEntryName | null;
+        category: string | import("..").CatalogEntryName | null;
         range_min: number | null;
         range_max: number | null;
         commission_price: number | null;
@@ -304,7 +304,7 @@ export declare function getAgencySchema(transformer: LocalizedCatalogTransformer
         firstname: string;
         lastname: string;
         language: string;
-        group: string | import("../services/storage/types").CatalogEntryName | null;
+        group: string | import("..").CatalogEntryName | null;
         email: string;
         phone: string | null;
         mobile: string;