feat: adding 3ds feature

[aqudsilva]

Implementação de Suporte a 3DS (3D Secure) em Orders

🔍 Processo de Descoberta e Implementação

Esta seção documenta o passo a passo completo para implementar novas features no SDK, servindo como guia para futuras implementações.

1. Monitoramento de Mudanças

Canal de comunicação: mp-op-public-order-updates

• Acompanhar anúncios de mudanças na API
• Identificar novas features ou campos adicionados
• Verificar se há breaking changes ou apenas adições

Neste caso: Foi anunciada a feature de 3DS (3D Secure) para Orders.

2. Verificação no Fury Spec Hub

O que fazer:

1. Verificar se há uma nova versão stable do swagger
2. Localizar os endpoints e exemplos correspondentes à mudança anunciada

Neste caso:

• Encontrada spec com exemplo: "POST /v1/orders - Online with 3DS"
• Nós do JSON identificados:

  config:
    online:
      transaction_security:
        validation: "on_fraud_risk"
        liability_shift: "required"

3. Análise da Spec e Exemplos

O que analisar no swagger:

• Request Schema: Quais campos novos foram adicionados
• Response Schema: O que a API retorna de novo
• Exemplos: Casos de uso práticos (ex: "Online - Payment with 3DS")
• Campos obrigatórios vs opcionais

Neste caso:

• Request

  transaction_security:
    type: object
    properties:
      validation:
        type: string
        enum: [always, on_fraud_risk, never]
      liability_shift:
        type: string
        enum: [required, preferred]

• Response

  payment_method:
    transaction_security:
      url: "https://..." # URL do Challenge
      validation: "on_fraud_risk"
      liability_shift: "required"
      type: "string"
      status: "string"

4. Mapeamento para Estrutura do SDK Node.js

4.1 Entendendo a Estrutura de Pastas

src/
├── clients/
│   └── order/
│       ├── commonTypes.ts           # Tipos compartilhados (Request/Response)
│       ├── create/
│       │   └── types.ts            # Tipos específicos do Create
│       ├── get/
│       │   └── types.ts            # Tipos específicos do Get
│       └── index.ts                # Cliente principal
│
├── examples/
│   └── order/
│       ├── create.ts
│       ├── createWith3DS.ts        # [NOVO] Exemplo com 3DS
│       └── handle3DSResponse.ts    # [NOVO] Tratamento de respostas
│
└── e2e/
    └── order/
        ├── create.spec.ts
        ├── create3DS.spec.ts       # [NOVO] Testes 3DS
        └── get3DS.spec.ts          # [NOVO] Testes de consulta

4.2 Mapeamento JSON → Tipos TypeScript

Regra geral:

• Cada objeto no JSON vira um type ou interface
• Cada propriedade no JSON vira uma property no tipo
• snake_case (JSON) → camelCase (TypeScript)
• Separar tipos de Request e Response quando necessário

Exemplo deste caso:

// JSON Request:
// config: {
//   online: {
//     transaction_security: {
//       validation: "on_fraud_risk",
//       liability_shift: "required"
//     }
//   }
// }

// Mapeamento TypeScript:
export declare type OnlineConfig = {
	callback_url?: string;
	// ... outras propriedades existentes
	transaction_security?: TransactionSecurity; // [NOVA PROPRIEDADE]
};

export declare type TransactionSecurity = {
	validation?: "always" | "on_fraud_risk" | "never";
	liability_shift?: "required" | "preferred";
};

// JSON Response:
// payment_method: {
//   transaction_security: {
//     url: "https://...",
//     validation: "on_fraud_risk",
//     liability_shift: "required",
//     type: "string",
//     status: "string"
//   }
// }

// Mapeamento TypeScript:
export declare type PaymentMethodResponse = {
	id?: string;
	// ... outras propriedades existentes
	transaction_security?: TransactionSecurityResponse; // [NOVA PROPRIEDADE]
};

export declare type TransactionSecurityResponse = {
	validation?: "always" | "on_fraud_risk" | "never";
	liability_shift?: "required" | "preferred";
	url?: string; // URL do Challenge
	type?: string; // Tipo de autenticação
	status?: string; // Status da autenticação
};

5. Implementação dos Tipos

5.1 Tipos Compartilhados (commonTypes.ts)

Arquivo: src/clients/order/commonTypes.ts

/**
 * 3DS Transaction Security types for requests
 */
export declare type TransactionSecurity = {
	validation?: "always" | "on_fraud_risk" | "never";
	liability_shift?: "required" | "preferred";
};

/**
 * 3DS Transaction Security types for responses
 */
export declare type TransactionSecurityResponse = {
	validation?: "always" | "on_fraud_risk" | "never";
	liability_shift?: "required" | "preferred";
	url?: string;
	type?: string;
	status?: string;
};

Pontos importantes:

• Union types para valores específicos ('always' | 'on_fraud_risk' | 'never')
• Separação clara entre Request e Response
• Documentação JSDoc para cada tipo

5.2 Integração com Tipos Existentes

Modificações necessárias:

// OnlineConfig (para requests)
export declare type OnlineConfig = {
	// ... propriedades existentes
	transaction_security?: TransactionSecurity;
};

// PaymentMethodResponse (para responses)
export declare type PaymentMethodResponse = {
	// ... propriedades existentes
	transaction_security?: TransactionSecurityResponse;
};

// PaymentMethodRequest (para create requests)
export declare type PaymentMethodRequest = {
	// ... propriedades existentes
	transaction_security?: TransactionSecurity;
};

6. Estrutura Completa do SDK (Resumo)

clients/
  └─ [recurso]/
      ├─ commonTypes.ts              # Tipos compartilhados
      ├─ create/
      │   ├─ types.ts               # Tipos específicos do Create
      │   └─ index.ts               # Implementação do Create
      ├─ get/
      │   ├─ types.ts               # Tipos específicos do Get
      │   └─ index.ts               # Implementação do Get
      └─ index.ts                   # Cliente principal

examples/
  └─ [recurso]/
      ├─ create.ts                  # Exemplo básico
      ├─ [featureEspecial].ts       # Ex: createWith3DS.ts
      └─ README_[FEATURE].md        # Documentação específica

e2e/
  └─ [recurso]/
      ├─ create.spec.ts             # Testes básicos
      └─ [feature].spec.ts          # Ex: create3DS.spec.ts

Fluxo de uma chamada:

1. Usuário cria objeto com tipos TypeScript
2. Chama order.create({ body: orderData })
3. SDK serializa para JSON
4. Envia POST para API
5. Recebe JSON de resposta
6. SDK deserializa usando tipos TypeScript
7. Usuário acessa response.transactions?.payments?.[0].payment_method?.transaction_security?.url

🎯 Objetivo

Permitir que integradores implementem autenticação 3DS em suas transações através do SDK Node.js, com:

• Configuração flexível de quando executar o 3DS (validation)
• Gestão de transferência de responsabilidade (liability_shift)
• Tratamento adequado do fluxo de Challenge
• Documentação completa e exemplos práticos
• Tipagem TypeScript completa

🔧 Alterações Técnicas

Arquivos Modificados

1. src/clients/order/commonTypes.ts

• Adicionados tipos TransactionSecurity e TransactionSecurityResponse
• Modificado OnlineConfig para incluir transaction_security?: TransactionSecurity
• Modificado PaymentMethodResponse para incluir transaction_security?: TransactionSecurityResponse

2. src/clients/order/create/types.ts

• Adicionado import de TransactionSecurity
• Modificado PaymentMethodRequest para incluir transaction_security?: TransactionSecurity

Novos Arquivos Criados

3. src/examples/order/createWith3DS.ts

Exemplo completo mostrando:

• Como configurar uma Order com 3DS
• Como verificar se o Challenge é necessário
• Como processar a resposta e obter a URL do Challenge

const response = await order.create({
	body: {
		type: "online",
		config: {
			online: {
				transaction_security: {
					validation: "on_fraud_risk",
					liability_shift: "required",
				},
			},
		},
		// ... demais campos
	},
});

4. src/examples/order/handle3DSResponse.ts

Exemplo de tratamento de diferentes cenários 3DS:

• Verificação de status após Challenge
• Tratamento de timeouts e falhas
• Código JavaScript para iframe handler

5. e2e/order/create3DS.spec.ts

Testes de integração para:

• Criação de Orders com diferentes configurações 3DS
• Validação de tipos e estruturas de resposta
• Cenários de Challenge e aprovação direta

6. e2e/order/get3DS.spec.ts

Testes de consulta para:

• Verificação de dados 3DS em Orders existentes
• Validação de diferentes status de pagamento
• Estrutura de resposta com informações 3DS