Web Lina Pay Sdk

Web Lina Pay SDK — skill de documentação

Skill para orientar assistentes e desenvolvedores com base na documentação oficial do SDK e nas tipagens de referência.

Fonte da verdade (ordem de consulta)

1. README.md na raiz do repositório — descrição, instalação, métodos, exemplos, estrutura de pastas, execução local, erros e tipos principais.
2. reference.md (nesta pasta) — catálogo consolidado de tipagens alinhado ao README e ao que o pacote exporta em src/types/index.ts e src/index.ts (inclui pagamento automático / recorrente e contas de recebimento em § dedicados).
3. Código em src/ — quando o README não cobrir um detalhe ou houver divergência; prefira citar arquivos concretos (controllers/, services/, types/).

Mapa do README (seções → conteúdo)

Métodos públicos (ordem do README)

Distinções importantes (evitar confusão)

• createPayment vs createPaymentRequest: o primeiro finaliza fluxo com tokens OAuth; o segundo envia dados do pagamento (valor, credor, redirect, schedule etc.) e retorna PaymentRequestCreated (id, redirectUri).
• createPaymentRequest vs getPaymentRequest: o primeiro cria a solicitação (POST) e retorna PaymentRequestCreated (id, redirectUri); o segundo consulta (GET) e retorna PaymentRequestData (objeto completo tipado no README e em reference.md).
• createPaymentRequest vs createAutomaticPaymentRequest: ambos usam POST no mesmo path base de pagamentos (PAYMENTS_REQUEST), mas o payload é diferente — DTO de solicitação simples (redirectUri, value, creditor, schedule…) vs consentimento recorrente (redirectUrl, details, recurringConsent com automatic ou sweeping). Retornos distintos: PaymentRequestCreated (id) vs AutomaticPaymentRequestCreated (paymentRequestId, redirectUrl). Ver README §12.1 e reference.md § pagamento automático.
• createAutomaticPaymentRequest vs getAutomaticPaymentRequest: primeiro cria (POST); segundo consulta (GET com paymentRequestId no path). Ambos aceitam LinaPayCredentials | TokenCredentials — ver README §12.
• LinaPayCredentials vs TokenCredentials: no primeiro o SDK obtém o Bearer no IAM quando subtenantId está presente; com TokenCredentials o integrador passa access_token já válido. Pagamento automático e contas de recebimento / identificadores bancários (createReceivingAccount … getBankIdentifier) aceitam o union LinaPayCredentials | TokenCredentials no primeiro argumento — ver controllers. Outros métodos (ex.: consentimento clássico, createPaymentRequest) podem continuar só com LinaPayCredentials; confirmar assinatura em src/index.ts se houver dúvida.
• CreatePaymentRequest (OAuth) vs CreatePaymentRequestDTO (solicitação de pagamento): nomes parecidos, payloads completamente diferentes — ver reference.md.
• Credenciais IAM (LinaPayCredentials.subtenantId / subtenantSecret) vs subTenantId no payload das contas de recebimento: o primeiro serve para obter o Bearer; o segundo é o segmento :subTenantId na URL da API de contas (/api/v1/sub-tenants-accounts/...). Podem coincidir ou não, conforme o modelo da integração — ver README §13.
• listReceivingAccounts vs getReceivingAccount / deleteReceivingAccount: a listagem valida só subTenantId; consulta e exclusão exigem também accountId (schemas distintos em receiving-accounts.utils.ts).

Como responder perguntas sobre o SDK

• Preferir exemplos em TypeScript alinhados ao README (nomes de campos e enums: PESSOA_NATURAL, CACC, dias da semana em português com _FEIRA, etc.).
• Mencionar configure quando o ambiente não for o padrão.
• Para payloads de createPaymentRequest, lembrar que a validação runtime exige schedule presente (pode ser {}) conforme documentação do README.
• Para createAutomaticPaymentRequest e getAutomaticPaymentRequest, o primeiro argumento pode ser { access_token } (TokenCredentials) quando o token já existir; caso contrário { subtenantId, subtenantSecret }. Resolução em resolveAutomaticPaymentsAccessToken em automatic-payments.controller.ts.
• Para createAutomaticPaymentRequest, o payload é inferido do schema Zod (CreateAutomaticPaymentRequest): recurringConfiguration deve ter apenas um ramo (automatic ou sweeping); dentro de sweeping.periodicLimits, apenas um de day | week | month | year. Campos monetários/configuração vêm em grande parte como string (ex.: amount, totalAllowedAmount). Detalhe completo em reference.md.
• Para getAutomaticPaymentRequest, validar paymentRequestId não vazio; retorno AutomaticPaymentRequest é extenso — remeter a reference.md / automatic-payment.types.ts.
• Para getPaymentRequest, usar created.id após createPaymentRequest (padrão do README §5); implementação em src/controllers/payment.controller.ts / getPaymentRequestService em src/services/payment.service.ts.
• Para contas de recebimento e identificadores bancários, lembrar validação Zod (Invalid payload): listagem de contas ≠ por accountId; updateReceivingAccount envia o objeto payload completo no PATCH (inclui subTenantId e accountId no corpo, conforme serviço atual). getBankIdentifiers / getBankIdentifier não usam subTenantId na URL (endpoints globais sob RECEIVING_ACCOUNTS); retornam BankIdentifier (name, ispb).
• Tipos exportados: PaymentRequestCreated, PaymentRequestData, PaymentRequestPaymentItem, TokenCredentials, CreateAutomaticPaymentRequest, AutomaticPaymentRequestCreated, GetAutomaticPaymentRequest, AutomaticPaymentRequest, ReceivingAccount, BankIdentifier, GetBankIdentifiersRequest, GetBankIdentifierRequest e DTOs de contas de recebimento — ver README “Tipos principais” e reference.md.
• Erros: descrever LinaPayError e uso de statusCode quando aplicável.

Progressive disclosure

• Para assinaturas completas, unions e interfaces aninhadas, abrir reference.md nesta pasta em vez de duplicar tudo no corpo deste skill (inclui § Autenticação com TokenCredentials, § Pagamento automático com criação/consulta e tipo AutomaticPaymentRequest, e § Contas de recebimento com identificadores bancários e tipos BankIdentifier / requests associados).
• Para comportamento HTTP ou endpoints, seguir src/config/environment.ts (ENDPOINTS: RECEIVING_ACCOUNTS = /api/v1/sub-tenants-accounts, PAYMENTS_REQUEST, etc.) e serviços em src/services/ (receiving-accounts.service.ts, automatic-payments.service.ts).

Idioma

• Responder em português quando o usuário do projeto utilizar português (alinhado ao README e ao repositório).