Elements headless

@flouviahq/elements/headless es el núcleo de Cord Elements. <CordBuilder>, los hooks de React y Vue y los Web Components son consumidores de este mismo núcleo. Importarlo no registra elementos ni toca el DOM: solo estado, validación y red. Úsalo cuando quieras una interfaz propia, en cualquier framework o sin ninguno.

npm install @flouviahq/elements

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

createCordClient

const client = createCordClient({ publishableKey: 'pk_test_...' });
// o, con tu backend de intermediario:
const viaProxy = createCordClient({ proxyUrl: '/api/cord' });

Pasa una de las dos: publishableKey (una pk_, que solo puede usar las rutas de Elements) o proxyUrl (la base de tu proxy de servidor, con la forma de /api/v1). Con las dos, o con una sk_, lanza un error.

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: 'compras@acme.mx' });
const key = builder.addItem({ descripcion: 'Instalación', cantidad: 1, precio_unitario: 12500 });
builder.updateItem(key, { cantidad: 2 });

const quote = await builder.submit(); // null si hay errores o falló

Al crearse, el builder carga la configuración y el catálogo solo (status pasa de loading a ready). Cada cambio recalcula los totales con el mismo motor que el servidor, y la tasa de cada línea sale del catálogo real de impuestos de la organización.

submit() usa una sola Idempotency-Key por intento de envío: un doble clic o un reintento por red nunca crean dos cotizaciones. La clave se renueva en cuanto cambias algo.

El estado (builder.get()) trae:

Para tu analítica, onEvent(evento, datos) recibe builder.loaded, builder.item_added, builder.item_removed, builder.submitted, builder.created, builder.failed y builder.ai_drafted. Los nombres son estables entre versiones.

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 receptor = fiscal.submit(); // el receptor normalizado, o null

builder.setFiscal(receptor);

El estado trae values, touched, validation (con ok, value, errors, warnings y persona), visibleErrors, los regimenes y usosCfdi que aplican al tipo de RFC, y los fields del país. Las reglas están en Formulario fiscal.

Con tu framework

El store sigue el contrato get() + subscribe(), así que se conecta a cualquier sistema reactivo:

import { useSyncExternalStore } from 'react';

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

import { useCordQuoteBuilder, useCordStore } from '@flouviahq/elements/vue';
// useCordStore(store) devuelve un ShallowRef que sigue al store.

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

Estado en vivo de una cotización embebida

reduceQuoteView(estado, evento) convierte los eventos que relaya el iframe de <cord-quote> en un estado (ready, status, folio, moneda, total, approved, rejected, paid, signedBy, lastEvent). Es lo que hay detrás de la propiedad state y el evento statechange del Web Component; ver Web Components.