list_pca_itens

Instructions

Implementation Reference

• src/tools/list_pca_itens.ts:31-57 (handler)

  The handler function that executes the list_pca_itens tool logic: parses input (orgaoCnpj, anoPca, sequencialPca, optional palavraChave), calls the adapter to fetch PCA items, applies optional keyword filtering, and returns the results with metadata.

  async handler(rawArgs) {
    const parse = ArgsSchema.safeParse(rawArgs ?? {});
    if (!parse.success) return errorResult(`Invalid arguments: ${parse.error.message}`);
    const args = parse.data;
    try {
      const cnpj = normalizeCnpj(args.orgaoCnpj);
      const itens = await listPcaItens(cnpj, args.anoPca, args.sequencialPca);
      const filtered = args.palavraChave
        ? itens.filter((i) =>
            (i.descricaoItem ?? '').toLowerCase().includes(args.palavraChave!.toLowerCase()),
          )
        : itens;
      return jsonResult({
        meta: {
          orgaoCnpj: cnpj,
          anoPca: args.anoPca,
          sequencialPca: args.sequencialPca,
          total: filtered.length,
          totalAntesFiltro: itens.length,
        },
        itens: filtered,
      });
    } catch (err) {
      const msg = err instanceof PncpError ? err.message : String(err);
      return errorResult(`Failed to list PCA itens: ${msg}`);
    }
  },

• src/adapters/pncp.ts:618-642 (handler)

  The adapter function listPcaItens that makes the HTTP GET request to /orgaos/{cnpj}/pca/{ano}/{sequencial}/itens, caches the result with a 30-min TTL, and parses using PcaItemSchema.

  export async function listPcaItens(
    orgaoCnpj: string,
    anoPca: number,
    sequencialPca: number,
  ): Promise<PcaItem[]> {
    const cacheKey = `list:pca-itens:${orgaoCnpj}:${anoPca}:${sequencialPca}`;
    const cached = cache.get<PcaItem[]>(cacheKey);
    if (cached) return cached;
  
    try {
      const { data } = await withRetry(() =>
        pncpClient.get(`/orgaos/${orgaoCnpj}/pca/${anoPca}/${sequencialPca}/itens`),
      );
      const arr = asArray(data);
      const parsed = PcaItemSchema.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:328-351 (schema)

  PcaItemSchema: Zod schema defining each PCA item's fields (description, quantities, unit values, classification, dates, etc.) with passthrough for extra fields.

  export const PcaItemSchema = z
    .object({
      orgaoCnpj: z.string().nullable().optional(),
      anoPca: z.number().nullable().optional(),
      codigoUnidade: z.string().nullable().optional(),
      nomeUnidade: z.string().nullable().optional(),
      numeroItem: z.number().nullable().optional(),
      codigoItem: z.string().nullable().optional(),
      descricaoItem: z.string().nullable().optional(),
      quantidadeEstimada: z.number().nullable().optional(),
      valorUnitario: z.number().nullable().optional(),
      valorTotal: z.number().nullable().optional(),
      valorOrcamentoExercicio: z.number().nullable().optional(),
      classificacaoCatalogoId: z.number().nullable().optional(),
      classificacaoSuperiorCodigo: z.string().nullable().optional(),
      classificacaoSuperiorNome: z.string().nullable().optional(),
      grupoContratacaoCodigo: z.string().nullable().optional(),
      grupoContratacaoNome: z.string().nullable().optional(),
      categoriaItemPcaNome: z.string().nullable().optional(),
      unidadeRequisitante: z.string().nullable().optional(),
      unidadeFornecimento: z.string().nullable().optional(),
      dataDesejada: z.string().nullable().optional(),
    })
    .passthrough();

• src/tools/list_pca_itens.ts:7-12 (schema)

  ArgsSchema: Zod schema for tool input validation of orgaoCnpj, anoPca, sequencialPca, and optional palavraChave.

  const ArgsSchema = z.object({
    orgaoCnpj: z.string(),
    anoPca: z.number().int(),
    sequencialPca: z.number().int(),
    palavraChave: z.string().min(2).optional(),
  });

• src/tools/index.ts:41-47 (registration)

  Registration of listPcaItensTool in the allTools array (line 41) and export of the toolMap at line 49.

    listPcaItensTool,
    // CNPJ enrichment
    getCnpjDataTool,
    // Análise agregada (v0.2.0)
    aggregateLicitacoes,
    comparePeriodos,
  ];