Node.js Plugin ts-immo-js

Overview

ts-immo-js is the official SDK for Node.js. It provides a strongly typed client to interact with the Ts-Immo API, with support for Promises, async/await, and full TypeScript typing.

Installation

# npm
npm install ts-immo-js

# yarn
yarn add ts-immo-js

# pnpm
pnpm add ts-immo-js

Quick Start

Create a client and start using the API in a few lines:

import { TsImmo } from 'ts-immo-js';

const client = new TsImmo({
  apiKey: process.env.TS_IMMO_API_KEY,
  baseUrl: 'https://api.ts-immo.org/v1',
  locale: 'fr', // 'fr' | 'en' | 'de' | 'it'
});

// Récupérer les propriétés
const properties = await client.properties.list({
  type: 'sale',
  limit: 20,
  page: 1,
});

console.log(properties.data); // Property[]

Authentication

Configure your API key via environment variables (recommended) or directly in code:

// Via variables d'environnement (recommandé)
// .env
TS_IMMO_API_KEY=votre-cle-api
TS_IMMO_BASE_URL=https://api.ts-immo.org/v1

// Via configuration directe
const client = new TsImmo({
  apiKey: 'votre-cle-api',
  timeout: 10000,       // ms, défaut: 30000
  retries: 3,           // tentatives, défaut: 3
  locale: 'fr',
});

Property Management

Full CRUD on real estate properties:

// Lister les propriétés avec filtres
const results = await client.properties.list({
  type: 'sale',           // 'sale' | 'rent' | 'seasonal'
  status: 'active',
  minPrice: 150000,
  maxPrice: 500000,
  bedrooms: 3,
  city: 'Paris',
  limit: 10,
  page: 1,
});

// Récupérer une propriété par ID
const property = await client.properties.get('prop-123');

// Créer une propriété
const newProperty = await client.properties.create({
  title: 'Appartement 3 pièces Paris 11e',
  type: 'sale',
  price: 350000,
  surface: 68,
  bedrooms: 2,
  bathrooms: 1,
  address: {
    street: '12 rue de la Roquette',
    city: 'Paris',
    postalCode: '75011',
    country: 'FR',
  },
});

// Mettre à jour
const updated = await client.properties.update('prop-123', {
  price: 340000,
  status: 'sold',
});

// Supprimer
await client.properties.delete('prop-123');

Media

import { createReadStream } from 'fs';

// Upload d'images
const media = await client.media.upload('prop-123', {
  file: createReadStream('./photo.jpg'),
  type: 'image',
  isPrimary: true,
});

// Lister les médias d'une propriété
const mediaList = await client.media.list('prop-123');

// Supprimer un média
await client.media.delete('prop-123', 'media-456');

Synchronization & Webhooks

Trigger synchronizations and react to events in real time:

// Synchronisation manuelle
const syncResult = await client.sync.run({
  source: 'mls',       // source externe
  dryRun: false,
  filters: { city: 'Paris' },
});

// Écouter les webhooks de sync
client.webhooks.on('property.created', (event) => {
  console.log('Nouvelle propriété:', event.data.id);
});

client.webhooks.on('property.updated', (event) => {
  console.log('Propriété mise à jour:', event.data.id);
});

TypeScript Support

ts-immo-js is fully written in TypeScript and exports all necessary types:

import type {
  Property,
  PropertyType,
  PropertyStatus,
  Address,
  MediaItem,
  SyncResult,
  PaginatedResponse,
  TsImmoConfig,
} from 'ts-immo-js';

// Typage complet
const fetchProperties = async (): Promise<PaginatedResponse<Property>> => {
  return client.properties.list({ limit: 10 });
};

Error Handling

import { TsImmoError, NotFoundError, AuthError } from 'ts-immo-js';

try {
  const property = await client.properties.get('inexistant');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Propriété non trouvée');
  } else if (err instanceof AuthError) {
    console.log('Clé API invalide');
  } else if (err instanceof TsImmoError) {
    console.log('Erreur API:', err.message, err.code);
  }
}