Elements headless

@flouviahq/elements/headless é o núcleo do Cord Elements. <CordBuilder>, os hooks de React e Vue e os Web Components consomem esse mesmo núcleo. Importá-lo não registra elementos nem toca o DOM: apenas estado, validação e rede. Use-o quando quiser uma interface própria, em qualquer framework ou sem nenhum.

npm install @flouviahq/elements

import { createCordClient, createQuoteBuilder, createFiscalForm } from '@flouviahq/elements/headless';

createCordClient

const client = createCordClient({ publishableKey: 'pk_test_...' });
// ou, com o seu backend como intermediário:
const viaProxy = createCordClient({ proxyUrl: '/api/cord' });

Passe uma das duas: publishableKey (uma chave pk_, que só pode usar as rotas do Elements) ou proxyUrl (a base do seu proxy de servidor, com o formato de /api/v1). Com as duas, ou com uma chave sk_, lança um erro.

const config = await client.config();
console.log(config.org.moneda, config.impuestos.etiqueta, config.monedas);

createQuoteBuilder

const builder = createQuoteBuilder({
  client,
  onCreated: (quote) => console.log(quote.folio, quote.link_publico),
});

const unsubscribe = builder.subscribe((state) => render(state));

builder.setCliente({ empresa: 'Acme', email: 'purchasing@acme.com' });
const key = builder.addItem({ descripcion: 'Installation', cantidad: 1, precio_unitario: 12500 });
builder.updateItem(key, { cantidad: 2 });

const quote = await builder.submit(); // null se houver erros ou se falhou

Ao ser criado, o builder carrega sozinho a configuração e o catálogo (status passa de loading para ready). Cada alteração recalcula os totais com o mesmo motor do servidor, e a alíquota de cada linha vem do catálogo real de impostos da organização.

submit() usa uma única Idempotency-Key por tentativa de envio: um clique duplo ou uma nova tentativa por falha de rede nunca criam dois orçamentos. A chave é renovada assim que você altera qualquer coisa.

O estado (builder.get()) traz:

Para o seu analytics, onEvent(event, data) recebe builder.loaded, builder.item_added, builder.item_removed, builder.submitted, builder.created, builder.failed e builder.ai_drafted. Os nomes são estáveis entre versões.

createFiscalForm

const fiscal = createFiscalForm({ country: 'MX' });

fiscal.subscribe((s) => {
  console.log(s.visibleErrors, s.regimenes.map((r) => r.codigo));
});

fiscal.set('tax_id', 'EKU9003173C9');
fiscal.touch('tax_id');
const recipient = fiscal.submit(); // o destinatário normalizado, ou null

builder.setFiscal(recipient);

O estado traz values, touched, validation (com ok, value, errors, warnings e persona), visibleErrors, os regimenes e usosCfdi que se aplicam ao tipo de RFC e os fields do país. As regras estão em Formulário fiscal.

Com o seu framework

O store segue o contrato get() + subscribe(), por isso se conecta a qualquer sistema reativo:

import { useSyncExternalStore } from 'react';

function useBuilderState(builder) {
  return useSyncExternalStore(builder.subscribe, builder.get, builder.get);
}

import { useCordQuoteBuilder, useCordStore } from '@flouviahq/elements/vue';
// useCordStore(store) devolve um ShallowRef que acompanha o store.

const total = document.querySelector('#total');
builder.subscribe((s) => {
  total.textContent = new Intl.NumberFormat(s.config?.org.locale ?? 'en', {
    style: 'currency',
    currency: s.moneda || 'USD',
  }).format(s.totals.total);
});

Estado em tempo real de um orçamento incorporado

reduceQuoteView(state, event) converte os eventos que o iframe de <cord-quote> retransmite em um estado (ready, status, folio, moneda, total, approved, rejected, paid, signedBy, lastEvent). É o que está por trás da propriedade state e do evento statechange do Web Component; veja Web Components.