@wasto/sdk 1.0.3 → 1.0.4

package/src/client.ts

@@ -1,692 +1,701 @@
-import type {
-  PaginatedResponse,
-  PaginationMeta,
-} from './types/pagination.types';
-import type {
-  SearchStreetSectorsQuery,
-  SearchStreetSectorsResponse,
-} from './types/calendar-pdf.types';
-
-const DEFAULT_PAGE = 1;
-const DEFAULT_PAGE_SIZE = 20;
-
-export interface WastoClientConfig {
-  baseUrl: string;
-  getToken?: () => string | null;
-  /** Headers added to every request (e.g. X-Wasto-Client). */
-  defaultHeaders?: Record<string, string>;
-  /**
-   * Optional hook when a request fails (HTTP error or network).
-   * Called before the error is rethrown. Host apps (e.g. via cms-components)
-   * wire Sentry here — wasto-sdk stays vendor-agnostic.
-   */
-  onRequestError?: (error: Error, context: WastoRequestErrorContext) => void;
-}
-
-export type WastoRequestErrorContext = {
-  method: string;
-  url: string;
-  path: string;
-  status?: number;
-};
-
-export class WastoApiError extends Error {
-  constructor(
-    message: string,
-    public status: number,
-    public body?: unknown,
-  ) {
-    super(message);
-    this.name = 'WastoApiError';
-  }
-}
-
-function getHeaders(config: WastoClientConfig, init?: HeadersInit): HeadersInit {
-  const token = config.getToken?.();
-  const headers: Record<string, string> = {
-    ...(config.defaultHeaders ?? {}),
-    ...(init as Record<string, string>),
-  };
-  if (token) {
-    headers['Authorization'] = `Bearer ${token}`;
-  }
-  const body = (init as { body?: unknown })?.body;
-if (!headers['Content-Type'] && !(typeof FormData !== 'undefined' && body instanceof FormData)) {
-    headers['Content-Type'] = 'application/json';
-  }
-  return headers;
-}
-
-async function handleResponse<T>(res: Response): Promise<T> {
-  if (!res.ok) {
-    let message = `HTTP ${res.status}`;
-    try {
-      const text = await res.text();
-      if (text) {
-        try {
-          const json = JSON.parse(text);
-          message = json.message ?? json.error ?? text;
-        } catch {
-          message = text;
-        }
-      }
-    } catch {
-      // ignore
-    }
-    throw new WastoApiError(message, res.status, undefined);
-  }
-  const contentType = res.headers.get('content-type');
-  if (contentType?.includes('application/json')) {
-    return res.json() as Promise<T>;
-  }
-  return res.text() as Promise<T>;
-}
-
-export function createWastoClient(config: WastoClientConfig) {
-  const base = config.baseUrl.replace(/\/$/, '');
-
-  const notifyRequestError = (
-    err: unknown,
-    context: Omit<WastoRequestErrorContext, 'status'> & { status?: number },
-  ) => {
-    if (!config.onRequestError) return;
-    const error = err instanceof Error ? err : new Error(String(err));
-    const status =
-      context.status ??
-      (error instanceof WastoApiError ? error.status : undefined);
-    try {
-      config.onRequestError(error, {
-        method: context.method,
-        url: context.url,
-        path: context.path,
-        status,
-      });
-    } catch {
-      // Never let the reporter break the request path.
-    }
-  };
-
-  const request = async <T>(
-    path: string,
-    options: RequestInit = {},
-  ): Promise<T> => {
-    const url = path.startsWith('http') ? path : `${base}${path.startsWith('/') ? path : `/${path}`}`;
-    const method = (options.method ?? 'GET').toUpperCase();
-    try {
-      const res = await fetch(url, {
-        ...options,
-        headers: getHeaders(config, options.headers),
-      });
-      return await handleResponse<T>(res);
-    } catch (err) {
-      notifyRequestError(err, { method, url, path });
-      throw err;
-    }
-  };
-
-  /** Public API: no Authorization header (for /public/* routes) */
-  const requestPublic = async <T>(
-    path: string,
-    options: RequestInit = {},
-  ): Promise<T> => {
-    const url = path.startsWith('http') ? path : `${base}${path.startsWith('/') ? path : `/${path}`}`;
-    const method = (options.method ?? 'GET').toUpperCase();
-    const headers: Record<string, string> = {
-      ...(options.headers as Record<string, string>),
-    };
-    const body = (options as { body?: unknown })?.body;
-    // Keep behavior aligned with `request`/`getHeaders`: if a JSON body is provided,
-    // ensure the API receives `Content-Type: application/json` so body parsing works.
-    if (!headers['Content-Type'] && !(typeof FormData !== 'undefined' && body instanceof FormData)) {
-      headers['Content-Type'] = 'application/json';
-    }
-    try {
-      const res = await fetch(url, { ...options, headers });
-      return await handleResponse<T>(res);
-    } catch (err) {
-      notifyRequestError(err, { method, url, path });
-      throw err;
-    }
-  };
-
-  return {
-    request,
-
-    auth: {
-      login: (email: string, password: string) =>
-        request<
-          | { access_token: string; user?: unknown }
-          | { requiresTwoFactor: true; pendingToken: string }
-        >('/auth/login', {
-          method: 'POST',
-          body: JSON.stringify({ email, password }),
-        }),
-      register: (data: { email: string; password: string; firstName?: string; lastName?: string }) =>
-        request<{ access_token?: string; user?: unknown }>('/auth/register', {
-          method: 'POST',
-          body: JSON.stringify(data),
-        }),
-      forgotPassword: (email: string) =>
-        request<{ ok: boolean }>('/auth/forgot-password', {
-          method: 'POST',
-          body: JSON.stringify({ email }),
-        }),
-      resetPassword: (token: string, password: string) =>
-        request<{ ok: boolean }>('/auth/reset-password', {
-          method: 'POST',
-          body: JSON.stringify({ token, password }),
-        }),
-      acceptInvite: (data: {
-        token: string;
-        password: string;
-        firstName?: string;
-        lastName?: string;
-      }) =>
-        request<{ access_token: string; user?: unknown }>('/auth/accept-invite', {
-          method: 'POST',
-          body: JSON.stringify(data),
-        }),
-      verify2fa: (pendingToken: string, code: string) =>
-        request<{ access_token: string; user?: unknown }>('/auth/verify-2fa', {
-          method: 'POST',
-          body: JSON.stringify({ pendingToken, code }),
-        }),
-    },
-
-    users: {
-      findAll: (params?: { page?: number; pageSize?: number }) => {
-        const q = new URLSearchParams();
-        if (params?.page != null) q.set('page', String(params.page));
-        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-        const query = q.toString();
-        return request<PaginatedResponse<unknown>>(`/users${query ? `?${query}` : ''}`);
-      },
-      getById: (id: string) => request<unknown>(`/users/${id}`),
-      getMe: () => request<unknown>('/users/me'),
-      create: (data: unknown) =>
-        request<unknown>('/users', { method: 'POST', body: JSON.stringify(data) }),
-      invite: (data: unknown) =>
-        request<unknown>('/users/invite', { method: 'POST', body: JSON.stringify(data) }),
-      update: (id: string, data: unknown) =>
-        request<unknown>(`/users/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
-      updateMe: (data: unknown) =>
-        request<unknown>('/users/me', { method: 'PATCH', body: JSON.stringify(data) }),
-      remove: (id: string) =>
-        request<void>(`/users/${id}`, { method: 'DELETE' }),
-    },
-
-    assets: {
-      findAll: (params?: { page?: number; pageSize?: number; cityId?: string; cityGroupId?: string; type?: string; status?: string }) => {
-        const q = new URLSearchParams();
-        if (params?.page != null) q.set('page', String(params.page));
-        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-        if (params?.cityId) q.set('cityId', params.cityId);
-        if (params?.cityGroupId) q.set('cityGroupId', params.cityGroupId);
-        if (params?.type) q.set('type', params.type);
-        if (params?.status) q.set('status', params.status);
-        const query = q.toString();
-        return request<PaginatedResponse<unknown>>(`/assets${query ? `?${query}` : ''}`);
-      },
-      getMapLocations: (params?: { page?: number; pageSize?: number; cityId?: string; cityGroupId?: string; type?: string; status?: string }) => {
-        const q = new URLSearchParams();
-        if (params?.page != null) q.set('page', String(params.page));
-        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-        if (params?.cityId) q.set('cityId', params.cityId);
-        if (params?.cityGroupId) q.set('cityGroupId', params.cityGroupId);
-        if (params?.type) q.set('type', params.type);
-        if (params?.status) q.set('status', params.status);
-        const query = q.toString();
-        return request<PaginatedResponse<unknown>>(`/assets/map/locations${query ? `?${query}` : ''}`);
-      },
-      getById: (id: string) => request<unknown>(`/assets/${id}`),
-      create: (data: unknown) =>
-        request<unknown>('/assets', { method: 'POST', body: JSON.stringify(data) }),
-      update: (id: string, data: unknown) =>
-        request<unknown>(`/assets/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
-      remove: (id: string) =>
-        request<void>(`/assets/${id}`, { method: 'DELETE' }),
-    },
-
-    cities: {
-      findAll: (params?: { page?: number; pageSize?: number }) => {
-        const q = new URLSearchParams();
-        if (params?.page != null) q.set('page', String(params.page));
-        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-        const query = q.toString();
-        return request<PaginatedResponse<unknown>>(`/cities${query ? `?${query}` : ''}`);
-      },
-      getById: (id: string) => request<unknown>(`/cities/${id}`),
-      create: (data: unknown) =>
-        request<unknown>('/cities', { method: 'POST', body: JSON.stringify(data) }),
-      update: (id: string, data: unknown) =>
-        request<unknown>(`/cities/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
-      remove: (id: string) =>
-        request<void>(`/cities/${id}`, { method: 'DELETE' }),
-
-      wasteTypes: (cityId: string) => ({
-        /** @deprecated Préférez cityGroups.wasteTypes pour la gestion du catalogue. */
-        list: (params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/waste-types${query ? `?${query}` : ''}`);
-        },
-        /** @deprecated Préférez cityGroups.wasteTypes.create */
-        create: (data: unknown) =>
-          request<unknown>(`/cities/${cityId}/waste-types`, {
-            method: 'POST',
-            body: JSON.stringify(data),
-          }),
-        getById: (id: string) =>
-          request<unknown>(`/cities/${cityId}/waste-types/${id}`),
-        /** @deprecated Préférez cityGroups.wasteTypes.update */
-        update: (id: string, data: unknown) =>
-          request<unknown>(`/cities/${cityId}/waste-types/${id}`, {
-            method: 'PATCH',
-            body: JSON.stringify(data),
-          }),
-        /** @deprecated Délie la ville ; préférez cityGroups.wasteTypes.unlinkCity ou remove */
-        remove: (id: string) =>
-          request<void>(`/cities/${cityId}/waste-types/${id}`, {
-            method: 'DELETE',
-          }),
-      }),
-
-      wasteCollectionPlaces: (cityId: string) => ({
-        list: (params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/waste-collection-places${query ? `?${query}` : ''}`);
-        },
-        create: (data: unknown) =>
-          request<unknown>(`/cities/${cityId}/waste-collection-places`, {
-            method: 'POST',
-            body: JSON.stringify(data),
-          }),
-        getById: (id: string) =>
-          request<unknown>(`/cities/${cityId}/waste-collection-places/${id}`),
-        update: (id: string, data: unknown) =>
-          request<unknown>(`/cities/${cityId}/waste-collection-places/${id}`, {
-            method: 'PATCH',
-            body: JSON.stringify(data),
-          }),
-        remove: (id: string) =>
-          request<void>(`/cities/${cityId}/waste-collection-places/${id}`, {
-            method: 'DELETE',
-          }),
-      }),
-
-      quizQuestions: (cityId: string) => ({
-        list: (params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/quiz-questions${query ? `?${query}` : ''}`);
-        },
-        create: (data: unknown) =>
-          request<unknown>(`/cities/${cityId}/quiz-questions`, {
-            method: 'POST',
-            body: JSON.stringify(data),
-          }),
-        getById: (id: string) =>
-          request<unknown>(`/cities/${cityId}/quiz-questions/${id}`),
-        update: (id: string, data: unknown) =>
-          request<unknown>(`/cities/${cityId}/quiz-questions/${id}`, {
-            method: 'PATCH',
-            body: JSON.stringify(data),
-          }),
-        remove: (id: string) =>
-          request<void>(`/cities/${cityId}/quiz-questions/${id}`, {
-            method: 'DELETE',
-          }),
-      }),
-
-      recyclingPoints: (cityId: string) => ({
-        list: (params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/recycling-points${query ? `?${query}` : ''}`);
-        },
-        create: (data: unknown) =>
-          request<unknown>(`/cities/${cityId}/recycling-points`, {
-            method: 'POST',
-            body: JSON.stringify(data),
-          }),
-        getById: (id: string) =>
-          request<unknown>(`/cities/${cityId}/recycling-points/${id}`),
-        update: (id: string, data: unknown) =>
-          request<unknown>(`/cities/${cityId}/recycling-points/${id}`, {
-            method: 'PATCH',
-            body: JSON.stringify(data),
-          }),
-        remove: (id: string) =>
-          request<void>(`/cities/${cityId}/recycling-points/${id}`, {
-            method: 'DELETE',
-          }),
-      }),
-    },
-
-    wasteTypeDetails: (wasteTypeId: string) => ({
-      list: (params?: { page?: number; pageSize?: number }) => {
-        const q = new URLSearchParams();
-        if (params?.page != null) q.set('page', String(params.page));
-        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-        const query = q.toString();
-        return request<PaginatedResponse<unknown>>(`/waste-types/${wasteTypeId}/details${query ? `?${query}` : ''}`);
-      },
-      create: (data: unknown) =>
-        request<unknown>(`/waste-types/${wasteTypeId}/details`, {
-          method: 'POST',
-          body: JSON.stringify(data),
-        }),
-      update: (id: string, data: unknown) =>
-        request<unknown>(`/waste-types/${wasteTypeId}/details/${id}`, {
-          method: 'PATCH',
-          body: JSON.stringify(data),
-        }),
-      remove: (id: string) =>
-        request<void>(`/waste-types/${wasteTypeId}/details/${id}`, {
-          method: 'DELETE',
-        }),
-    }),
-
-    cityGroups: {
-      findAll: (params?: { page?: number; pageSize?: number }) => {
-        const q = new URLSearchParams();
-        if (params?.page != null) q.set('page', String(params.page));
-        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-        const query = q.toString();
-        return request<PaginatedResponse<unknown>>(`/city-groups${query ? `?${query}` : ''}`);
-      },
-      getById: (id: string) => request<unknown>(`/city-groups/${id}`),
-      create: (data: unknown) =>
-        request<unknown>('/city-groups', { method: 'POST', body: JSON.stringify(data) }),
-      update: (id: string, data: unknown) =>
-        request<unknown>(`/city-groups/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
-      remove: (id: string) =>
-        request<void>(`/city-groups/${id}`, { method: 'DELETE' }),
-
-      wasteTypes: (cityGroupId: string) => ({
-        list: (params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return request<PaginatedResponse<unknown>>(
-            `/city-groups/${cityGroupId}/waste-types${query ? `?${query}` : ''}`,
-          );
-        },
-        getById: (id: string) =>
-          request<unknown>(`/city-groups/${cityGroupId}/waste-types/${id}`),
-        create: (data: unknown) =>
-          request<unknown>(`/city-groups/${cityGroupId}/waste-types`, {
-            method: 'POST',
-            body: JSON.stringify(data),
-          }),
-        update: (id: string, data: unknown) =>
-          request<unknown>(`/city-groups/${cityGroupId}/waste-types/${id}`, {
-            method: 'PATCH',
-            body: JSON.stringify(data),
-          }),
-        remove: (id: string) =>
-          request<void>(`/city-groups/${cityGroupId}/waste-types/${id}`, {
-            method: 'DELETE',
-          }),
-        linkCity: (wasteTypeId: string, cityId: string) =>
-          request<unknown>(
-            `/city-groups/${cityGroupId}/waste-types/${wasteTypeId}/cities/${cityId}`,
-            { method: 'POST' },
-          ),
-        unlinkCity: (wasteTypeId: string, cityId: string) =>
-          request<void>(
-            `/city-groups/${cityGroupId}/waste-types/${wasteTypeId}/cities/${cityId}`,
-            { method: 'DELETE' },
-          ),
-      }),
-    },
-
-    public: {
-      cities: {
-        findAll: (params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/cities${query ? `?${query}` : ''}`);
-        },
-        getById: (id: string) => requestPublic<unknown>(`/public/cities/${id}`),
-        getWasteTypes: (cityId: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/waste-types${query ? `?${query}` : ''}`);
-        },
-        getWasteCollectionPlaces: (cityId: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/waste-collection-places${query ? `?${query}` : ''}`);
-        },
-        getRecyclingPoints: (cityId: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/recycling-points${query ? `?${query}` : ''}`);
-        },
-        getChallenges: (cityId: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/challenges${query ? `?${query}` : ''}`);
-        },
-        getBadges: (cityId: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/badges${query ? `?${query}` : ''}`);
-        },
-        getOperationalZones: (cityId: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/operational-zones${query ? `?${query}` : ''}`);
-        },
-        searchStreetSectors: (
-          cityId: string,
-          params: SearchStreetSectorsQuery,
-        ) => {
-          const q = new URLSearchParams();
-          q.set('q', params.q);
-          if (params.cityGroupId) q.set('cityGroupId', params.cityGroupId);
-          return requestPublic<SearchStreetSectorsResponse>(
-            `/public/cities/${encodeURIComponent(cityId)}/street-sectors?${q.toString()}`,
-          );
-        },
-        getCalendarPdfUrl: (cityId: string, placeId: string, year?: number) => {
-          const q = new URLSearchParams();
-          if (year != null) q.set('year', String(year));
-          const query = q.toString();
-          return `${base}/public/cities/${encodeURIComponent(cityId)}/places/${encodeURIComponent(placeId)}/calendar-pdf${query ? `?${query}` : ''}`;
-        },
-        getCalendarPrintUrl: (
-          cityId: string,
-          placeId: string,
-          year?: number,
-          preview = false,
-        ) => {
-          const q = new URLSearchParams();
-          if (year != null) q.set('year', String(year));
-          if (preview) q.set('preview', '1');
-          const query = q.toString();
-          return `${base}/public/cities/${encodeURIComponent(cityId)}/places/${encodeURIComponent(placeId)}/calendar-print${query ? `?${query}` : ''}`;
-        },
-      },
-      challenges: {
-        list: (cityId?: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (cityId != null) q.set('cityId', cityId);
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/challenges${query ? `?${query}` : ''}`);
-        },
-        getById: (id: string) => requestPublic<unknown>(`/public/challenges/${id}`),
-        getSeries: (id: string) =>
-          requestPublic<unknown>(`/public/challenges/${id}/series`),
-        complete: (id: string, body: { deviceId: string; score: number; seriesId: string }) =>
-          requestPublic<unknown>(`/public/challenges/${id}/complete`, {
-            method: 'POST',
-            body: JSON.stringify(body),
-          }),
-        getProgress: (deviceId: string) =>
-          requestPublic<unknown[]>(`/public/challenges/progress/${encodeURIComponent(deviceId)}`),
-      },
-      blogPosts: {
-        list: (cityGroupId?: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (cityGroupId != null) q.set('cityGroupId', cityGroupId);
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/blog-posts${query ? `?${query}` : ''}`);
-        },
-        getById: (id: string) => requestPublic<unknown>(`/public/blog-posts/${id}`),
-      },
-      announcements: {
-        listForCity: (cityId: string) =>
-          requestPublic<
-            Array<{
-              id: string;
-              title: string;
-              body: string;
-              imageUrl?: string | null;
-              sentAt?: string | null;
-            }>
-          >(`/public/announcements?cityId=${encodeURIComponent(cityId)}`),
-      },
-      cityGroups: {
-        searchStreetSectors: (cityGroupId: string, params: { q: string }) => {
-          const q = new URLSearchParams();
-          q.set('q', params.q);
-          return requestPublic<SearchStreetSectorsResponse>(
-            `/public/city-groups/${encodeURIComponent(cityGroupId)}/street-sectors?${q.toString()}`,
-          );
-        },
-      },
-      tickets: {
-        getForms: (params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/tickets/forms${query ? `?${query}` : ''}`);
-        },
-        getForm: (id: string) => requestPublic<unknown>(`/public/tickets/forms/${id}`),
-        create: (data: unknown) =>
-          requestPublic<unknown>('/public/tickets', {
-            method: 'POST',
-            body: JSON.stringify(data),
-          }),
-        getByAccessKey: (accessKey: string) =>
-          requestPublic<unknown>(`/public/tickets/${encodeURIComponent(accessKey)}`),
-      },
-      chat: {
-        getAvailability: (params: string | { cityId?: string; cityGroupId?: string }) => {
-          const q = new URLSearchParams();
-          if (typeof params === 'string') {
-            q.set('cityId', params);
-          } else {
-            if (params.cityGroupId) q.set('cityGroupId', params.cityGroupId);
-            if (params.cityId) q.set('cityId', params.cityId);
-          }
-          return requestPublic<{
-            enabled: boolean;
-            cityGroupId: string | null;
-            reason?: string;
-          }>(`/public/chat/availability?${q.toString()}`);
-        },
-        createConversation: (body: {
-          deviceId: string;
-          cityId?: string;
-          cityGroupId?: string;
-        }) =>
-          requestPublic<unknown>('/public/chat/conversations', {
-            method: 'POST',
-            body: JSON.stringify(body),
-          }),
-        setConversationLocation: (
-          conversationId: string,
-          body: { cityId: string; placeId?: string },
-        ) =>
-          requestPublic<unknown>(
-            `/public/chat/conversations/${encodeURIComponent(conversationId)}/location`,
-            {
-              method: 'PATCH',
-              body: JSON.stringify(body),
-            },
-          ),
-        getConversations: (deviceId: string, params?: { page?: number; pageSize?: number }) => {
-          const q = new URLSearchParams();
-          if (params?.page != null) q.set('page', String(params.page));
-          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
-          const query = q.toString();
-          return requestPublic<PaginatedResponse<unknown>>(`/public/chat/conversations/${encodeURIComponent(deviceId)}${query ? `?${query}` : ''}`);
-        },
-        getMessages: (conversationId: string) =>
-          requestPublic<unknown>(`/public/chat/conversations/${conversationId}/messages`),
-        sendMessage: (
-          conversationId: string,
-          body: { content: string; actionOptionId?: string; placeId?: string },
-        ) =>
-          requestPublic<unknown>(`/public/chat/conversations/${conversationId}/messages`, {
-            method: 'POST',
-            body: JSON.stringify(body),
-          }),
-      },
-      devices: {
-        registerPushToken: (deviceId: string, body: { token: string }) =>
-          requestPublic<void>(`/public/devices/${encodeURIComponent(deviceId)}/push-token`, {
-            method: 'POST',
-            body: JSON.stringify(body),
-          }),
-      },
-      analytics: {
-        track: (payload: unknown) =>
-          requestPublic<void>('/public/analytics/track', {
-            method: 'POST',
-            body: JSON.stringify(payload),
-          }),
-        delete: (deviceId: string) =>
-          requestPublic<void>(`/public/analytics/delete/${encodeURIComponent(deviceId)}`, {
-            method: 'DELETE',
-          }),
-      },
-      cms: {
-        getPageById: (id: string) =>
-          requestPublic<unknown>(`/public/cms/pages/${encodeURIComponent(id)}`),
-        getSiteBySlug: (slug: string) =>
-          requestPublic<unknown>(`/public/cms/sites/${encodeURIComponent(slug)}`),
-        getAppBySlug: (slug: string) =>
-          requestPublic<unknown>(`/public/cms/apps/${encodeURIComponent(slug)}`),
-        getAppMenuById: (appSlug: string, menuId: string) =>
-          requestPublic<unknown>(
-            `/public/cms/apps/${encodeURIComponent(appSlug)}/menus/by-id/${encodeURIComponent(menuId)}`,
-          ),
-      },
-    },
-  };
-}
-
-export type WastoClient = ReturnType<typeof createWastoClient>;
+import type {
+  PaginatedResponse,
+  PaginationMeta,
+} from './types/pagination.types';
+import type {
+  SearchStreetSectorsQuery,
+  SearchStreetSectorsResponse,
+} from './types/calendar-pdf.types';
+import type { CityAppPreload } from './types/app-preload.types';
+
+const DEFAULT_PAGE = 1;
+const DEFAULT_PAGE_SIZE = 20;
+
+export interface WastoClientConfig {
+  baseUrl: string;
+  getToken?: () => string | null;
+  /** Headers added to every request (e.g. X-Wasto-Client). */
+  defaultHeaders?: Record<string, string>;
+  /**
+   * Optional hook when a request fails (HTTP error or network).
+   * Called before the error is rethrown. Host apps (e.g. via cms-components)
+   * wire Sentry here — wasto-sdk stays vendor-agnostic.
+   */
+  onRequestError?: (error: Error, context: WastoRequestErrorContext) => void;
+}
+
+export type WastoRequestErrorContext = {
+  method: string;
+  url: string;
+  path: string;
+  status?: number;
+};
+
+export class WastoApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public body?: unknown,
+  ) {
+    super(message);
+    this.name = 'WastoApiError';
+  }
+}
+
+function getHeaders(config: WastoClientConfig, init?: HeadersInit): HeadersInit {
+  const token = config.getToken?.();
+  const headers: Record<string, string> = {
+    ...(config.defaultHeaders ?? {}),
+    ...(init as Record<string, string>),
+  };
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+  const body = (init as { body?: unknown })?.body;
+if (!headers['Content-Type'] && !(typeof FormData !== 'undefined' && body instanceof FormData)) {
+    headers['Content-Type'] = 'application/json';
+  }
+  return headers;
+}
+
+async function handleResponse<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    let message = `HTTP ${res.status}`;
+    try {
+      const text = await res.text();
+      if (text) {
+        try {
+          const json = JSON.parse(text);
+          message = json.message ?? json.error ?? text;
+        } catch {
+          message = text;
+        }
+      }
+    } catch {
+      // ignore
+    }
+    throw new WastoApiError(message, res.status, undefined);
+  }
+  const contentType = res.headers.get('content-type');
+  if (contentType?.includes('application/json')) {
+    return res.json() as Promise<T>;
+  }
+  return res.text() as Promise<T>;
+}
+
+export function createWastoClient(config: WastoClientConfig) {
+  const base = config.baseUrl.replace(/\/$/, '');
+
+  const notifyRequestError = (
+    err: unknown,
+    context: Omit<WastoRequestErrorContext, 'status'> & { status?: number },
+  ) => {
+    if (!config.onRequestError) return;
+    const error = err instanceof Error ? err : new Error(String(err));
+    const status =
+      context.status ??
+      (error instanceof WastoApiError ? error.status : undefined);
+    try {
+      config.onRequestError(error, {
+        method: context.method,
+        url: context.url,
+        path: context.path,
+        status,
+      });
+    } catch {
+      // Never let the reporter break the request path.
+    }
+  };
+
+  const request = async <T>(
+    path: string,
+    options: RequestInit = {},
+  ): Promise<T> => {
+    const url = path.startsWith('http') ? path : `${base}${path.startsWith('/') ? path : `/${path}`}`;
+    const method = (options.method ?? 'GET').toUpperCase();
+    try {
+      const res = await fetch(url, {
+        ...options,
+        headers: getHeaders(config, options.headers),
+      });
+      return await handleResponse<T>(res);
+    } catch (err) {
+      notifyRequestError(err, { method, url, path });
+      throw err;
+    }
+  };
+
+  /** Public API: no Authorization header (for /public/* routes) */
+  const requestPublic = async <T>(
+    path: string,
+    options: RequestInit = {},
+  ): Promise<T> => {
+    const url = path.startsWith('http') ? path : `${base}${path.startsWith('/') ? path : `/${path}`}`;
+    const method = (options.method ?? 'GET').toUpperCase();
+    const headers: Record<string, string> = {
+      ...(options.headers as Record<string, string>),
+    };
+    const body = (options as { body?: unknown })?.body;
+    // Keep behavior aligned with `request`/`getHeaders`: if a JSON body is provided,
+    // ensure the API receives `Content-Type: application/json` so body parsing works.
+    if (!headers['Content-Type'] && !(typeof FormData !== 'undefined' && body instanceof FormData)) {
+      headers['Content-Type'] = 'application/json';
+    }
+    try {
+      const res = await fetch(url, { ...options, headers });
+      return await handleResponse<T>(res);
+    } catch (err) {
+      notifyRequestError(err, { method, url, path });
+      throw err;
+    }
+  };
+
+  return {
+    request,
+
+    auth: {
+      login: (email: string, password: string) =>
+        request<
+          | { access_token: string; user?: unknown }
+          | { requiresTwoFactor: true; pendingToken: string }
+        >('/auth/login', {
+          method: 'POST',
+          body: JSON.stringify({ email, password }),
+        }),
+      register: (data: { email: string; password: string; firstName?: string; lastName?: string }) =>
+        request<{ access_token?: string; user?: unknown }>('/auth/register', {
+          method: 'POST',
+          body: JSON.stringify(data),
+        }),
+      forgotPassword: (email: string) =>
+        request<{ ok: boolean }>('/auth/forgot-password', {
+          method: 'POST',
+          body: JSON.stringify({ email }),
+        }),
+      resetPassword: (token: string, password: string) =>
+        request<{ ok: boolean }>('/auth/reset-password', {
+          method: 'POST',
+          body: JSON.stringify({ token, password }),
+        }),
+      acceptInvite: (data: {
+        token: string;
+        password: string;
+        firstName?: string;
+        lastName?: string;
+      }) =>
+        request<{ access_token: string; user?: unknown }>('/auth/accept-invite', {
+          method: 'POST',
+          body: JSON.stringify(data),
+        }),
+      verify2fa: (pendingToken: string, code: string) =>
+        request<{ access_token: string; user?: unknown }>('/auth/verify-2fa', {
+          method: 'POST',
+          body: JSON.stringify({ pendingToken, code }),
+        }),
+    },
+
+    users: {
+      findAll: (params?: { page?: number; pageSize?: number }) => {
+        const q = new URLSearchParams();
+        if (params?.page != null) q.set('page', String(params.page));
+        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+        const query = q.toString();
+        return request<PaginatedResponse<unknown>>(`/users${query ? `?${query}` : ''}`);
+      },
+      getById: (id: string) => request<unknown>(`/users/${id}`),
+      getMe: () => request<unknown>('/users/me'),
+      create: (data: unknown) =>
+        request<unknown>('/users', { method: 'POST', body: JSON.stringify(data) }),
+      invite: (data: unknown) =>
+        request<unknown>('/users/invite', { method: 'POST', body: JSON.stringify(data) }),
+      update: (id: string, data: unknown) =>
+        request<unknown>(`/users/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
+      updateMe: (data: unknown) =>
+        request<unknown>('/users/me', { method: 'PATCH', body: JSON.stringify(data) }),
+      remove: (id: string) =>
+        request<void>(`/users/${id}`, { method: 'DELETE' }),
+    },
+
+    assets: {
+      findAll: (params?: { page?: number; pageSize?: number; cityId?: string; cityGroupId?: string; type?: string; status?: string }) => {
+        const q = new URLSearchParams();
+        if (params?.page != null) q.set('page', String(params.page));
+        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+        if (params?.cityId) q.set('cityId', params.cityId);
+        if (params?.cityGroupId) q.set('cityGroupId', params.cityGroupId);
+        if (params?.type) q.set('type', params.type);
+        if (params?.status) q.set('status', params.status);
+        const query = q.toString();
+        return request<PaginatedResponse<unknown>>(`/assets${query ? `?${query}` : ''}`);
+      },
+      getMapLocations: (params?: { page?: number; pageSize?: number; cityId?: string; cityGroupId?: string; type?: string; status?: string }) => {
+        const q = new URLSearchParams();
+        if (params?.page != null) q.set('page', String(params.page));
+        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+        if (params?.cityId) q.set('cityId', params.cityId);
+        if (params?.cityGroupId) q.set('cityGroupId', params.cityGroupId);
+        if (params?.type) q.set('type', params.type);
+        if (params?.status) q.set('status', params.status);
+        const query = q.toString();
+        return request<PaginatedResponse<unknown>>(`/assets/map/locations${query ? `?${query}` : ''}`);
+      },
+      getById: (id: string) => request<unknown>(`/assets/${id}`),
+      create: (data: unknown) =>
+        request<unknown>('/assets', { method: 'POST', body: JSON.stringify(data) }),
+      update: (id: string, data: unknown) =>
+        request<unknown>(`/assets/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
+      remove: (id: string) =>
+        request<void>(`/assets/${id}`, { method: 'DELETE' }),
+    },
+
+    cities: {
+      findAll: (params?: { page?: number; pageSize?: number }) => {
+        const q = new URLSearchParams();
+        if (params?.page != null) q.set('page', String(params.page));
+        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+        const query = q.toString();
+        return request<PaginatedResponse<unknown>>(`/cities${query ? `?${query}` : ''}`);
+      },
+      getById: (id: string) => request<unknown>(`/cities/${id}`),
+      create: (data: unknown) =>
+        request<unknown>('/cities', { method: 'POST', body: JSON.stringify(data) }),
+      update: (id: string, data: unknown) =>
+        request<unknown>(`/cities/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
+      remove: (id: string) =>
+        request<void>(`/cities/${id}`, { method: 'DELETE' }),
+
+      wasteTypes: (cityId: string) => ({
+        /** @deprecated Préférez cityGroups.wasteTypes pour la gestion du catalogue. */
+        list: (params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/waste-types${query ? `?${query}` : ''}`);
+        },
+        /** @deprecated Préférez cityGroups.wasteTypes.create */
+        create: (data: unknown) =>
+          request<unknown>(`/cities/${cityId}/waste-types`, {
+            method: 'POST',
+            body: JSON.stringify(data),
+          }),
+        getById: (id: string) =>
+          request<unknown>(`/cities/${cityId}/waste-types/${id}`),
+        /** @deprecated Préférez cityGroups.wasteTypes.update */
+        update: (id: string, data: unknown) =>
+          request<unknown>(`/cities/${cityId}/waste-types/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+          }),
+        /** @deprecated Délie la ville ; préférez cityGroups.wasteTypes.unlinkCity ou remove */
+        remove: (id: string) =>
+          request<void>(`/cities/${cityId}/waste-types/${id}`, {
+            method: 'DELETE',
+          }),
+      }),
+
+      wasteCollectionPlaces: (cityId: string) => ({
+        list: (params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/waste-collection-places${query ? `?${query}` : ''}`);
+        },
+        create: (data: unknown) =>
+          request<unknown>(`/cities/${cityId}/waste-collection-places`, {
+            method: 'POST',
+            body: JSON.stringify(data),
+          }),
+        getById: (id: string) =>
+          request<unknown>(`/cities/${cityId}/waste-collection-places/${id}`),
+        update: (id: string, data: unknown) =>
+          request<unknown>(`/cities/${cityId}/waste-collection-places/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+          }),
+        remove: (id: string) =>
+          request<void>(`/cities/${cityId}/waste-collection-places/${id}`, {
+            method: 'DELETE',
+          }),
+      }),
+
+      quizQuestions: (cityId: string) => ({
+        list: (params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/quiz-questions${query ? `?${query}` : ''}`);
+        },
+        create: (data: unknown) =>
+          request<unknown>(`/cities/${cityId}/quiz-questions`, {
+            method: 'POST',
+            body: JSON.stringify(data),
+          }),
+        getById: (id: string) =>
+          request<unknown>(`/cities/${cityId}/quiz-questions/${id}`),
+        update: (id: string, data: unknown) =>
+          request<unknown>(`/cities/${cityId}/quiz-questions/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+          }),
+        remove: (id: string) =>
+          request<void>(`/cities/${cityId}/quiz-questions/${id}`, {
+            method: 'DELETE',
+          }),
+      }),
+
+      recyclingPoints: (cityId: string) => ({
+        list: (params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return request<PaginatedResponse<unknown>>(`/cities/${cityId}/recycling-points${query ? `?${query}` : ''}`);
+        },
+        create: (data: unknown) =>
+          request<unknown>(`/cities/${cityId}/recycling-points`, {
+            method: 'POST',
+            body: JSON.stringify(data),
+          }),
+        getById: (id: string) =>
+          request<unknown>(`/cities/${cityId}/recycling-points/${id}`),
+        update: (id: string, data: unknown) =>
+          request<unknown>(`/cities/${cityId}/recycling-points/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+          }),
+        remove: (id: string) =>
+          request<void>(`/cities/${cityId}/recycling-points/${id}`, {
+            method: 'DELETE',
+          }),
+      }),
+    },
+
+    wasteTypeDetails: (wasteTypeId: string) => ({
+      list: (params?: { page?: number; pageSize?: number }) => {
+        const q = new URLSearchParams();
+        if (params?.page != null) q.set('page', String(params.page));
+        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+        const query = q.toString();
+        return request<PaginatedResponse<unknown>>(`/waste-types/${wasteTypeId}/details${query ? `?${query}` : ''}`);
+      },
+      create: (data: unknown) =>
+        request<unknown>(`/waste-types/${wasteTypeId}/details`, {
+          method: 'POST',
+          body: JSON.stringify(data),
+        }),
+      update: (id: string, data: unknown) =>
+        request<unknown>(`/waste-types/${wasteTypeId}/details/${id}`, {
+          method: 'PATCH',
+          body: JSON.stringify(data),
+        }),
+      remove: (id: string) =>
+        request<void>(`/waste-types/${wasteTypeId}/details/${id}`, {
+          method: 'DELETE',
+        }),
+    }),
+
+    cityGroups: {
+      findAll: (params?: { page?: number; pageSize?: number }) => {
+        const q = new URLSearchParams();
+        if (params?.page != null) q.set('page', String(params.page));
+        if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+        const query = q.toString();
+        return request<PaginatedResponse<unknown>>(`/city-groups${query ? `?${query}` : ''}`);
+      },
+      getById: (id: string) => request<unknown>(`/city-groups/${id}`),
+      create: (data: unknown) =>
+        request<unknown>('/city-groups', { method: 'POST', body: JSON.stringify(data) }),
+      update: (id: string, data: unknown) =>
+        request<unknown>(`/city-groups/${id}`, { method: 'PATCH', body: JSON.stringify(data) }),
+      remove: (id: string) =>
+        request<void>(`/city-groups/${id}`, { method: 'DELETE' }),
+
+      wasteTypes: (cityGroupId: string) => ({
+        list: (params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return request<PaginatedResponse<unknown>>(
+            `/city-groups/${cityGroupId}/waste-types${query ? `?${query}` : ''}`,
+          );
+        },
+        getById: (id: string) =>
+          request<unknown>(`/city-groups/${cityGroupId}/waste-types/${id}`),
+        create: (data: unknown) =>
+          request<unknown>(`/city-groups/${cityGroupId}/waste-types`, {
+            method: 'POST',
+            body: JSON.stringify(data),
+          }),
+        update: (id: string, data: unknown) =>
+          request<unknown>(`/city-groups/${cityGroupId}/waste-types/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(data),
+          }),
+        remove: (id: string) =>
+          request<void>(`/city-groups/${cityGroupId}/waste-types/${id}`, {
+            method: 'DELETE',
+          }),
+        linkCity: (wasteTypeId: string, cityId: string) =>
+          request<unknown>(
+            `/city-groups/${cityGroupId}/waste-types/${wasteTypeId}/cities/${cityId}`,
+            { method: 'POST' },
+          ),
+        unlinkCity: (wasteTypeId: string, cityId: string) =>
+          request<void>(
+            `/city-groups/${cityGroupId}/waste-types/${wasteTypeId}/cities/${cityId}`,
+            { method: 'DELETE' },
+          ),
+      }),
+    },
+
+    public: {
+      cities: {
+        findAll: (params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/cities${query ? `?${query}` : ''}`);
+        },
+        getById: (id: string) => requestPublic<unknown>(`/public/cities/${id}`),
+        /**
+         * Cold-start agrégé : ville + types de déchets + lieux de collecte + points carte.
+         * Remplace 4 appels paginés au lancement de l’app générée.
+         */
+        getAppPreload: (cityId: string) =>
+          requestPublic<CityAppPreload>(
+            `/public/cities/${encodeURIComponent(cityId)}/app-preload`,
+          ),
+        getWasteTypes: (cityId: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/waste-types${query ? `?${query}` : ''}`);
+        },
+        getWasteCollectionPlaces: (cityId: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/waste-collection-places${query ? `?${query}` : ''}`);
+        },
+        getRecyclingPoints: (cityId: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/recycling-points${query ? `?${query}` : ''}`);
+        },
+        getChallenges: (cityId: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/challenges${query ? `?${query}` : ''}`);
+        },
+        getBadges: (cityId: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/badges${query ? `?${query}` : ''}`);
+        },
+        getOperationalZones: (cityId: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/cities/${encodeURIComponent(cityId)}/operational-zones${query ? `?${query}` : ''}`);
+        },
+        searchStreetSectors: (
+          cityId: string,
+          params: SearchStreetSectorsQuery,
+        ) => {
+          const q = new URLSearchParams();
+          q.set('q', params.q);
+          if (params.cityGroupId) q.set('cityGroupId', params.cityGroupId);
+          return requestPublic<SearchStreetSectorsResponse>(
+            `/public/cities/${encodeURIComponent(cityId)}/street-sectors?${q.toString()}`,
+          );
+        },
+        getCalendarPdfUrl: (cityId: string, placeId: string, year?: number) => {
+          const q = new URLSearchParams();
+          if (year != null) q.set('year', String(year));
+          const query = q.toString();
+          return `${base}/public/cities/${encodeURIComponent(cityId)}/places/${encodeURIComponent(placeId)}/calendar-pdf${query ? `?${query}` : ''}`;
+        },
+        getCalendarPrintUrl: (
+          cityId: string,
+          placeId: string,
+          year?: number,
+          preview = false,
+        ) => {
+          const q = new URLSearchParams();
+          if (year != null) q.set('year', String(year));
+          if (preview) q.set('preview', '1');
+          const query = q.toString();
+          return `${base}/public/cities/${encodeURIComponent(cityId)}/places/${encodeURIComponent(placeId)}/calendar-print${query ? `?${query}` : ''}`;
+        },
+      },
+      challenges: {
+        list: (cityId?: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (cityId != null) q.set('cityId', cityId);
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/challenges${query ? `?${query}` : ''}`);
+        },
+        getById: (id: string) => requestPublic<unknown>(`/public/challenges/${id}`),
+        getSeries: (id: string) =>
+          requestPublic<unknown>(`/public/challenges/${id}/series`),
+        complete: (id: string, body: { deviceId: string; score: number; seriesId: string }) =>
+          requestPublic<unknown>(`/public/challenges/${id}/complete`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+          }),
+        getProgress: (deviceId: string) =>
+          requestPublic<unknown[]>(`/public/challenges/progress/${encodeURIComponent(deviceId)}`),
+      },
+      blogPosts: {
+        list: (cityGroupId?: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (cityGroupId != null) q.set('cityGroupId', cityGroupId);
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/blog-posts${query ? `?${query}` : ''}`);
+        },
+        getById: (id: string) => requestPublic<unknown>(`/public/blog-posts/${id}`),
+      },
+      announcements: {
+        listForCity: (cityId: string) =>
+          requestPublic<
+            Array<{
+              id: string;
+              title: string;
+              body: string;
+              imageUrl?: string | null;
+              sentAt?: string | null;
+            }>
+          >(`/public/announcements?cityId=${encodeURIComponent(cityId)}`),
+      },
+      cityGroups: {
+        searchStreetSectors: (cityGroupId: string, params: { q: string }) => {
+          const q = new URLSearchParams();
+          q.set('q', params.q);
+          return requestPublic<SearchStreetSectorsResponse>(
+            `/public/city-groups/${encodeURIComponent(cityGroupId)}/street-sectors?${q.toString()}`,
+          );
+        },
+      },
+      tickets: {
+        getForms: (params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/tickets/forms${query ? `?${query}` : ''}`);
+        },
+        getForm: (id: string) => requestPublic<unknown>(`/public/tickets/forms/${id}`),
+        create: (data: unknown) =>
+          requestPublic<unknown>('/public/tickets', {
+            method: 'POST',
+            body: JSON.stringify(data),
+          }),
+        getByAccessKey: (accessKey: string) =>
+          requestPublic<unknown>(`/public/tickets/${encodeURIComponent(accessKey)}`),
+      },
+      chat: {
+        getAvailability: (params: string | { cityId?: string; cityGroupId?: string }) => {
+          const q = new URLSearchParams();
+          if (typeof params === 'string') {
+            q.set('cityId', params);
+          } else {
+            if (params.cityGroupId) q.set('cityGroupId', params.cityGroupId);
+            if (params.cityId) q.set('cityId', params.cityId);
+          }
+          return requestPublic<{
+            enabled: boolean;
+            cityGroupId: string | null;
+            reason?: string;
+          }>(`/public/chat/availability?${q.toString()}`);
+        },
+        createConversation: (body: {
+          deviceId: string;
+          cityId?: string;
+          cityGroupId?: string;
+        }) =>
+          requestPublic<unknown>('/public/chat/conversations', {
+            method: 'POST',
+            body: JSON.stringify(body),
+          }),
+        setConversationLocation: (
+          conversationId: string,
+          body: { cityId: string; placeId?: string },
+        ) =>
+          requestPublic<unknown>(
+            `/public/chat/conversations/${encodeURIComponent(conversationId)}/location`,
+            {
+              method: 'PATCH',
+              body: JSON.stringify(body),
+            },
+          ),
+        getConversations: (deviceId: string, params?: { page?: number; pageSize?: number }) => {
+          const q = new URLSearchParams();
+          if (params?.page != null) q.set('page', String(params.page));
+          if (params?.pageSize != null) q.set('pageSize', String(params.pageSize));
+          const query = q.toString();
+          return requestPublic<PaginatedResponse<unknown>>(`/public/chat/conversations/${encodeURIComponent(deviceId)}${query ? `?${query}` : ''}`);
+        },
+        getMessages: (conversationId: string) =>
+          requestPublic<unknown>(`/public/chat/conversations/${conversationId}/messages`),
+        sendMessage: (
+          conversationId: string,
+          body: { content: string; actionOptionId?: string; placeId?: string },
+        ) =>
+          requestPublic<unknown>(`/public/chat/conversations/${conversationId}/messages`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+          }),
+      },
+      devices: {
+        registerPushToken: (deviceId: string, body: { token: string }) =>
+          requestPublic<void>(`/public/devices/${encodeURIComponent(deviceId)}/push-token`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+          }),
+      },
+      analytics: {
+        track: (payload: unknown) =>
+          requestPublic<void>('/public/analytics/track', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+          }),
+        delete: (deviceId: string) =>
+          requestPublic<void>(`/public/analytics/delete/${encodeURIComponent(deviceId)}`, {
+            method: 'DELETE',
+          }),
+      },
+      cms: {
+        getPageById: (id: string) =>
+          requestPublic<unknown>(`/public/cms/pages/${encodeURIComponent(id)}`),
+        getSiteBySlug: (slug: string) =>
+          requestPublic<unknown>(`/public/cms/sites/${encodeURIComponent(slug)}`),
+        getAppBySlug: (slug: string) =>
+          requestPublic<unknown>(`/public/cms/apps/${encodeURIComponent(slug)}`),
+        getAppMenuById: (appSlug: string, menuId: string) =>
+          requestPublic<unknown>(
+            `/public/cms/apps/${encodeURIComponent(appSlug)}/menus/by-id/${encodeURIComponent(menuId)}`,
+          ),
+      },
+    },
+  };
+}
+
+export type WastoClient = ReturnType<typeof createWastoClient>;