apimo.js 1.0.1

package/src/core/api.test.ts

@@ -0,0 +1,308 @@
+import type { MockedFunction } from 'vitest'
+import type { CatalogName } from '../consts/catalogs'
+import type { ApiCulture } from '../consts/languages'
+import { afterEach, beforeEach, it as defaultIt, describe, expect, vi } from 'vitest'
+import { z } from 'zod'
+import { DummyCache } from '../services/storage/dummy.cache'
+import { MemoryCache } from '../services/storage/memory.cache'
+import { Api, DEFAULT_BASE_URL } from './api'
+
+// Mock fetch globally
+const mockFetch = vi.fn() as MockedFunction<typeof fetch>
+
+interface ResponseMockerConfig {
+  ok?: boolean
+  status?: number
+  json?: () => any
+}
+
+type ResponseMocker = (config?: ResponseMockerConfig) => void
+
+const PROVIDER = '0'
+const TOKEN = 'TOKEN'
+
+const BasicAuthHeaders = {
+  Authorization: `Basic ${btoa(`${PROVIDER}:${TOKEN}`)}`,
+}
+
+const it = defaultIt.extend<{
+  api: Api
+  mockResponse: ResponseMocker
+}>({
+  // eslint-disable-next-line no-empty-pattern
+  api: async ({}, use) => {
+    let api: Api | null = new Api('0', 'TOKEN', {
+      catalogs: {
+        transform: {
+          active: false,
+        },
+      },
+    })
+    await use(api)
+    api = null
+  },
+  // eslint-disable-next-line no-empty-pattern
+  mockResponse: async ({}, use) => {
+    const mockResponse: ResponseMocker = (config) => {
+      mockFetch.mockResolvedValue({
+        ok: config?.ok ?? true,
+        status: config?.status ?? 200,
+        json: config?.json ? vi.fn().mockResolvedValue(config.json()) : vi.fn().mockResolvedValue({}),
+        text: vi.fn(),
+        headers: new Headers(),
+        statusText: 'OK',
+        url: '',
+        redirected: false,
+        type: 'basic',
+        body: null,
+        bodyUsed: false,
+        clone: vi.fn(),
+        arrayBuffer: vi.fn(),
+        blob: vi.fn(),
+        formData: vi.fn(),
+      } as unknown as Response)
+    }
+    await use(mockResponse)
+  },
+})
+
+describe('api', () => {
+  let mockResponse: Response
+
+  beforeEach(() => {
+    // Mock global fetch
+    vi.stubGlobal('fetch', mockFetch)
+
+    // Create a mock response object
+    mockResponse = {
+      ok: true,
+      status: 200,
+      json: vi.fn(),
+      text: vi.fn(),
+      headers: new Headers(),
+      statusText: 'OK',
+      url: '',
+      redirected: false,
+      type: 'basic',
+      body: null,
+      bodyUsed: false,
+      clone: vi.fn(),
+      arrayBuffer: vi.fn(),
+      blob: vi.fn(),
+      formData: vi.fn(),
+    } as unknown as Response
+
+    mockFetch.mockResolvedValue(mockResponse)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.clearAllMocks()
+  })
+
+  describe('constructor', () => {
+    it('should accept a provider, a token and a base config', ({ api }) => {
+      expect(api).toBeInstanceOf(Api)
+    })
+
+    it('should use default config when no additional config provided', ({ api }) => {
+      expect(api.config).toStrictEqual({
+        baseUrl: DEFAULT_BASE_URL,
+        culture: 'en' as ApiCulture,
+        catalogs: {
+          cache: {
+            active: true,
+            adapter: expect.any(MemoryCache),
+          },
+          transform: {
+            active: false,
+          },
+        },
+      })
+    })
+
+    it('should merge custom config with defaults', () => {
+      const testApi = new Api('provider', 'token', {
+        baseUrl: 'https://custom.api.com',
+        culture: 'fr' as ApiCulture,
+        catalogs: {
+          cache: {
+            active: false,
+            adapter: new DummyCache(),
+          },
+        },
+      })
+
+      expect(testApi.config).toStrictEqual({
+        baseUrl: 'https://custom.api.com',
+        culture: 'fr',
+        catalogs: {
+          cache: {
+            active: false,
+            adapter: expect.any(DummyCache),
+          },
+          transform: {
+            active: true,
+          },
+        },
+      })
+    })
+
+    it('should use provided cache adapter', () => {
+      const testApi = new Api('provider', 'token', {
+        catalogs: {
+          cache: {
+            adapter: new DummyCache(),
+          },
+        },
+      })
+      expect(testApi.cache).toBeInstanceOf(DummyCache)
+    })
+
+    it('should use DummyCache when cache is not active', () => {
+      const testApi = new Api('provider', 'token', {
+        catalogs: {
+          cache: {
+            active: false,
+            adapter: new MemoryCache(),
+          },
+        },
+      })
+      expect(testApi.cache).toBeInstanceOf(DummyCache)
+    })
+  })
+
+  describe('fetch', () => {
+    it('should have the right authorization headers when fetching', async () => {
+      const testApi = new Api('provider', 'token')
+      await testApi.fetch(DEFAULT_BASE_URL)
+
+      expect(mockFetch).toHaveBeenCalledExactlyOnceWith(
+        DEFAULT_BASE_URL,
+        {
+          headers: {
+            Authorization: `Basic ${btoa('provider:token')}`,
+          },
+        },
+      )
+    })
+
+    it('should merge additional headers with authorization', async ({ api }) => {
+      const customHeaders = { 'Content-Type': 'application/json' }
+      await api.fetch(DEFAULT_BASE_URL, { headers: customHeaders })
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        DEFAULT_BASE_URL,
+        {
+          headers: {
+            ...BasicAuthHeaders,
+            'Content-Type': 'application/json',
+          },
+        },
+      )
+    })
+
+    it('should pass through other fetch options', async ({ api }) => {
+      const options = {
+        method: 'POST',
+        body: JSON.stringify({ test: 'data' }),
+        headers: { 'Custom-Header': 'value' },
+      }
+
+      await api.fetch(DEFAULT_BASE_URL, options)
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        DEFAULT_BASE_URL,
+        {
+          method: 'POST',
+          body: JSON.stringify({ test: 'data' }),
+          headers: {
+            ...BasicAuthHeaders,
+            'Custom-Header': 'value',
+          },
+        },
+      )
+    })
+
+    it('should handle rate limiting with Bottleneck', async ({ api }) => {
+      // Make multiple concurrent requests to test rate limiting
+      const promises = Array.from({ length: 3 }, () => api.fetch(DEFAULT_BASE_URL))
+      await Promise.all(promises)
+
+      expect(mockFetch).toHaveBeenCalledTimes(3)
+    })
+  })
+
+  describe('get', () => {
+    it('should fetch and parse according to the specified schema', async ({ mockResponse, api }) => {
+      mockResponse({
+        json: () => ({ success: true }),
+      })
+
+      const spy = vi.spyOn(api, 'fetch')
+      await api.get(['path', 'to', 'catalogs'], z.object({ success: z.boolean() }), { culture: 'en' })
+      expect(spy).toHaveBeenCalledExactlyOnceWith(
+        new URL('https://api.apimo.pro/path/to/catalogs?culture=en'),
+      )
+    })
+  })
+
+  describe('populateCache', () => {
+    it('should populate cache without returning entry when no id provided', async ({ api, mockResponse }) => {
+      const catalogName: CatalogName = 'property_type'
+      const culture: ApiCulture = 'en'
+      const mockEntries = [
+        { id: 1, name: 'Apartment', name_plurial: 'Apartments' },
+        { id: 2, name: 'House', name_plurial: 'Houses' },
+      ]
+
+      mockResponse({
+        json: () => mockEntries,
+      })
+
+      const result = await api.populateCache(catalogName, culture)
+
+      expect(result).toBeUndefined()
+      expect(mockFetch).toHaveBeenCalledExactlyOnceWith(
+        new URL(`https://api.apimo.pro/catalogs/${catalogName}?culture=${culture}`),
+        {
+          headers: BasicAuthHeaders,
+        },
+      )
+    })
+
+    it('should populate cache and return specific entry when id provided', async ({ api, mockResponse }) => {
+      const catalogName: CatalogName = 'property_type'
+      const culture: ApiCulture = 'en'
+      const mockEntries = [
+        { id: 1, name: 'Apartment', name_plurial: 'Apartments' },
+        { id: 2, name: 'House', name_plurial: 'Houses' },
+      ]
+
+      mockResponse({
+        json: () => mockEntries,
+      })
+
+      const result = await api.populateCache(catalogName, culture, 1)
+
+      expect(result).toEqual({
+        name: 'Apartment',
+        namePlural: 'Apartments',
+      })
+    })
+
+    it('should return null when requested id not found', async ({ api, mockResponse }) => {
+      const catalogName: CatalogName = 'property_type'
+      const culture: ApiCulture = 'en'
+      const mockEntries = [
+        { id: 1, name: 'Apartment', name_plurial: 'Apartments' },
+      ]
+
+      mockResponse({ json: () => mockEntries })
+
+      const result = await api.populateCache(catalogName, culture, 999)
+
+      expect(result).toBeNull()
+    })
+  })
+})

package/src/core/api.ts

@@ -0,0 +1,230 @@
+import type { CatalogName } from '../consts/catalogs'
+import type { ApiCulture } from '../consts/languages'
+import type { CatalogDefinition, CatalogEntry, CatalogTransformer, LocalizedCatalogTransformer } 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 { 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'
+
+/**
+ * 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 {
+  // Base path for API access. Defaults to "https://api.apimo.pro/".
+  baseUrl: string
+  // The default language to use when none is provided. Translates to "culture" in the API.
+  culture: ApiCulture
+  // Catalog related configuration
+  catalogs: {
+    // Caching of catalogs, for faster transformation
+    cache: {
+      // Whether to use the catalog caching. A value of false means that catalogs won't be cached. You will need to supply your own `catalogs.transform.transformFn`.
+      active: boolean
+      // Where to store the catalogs cache. Currently only file is supported.
+      adapter: ApiCacheAdapter
+    }
+    // Catalog transformation related configuration
+    transform: {
+      // Whether to use the catalog transformation. A value of false will apply an identity function to the catalog ids.
+      active: boolean
+      // If provided, the function that will replace the default catalog transformer function.
+      transformFn?: CatalogTransformer
+    }
+  }
+}
+
+export const DEFAULT_BASE_URL = 'https://api.apimo.pro'
+
+export const DEFAULT_ADDITIONAL_CONFIG: AdditionalConfig = {
+  baseUrl: DEFAULT_BASE_URL,
+  culture: 'en',
+  catalogs: {
+    cache: {
+      active: true,
+      adapter: new MemoryCache(),
+    },
+    transform: {
+      active: true,
+    },
+  },
+}
+
+export class Api {
+  readonly config: AdditionalConfig
+  readonly cache: ApiCacheAdapter
+  readonly limiter: Bottleneck
+
+  constructor(
+    // The site identifier, in a string of numbers format. You can request yours by contacting Apimo.net customer service.
+    private readonly provider: string,
+    // The secret token for API authentication
+    private readonly token: string,
+    // Additional config, to tweak how the API is handled
+    config: DeepPartial<AdditionalConfig> = DEFAULT_ADDITIONAL_CONFIG,
+  ) {
+    this.config = merge(DEFAULT_ADDITIONAL_CONFIG, config) as AdditionalConfig
+    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.
+   */
+  public fetch(...parameters: Parameters<typeof fetch>): Promise<Response> {
+    const [input, init] = parameters
+    const extendedInit: RequestInit = {
+      ...init,
+      headers: {
+        Authorization: `Basic ${btoa(`${this.provider}:${this.token}`)}`,
+        ...init?.headers,
+      },
+    }
+
+    return this.limiter.schedule(() => fetch(input, extendedInit))
+  }
+
+  public async get<S extends z.Schema>(path: string[], schema: S, options?: Partial<ApiSearchParams>): Promise<z.infer<S>> {
+    const response = await this.fetch(
+      makeApiUrl(path, this.config, {
+        culture: this.config.culture,
+        ...options,
+      }),
+    )
+
+    if (!response.ok) {
+      throw new Error(await response.json())
+    }
+
+    return schema.parseAsync(await response.json())
+  }
+
+  public async fetchCatalogs(): Promise<CatalogDefinition[]> {
+    return this.get(
+      ['catalogs'],
+      z.array(CatalogDefinitionSchema),
+    )
+  }
+
+  public async populateCache(catalogName: CatalogName, culture: ApiCulture): Promise<void>
+  public async populateCache(catalogName: CatalogName, culture: ApiCulture, id: number): Promise<CatalogEntryName | null>
+  public async populateCache(catalogName: CatalogName, culture: ApiCulture, id?: number): Promise<void | CatalogEntryName | null> {
+    const catalog = await this.fetchCatalog(
+      catalogName,
+      { culture },
+    )
+    await 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
+    }
+  }
+
+  public async getCatalogEntries(catalogName: CatalogName, options?: Pick<ApiSearchParams, 'culture'>): Promise<CatalogEntry[]> {
+    try {
+      return await this.cache.getEntries(catalogName, options?.culture ?? this.config.culture)
+    }
+    catch (e) {
+      if (e instanceof CacheExpiredError) {
+        await this.populateCache(catalogName, options?.culture ?? this.config.culture)
+        return this.cache.getEntries(catalogName, options?.culture ?? this.config.culture)
+      }
+      else {
+        throw e
+      }
+    }
+  }
+
+  public async fetchCatalog(catalogName: CatalogName, options?: Pick<ApiSearchParams, 'culture'>): Promise<CatalogEntry[]> {
+    return this.get(
+      ['catalogs', catalogName],
+      z.array(CatalogEntrySchema),
+      options,
+    )
+  }
+
+  public async fetchAgencies(options?: Pick<ApiSearchParams, 'culture' | 'limit' | 'offset'>) {
+    return this.get(
+      ['agencies'],
+      z.object({
+        total_items: z.number(),
+        agencies: getAgencySchema(this.getLocalizedCatalogTransformer(
+          options?.culture ?? this.config.culture,
+        ), this.config).array(),
+        timestamp: z.number(),
+      },
+      ),
+    )
+  }
+
+  public async fetchProperties(agencyId: number, options?: Pick<ApiSearchParams, 'culture' | 'limit' | 'offset' | 'timestamp' | 'step' | 'status' | 'group'>) {
+    return this.get(
+      ['agencies', agencyId.toString(), 'properties'],
+      z.object({
+        total_items: z.number(),
+        timestamp: z.number(),
+        properties: getPropertySchema(this.getLocalizedCatalogTransformer(
+          options?.culture ?? this.config.culture,
+        )).array(),
+      }),
+      options,
+    )
+  }
+
+  private getLocalizedCatalogTransformer(culture: ApiCulture): LocalizedCatalogTransformer {
+    return async (catalogName, id) => {
+      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)
+    }
+  }
+
+  private async catalogTransformer(catalogName: CatalogName, culture: ApiCulture, id: number): Promise<CatalogEntryName | null> {
+    try {
+      return await this.cache.getEntry(catalogName, culture, id)
+    }
+    catch (e) {
+      if (e instanceof CacheExpiredError) {
+        return await this.populateCache(catalogName, culture, id)
+      }
+      else {
+        throw e
+      }
+    }
+  }
+}

package/src/core/converters.ts

@@ -0,0 +1,7 @@
+export const Converters = {
+  toDate: (v: string) => new Date(v),
+  toUrl: (path: string, baseUrl: string) => (v: string) => new URL(
+    `${path}${v}`,
+    baseUrl,
+  ).href,
+}

package/src/schemas/agency.ts

@@ -0,0 +1,66 @@
+import type { AdditionalConfig } from '../core/api'
+import type { LocalizedCatalogTransformer } from './common'
+import { z } from 'zod'
+import { Converters } from '../core/converters'
+import { CitySchema, getUserSchema, NameIdPairSchema } from './common'
+
+export function getRateSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    id: z.coerce.number(),
+    category: z.coerce.number().transform(v => transformer('property_category', v)),
+    range_min: z.coerce.number().nullable(),
+    range_max: z.coerce.number().nullable(),
+    commission_price: z.coerce.number().nullable(),
+    commission_rate: z.coerce.number().nullable(),
+    comment: z.string(),
+    url: z.string().nullable(),
+  })
+}
+
+export const PartnerSchema = z.object({
+  type: z.coerce.number(),
+  partner: z.coerce.number().nullable(),
+  name: z.string().nullable(),
+  reference: z.string(),
+  amount: z.coerce.number(),
+  currency: z.string().toLowerCase(),
+})
+
+export function getAgencySchema(transformer: LocalizedCatalogTransformer, config: AdditionalConfig) {
+  return z.object({
+    id: z.coerce.number(),
+    reference: z.coerce.number(),
+    active: z.boolean(),
+    name: z.string(),
+    company: NameIdPairSchema,
+    brand: z.unknown().nullable(),
+    networks: z.unknown().array(),
+    address: z.string(),
+    address_more: z.string().nullable(),
+    city: CitySchema,
+    district: z.unknown(),
+    country: z.string().toLowerCase(),
+    region: z.string().toLowerCase(),
+    latitude: z.coerce.number(),
+    longitude: z.coerce.number(),
+    email: z.string().email(),
+    phone: z.string(),
+    fax: z.string().nullable(),
+    url: z.string(),
+    logo: z.string().url(),
+    logo_svg: z.string().nullable(),
+    picture: z.string().url(),
+    currency: z.string().toLowerCase(),
+    timetable: z.string(),
+    created_at: z.coerce.string().transform(Converters.toDate),
+    updated_at: z.coerce.string().transform(Converters.toDate),
+    providers: z.string().transform(Converters.toUrl('agencies', config.baseUrl)),
+    rates: getRateSchema(transformer).array(),
+    partners: PartnerSchema.array(),
+    stories: z.unknown().array(),
+    users: getUserSchema(transformer).array(),
+    sectors: z.unknown().array(),
+    parameters: z.string().transform(Converters.toUrl('agencies', config.baseUrl)),
+    subscription: z.string(),
+  })
+}

package/src/schemas/common.ts

@@ -0,0 +1,67 @@
+import type { CatalogName } from '../consts/catalogs'
+import type { ApiCulture } from '../consts/languages'
+import type { CatalogEntryName } from '../services/storage/types'
+import { unknown, z } from 'zod'
+import { Converters } from '../core/converters'
+
+export interface CatalogTransformer {
+  (catalogName: CatalogName, culture: ApiCulture, id: number): Promise<CatalogEntryName | string | null>
+}
+
+export interface LocalizedCatalogTransformer {
+  (catalogName: CatalogName, id: number): Promise<CatalogEntryName | string | null>
+}
+
+export const CatalogDefinitionSchema = z.object({
+  name: z.string(),
+  path: z.string().url(),
+  private: z.boolean(),
+})
+
+export type CatalogDefinition = z.infer<typeof CatalogDefinitionSchema>
+
+export const CatalogEntrySchema = z.object({
+  id: z.number(),
+  culture: z.string().optional(),
+  name: z.string(),
+  name_plurial: z.string().optional(),
+})
+
+export type CatalogEntry = z.infer<typeof CatalogEntrySchema>
+
+export const NameIdPairSchema = z.object({
+  id: z.coerce.number(),
+  name: z.string(),
+})
+
+export const CitySchema = NameIdPairSchema.extend({
+  zipcode: z.string(),
+})
+
+export function getUserSchema(transformer: LocalizedCatalogTransformer) {
+  return z.object({
+    id: z.coerce.number(),
+    agency: z.coerce.number(),
+    active: z.boolean(),
+    created_at: z.coerce.string().transform(Converters.toDate),
+    updated_at: z.coerce.string().transform(Converters.toDate),
+    firstname: z.string(),
+    lastname: z.string(),
+    username: z.string().optional(),
+    password: z.string().optional(),
+    language: z.string(),
+    spoken_languages: z.string().array().optional(),
+    group: z.coerce.number().transform(v => transformer('user_group', v)),
+    email: z.string().email(),
+    phone: z.string().nullable(),
+    mobile: z.string(),
+    fax: z.string().nullable(),
+    city: NameIdPairSchema.nullable().optional(),
+    birthday_at: z.coerce.string().transform(Converters.toDate),
+    timezone: z.string().nullable(),
+    picture: z.string().nullable(),
+    partners: unknown().array().optional(),
+    stories: unknown().array().optional(),
+    rates: unknown(),
+  })
+}

package/src/schemas/internal.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+export const TYPE_UNDOCUMENTED = z.unknown().transform((v, { path }) => {
+  console.warn(`Unhandled \`${path}\` with value \`${v}\``)
+  return v
+})
+
+export const TYPE_UNDOCUMENTED_NULLABLE = z.unknown().nullable().transform((v, { path }) => {
+  if (v !== null) {
+    console.warn(`Unhandled \`${path}\` with value \`${v}\``)
+  }
+  return v
+})