Webhook Centralizer SDK

SDK para gerenciamento de plataformas de webhook e centralização de eventos de plataformas de pagamento.

Instalação

npm install @agenus-io/webhook-centralizer
# ou
yarn add @agenus-io/webhook-centralizer
# ou
pnpm add @agenus-io/webhook-centralizer

Funcionalidades

Este SDK fornece funcionalidades para gerenciar plataformas de webhook e centralizar eventos de plataformas de pagamento, permitindo:

1. Gerenciamento de Plataformas: CRUD completo de plataformas de webhook
2. Consulta de Webhooks: Listagem e consulta de webhooks processados
3. KPIs: Métricas de aceitação e rejeição de webhooks
4. Configurações: Consulta de configurações disponíveis de plataformas

Uso

Configuração Inicial

import { WebhookCentralizerSDK } from "@agenus-io/webhook-centralizer";

// Configure o SDK com suas credenciais da aplicação
const appId = process.env.APP_ID!;
const appToken = process.env.APP_TOKEN!;
const environment = process.env.NODE_ENV === "production" ? "production" : "develop";

const sdk = new WebhookCentralizerSDK(appId, appToken, environment);

1. Criar Plataforma de Webhook

import { WebhookCentralizerPlatformEnum, WebhookPlatformRoleEnum } from "@agenus-io/webhook-centralizer";

const result = await sdk.Create({
  workSpaceId: "workspace-123",
  title: "Plataforma Hotmart",
  type: WebhookCentralizerPlatformEnum.HOTMART,
  role: WebhookPlatformRoleEnum.PRODUCER,
  platformToken: "token-da-plataforma", // opcional
  apiToken: "api-token", // opcional
  slug: "hotmart-slug", // opcional
  meta: { // opcional
    customField: "value"
  },
});

if (result.isError) {
  console.error("Erro ao criar plataforma:", result.error);
} else {
  console.log("Plataforma criada com sucesso! ID:", result.id);
}

2. Listar Plataformas

const result = await sdk.Get({
  workSpaceId: "workspace-123",
  page: 1,
  pageSize: 10,
  filter: undefined, // opcional - filtro de busca
});

console.log(result.data); // Array de plataformas
console.log(result.meta); // Metadados de paginação
// {
//   total: 50,
//   totalPages: 5,
//   page: 1,
//   pageSize: 10
// }

3. Buscar Plataforma por ID

const result = await sdk.GetById({
  id: "platform-id-123",
  workSpaceId: "workspace-123",
});

if (result.isError) {
  console.error("Erro ao buscar plataforma:", result.error);
} else {
  console.log("Plataforma encontrada:", result.data);
}

4. Buscar Plataforma por Título

const result = await sdk.GetByTitle({
  title: "Plataforma Hotmart",
  workSpaceId: "workspace-123",
});

console.log("Plataforma encontrada:", result);

5. Atualizar Plataforma

const result = await sdk.Update({
  id: "platform-id-123",
  workSpaceId: "workspace-123",
  title: "Plataforma Atualizada", // opcional
  platformToken: "novo-token", // opcional
  // Apenas os campos que deseja atualizar
});

if (result.isError) {
  console.error("Erro ao atualizar plataforma:", result.error);
} else {
  console.log("Plataforma atualizada com sucesso!");
}

6. Deletar Plataforma

const result = await sdk.Delete({
  id: "platform-id-123",
  workSpaceId: "workspace-123",
});

if (result.isError) {
  console.error("Erro ao deletar plataforma:", result.error);
} else {
  console.log("Plataforma deletada com sucesso!");
}

7. Listar Webhooks de uma Plataforma

import { WebhookCentralizerStatusEnum } from "@agenus-io/webhook-centralizer";

const result = await sdk.GetWebhooks({
  id: "platform-id-123",
  workSpaceId: "workspace-123",
  page: 1,
  pageSize: 10,
  filter: undefined, // opcional
  status: WebhookCentralizerStatusEnum.COMPLETED, // opcional - filtrar por status
});

console.log(result.data); // Array de webhooks
console.log(result.meta); // Metadados de paginação

8. Buscar Webhook por ID

const result = await sdk.GetWebhookById({
  id: "webhook-id-123",
  workSpaceId: "workspace-123",
});

if (result.isError) {
  console.error("Erro ao buscar webhook:", result.error);
} else {
  console.log("Webhook encontrado:", result.data);
}

9. Consultar Configurações de Plataformas Disponíveis

const result = await sdk.GetPlatformSettings();

console.log(result.data); // Array de configurações disponíveis
// Cada configuração contém informações sobre:
// - Plataformas suportadas
// - Se tem PostBack
// - Se tem Token
// - Se tem Slug
// - Se tem API
// - Se está em preparação

10. Consultar KPIs

import { 
  WebhookCentralizerStatusEnum, 
  WebhookCentralizerEventEnum 
} from "@agenus-io/webhook-centralizer";

const result = await sdk.Kpi({
  id: "platform-id-123",
  workSpaceId: "workspace-123",
  status: [
    WebhookCentralizerStatusEnum.COMPLETED,
    WebhookCentralizerStatusEnum.PROCESSING
  ],
  event: [
    WebhookCentralizerEventEnum.PURCHASE_CONFIRMED,
    WebhookCentralizerEventEnum.PURCHASE_PENDING
  ],
});

console.log("Total:", result.total);
console.log("Aceitos:", result.amountAccepted);
console.log("Rejeitados:", result.amountRejected);

Tipos Exportados

webhookCentralizerPlatform

Plataformas de pagamento suportadas:

type webhookCentralizerPlatform = 
  | "BEMONY" 
  | "B4YOU" 
  | "BRAIP" 
  | "CARTPANDA" 
  | "NUTRALINK" 
  | "HOTMART" 
  | "KIRVANO" 
  | "KIWIFY" 
  | "LAST_LINK" 
  | "PAYT" 
  | "DIGISTORE";

webhookCentralizerEvent

Eventos de webhook suportados:

type webhookCentralizerEvent = 
  | "ABANDONED_CART"
  | "PURCHASE_UPSELL"
  | "PURCHASE_CONFIRMED"
  | "PURCHASE_PENDING"
  | "PURCHASE_EXPIRED"
  | "PURCHASE_CANCELED"
  | "PURCHASE_SHIPPED"
  | "PURCHASE_REFUND"
  | "PURCHASE_UPDATED"
  | "PURCHASE_CHARGEBACK"
  | "SUBSCRIPTION_INITIATED"
  | "SUBSCRIPTION_RENEWAL"
  | "SUBSCRIPTION_RENEWAL_PENDING"
  | "SUBSCRIPTION_UPDATED"
  | "SUBSCRIPTION_CANCELED"
  | "SUBSCRIPTION_EXPIRED"
  | "SUBSCRIPTION_RENEWAL_CANCELLED"
  | "SUBSCRIPTION_RENEWAL_RESUMED"
  | "REJECTED"
  | "UNKNOWN";

webhookCentralizerOrderStatus

Status de pedidos:

type webhookCentralizerOrderStatus = 
  | "PENDING" 
  | "PROCESSING" 
  | "COMPLETED" 
  | "FAILED";

webhookCentralizerDispatchType

Tipo de despacho:

type webhookCentralizerDispatchType = "WEBHOOK" | "POST_BACK";

webhookPlatformRole

Papel da plataforma:

type webhookPlatformRole = "PRODUCER" | "CO_PRODUCER" | "AFFILIATE";

Enums Disponíveis

O SDK exporta enums para facilitar o uso:

import {
  WebhookCentralizerPlatformEnum,
  WebhookCentralizerEventEnum,
  WebhookCentralizerStatusEnum,
  WebhookCentralizerDispatchTypeEnum,
  WebhookPlatformRoleEnum,
} from "@agenus-io/webhook-centralizer";

// Exemplo de uso
const platform = WebhookCentralizerPlatformEnum.HOTMART;
const event = WebhookCentralizerEventEnum.PURCHASE_CONFIRMED;
const status = WebhookCentralizerStatusEnum.COMPLETED;

Tipos de Dados Centralizados

O SDK também exporta tipos para estruturas de dados centralizadas:

import type {
  ICentralizedSaleDTO,
  ICentralizedSubscriptionDTO,
  ICentralizedAbandonedCartDTO,
} from "@agenus-io/webhook-centralizer";

Variáveis de Ambiente

As credenciais da aplicação devem ser fornecidas ao instanciar o SDK. Recomendamos usar variáveis de ambiente:

APP_ID=your-app-id
APP_TOKEN=your-app-token
NODE_ENV=production # ou develop

Exemplo Completo

import { 
  WebhookCentralizerSDK,
  WebhookCentralizerPlatformEnum,
  WebhookPlatformRoleEnum,
  WebhookCentralizerStatusEnum,
  WebhookCentralizerEventEnum,
} from "@agenus-io/webhook-centralizer";

// 1. Configurar SDK
const sdk = new WebhookCentralizerSDK(
  process.env.APP_ID!,
  process.env.APP_TOKEN!,
  process.env.NODE_ENV === "production" ? "production" : "develop"
);

// 2. Criar uma nova plataforma
async function criarPlataforma() {
  const result = await sdk.Create({
    workSpaceId: "workspace-123",
    title: "Minha Plataforma Hotmart",
    type: WebhookCentralizerPlatformEnum.HOTMART,
    role: WebhookPlatformRoleEnum.PRODUCER,
    platformToken: "token-da-plataforma",
  });

  if (result.isError) {
    console.error("Erro:", result.error);
    return;
  }

  console.log("Plataforma criada com ID:", result.id);
  return result.id;
}

// 3. Listar todas as plataformas
async function listarPlataformas(workSpaceId: string) {
  const result = await sdk.Get({
    workSpaceId,
    page: 1,
    pageSize: 10,
  });

  console.log(`Total de plataformas: ${result.meta.total}`);
  result.data.forEach(platform => {
    console.log(`- ${platform.title} (${platform.type})`);
    console.log(`  Aceitos: ${platform.amountAccepted}, Rejeitados: ${platform.amountRejected}`);
  });
}

// 4. Consultar webhooks de uma plataforma
async function consultarWebhooks(platformId: string, workSpaceId: string) {
  const result = await sdk.GetWebhooks({
    id: platformId,
    workSpaceId,
    page: 1,
    pageSize: 20,
    status: WebhookCentralizerStatusEnum.COMPLETED,
  });

  console.log(`Total de webhooks: ${result.meta.total}`);
  result.data.forEach(webhook => {
    console.log(`- ${webhook.event} (${webhook.status}) - ${webhook.code}`);
  });
}

// 5. Consultar KPIs
async function consultarKPIs(platformId: string, workSpaceId: string) {
  const result = await sdk.Kpi({
    id: platformId,
    workSpaceId,
    status: [
      WebhookCentralizerStatusEnum.COMPLETED,
      WebhookCentralizerStatusEnum.PROCESSING,
    ],
    event: [
      WebhookCentralizerEventEnum.PURCHASE_CONFIRMED,
      WebhookCentralizerEventEnum.PURCHASE_PENDING,
    ],
  });

  console.log("KPIs da Plataforma:");
  console.log(`Total: ${result.total}`);
  console.log(`Aceitos: ${result.amountAccepted}`);
  console.log(`Rejeitados: ${result.amountRejected}`);
  console.log(`Taxa de sucesso: ${((result.amountAccepted / result.total) * 100).toFixed(2)}%`);
}

// 6. Fluxo completo
async function exemploCompleto() {
  const workSpaceId = "workspace-123";

  // Listar plataformas existentes
  await listarPlataformas(workSpaceId);

  // Criar nova plataforma
  const platformId = await criarPlataforma();

  if (platformId) {
    // Consultar webhooks
    await consultarWebhooks(platformId, workSpaceId);

    // Consultar KPIs
    await consultarKPIs(platformId, workSpaceId);
  }
}

Tratamento de Erros

Todos os métodos que podem retornar erros seguem o padrão:

const result = await sdk.Create({ /* ... */ });

if (result.isError) {
  // Tratar erro
  console.error("Erro:", result.error);
} else {
  // Sucesso
  console.log("ID:", result.id);
}

Para métodos que lançam exceções (Get, GetByTitle, GetWebhooks), use try/catch:

try {
  const result = await sdk.Get({
    workSpaceId: "workspace-123",
    page: 1,
    pageSize: 10,
  });
  // Processar resultado
} catch (error) {
  console.error("Erro ao listar plataformas:", error);
}

Ambientes

O SDK suporta dois ambientes:

• production: Conecta-se a https://webhook-centralizer-production.up.railway.app
• develop: Conecta-se a https://service-webhook-develop.up.railway.app

O ambiente é definido no construtor:

const sdk = new WebhookCentralizerSDK(
  appId,
  appToken,
  "production" // ou "develop"
);

API de Webhooks

O SDK se conecta à API de centralização de webhooks hospedada em:

• Produção: https://webhook-centralizer-production.up.railway.app
• Desenvolvimento: https://service-webhook-develop.up.railway.app

Todas as operações utilizam autenticação via headers:

• app-id: ID da aplicação
• app-secret-token: Token secreto da aplicação
• work-space-id: ID do workspace (quando aplicável)

Schemas de Validação

O SDK exporta schemas Zod para validação:

import {
  WebhookCentralizerCreatePlatformSchema,
  WebhookCentralizerUpdatePlatformSchema,
  WebhookCentralizerGetPlatformsSchema,
  WebhookCentralizerGetPlatformWebhooksSchema,
} from "@agenus-io/webhook-centralizer";

// Validar dados antes de criar
const data = WebhookCentralizerCreatePlatformSchema.parse({
  title: "Minha Plataforma",
  type: "HOTMART",
  role: "PRODUCER",
});

Manutenção

Quando houver atualizações no SDK:

1. A versão será atualizada no npm
2. Atualize o pacote nos seus apps: npm update @agenus-io/webhook-centralizer
3. Se houver breaking changes, serão documentados nas release notes

Segurança

⚠️ IMPORTANTE: Nunca commite credenciais ou tokens no código fonte. Sempre use variáveis de ambiente ou serviços de gerenciamento de segredos.

Suporte

Para questões ou problemas, abra uma issue no repositório do projeto.