Client SDK

Le client officiel @wasto/sdk permet d'appeler l'API Wast-o depuis JavaScript ou TypeScript avec un client typé, sans gérer les URLs ni les en-têtes à la main.

Installation

npm install @wasto/sdk

En monorepo (workspace) :

# Dans le package.json de votre app
"dependencies": {
  "@wasto/sdk": "file:../packages/wasto-sdk"
}

Création du client

import { createWastoClient } from '@wasto/sdk';

const client = createWastoClient({
  baseUrl: 'https://api.wast-o.com',
});

// Optionnel : pour les routes authentifiées (admin, etc.)
const clientWithAuth = createWastoClient({
  baseUrl: 'https://api.wast-o.com',
  getToken: () => localStorage.getItem('wasto_token'),
});

Namespace public

Les routes publiques (sans authentification) sont regroupées sous client.public :

Groupe	Méthodes	Usage
public.cities	findAll(), getById(id), getWasteTypes(id), getWasteCollectionPlaces(id), getRecyclingPoints(id), getChallenges(cityId), getBadges(id), getOperationalZones(id), searchStreetSectors(cityId, { q, cityGroupId }), getCalendarPdfUrl(cityId, placeId, year?)	Villes, calendriers, défis, recherche rue → secteur, URL PDF
public.challenges	list(cityId?), getById(id), getSeries(id), complete(id, { deviceId, score }), getProgress(deviceId)	Défis, quiz, progression
public.blogPosts	list(cityGroupId?), getById(id)	Articles de blog
public.announcements	listForCity(cityId)	Modales in-app
public.tickets	getForms(), getForm(id), create(data), getByAccessKey(accessKey)	Formulaires et tickets
public.cms	getPageById, getSiteBySlug, getAppBySlug, getAppMenuById	CMS public (partiel)
public.chat	createConversation(body), getConversations(deviceId), getMessages(conversationId), sendMessage(conversationId, body)	Chatbot
public.devices	registerPushToken(deviceId, { token })	Enregistrement push (apps mobiles)
public.analytics	track(payload), delete(deviceId)	Analytics anonymes

Exemples

Récupérer une ville et ses types de déchets

const city = await client.public.cities.getById('ville-id');
console.log(city.name, city.wasteTypes);

Lister les défis d'une ville

const challenges = await client.public.cities.getChallenges('ville-id');

Recherche d'adresse → secteurs → PDF calendrier

const { data } = await client.public.cities.searchStreetSectors('ville-id', {
  q: 'rue de la république',
});
const street = data[0];
const sector = street?.sectors[0];
if (sector) {
  const pdfUrl = client.public.cities.getCalendarPdfUrl(sector.cityId, sector.id, 2026);
  window.open(pdfUrl, '_blank');
}

Compléter un défi (quiz)

await client.public.challenges.complete('challenge-id', {
  deviceId: 'mon-device-uuid',
  score: 85,
});

Récupérer la progression utilisateur

const progress = await client.public.challenges.getProgress('mon-device-uuid');

Articles de blog

const posts = await client.public.blogPosts.list(); // ou .list('cityGroupId')
const post = await client.public.blogPosts.getById('post-id');

Créer une conversation chat

const conversation = await client.public.chat.createConversation({
  deviceId: getOrCreateDeviceId(),
  cityId: 'ville-id', // optionnel
});
await client.public.chat.sendMessage(conversation.id, { content: 'Bonjour' });

Tickets (formulaires publics)

const forms = await client.public.tickets.getForms();
const ticket = await client.public.tickets.create({
  ticketFormId: 'form-id',
  values: [{ fieldId: 'field-1', value: 'Ma réponse' }],
  deviceId: 'optional-device-id',
});

Gestion des erreurs

Le SDK lance WastoApiError en cas de réponse HTTP non OK (avec message, status, body) :

import { createWastoClient, WastoApiError } from '@wasto/sdk';

try {
  await client.public.cities.getById('invalide');
} catch (err) {
  if (err instanceof WastoApiError) {
    console.error(err.status, err.message);
  }
}

Référence API

Pour le détail des endpoints et des schémas de données, consultez la documentation API.