web-lina-pay-sdk

name

web-lina-pay-sdk

description

Documentação e integração do pacote npm @lina-openx/web-lina-pay-sdk (Lina OpenX / Open Finance). Use este skill sempre que o utilizador pedir ajuda com este SDK: exemplos de chamadas, payloads TypeScript, tipos exportados, fluxos de consentimento, payment request, getPaymentRequest, pagamento OAuth, enrollment e FIDO, participantes, configure / ambientes IAM e API, LinaPayError, ou organização do repo web-lina-pay-sdk. Inclua também pagamento automático/recorrente: createAutomaticPaymentRequest, getAutomaticPaymentRequest, CreateAutomaticPaymentRequest, AutomaticPaymentRequestCreated, GetAutomaticPaymentRequest, AutomaticPaymentRequest, autenticação com LinaPayCredentials ou TokenCredentials (access_token direto, sem IAM no SDK para esse fluxo), sweeping/automatic. Inclua contas de recebimento e identificadores bancários (ISPB): createReceivingAccount, listReceivingAccounts, getReceivingAccount, updateReceivingAccount, deleteReceivingAccount, getBankIdentifiers, getBankIdentifier, tipos ReceivingAccount, BankIdentifier, GetBankIdentifiersRequest, GetBankIdentifierRequest, rotas sub-tenants-accounts (incl. /bank-identifiers), RECEIVING_ACCOUNTS. Prefira consultar README.md na raiz e reference.md nesta pasta.

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)

Seção README	O que cobre
Descrição	Escopo do SDK (consentimento, payment request, pagamento automático/recorrente, contas de recebimento do subtenant, consulta de payment request, pagamento, enrollment, participantes, FIDO/WebAuthn).
Instalação	npm / yarn / pnpm para @lina-openx/web-lina-pay-sdk.
Como usar → Importação	Funções e LinaPayError exportados pelo pacote.
Configuração inicial	configure({ iamBaseUrl, apiBaseUrl }) — HML vs produção.
Métodos 1–12 + §13 contas / ISPB	API pública: 1–11 README; §12 pagamento automático (12.1 criação, 12.2 consulta getAutomaticPaymentRequest); §13 cinco funções de contas de recebimento + §13.6–13.7 getBankIdentifiers / getBankIdentifier (identificadores bancários); ver tabela abaixo.
Organização de pastas	src/config, controllers, services, types, utils, index.ts.
Como rodar localmente	Node 18+, scripts dev, test, format, build, ci, clone, pasta example/.
Tratamento de erros	try/catch, instanceof LinaPayError, statusCode.
Tipos principais	Credenciais (LinaPayCredentials, TokenCredentials para automatic-payments e para contas/ISPB quando aplicável), consentimento, CreatePaymentRequestDTO, CreateAutomaticPaymentRequest / AutomaticPaymentRequestCreated / GetAutomaticPaymentRequest / AutomaticPaymentRequest, ReceivingAccount, , , , DTOs de contas de recebimento, , + , demais tipos citados nos exemplos.

Métodos públicos (ordem do README)

#	Função	Resumo
1	configure	URLs base IAM e API (LinaPayConfig).
2	createConsent	Consentimento de pagamento (CreateConsentRequest → CreateConsentResponse).
3	createPayment	Pagamento pós-OAuth (CreatePaymentRequest: state, code, idToken, tenantId → CreatePaymentResponse).
4	createPaymentRequest	Solicitação de pagamento distinta de createPayment (CreatePaymentRequestDTO → Promise<PaymentRequestCreated>: id, redirectUri); validação Zod; erro Invalid payload.
5	getPaymentRequest	Consulta detalhes (GET …/requests/:id); (credentials, id) → Promise<PaymentRequestData>; o id costuma ser PaymentRequestCreated.id; SDK devolve só o data do envelope; datas ISO em string (não Date em runtime) — ver tabela de campos no README §5.
6	createEnrollment	Enrollment FIDO (CreateEnrollmentRequest → CreateEnrollmentResponse).
7	registerDevice	Callback pós-enrollment (RegisterDeviceRequest → tipo exportado como Enrollment).
8	getEnrollmentList	Lista por CPF (EnrollmentList).
9	revokeEnrollment	Revoga por ID (RevokeEnrollmentResponse).
10	createPaymentWithEnrollment	Pagamento com enrollment (PaymentWithEnrollmentRequest → RetornoJsrPaymentDto).

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 o integrador passa já válido. e ( … ) aceitam o no primeiro argumento — ver controllers. Outros métodos (ex.: consentimento clássico, ) podem continuar só com ; confirmar assinatura em se houver dúvida.

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.

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).