apimo.js 1.0.3 → 1.0.5

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Vitaly Lysen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -4,17 +4,19 @@
 [![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)
 
-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.
+A TypeScript-first wrapper for the [Apimo API](https://apimo.net/en/api/webservice/) with intelligent caching, automatic retries, rate limiting, and catalog transformation for building custom real estate websites.
+
+> **Note:** This library is in active development. No breaking changes are planned, but please pin your version in production.
 
 ## 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%
+- 🔷 **TypeScript-first** — Full type safety with Zod schema validation on every response
+- 📦 **Smart caching** — Memory, Filesystem, and Dummy cache adapters with automatic TTL invalidation
+- 🔁 **Automatic retries** — Configurable retry strategy (exponential / linear / fixed back-off) for transient failures
+- 🚦 **Rate limiting** — Built-in Bottleneck throttle to stay within Apimo's API limits
+- 🌍 **Multi-language** — First-class `culture` support for all endpoints and catalog lookups
+- 🏗️ **Full coverage** — Properties, agencies, and catalog endpoints
+- 🐛 **Developer-friendly errors** — Typed error classes with status codes, request URLs, and response bodies
 
 ## Installation
 
@@ -27,153 +29,123 @@ yarn add apimo.js
 ## Quick Start
 
 ```typescript
-import { Apimo } from 'apimo.js'
+import { Apimo, MemoryCache } from 'apimo.js'
 
 const api = new Apimo(
-  'YOUR_BRIDGE_ID', // Get from Apimo support
-  'YOUR_API_TOKEN', // Get from Apimo support
+  'YOUR_PROVIDER_ID', // Numeric string — request from Apimo support
+  'YOUR_API_TOKEN', // Secret token — request from Apimo support
   {
-    culture: 'en', // Default language
+    culture: 'en',
     catalogs: {
-      cache: {
-        active: true,
-        adapter: new MemoryCache() // or FilesystemCache()
-      }
-    }
-  }
+      cache: { active: true, adapter: new MemoryCache() },
+    },
+  },
 )
 
-// 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()
+const { properties } = await api.fetchProperties(agencyId)
+const { agencies } = await api.fetchAgencies()
 ```
 
 ## Configuration
 
-### Basic Configuration
+### Full Config Reference
 
 ```typescript
-const api = new Apimo(bridgeId, token, {
-  baseUrl: 'https://api.apimo.pro', // API base URL
-  culture: 'en', // Default language (en, fr)
+const api = new Apimo(providerId, token, {
+  // Base URL for API requests. Default: 'https://api.apimo.pro'
+  baseUrl: 'https://api.apimo.pro',
+
+  // Default language for all requests. Default: 'en'
+  culture: 'en',
+
   catalogs: {
     cache: {
-      active: true, // Enable catalog caching
-      adapter: new MemoryCache() // Cache implementation
+      // Enable catalog caching. Default: true
+      active: true,
+      // Cache implementation. Default: new MemoryCache()
+      adapter: new MemoryCache(),
     },
     transform: {
-      active: true, // Enable catalog transformation
-      transformFn: customTransformer // Optional custom transformer
-    }
-  }
+      // Resolve catalog IDs to human-readable names. Default: true
+      active: true,
+      // Optionally supply your own resolver function
+      transformFn: async (catalogName, culture, id) => { /* ... */ },
+    },
+  },
+
+  retry: {
+    // Total number of attempts (1 = no retries). Default: 3
+    attempts: 3,
+    // Delay in ms before the first retry. Default: 200
+    initialDelayMs: 200,
+    // Back-off strategy: 'exponential' | 'linear' | 'fixed'. Default: 'exponential'
+    backoff: 'exponential',
+  },
 })
 ```
 
 ### Cache Adapters
 
-#### Memory Cache (Default)
+#### MemoryCache *(default)*
+
+Stores catalog entries in process memory. Fast and zero-config. Data is lost when the process restarts.
 
 ```typescript
 import { MemoryCache } from 'apimo.js'
 
-const api = new Apimo(bridgeId, token, {
-  catalogs: {
-    cache: {
-      adapter: new MemoryCache()
-    }
-  }
-})
+const memoryCache = new MemoryCache({ cacheExpirationMs: 7 * 24 * 60 * 60 * 1000 }) // default: 1 week
 ```
 
-#### Filesystem Cache
+#### FilesystemCache
+
+Persists catalog entries to JSON files on disk. Survives restarts.
 
 ```typescript
 import { FilesystemCache } from 'apimo.js'
 
-const api = new Apimo(bridgeId, token, {
-  catalogs: {
-    cache: {
-      adapter: new FilesystemCache('./cache')
-    }
-  }
+const fsCache = new FilesystemCache({
+  path: './cache/catalogs', // default
+  cacheExpirationMs: 7 * 24 * 60 * 60 * 1000,
 })
 ```
 
-#### Dummy Cache (No Caching)
+#### DummyCache
+
+Disables caching entirely. Every catalog look-up hits the API directly.
 
 ```typescript
 import { DummyCache } from 'apimo.js'
 
-const api = new Apimo(bridgeId, token, {
-  catalogs: {
-    cache: {
-      adapter: new DummyCache()
-    }
-  }
-})
+const dummyCache = new DummyCache()
 ```
 
 ## API Reference
 
 ### Properties
 
-#### `getProperties(options?)`
-
-Fetch a list of properties with optional filtering.
+#### `fetchProperties(agencyId, options?)`
 
 ```typescript
-const properties = await api.getProperties({
+const { total_items, properties, timestamp } = await api.fetchProperties(agencyId, {
+  culture: 'fr',
   limit: 20,
   offset: 0,
-  culture: 'fr',
-  // Add property filters as needed
-})
-```
-
-#### `getProperty(id, options?)`
-
-Fetch a specific property by ID.
-
-```typescript
-const property = await api.getProperty(123, {
-  culture: 'en'
 })
 ```
 
 ### Agencies
 
-#### `getAgencies(options?)`
-
-Fetch a list of agencies.
-
-```typescript
-const agencies = await api.getAgencies({
-  limit: 10,
-  culture: 'fr'
-})
-```
-
-#### `getAgency(id, options?)`
-
-Fetch a specific agency by ID.
+#### `fetchAgencies(options?)`
 
 ```typescript
-const agency = await api.getAgency(456)
+const { total_items, agencies } = await api.fetchAgencies({ limit: 10 })
 ```
 
 ### Catalogs
 
 #### `fetchCatalogs()`
 
-Get all available catalog definitions.
+Returns the list of all available catalog definitions.
 
 ```typescript
 const catalogs = await api.fetchCatalogs()
@@ -181,140 +153,153 @@ const catalogs = await api.fetchCatalogs()
 
 #### `fetchCatalog(catalogName, options?)`
 
-Fetch entries for a specific catalog.
+Fetches raw entries for a specific catalog.
 
 ```typescript
-const propertyTypes = await api.fetchCatalog('property_type', {
-  culture: 'en'
-})
+const entries = await api.fetchCatalog('property_type', { culture: 'en' })
 ```
 
 #### `getCatalogEntries(catalogName, options?)`
 
-Get catalog entries from cache (populates cache if needed).
+Returns catalog entries, automatically populating the cache when empty or expired.
 
 ```typescript
-const entries = await api.getCatalogEntries('property_category', {
-  culture: 'fr'
-})
+const entries = await api.getCatalogEntries('property_category', { culture: 'fr' })
 ```
 
 ### Low-level API
 
 #### `get(path, schema, options?)`
 
-Make a direct API call with schema validation.
+Makes a direct API call with Zod schema validation. Retries are applied automatically.
 
 ```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
-})
+const result = await api.get(
+  ['agencies', '123', 'properties'],
+  z.object({ total_items: z.number() }),
+  { 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:
+Raw authenticated fetch — adds the `Authorization` header and runs through the rate limiter. Use when you need full control.
 
 ```typescript
-// Raw API response
-const rawResponse = {
-  type: 1,
-  category: 2
-}
-
-// Transformed response
-const transformedResponse = {
-  type: 'House',
-  category: 'Sale'
-}
+const response = await api.fetch('https://api.apimo.pro/catalogs')
 ```
 
-### Custom Transformers
+## Error Handling
 
-```typescript
-async function customTransformer(catalogName, culture, id) {
-  // Your custom transformation logic
-  return await myCustomCatalogLookup(catalogName, culture, id)
-}
+All errors thrown by the library extend `ApimoError`, so you can catch them selectively.
 
-const api = new Apimo(bridgeId, token, {
-  catalogs: {
-    transform: {
-      active: true,
-      transformFn: customTransformer
-    }
-  }
-})
-```
+### Error Hierarchy
 
-## Rate Limiting
+| Class | When thrown |
+|---|---|
+| `ApimoError` | Base class — catch-all |
+| `ApiHttpError` | Any non-2xx HTTP response — has `.statusCode`, `.url`, `.responseBody` |
+| `ApiBadRequestError` | HTTP 400 — malformed request |
+| `ApiUnauthorizedError` | HTTP 401 — invalid credentials |
+| `ApiForbiddenError` | HTTP 403 — insufficient permissions |
+| `ApiNotFoundError` | HTTP 404 — resource does not exist |
+| `ApiRateLimitError` | HTTP 429 — rate limit exceeded |
+| `ApiServerError` | HTTP 5xx — Apimo server-side failure |
+| `ApiResponseValidationError` | Response body doesn't match expected schema — has `.url`, `.zodError` |
+| `ApiConfigurationError` | Invalid constructor arguments (empty credentials, bad `baseUrl`) |
+| `ApiRetryExhaustedError` | All retry attempts failed — has `.attempts`, `.cause` |
 
-The library includes built-in rate limiting to respect Apimo's API limits:
+### Retry behaviour
 
-- **10 requests per second** (configurable)
-- **Automatic queuing** of excess requests
-- **Bottleneck integration** for advanced rate limiting scenarios
+Retries are applied automatically to **transient** errors (429, 5xx, network failures). **Non-transient** errors (4xx except 429, schema validation failures) are thrown immediately without retrying.
 
-## Error Handling
+When all attempts are exhausted, `ApiRetryExhaustedError` is thrown. Its `.cause` property holds the underlying error from the last attempt.
 
 ```typescript
+import {
+  ApimoError,
+  ApiResponseValidationError,
+  ApiRetryExhaustedError,
+  ApiServerError,
+  ApiUnauthorizedError,
+  CacheExpiredError,
+} from 'apimo.js'
+
 try {
-  const properties = await api.getProperties()
+  const { properties } = await api.fetchProperties(agencyId)
 }
 catch (error) {
-  if (error instanceof CacheExpiredError) {
-    // Handle cache expiration
+  if (error instanceof ApiUnauthorizedError) {
+    // Credentials are wrong — fail fast, no retry
+    console.error('Check your provider ID and token.')
+  }
+  else if (error instanceof ApiRetryExhaustedError) {
+    // Transient failure survived all retries
+    console.error(`Failed after ${error.attempts} attempts.`, error.cause)
   }
-  else {
-    // Handle other API errors
-    console.error('API Error:', error.message)
+  else if (error instanceof ApiResponseValidationError) {
+    // The API changed its response shape
+    console.error('Schema mismatch:', error.zodError.format())
+  }
+  else if (error instanceof ApimoError) {
+    // Any other library error
+    console.error(error.message)
   }
 }
 ```
 
-## TypeScript Support
+### Disabling retries
+
+```typescript
+const api = new Apimo(providerId, token, {
+  retry: { attempts: 1 }, // 1 attempt = no retries
+})
+```
+
+## Data Transformation
 
-Full TypeScript support with comprehensive type definitions:
+When `catalogs.transform.active` is `true` (the default), numeric catalog IDs in API responses are automatically resolved to their human-readable names via the cache.
 
 ```typescript
-import type { Agency, CatalogEntry, Property } from 'apimo.js'
+// Without transformation:   { type: 1, category: 6 }
+// With transformation:       { type: 'House', category: 'Sale' }
+```
+
+### Custom transformer
 
-const property: Property = await api.getProperty(123)
-const agency: Agency = await api.getAgency(456)
+```typescript
+const api = new Apimo(providerId, token, {
+  catalogs: {
+    transform: {
+      active: true,
+      transformFn: async (catalogName, culture, id) => {
+        return await myDatabase.lookupCatalog(catalogName, culture, id)
+      },
+    },
+  },
+})
 ```
 
-## Supported Languages
+## Rate Limiting
 
-- English (`en`)
-- French (`fr`)
+The library uses [Bottleneck](https://github.com/SGrondin/bottleneck) internally to throttle requests to **10 per second** — well within Apimo's documented daily limits. No extra configuration is required.
 
-More languages can be added based on Apimo API support.
+## TypeScript
 
-## Contributing
+All public methods and types are fully typed. Import what you need:
 
-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
+```typescript
+import type {
+  AdditionalConfig,
+  ApimoAgency,
+  ApimoProperty,
+  CatalogEntry,
+} from 'apimo.js'
+```
 
-### Development
+## Development
 
 ```bash
 # Install dependencies
@@ -326,25 +311,26 @@ yarn test
 # Run tests with coverage
 yarn test-coverage
 
-# Run linting
+# Lint
 yarn lint
 
-# Build the package
+# Build
 yarn build
 ```
 
-## License
+## Getting API Credentials
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+You need two things to use this library:
 
-## Getting API Credentials
+1. **Provider ID** — a numeric string identifying your site
+2. **API Token** — your secret authentication token
 
-To use this library, you need:
+Request both by contacting [Apimo customer service](https://apimo.net/en/contact/).
 
-1. **Bridge ID** - Your site identifier (string of numbers)
-2. **API Token** - Secret token for authentication
+## Roadmap
 
-Contact [Apimo customer service](https://apimo.net/en/contact/) to request your credentials.
+- [ ] Minified production build
+- [ ] Complete JSDoc coverage for all public methods
 
 ## Support
 
@@ -352,6 +338,10 @@ Contact [Apimo customer service](https://apimo.net/en/contact/) to request your
 - 🐛 [Issue Tracker](https://github.com/Neikow/apimo.js/issues)
 - 💬 [Discussions](https://github.com/Neikow/apimo.js/discussions)
 
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
 ---
 
 Made with ❤️ by [Vitaly Lysen](https://lysen.dev)