Elements headless

@flouviahq/elements/headless est le cœur de Cord Elements. <CordBuilder>, les hooks React et Vue et les Web Components consomment tous ce même cœur. L’importer n’enregistre aucun élément et ne touche pas au DOM : uniquement l’état, la validation et le réseau. Utilisez-le lorsque vous voulez votre propre interface, avec n’importe quel framework ou sans framework.

npm install @flouviahq/elements

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

createCordClient

const client = createCordClient({ publishableKey: 'pk_test_...' });
// ou, avec votre backend comme intermédiaire :
const viaProxy = createCordClient({ proxyUrl: '/api/cord' });

Passez l’une des deux options : publishableKey (une clé pk_, qui ne peut utiliser que les routes d’Elements) ou proxyUrl (la base de votre proxy serveur, sur le modèle de /api/v1). Avec les deux, ou avec une clé sk_, une erreur est levée.

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 s’il y a des erreurs ou en cas d’échec

À sa création, le builder charge de lui-même la configuration et le catalogue (status passe de loading à ready). Chaque modification recalcule les totaux avec le même moteur que le serveur, et le taux de chaque ligne provient du catalogue réel de taxes de l’organisation.

submit() utilise une seule Idempotency-Key par tentative d’envoi : un double clic ou une nouvelle tentative réseau ne créent jamais deux devis. La clé est renouvelée dès que vous modifiez quoi que ce soit.

L’état (builder.get()) contient :

Pour votre analyse, onEvent(event, data) reçoit builder.loaded, builder.item_added, builder.item_removed, builder.submitted, builder.created, builder.failed et builder.ai_drafted. Les noms restent stables d’une version à l’autre.

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(); // le destinataire normalisé, ou null

builder.setFiscal(recipient);

L’état contient values, touched, validation (avec ok, value, errors, warnings et persona), visibleErrors, les regimenes et usosCfdi applicables au type de RFC, et les fields du pays. Les règles se trouvent dans Formulaire fiscal.

Avec votre framework

Le store respecte le contrat get() + subscribe(), il se branche donc sur n’importe quel système réactif :

import { useSyncExternalStore } from 'react';

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

import { useCordQuoteBuilder, useCordStore } from '@flouviahq/elements/vue';
// useCordStore(store) renvoie un ShallowRef qui suit le 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);
});

État en direct d’un devis intégré

reduceQuoteView(state, event) transforme les événements relayés par l’iframe de <cord-quote> en un état (ready, status, folio, moneda, total, approved, rejected, paid, signedBy, lastEvent). C’est ce qui se trouve derrière la propriété state et l’événement statechange du Web Component ; voir Web Components.