Elements headless

@flouviahq/elements/headless ist der Kern von Cord Elements. <CordBuilder>, die Hooks für React und Vue und die Web Components nutzen alle diesen Kern. Der Import registriert keine Elemente und berührt das DOM nicht: nur Zustand, Validierung und Netzwerk. Verwenden Sie ihn, wenn Sie eine eigene Oberfläche möchten, mit jedem Framework oder ganz ohne.

npm install @flouviahq/elements

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

createCordClient

const client = createCordClient({ publishableKey: 'pk_test_...' });
// oder mit Ihrem Backend dazwischen:
const viaProxy = createCordClient({ proxyUrl: '/api/cord' });

Übergeben Sie eine der beiden Optionen: publishableKey (ein pk_-Schlüssel, der nur die Elements-Routen nutzen kann) oder proxyUrl (die Basis Ihres Server-Proxys, aufgebaut wie /api/v1). Mit beiden oder mit einem sk_-Schlüssel wirft der Client einen Fehler.

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 bei Fehlern oder wenn der Versuch fehlschlägt

Beim Erstellen lädt der Builder Konfiguration und Katalog selbstständig (status wechselt von loading zu ready). Jede Änderung berechnet die Gesamtbeträge mit derselben Logik wie der Server neu, und der Steuersatz jeder Position stammt aus dem echten Steuerkatalog der Organisation.

submit() verwendet einen einzigen Idempotency-Key pro Sendeversuch: Ein Doppelklick oder eine Wiederholung wegen des Netzwerks erzeugt nie zwei Angebote. Der Schlüssel wird erneuert, sobald Sie etwas ändern.

Der Zustand (builder.get()) enthält:

Für Ihre Analytics erhält onEvent(event, data) die Ereignisse builder.loaded, builder.item_added, builder.item_removed, builder.submitted, builder.created, builder.failed und builder.ai_drafted. Die Namen bleiben über Versionen hinweg stabil.

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(); // der normalisierte Rechnungsempfänger oder null

builder.setFiscal(recipient);

Der Zustand enthält values, touched, validation (mit ok, value, errors, warnings und persona), visibleErrors, die regimenes und usosCfdi, die für den RFC-Typ gelten, sowie die fields des Landes. Die Regeln finden Sie unter Steuerformular.

Mit Ihrem Framework

Der Store folgt dem Vertrag get() + subscribe() und lässt sich daher an jedes reaktive System anbinden:

import { useSyncExternalStore } from 'react';

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

import { useCordQuoteBuilder, useCordStore } from '@flouviahq/elements/vue';
// useCordStore(store) gibt eine ShallowRef zurück, die dem Store folgt.

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);
});

Live-Zustand eines eingebetteten Angebots

reduceQuoteView(state, event) wandelt die Ereignisse, die das iframe von <cord-quote> weiterleitet, in einen Zustand um (ready, status, folio, moneda, total, approved, rejected, paid, signedBy, lastEvent). Darauf beruhen die Eigenschaft state und das Ereignis statechange des Web Component; siehe Web Components.