reunion_get_caf_amounts

Instructions

Implementation Reference

• src/modules/social.ts:49-81 (handler)

  The handler function for 'reunion_get_caf_amounts' tool. It queries the OpenDataSoft API dataset 'montant-presta-sociales-caf-lareunion', filters by benefit_type, date range (from/to), applies a limit, and returns monthly total amounts (in EUR) paid out by CAF Réunion per social-benefit category. Results include date, benefit_type, and amount_eur.

  server.tool(
    'reunion_get_caf_amounts',
    'Monthly total amounts (in EUR) paid out by CAF Réunion for each social-benefit category. Each row is one (month × benefit type) with the cumulated payouts for that category. Useful for public-spending analysis, social-policy monitoring, comparison with beneficiary counts (use reunion_get_caf_beneficiaries to derive average per beneficiary). Sorted by date descending.',
    {
      benefit_type: z.string().optional().describe('Benefit type label prefix match. Examples: "RSA", "AAH", "Prime d\'activité", "Allocations familiales"'),
      from: z.string().optional().describe('Inclusive lower bound on date, ISO format YYYY-MM-DD'),
      to: z.string().optional().describe('Inclusive upper bound on date, ISO format YYYY-MM-DD'),
      limit: z.number().int().min(1).max(500).default(50).describe('Max rows to return (1-500, default 50)'),
    },
    async ({ benefit_type, from, to, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_CAF_AMOUNTS, {
          where: buildWhere([
            benefit_type ? `type_de_prestation LIKE ${quote(`${benefit_type}%`)}` : undefined,
            from ? `date >= date${quote(from)}` : undefined,
            to ? `date <= date${quote(to)}` : undefined,
          ]),
          order_by: 'date DESC',
          limit,
        });
        return jsonResult({
          total_rows: data.total_count,
          series: data.results.map((row) => ({
            date: pickString(row, ['date']),
            benefit_type: pickString(row, ['type_de_prestation']),
            amount_eur: pickNumber(row, ['montant']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to fetch CAF amounts');
      }
    }
  );

• src/modules/social.ts:52-57 (schema)

  Zod schema defining the input parameters for reunion_get_caf_amounts: benefit_type (optional string prefix match), from (optional ISO date), to (optional ISO date), and limit (number 1-500, default 50).

  {
    benefit_type: z.string().optional().describe('Benefit type label prefix match. Examples: "RSA", "AAH", "Prime d\'activité", "Allocations familiales"'),
    from: z.string().optional().describe('Inclusive lower bound on date, ISO format YYYY-MM-DD'),
    to: z.string().optional().describe('Inclusive upper bound on date, ISO format YYYY-MM-DD'),
    limit: z.number().int().min(1).max(500).default(50).describe('Max rows to return (1-500, default 50)'),
  },

• src/modules/social.ts:49-81 (registration)

  The tool is registered via server.tool('reunion_get_caf_amounts', ...) inside registerSocialTools() in src/modules/social.ts. registerSocialTools is called from src/modules/index.ts (line 49) and ultimately bootstrapped in src/index.ts (line 22).

  server.tool(
    'reunion_get_caf_amounts',
    'Monthly total amounts (in EUR) paid out by CAF Réunion for each social-benefit category. Each row is one (month × benefit type) with the cumulated payouts for that category. Useful for public-spending analysis, social-policy monitoring, comparison with beneficiary counts (use reunion_get_caf_beneficiaries to derive average per beneficiary). Sorted by date descending.',
    {
      benefit_type: z.string().optional().describe('Benefit type label prefix match. Examples: "RSA", "AAH", "Prime d\'activité", "Allocations familiales"'),
      from: z.string().optional().describe('Inclusive lower bound on date, ISO format YYYY-MM-DD'),
      to: z.string().optional().describe('Inclusive upper bound on date, ISO format YYYY-MM-DD'),
      limit: z.number().int().min(1).max(500).default(50).describe('Max rows to return (1-500, default 50)'),
    },
    async ({ benefit_type, from, to, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_CAF_AMOUNTS, {
          where: buildWhere([
            benefit_type ? `type_de_prestation LIKE ${quote(`${benefit_type}%`)}` : undefined,
            from ? `date >= date${quote(from)}` : undefined,
            to ? `date <= date${quote(to)}` : undefined,
          ]),
          order_by: 'date DESC',
          limit,
        });
        return jsonResult({
          total_rows: data.total_count,
          series: data.results.map((row) => ({
            date: pickString(row, ['date']),
            benefit_type: pickString(row, ['type_de_prestation']),
            amount_eur: pickNumber(row, ['montant']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to fetch CAF amounts');
      }
    }
  );

• src/utils/helpers.ts:36-41 (helper)

  buildWhere() helper used to construct the ODSQL WHERE clause from the optional filter conditions (benefit_type, from, to).

  export function buildWhere(
    conditions: Array<string | undefined | null | false>
  ): string | undefined {
    const valid = conditions.filter((condition): condition is string => Boolean(condition));
    return valid.length > 0 ? valid.join(' AND ') : undefined;
  }

• src/utils/helpers.ts:53-55 (helper)

  quote() helper used to safely quote ODSQL string literals in filter conditions.

  export function quote(value: string): string {
    return `'${escapeOdSqlString(value)}'`;
  }