list_licitacao_resultados

Instructions

Implementation Reference

• src/tools/list_licitacao_resultados.ts:39-57 (handler)

  Main handler function that parses arguments, resolves the PNCP ID, calls listItemResultados adapter, and returns the bidding results for a specific item.

    async handler(rawArgs) {
      const parse = ArgsSchema.safeParse(rawArgs ?? {});
      if (!parse.success) {
        return errorResult(`Invalid arguments: ${parse.error.message}`);
      }
      try {
        const { orgaoCnpj, ano, sequencial } = resolvePncpId(parse.data);
        const { numeroItem } = parse.data;
        const results = await listItemResultados(orgaoCnpj, ano, sequencial, numeroItem);
        return jsonResult({
          meta: { orgaoCnpj, ano, sequencial, numeroItem, total: results.length },
          resultados: results,
        });
      } catch (err) {
        const msg = err instanceof PncpError ? err.message : String(err);
        return errorResult(`Failed to list resultados: ${msg}`);
      }
    },
  };

• src/tools/list_licitacao_resultados.ts:7-15 (schema)

  Zod schema that extends PncpIdInputSchema with a required 'numeroItem' (positive integer) field for argument validation.

  const ArgsSchema = PncpIdInputSchema.and(
    z.object({
      numeroItem: z
        .number()
        .int()
        .positive()
        .describe('Item number within the licitação (use list_licitacao_itens first to discover).'),
    }),
  );

• src/tools/index.ts:5-49 (registration)

  Import and registration of listLicitacaoResultados in the allTools array (line 26) and toolMap (line 49).

  import { listLicitacaoResultados } from './list_licitacao_resultados.js';
  import { listLicitacaoArquivos } from './list_licitacao_arquivos.js';
  import { searchContratos } from './search_contratos.js';
  import { getContratoTool } from './get_contrato.js';
  import { listContratoTermosTool } from './list_contrato_termos.js';
  import { listContratoInstrumentosTool } from './list_contrato_instrumentos.js';
  import { searchAtasRp } from './search_atas_rp.js';
  import { getAtaRp } from './get_ata_rp.js';
  import { getOrgaoTool } from './get_orgao.js';
  import { getFornecedorContratos } from './get_fornecedor_contratos.js';
  import { searchPca } from './search_pca.js';
  import { listPcaItensTool } from './list_pca_itens.js';
  import { getCnpjDataTool } from './get_cnpj_data.js';
  import { aggregateLicitacoes } from './aggregate_licitacoes.js';
  import { comparePeriodos } from './compare_periodos.js';
  
  export const allTools: ToolDef[] = [
    // Compras / Licitações
    searchLicitacoes,
    getLicitacao,
    listLicitacaoItens,
    listLicitacaoResultados,
    listLicitacaoArquivos,
    // Contratos
    searchContratos,
    getContratoTool,
    listContratoTermosTool,
    listContratoInstrumentosTool,
    // Atas RP
    searchAtasRp,
    getAtaRp,
    // Órgãos / Fornecedores
    getOrgaoTool,
    getFornecedorContratos,
    // PCA
    searchPca,
    listPcaItensTool,
    // CNPJ enrichment
    getCnpjDataTool,
    // Análise agregada (v0.2.0)
    aggregateLicitacoes,
    comparePeriodos,
  ];
  
  export const toolMap = new Map<string, ToolDef>(allTools.map((t) => [t.definition.name, t]));

• src/adapters/pncp.ts:225-252 (helper)

  Adapter function listItemResultados that makes the actual HTTP GET request to PNCP API to fetch bidding results for a specific item, with caching and error handling.

  export async function listItemResultados(
    orgaoCnpj: string,
    ano: number,
    sequencial: number,
    numeroItem: number,
  ): Promise<ResultadoItem[]> {
    const cacheKey = `list:resultados:${orgaoCnpj}:${ano}:${sequencial}:${numeroItem}`;
    const cached = cache.get<ResultadoItem[]>(cacheKey);
    if (cached) return cached;
  
    try {
      const { data } = await withRetry(() =>
        pncpClient.get(
          `/orgaos/${orgaoCnpj}/compras/${ano}/${sequencial}/itens/${numeroItem}/resultados`,
        ),
      );
      const arr = asArray(data);
      const parsed = ResultadoItemSchema.array().parse(arr);
      cache.set(cacheKey, parsed, TTL_30_MIN);
      return parsed;
    } catch (err) {
      if (err instanceof AxiosError) {
        if (err.response?.status === 404) return [];
        throw new PncpError(describeAxiosError(err), err);
      }
      throw err;
    }
  }

• src/schemas/pncp.ts:106-127 (schema)

  ResultadoItemSchema — Zod schema defining the shape of each bidding result object (supplier info, prices, status, etc.).

  export const ResultadoItemSchema = z
    .object({
      numeroItem: z.number().optional(),
      numeroResultado: z.number().optional(),
      ordemClassificacaoSrp: z.number().nullable().optional(),
      niFornecedor: z.string().nullable().optional(),
      tipoPessoa: z.string().nullable().optional(),
      nomeRazaoSocialFornecedor: z.string().nullable().optional(),
      porteFornecedorId: z.number().nullable().optional(),
      porteFornecedorNome: z.string().nullable().optional(),
      situacaoCompraItemResultadoId: z.number().nullable().optional(),
      situacaoCompraItemResultadoNome: z.string().nullable().optional(),
      valorUnitario: z.number().nullable().optional(),
      valorTotal: z.number().nullable().optional(),
      percentualDesconto: z.number().nullable().optional(),
      marca: z.string().nullable().optional(),
      modelo: z.string().nullable().optional(),
      dataResultado: z.string().nullable().optional(),
    })
    .passthrough();
  
  export type ResultadoItem = z.infer<typeof ResultadoItemSchema>;