@codedartdev/coinsentry-kyc-react

Consulte o changelog para as mudanças da versão coordenada.

Hook React headless para o KYC universal CoinSentry. O pacote entrega estado, navegacao permitida e helpers de submit/upload, mas nao renderiza layout nem decide fluxo localmente.

Instalação coordenada

0.2.0 é publicada diretamente no dist-tag npm latest. Instale KYC React com as mesmas versões do SDK e do provider React:

npm install @codedartdev/[email protected] @codedartdev/[email protected] @codedartdev/[email protected]

Em uma aplicação Next completa, mantenha também @codedartdev/[email protected]. Não misture versões internas da série coordenada.

Responsabilidade

• useCoinSentryKycFlow.
• Preservar requirements resolvidos server-side como anchor.
• Usar apenas endpoints de overview/status permitidos no browser.
• Enviar steps pelos endpoints configurados pelo contrato do backend.
• Expor submitCurrentStep e uploadForCurrentStep para UI customizada.
• Expor estados isLoading, isRefreshing, isSubmitting, isUploading e error.

Fora Do Escopo

• Wizard visual obrigatorio.
• Componentes de formulario especificos da whitelabel.
• Chamada browser para /api/v1/kyc/requirements.
• Setters publicos para jurisdicao, customer type, client_flow ou proxima tela.

Uso Com Provider

'use client';

import { useCoinSentryKycFlow } from '@codedartdev/coinsentry-kyc-react';

export function MyKycWizard() {
  const flow = useCoinSentryKycFlow();

  if (flow.isLoading) return <Loading />;
  if (flow.configMissing) return <KycUnavailable />;
  if (!flow.activeStep) return <KycState status={flow.status?.status} />;

  return (
    <MyWizard step={flow.activeStep} progress={flow.progress}>
      <MyStepRenderer
        step={flow.activeStep}
        canOpenStep={flow.canOpenStep}
        goToStep={flow.goToStep}
        submit={flow.submitCurrentStep}
        upload={flow.uploadForCurrentStep}
        submitting={flow.isSubmitting}
        uploading={flow.isUploading}
        error={flow.error}
      />
    </MyWizard>
  );
}

Este modo usa o client e o initialKycOverview fornecidos pelo CoinSentryProvider.

Cliente compartilhado

O hook exige CoinSentryProvider e reutiliza exatamente a mesma instância do SDK. A opção client permanece deprecated por uma versão e só é aceita quando referencia o próprio cliente compartilhado. Isso impede transportes, sessões e gerenciadores CSRF paralelos.

Quando session.authorities.customer === false, o hook não inicia requests KYC e falha fechado como indisponível para aquela autoridade.

O provider e o BFF devem permanecer same-origin. Nunca crie um segundo client para KYC e nunca exponha WHITELABEL_PROXY_SIGNATURE_SECRET no browser.

Submit E Upload

await flow.submitCurrentStep(payload);
await flow.uploadForCurrentStep(formData);

• submitCurrentStep envia payload para o endpoint do step ativo.
• uploadForCurrentStep envia FormData pelo BFF same-origin.
• isSubmitting e isUploading representam apenas a acao em andamento.
• Uma nova operação cancela a anterior e o unmount aborta requests e delays de reconciliação.
• Falhas de submit/upload sao normalizadas em flow.error.
• Conflitos 409 provocam um refresh do overview para que required_action e flow_state.current_step do backend reposicionem o fluxo.
• O pacote nunca cria um step de revisao ausente em client_flow.

Lifecycle, 401 E Cleanup

O hook controla seu próprio AbortController. Uma nova atualização ou mutation cancela a anterior; perder authorities.customer ou desmontar o componente aborta refresh, submit, upload e delays de reconciliação. Resoluções tardias são ignoradas, inclusive durante o replay de efeitos do React Strict Mode, e não podem atualizar estado depois do unmount.

Não é necessário expor um método manual de descarte. O consumidor deve apenas desmontar o hook quando a tela ou sessão deixar de existir e evitar capturar flow em tarefas externas não canceláveis.

flow.error usa o contrato normalizado do SDK. Ao receber status: 401/code: 'unauthenticated', não repita submit ou upload: deixe o dono do CoinSentryProvider limpar a sessão, inscrições realtime e dados privados, e volte ao login. Quando a autoridade customer desaparecer, o hook cancela o trabalho KYC ainda em voo.

Regras De Seguranca

• A UI pode escolher composicao visual, labels e componentes.
• A UI so deve navegar por flow.steps, flow.activeStep e flow.canOpenStep.
• A UI nao deve inferir jurisdicao, tipo de cliente ou proxima tela por conta propria.
• Ausencia de client_flow falha fechado por flow.configMissing.
• Uploads devem usar flow.uploadForCurrentStep(formData) para manter o BFF como ponto unico de assinatura multipart.

Estado Atual

Versão coordenada 0.2.0, distribuída no dist-tag npm latest. O pacote gera dist, .d.ts, .d.ts.map e sourcemaps. O prepack sempre executa um build limpo para evitar artefatos obsoletos no tarball. O pacote permanece UNLICENSED enquanto os contratos publicos seguem em beta.

Atualização do snapshot autenticado (0.2.1)

Após submit/upload aceito e reconciliação do fluxo KYC, o hook solicita um refresh compartilhado da sessão no provider. Essa leitura atualiza o bloqueio pessoal e o catálogo de operações. Erro na leitura não transforma a mutation aceita em erro reenviável; não há repetição automática do submit/upload por esse motivo. Requer React SDK 0.2.2 e SDK 0.2.4 para o lifecycle atualizado.

Form-bound CAPTCHA (next release, not published)

Verification requires the exact final JSON form values. SlideCaptcha and useSlideCaptcha require formData; direct client verification requires form_data. The CoinSentry adapter receives a frozen formData snapshot. Do not log snapshots or place credentials/proofs in persistent storage. Cancel pending attempts when fields change. Concurrent proof acquisitions are rejected. Laravel Slide CAPTCHA 0.3.0 validates the values authoritatively and consumes mismatched proofs. The browser/mobile checks alone are not a security boundary.

Publish compatible package versions before updating application npm locks. Local test tarballs are not production releases. Roll out updated application, assets, Composer dependency and npm locks together.