@defarm/partner-client

Cliente oficial da DeFarm para integrações de parceiros de dados.

Foco: um endpoint de ingestão inteligente (POST /api/partner/upload) com suporte a CSV/JSON, preview, roteamento e reconciliação por referência do parceiro.

Instalação

npm install @defarm/partner-client

Quickstart (API key)

import { DefarmPartnerClient } from "@defarm/partner-client";

const client = new DefarmPartnerClient({
  gatewayBaseUrl: "https://gateway.defarm.net",
  apiKey: process.env.DEFARM_PARTNER_KEY,
  retry: { maxRetries: 2, baseDelayMs: 250 },
  responseValidation: "strict",
});

const result = await client.upload({
  file: "partner_internal_id,sisbov,car,value_chain,country,year\\nROW-1,12345678901234,MT-1234.56789.0000.00,BEEF,BR,2026",
  fileName: "animals.csv",
  autoCreateCircuit: true,
});

console.log(result.summary);
console.log(result.routed_batches[0].item_links[0].public_url);

Quickstart (JWT)

import { DefarmPartnerClient } from "@defarm/partner-client";

const client = new DefarmPartnerClient({
  gatewayBaseUrl: "https://gateway.defarm.net",
  accessToken: "<jwt>",
});

const preview = await client.previewUpload({
  file: "/tmp/animals.csv",
  sourceCircuitId: "<staging_circuit_id>",
  autoCreateCircuit: true,
});

console.log(preview.routing_plan);

Entrada de arquivo suportada

upload() e previewUpload() aceitam:

• caminho de arquivo (string)
• conteúdo bruto (string CSV/JSON)
• Uint8Array / ArrayBuffer

Campos opcionais:

• sourceCircuitId (obrigatório com JWT, opcional com API key workspace_ingestion)
• autoCreateCircuit (default do backend: true)

Reconciliação fácil por referência do parceiro

const grouped = client.groupItemLinksByReference(result);

for (const [key, entry] of grouped) {
  console.log(key, entry.itemLinks.map((x) => x.dfid));
}

Exemplo de chave: partner_internal_id:ROW-1

API disponível

Ingestão

• upload(input)
• previewUpload(input)

API keys

• createApiKey(payload)
• listApiKeys()
• revokeApiKey(keyId)
• apiKeyMetrics(keyId)

Roteamento

• listRoutingRules(identifierType?)
• upsertRoutingRule(payload)
• deleteRoutingRule(ruleId)
• listRoutingIssues(limit?)

Payload bruto

• listRawPayloads(limit?)
• downloadRawPayload(rawPayloadId)

Tratamento de erro

Erros de API retornam PartnerApiError:

try {
  await client.listRoutingRules();
} catch (err) {
  if (err instanceof PartnerApiError) {
    console.error(err.status, err.message, err.details);
  }
}

Retry/backoff

Por padrão, o cliente faz retry apenas para métodos seguros (GET) em status transitórios (408, 429, 500, 502, 503, 504).

Exemplo:

const client = new DefarmPartnerClient({
  gatewayBaseUrl: "https://gateway.defarm.net",
  apiKey: process.env.DEFARM_PARTNER_KEY,
  retry: {
    maxRetries: 3,
    baseDelayMs: 200,
    maxDelayMs: 3000,
    retryUnsafeMethods: false,
  },
});

Se quiser habilitar retry também em POST, use retryUnsafeMethods: true (recomendado apenas quando seu fluxo estiver preparado para reenvio).

Validação de schema da resposta

Use responseValidation: \"strict\" para validar shape das respostas principais de parceiro antes de consumir no seu sistema.

Quando inválido, o cliente dispara PartnerApiError com mensagem: Schema validation failed ....

Build e teste

npm run check
npm test

Publicação no npm

npm publish --access public