SDK JavaScript

@formerie/client est le paquet public d’utilitaires JavaScript et TypeScript de Formerie. Il construit les URL de l’environnement d’exécution, récupère les schémas publics, soumet les charges utiles, normalise les erreurs de validation et fournit des fonctions utilitaires de formulaire pour le navigateur. L’API de l’environnement d’exécution de Formerie demeure la source de vérité.

Paquets

Les paquets de framework sont de minces adaptateurs par-dessus @formerie/client. Ils ne dupliquent pas l’acheminement des requêtes, l’analyse des réponses, le traitement des erreurs de validation ni le comportement de sécurité de l’API.

Installation

npm install @formerie/client

pnpm add @formerie/client

yarn add @formerie/client

bun add @formerie/client

CDN pour le navigateur

Pour du HTML simple ou du JavaScript de navigateur, chargez le bundle officiel pour navigateur à partir d’une version immuable du CDN de Formerie :

<script src="https://cdn.formerie.com/client/v0.1.0-alpha.7/formerie.iife.js"></script>

Les pages en production devraient rester sur des chemins versionnés immuables. L’alias /client/latest/ est un alias changeant, pratique pour les démos et les tests manuels, et non une version fixe stable pour la production.

Utilisation de base

import {
  FormerieRuntimeClient,
  getFieldErrors,
  getFirstFieldError,
  isValidationError
} from "@formerie/client";

const client = new FormerieRuntimeClient();

const result = await client.submit("example.com", "contact", {
  fields: {
    contact: {
      name: "Jane Example",
      email: "jane@example.com"
    }
  },
  verificationToken: captchaToken
});

if (!result.ok && isValidationError(result)) {
  const allEmailErrors = getFieldErrors(result, "contact.email");
  const firstEmailError = getFirstFieldError(result, "contact.email");
}

Par défaut, FormerieRuntimeClient utilise https://forms.formerie.com et des routes épurées comme /example/contact/submit.

Fonctions utilitaires du schéma public

import {
  evaluatePublicFieldVisibility,
  listPublicSchemaFields
} from "@formerie/client";

const schema = await client.schema("example.com", "contact");

if (schema.ok) {
  const fields = listPublicSchemaFields(schema);
  const visibility = evaluatePublicFieldVisibility(schema, {
    contact: {
      preferredMethod: "email"
    }
  });
}

Les fonctions utilitaires du schéma servent au rendu personnalisé et à une expérience utilisateur réactive. L’API de l’environnement d’exécution continue d’appliquer côté serveur la visibilité, la validation, la protection contre le pourriel, l’acheminement et la livraison.

Fonctions de montage pour le navigateur

import {
  FormerieRuntimeClient,
  mountFormerieRuntimeForm
} from "@formerie/client";

await mountFormerieRuntimeForm("#contact-form", {
  client: new FormerieRuntimeClient(),
  target: {
    workspace: "example.com",
    form: "contact"
  },
  resetOnSuccess: true
});

Utilisez mountFormerieRuntimeForm() lorsque le SDK doit charger le schéma public, afficher le formulaire, conserver les étapes publiques et les groupes d’objets sous forme de fieldsets, afficher des hooks de vérification sans danger pour le navigateur, charger le script public du fournisseur de vérification et recueillir les jetons de vérification à partir de ces hooks. Utilisez mountFormerieForm() lorsque votre application a déjà un schéma public, bindFormerieForm() lorsque votre page a déjà affiché une structure native <form data-formerie-form>, et bindFormerieHostedForm() lorsqu’une page rendue côté serveur a déjà à la fois une structure de formulaire et un script JSON de schéma public. Les structures hébergées générées peuvent appeler mountFormerieForm() avec le même schéma public et un submitUrl géré par le serveur. Passez un fournisseur verificationToken explicite seulement pour les interfaces personnalisées qui n’exposent pas les attributs de vérification et les champs de réponse standard de Formerie.

Les structures de formulaire générées acceptent des options de rendu publiques pour la sortie du titre, les hooks de classes CSS et un champ piège (honeypot) facultatif lorsque votre serveur est configuré pour en vérifier un.

Ces fonctions utilitaires améliorent l’expérience dans le navigateur, recueillent les jetons de vérification, structurent les charges utiles et affichent les erreurs de validation. La validation finale, la vérification, les contrôles de pourriel, l’acceptation des soumissions, l’acheminement et la livraison restent côté serveur.

Noms d’hôte de l’environnement d’exécution

const client = new FormerieRuntimeClient({
  endpoint: "https://forms.example.com"
});

await client.submitWorkspace("contact", {
  fields,
  verificationToken: captchaToken
});

Pour un nom d’hôte lié directement à un formulaire :

const contact = new FormerieRuntimeClient({
  endpoint: "https://contact.example.com"
});

await contact.submitForm({
  fields,
  verificationToken: captchaToken
});