@connectabil/match-sdk

SDK em TypeScript para consultar o mecanismo de matching entre vagas e candidatos indexados no Elasticsearch. O pacote encapsula autenticação, aplicação de filtros estruturados e cálculo do score híbrido (vetor + sinais adicionais) utilizado pelo serviço interno.

Instalação

npm install @connectabil/match-sdk
# ou
yarn add @connectabil/match-sdk

Uso rápido

import { MatchSdk } from '@connectabil/match-sdk';

const sdk = new MatchSdk({
  node: process.env.ELASTICSEARCH_NODE!,
  auth: {
    username: process.env.ELASTICSEARCH_USERNAME,
    password: process.env.ELASTICSEARCH_PASSWORD,
    apiKey: process.env.ELASTICSEARCH_API_KEY,
  },
  vacancyIndex: 'matching-vacancies',
  candidateIndex: 'matching-candidates',
});

// Buscar candidatos compatíveis com uma vaga
const candidates = await sdk.searchCandidatesForVacancy({
  vacancyId: 12345,
  limit: 10,
  filters: {
    states: ['SP'],
    salaryRange: { min: 5000, max: 12000 },
    systems: ['SAP', 'Totvs'],
    ageGroups: ['26-35', '36-45'],
    matchCompanyCulturalFit: true,
  },
});

// Buscar vagas compatíveis com um candidato
const vacancies = await sdk.searchVacanciesForCandidate({
  candidateId: 'cand_abc123',
  limit: 5,
  filters: {
    planTypes: ['Enterprise'],
    jobTypes: ['assessment'],
    createdAtRange: {
      start: new Date('2024-01-01'),
    },
  },
});

Cada item retornado contém:

• vectorScore: score retornado pelo Elasticsearch (similaridade vetorial);
• finalScore: score híbrido ponderado;
• scoreDetails: detalhamento por componente (último login, aderência de posições, distância geográfica etc.);
• payload: metadados replicados no índice do Elasticsearch.

Filtros disponíveis

• Candidatos

  • Localização (states, cities, zones, geoRadius)
  • Remuneração (salaryRange)
  • Sinais (hasCRC, isEmployed, minTestsAnswered)
  • Cultura (culturalFits, matchCompanyCulturalFit)
  • Competências (systems, skills, positions, languages)
  • Faixas etárias (ageGroups)
  • Termo de busca semântica (searchTerm)

• Vagas

  • Plano/tipo/status (planTypes, jobTypes, statuses)
  • Área/empresa (positionTitles, companyIds)
  • Localização (states, cities, zones, geoRadius)
  • Sistemas, cultura, responsáveis, códigos (systems, culturalFits, responsibleEmails, codes, internalCodes)
  • Intervalo de salários (salaryRange)
  • Data de criação (createdAtRange)

Score híbrido

A função computeCandidateMatchScore exportada pelo pacote pode ser utilizada para recalcular ou auditar o score. Os pesos padrão seguem a ordem de prioridade:

1. Último login
2. Similaridade vetorial
3. Aderência de posições
4. Experiências recentes
5. Proximidade geográfica
6. Compatibilidade salarial
7. Sistemas
8. Skills
9. Testes técnicos

Pesos customizados podem ser informados tanto no construtor (scoreWeights) quanto por requisição (query.scoreWeights).

Build local

cd packages/match-sdk
yarn install --ignore-scripts # se necessário
yarn build

O output é emitido em dist/ (ESM + declarações). Certifique-se de executar yarn build antes de publicar no npm.

Licença

Uso interno – consulte a equipe Connectabil antes de distribuir publicamente.