@codedartdev/coinsentry-kyc-react

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.

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.

Uso Com Client Explicito

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

const client = createCoinSentryClient({ baseUrl: '/' });

export function StandaloneKyc({ initialOverview }) {
  const flow = useCoinSentryKycFlow({
    client,
    initialOverview,
    autoRefresh: false,
  });

  return <MyKycWizardView flow={flow} />;
}

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

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

Beta npm (0.1.1, dist-tag latest). O pacote gera dist, .d.ts, .d.ts.map e sourcemaps. O pacote permanece UNLICENSED enquanto os contratos publicos seguem em beta.