boondmanager-mcp-server 2.4.0 → 2.6.0

package/dist/schemas/index.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, MAX_SEARCH_PAGE } from "../constants.js";
+import { appendOverridesToDescription, resolveLabel } from "../config/dictionary-overrides.js";
 // Common search schema
 export const SearchSchema = z
     .object({
@@ -437,6 +438,24 @@ export const IdTabSchema = z
     tab: TabSchema.optional().describe("Onglet spécifique à récupérer (information, technical, financial, actions, contracts, documents)"),
 })
     .strict();
+// ---- Dictionary-override-aware `state` field ----
+// Accepts the usual numeric dictionary id, plus a custom label when the
+// operator configured BOOND_DICTIONARY_OVERRIDES (see docs/dictionary-overrides.md).
+// IMPORTANT: the label is resolved inside `z.preprocess`, i.e. at PARSE time,
+// not at schema definition time -- so overrides injected after this module is
+// imported (tests, late env) are honoured. Unknown labels are left as-is so
+// the integer validation fails with an explicit error.
+export const stateField = (entity, baseDescription) => z
+    .preprocess((value) => {
+    if (typeof value === "string") {
+        const resolved = resolveLabel("state", entity, value);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return value;
+}, z.coerce.number().int())
+    .optional()
+    .describe(appendOverridesToDescription(baseDescription, "state", entity));
 // ---- Candidate schemas ----
 export const CandidateCreateSchema = z
     .object({
@@ -447,11 +466,31 @@ export const CandidateCreateSchema = z
     city: z.string().optional().describe("Ville"),
     country: z.string().optional().describe("Pays"),
     title: z.string().optional().describe("Titre du poste / fonction"),
-    state: z.number().int().optional().describe("État du candidat (0=en cours, 1=placé, 2=archivé...)"),
+    state: stateField("candidate", "État du candidat (0=en cours, 1=placé, 2=archivé...)"),
     mainSkills: z.string().optional().describe("Compétences principales (texte libre)"),
     note: z.string().optional().describe("Notes / commentaires"),
 })
     .strict();
+export const PositioningUpdateSchema = z
+    .object({
+    id: z.string().min(1).describe("ID du positionnement \u00e0 modifier"),
+    state: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("\u00c9tat du positionnement : ID num\u00e9rique du dictionnaire setting.state.positioning"),
+    stateReasonTypeOf: z
+        .number()
+        .int()
+        .optional()
+        .describe("Motif d'\u00e9tat : ID num\u00e9rique du type de motif (stateReason.typeOf)"),
+    stateReasonDetail: z.string().optional().describe("Motif d'\u00e9tat : d\u00e9tail libre (stateReason.detail)"),
+    startDate: z.string().optional().describe("Date de d\u00e9but (YYYY-MM-DD, ou cha\u00eene vide pour effacer)"),
+    endDate: z.string().optional().describe("Date de fin (YYYY-MM-DD, ou cha\u00eene vide pour effacer)"),
+    informationComments: z.string().max(250).optional().describe("Commentaires (max 250 caract\u00e8res)"),
+})
+    .strict();
 export const CandidateUpdateSchema = z
     .object({
     id: z.string().min(1).describe("ID du candidat à modifier"),
@@ -462,7 +501,7 @@ export const CandidateUpdateSchema = z
     city: z.string().optional().describe("Ville"),
     country: z.string().optional().describe("Pays"),
     title: z.string().optional().describe("Titre / fonction"),
-    state: z.number().int().optional().describe("État du candidat"),
+    state: stateField("candidate", "État du candidat"),
     mainSkills: z.string().optional().describe("Compétences principales"),
     note: z.string().optional().describe("Notes"),
 })
@@ -477,7 +516,7 @@ export const ResourceCreateSchema = z
     city: z.string().optional().describe("Ville"),
     country: z.string().optional().describe("Pays"),
     title: z.string().optional().describe("Titre / poste"),
-    state: z.number().int().optional().describe("État de la ressource"),
+    state: stateField("resource", "État de la ressource"),
     note: z.string().optional().describe("Notes"),
 })
     .strict();
@@ -491,7 +530,7 @@ export const ResourceUpdateSchema = z
     city: z.string().optional().describe("Ville"),
     country: z.string().optional().describe("Pays"),
     title: z.string().optional().describe("Titre / poste"),
-    state: z.number().int().optional().describe("État"),
+    state: stateField("resource", "État"),
     note: z.string().optional().describe("Notes"),
 })
     .strict();
@@ -638,7 +677,7 @@ export const CompanyCreateSchema = z
     country: z.string().optional().describe("Pays"),
     website: z.string().optional().describe("Site web"),
     siret: z.string().optional().describe("Numéro SIRET"),
-    state: z.number().int().optional().describe("État de la société"),
+    state: stateField("company", "État de la société"),
     note: z.string().optional().describe("Notes"),
 })
     .strict();
@@ -652,7 +691,7 @@ export const CompanyUpdateSchema = z
     country: z.string().optional().describe("Pays"),
     website: z.string().optional().describe("Site web"),
     siret: z.string().optional().describe("Numéro SIRET"),
-    state: z.number().int().optional().describe("État"),
+    state: stateField("company", "État"),
     note: z.string().optional().describe("Notes"),
 })
     .strict();
@@ -662,7 +701,7 @@ export const OpportunityCreateSchema = z
     name: z.string().min(1).describe("Nom / titre de l'opportunité"),
     companyId: z.string().optional().describe("ID de la société cliente"),
     contactId: z.string().optional().describe("ID du contact associé"),
-    state: z.number().int().optional().describe("État de l'opportunité"),
+    state: stateField("opportunity", "État de l'opportunité"),
     startDate: z.string().optional().describe("Date de début prévue (YYYY-MM-DD)"),
     endDate: z.string().optional().describe("Date de fin prévue (YYYY-MM-DD)"),
     note: z.string().optional().describe("Notes / description"),
@@ -672,7 +711,7 @@ export const OpportunityUpdateSchema = z
     .object({
     id: z.string().min(1).describe("ID de l'opportunité à modifier"),
     name: z.string().optional().describe("Nom / titre"),
-    state: z.number().int().optional().describe("État"),
+    state: stateField("opportunity", "État"),
     startDate: z.string().optional().describe("Date de début (YYYY-MM-DD)"),
     endDate: z.string().optional().describe("Date de fin (YYYY-MM-DD)"),
     note: z.string().optional().describe("Notes"),
@@ -696,11 +735,10 @@ export const ActionSearchSchema = z
 // and `text` (not subject/content) — anything else triggers a 422.
 export const ActionCreateSchema = z
     .object({
-    typeOf: z.coerce
-        .number()
-        .int()
-        .min(0)
-        .describe("Type d'action : ID numérique du dictionnaire BoondManager (setting.action.*, via boond_application_dictionary)"),
+    typeOf: z
+        .union([z.coerce.number().int().min(0), z.string().min(1)])
+        .describe("Type d'action : ID numérique du dictionnaire (setting.action.*, via boond_application_dictionary) " +
+        "ou libellé personnalisé si BOOND_DICTIONARY_OVERRIDES est configuré"),
     title: z.string().optional().describe("Titre de l'action"),
     text: z.string().optional().describe("Contenu / notes de l'action"),
     startDate: z
@@ -714,6 +752,10 @@ export const ActionCreateSchema = z
     opportunityId: z.string().optional().describe("ID de l'opportunité à laquelle rattacher l'action (dependsOn)"),
     projectId: z.string().optional().describe("ID du projet auquel rattacher l'action (dependsOn)"),
     companyId: z.string().optional().describe("ID de la société associée (uniquement en complément d'un contactId)"),
+    positioningId: z
+        .string()
+        .optional()
+        .describe("ID du positionnement à lier à l'action (relation positioning). Requis par l'API pour les types d'action liés aux positionnements (ex. RQ) — sans lui, erreur 422 « 1002 - Wrong or missing attribute (/data/relationships/positioning) »."),
 })
     .strict();
 // ---- Timesheet schemas ----
@@ -760,7 +802,7 @@ export const ProjectCreateSchema = z
     companyId: z.string().optional().describe("ID de la société cliente"),
     contactId: z.string().optional().describe("ID du contact associé"),
     opportunityId: z.string().optional().describe("ID de l'opportunité liée"),
-    state: z.number().int().optional().describe("État du projet (0=en cours, 1=terminé, 2=archivé...)"),
+    state: stateField("project", "État du projet (0=en cours, 1=terminé, 2=archivé...)"),
     startDate: z.string().optional().describe("Date de début (YYYY-MM-DD)"),
     endDate: z.string().optional().describe("Date de fin (YYYY-MM-DD)"),
     note: z.string().optional().describe("Notes / description du projet"),
@@ -770,7 +812,7 @@ export const ProjectUpdateSchema = z
     .object({
     id: z.string().min(1).describe("ID du projet à modifier"),
     name: z.string().optional().describe("Nom du projet"),
-    state: z.number().int().optional().describe("État du projet"),
+    state: stateField("project", "État du projet"),
     startDate: z.string().optional().describe("Date de début (YYYY-MM-DD)"),
     endDate: z.string().optional().describe("Date de fin (YYYY-MM-DD)"),
     note: z.string().optional().describe("Notes"),
@@ -959,11 +1001,34 @@ export const PositioningCreateSchema = z
     .strict();
 export const PositioningSearchSchema = z
     .object({
-    keywords: z.string().optional().describe("Mots-clés de recherche"),
-    candidateId: z.string().optional().describe("Filtrer par ID candidat"),
-    resourceId: z.string().optional().describe("Filtrer par ID ressource"),
-    projectId: z.string().optional().describe("Filtrer par ID projet"),
-    opportunityId: z.string().optional().describe("Filtrer par ID opportunité"),
+    keywords: z
+        .string()
+        .optional()
+        .describe("Mots-clés de recherche. L'API y accepte aussi des références d'entités (AO<id>, CAND<id>, COMP<id>...) — les filtres *Id ci-dessous sont convertis automatiquement en de telles références."),
+    candidateId: z
+        .string()
+        .optional()
+        .describe("Filtrer par ID candidat (envoyé à l'API comme référence keywords CAND<id>)"),
+    resourceId: z
+        .string()
+        .optional()
+        .describe("Filtrer par ID ressource (envoyé à l'API comme référence keywords COMP<id>)"),
+    opportunityId: z
+        .string()
+        .optional()
+        .describe("Filtrer par ID opportunité (envoyé à l'API comme référence keywords AO<id>)"),
+    companyId: z
+        .string()
+        .optional()
+        .describe("Filtrer par ID société (envoyé à l'API comme référence keywords CSOC<id>)"),
+    contactId: z
+        .string()
+        .optional()
+        .describe("Filtrer par ID contact (envoyé à l'API comme référence keywords CCON<id>)"),
+    productId: z
+        .string()
+        .optional()
+        .describe("Filtrer par ID produit (envoyé à l'API comme référence keywords PROD<id>)"),
     page: z.number().int().min(1).max(MAX_SEARCH_PAGE).default(1).describe(`Numéro de page (max: ${MAX_SEARCH_PAGE})`),
     pageSize: z.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE).describe("Résultats par page"),
 })
@@ -1055,51 +1120,169 @@ export const NotificationSearchSchema = z
 })
     .strict();
 // ---- Reporting schemas ----
-// `/reporting-companies` and `/reporting-resources` require `startDate` +
-// `endDate` (YYYY-MM-DD); the others tolerate omission but still benefit from
-// a period filter.
-export const ReportingDateRequiredSchema = z
-    .object({
-    startDate: z
-        .string()
-        .regex(/^\d{4}-\d{2}-\d{2}$/)
-        .describe("Date de début YYYY-MM-DD. Requis."),
-    endDate: z
-        .string()
-        .regex(/^\d{4}-\d{2}-\d{2}$/)
-        .describe("Date de fin YYYY-MM-DD. Requis."),
+// Sources (one search.raml per endpoint):
+//   https://doc.boondmanager.com/api-externe/raml-build/resources/reportingCompanies/search.raml
+//   .../reportingProjects/search.raml  .../reportingResources/search.raml
+//   .../reportingSynthesis/search.raml .../reportingProductionPlans/search.raml
+// Every reporting endpoint carries the `searchable` trait (perimeter filters)
+// plus endpoint-specific filters. These were previously dropped — only
+// startDate/endDate/keywords were forwarded — so a "filtered" reporting query
+// silently returned the full perimeter. Each tool now exposes its real filters.
+//
+// `period`/`periodDynamic` value sets are large and differ slightly per endpoint,
+// so they stay `z.string()` (documented in the description) rather than a strict
+// enum that could reject a value the API actually accepts. The small, stable
+// enums (reportingCategory, reportingType, positioningPeriod, useCache) are typed.
+const reportingPeriodField = z
+    .string()
+    .optional()
+    .describe("Découpage temporel : 'onePeriod' (unique, entre startDate/endDate), 'dynamicPeriod' (selon periodDynamic), " +
+    "'monthly' (6 mois depuis startDate), 'quarterly', 'semiAnnual', 'annual'. La synthèse accepte aussi 'weekly'.");
+const reportingPeriodDynamicField = z
+    .string()
+    .optional()
+    .describe("Période dynamique relative à aujourd'hui (avec period='dynamicPeriod') : today, thisWeek, thisMonth, " +
+    "thisTrimester, thisSemester, thisYear, thisFiscalYear, yesterday, lastWeek, lastMonth, lastTrimester, " +
+    "lastSemester, lastYear, lastFiscalYear, tomorrow, nextWeek, nextMonth, nextTrimester, nextSemester, " +
+    "nextYear, nextFiscalYear, lastCustomPeriod, nextCustomPeriod.");
+const reportingPeriodDynamicParametersField = z
+    .string()
+    .optional()
+    .describe("Paramètres de la période personnalisée (utilisé avec periodDynamic=lastCustomPeriod/nextCustomPeriod).");
+const reportingScorecardsField = strArray("IDs des scorecards (indicateurs) à retourner.");
+const reportingUseCacheField = z
+    .enum(["withCache", "withoutCache"])
+    .optional()
+    .describe("Cache de reporting : 'withCache' (valeurs mises en cache) ou 'withoutCache' (recalcul, défaut).");
+const reportingResourcesField = intArray("Filtrer sur ces IDs de ressources.");
+const reportingProjectsField = intArray("Filtrer sur ces IDs de projets.");
+const reportingContactsField = intArray("Filtrer sur ces IDs de contacts.");
+const reportingCompaniesField = intArray("Filtrer sur ces IDs de sociétés.");
+const reportingMaxField = (entity) => z
+    .number()
+    .int()
+    .min(1)
+    .max(10)
+    .optional()
+    .describe(`Nombre de ${entity} par page (1-10, défaut 1). Le nombre de résultats = ${entity} × indicateurs.`);
+// Perimeter + period filters shared by every reporting endpoint (searchable trait).
+const reportingCommonFields = {
     keywords: z.string().optional().describe("Mots-clés."),
-    page: z.number().int().min(1).max(MAX_SEARCH_PAGE).default(1).describe(`Numéro de page (max: ${MAX_SEARCH_PAGE})`),
-    pageSize: z
-        .number()
-        .int()
-        .min(1)
-        .max(MAX_PAGE_SIZE)
-        .default(DEFAULT_PAGE_SIZE)
-        .describe(`Nombre de résultats par page (max: ${MAX_PAGE_SIZE}, défaut: ${DEFAULT_PAGE_SIZE})`),
+    perimeterManagers: perimeterManagersField,
+    perimeterAgencies: perimeterAgenciesField,
+    perimeterPoles: perimeterPolesField,
+    perimeterBusinessUnits: perimeterBusinessUnitsField,
+    perimeterDynamic: perimeterDynamicField,
+    narrowPerimeter: narrowPerimeterField,
+    periodDynamic: reportingPeriodDynamicField,
+    periodDynamicParameters: reportingPeriodDynamicParametersField,
+    scorecards: reportingScorecardsField,
+    useCache: reportingUseCacheField,
+    page: pageField,
+    pageSize: pageSizeField,
+};
+const requiredDate = (label) => z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .describe(`${label} (YYYY-MM-DD). Requis par l'API.`);
+const optionalDate = (label) => z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe(`${label} (YYYY-MM-DD).`);
+export const ReportingCompaniesSchema = z
+    .object({
+    ...reportingCommonFields,
+    startDate: requiredDate("Date de début"),
+    endDate: requiredDate("Date de fin"),
+    companiesStates: intArray("IDs d'états de sociétés (dictionnaire setting.state.company)."),
+    maxCompanies: reportingMaxField("sociétés"),
+    showPercentage: z.boolean().optional().describe("Afficher les valeurs en pourcentage plutôt qu'en valeur réelle."),
+    companies: reportingCompaniesField,
 })
     .strict();
-export const ReportingDateOptionalSchema = z
+export const ReportingProjectsSchema = z
     .object({
-    startDate: z
-        .string()
-        .regex(/^\d{4}-\d{2}-\d{2}$/)
+    ...reportingCommonFields,
+    startDate: optionalDate("Date de début"),
+    endDate: optionalDate("Date de fin"),
+    projectTypes: intArray("IDs de types de projets (dictionnaire setting.typeOf.project)."),
+    projectStates: intArray("IDs d'états de projets (dictionnaire setting.state.project)."),
+    maxProjects: reportingMaxField("projets"),
+    resources: reportingResourcesField,
+    projects: reportingProjectsField,
+    contacts: reportingContactsField,
+    companies: reportingCompaniesField,
+})
+    .strict();
+export const ReportingResourcesSchema = z
+    .object({
+    ...reportingCommonFields,
+    startDate: optionalDate("Date de début"),
+    endDate: optionalDate("Date de fin"),
+    reportingCategory: z
+        .enum(["showByResources", "showByPeriods"])
         .optional()
-        .describe("Date de début YYYY-MM-DD."),
-    endDate: z
+        .describe("Vue : 'showByResources' (défaut, sans returnedPeriod) ou 'showByPeriods' (returnedPeriod requis)."),
+    maxResources: reportingMaxField("ressources"),
+    resourceTypes: intArray("IDs de types de ressources (dictionnaire setting.typeOf.resource)."),
+    resourceStates: intArray("IDs d'états de ressources (dictionnaire setting.state.resource)."),
+    period: reportingPeriodField,
+    resources: reportingResourcesField,
+    projects: reportingProjectsField,
+    contacts: reportingContactsField,
+    companies: reportingCompaniesField,
+})
+    .strict();
+export const ReportingSynthesisSchema = z
+    .object({
+    ...reportingCommonFields,
+    startDate: requiredDate("Date de début"),
+    endDate: optionalDate("Date de fin"),
+    reportingType: z
+        .enum(["realData", "targetsData"])
+        .optional()
+        .describe("Type de données : 'realData' (défaut, réel) ou 'targetsData' (objectifs)."),
+    reportingCategory: z
+        .enum([
+        "commercialSynthesis",
+        "humanResourcesSynthesis",
+        "recruitmentSynthesis",
+        "activityExpensesSynthesis",
+        "billingSynthesis",
+        "globalSynthesis",
+    ])
+        .optional()
+        .describe("Catégorie de synthèse (défaut 'commercialSynthesis') : commercial, RH, recrutement, activité & frais, " +
+        "facturation, ou globale. `resources` n'est pas disponible hors d'une vue par ressources."),
+    period: reportingPeriodField,
+    resources: reportingResourcesField,
+    projects: reportingProjectsField,
+    contacts: reportingContactsField,
+    companies: reportingCompaniesField,
+    compareIndicators: strArray("Indicateurs à comparer entre deux périodes."),
+    compareIndicatorsPeriod: z
         .string()
-        .regex(/^\d{4}-\d{2}-\d{2}$/)
         .optional()
-        .describe("Date de fin YYYY-MM-DD."),
-    keywords: z.string().optional().describe("Mots-clés."),
-    page: z.number().int().min(1).max(MAX_SEARCH_PAGE).default(1).describe(`Numéro de page (max: ${MAX_SEARCH_PAGE})`),
-    pageSize: z
-        .number()
-        .int()
-        .min(1)
-        .max(MAX_PAGE_SIZE)
-        .default(DEFAULT_PAGE_SIZE)
-        .describe(`Nombre de résultats par page (max: ${MAX_PAGE_SIZE}, défaut: ${DEFAULT_PAGE_SIZE})`),
+        .describe("Période de comparaison des indicateurs (défaut 'period')."),
+})
+    .strict();
+export const ReportingProductionPlansSchema = z
+    .object({
+    ...reportingCommonFields,
+    startDate: requiredDate("Date de début"),
+    endDate: requiredDate("Date de fin"),
+    resourceTypes: intArray("IDs de types de ressources (dictionnaire setting.typeOf.resource)."),
+    resourceStates: intArray("IDs d'états de ressources (dictionnaire setting.state.resource)."),
+    positioningStates: intArray("IDs d'états de positionnement (dictionnaire setting.state.positioning)."),
+    positioningPeriod: z
+        .enum(["created", "running"])
+        .optional()
+        .describe("'created' (positionnements créés entre les dates, défaut) ou 'running' (en cours sur la période)."),
+    showContracts: z.boolean().optional().describe("Afficher les contrats associés."),
+    projects: reportingProjectsField,
+    contacts: reportingContactsField,
+    companies: reportingCompaniesField,
 })
     .strict();
 export const DictionaryGetSchema = z