Plugin Node.js ts-immo-js

Vue d'ensemble

ts-immo-js est le SDK officiel pour Node.js. Il offre un client fortement typé pour interagir avec l'API TS-Immo, avec support des Promises, de async/await et un typage TypeScript complet.

Installation

# npm
npm install ts-immo-js

# yarn
yarn add ts-immo-js

# pnpm
pnpm add ts-immo-js

Démarrage rapide

Créez un client et commencez à utiliser l'API en quelques lignes :

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[]

Authentification

Configurez votre clé API via variables d'environnement (recommandé) ou directement dans le 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',
});

Gestion des propriétés

CRUD complet sur les propriétés immobilières :

// 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');

Médias

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');

Synchronisation & Webhooks

Déclenchez des synchronisations et réagissez aux événements en temps réel :

// 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);
});

Support TypeScript

ts-immo-js est entièrement écrit en TypeScript et exporte tous les types nécessaires :

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 });
};

Gestion des erreurs

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);
  }
}