Node

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";

const response = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    fields: {
      name: "Jane Example",
      email: "jane@example.com",
      message: "Hello from my server",
    },
  }),
  signal: AbortSignal.timeout(10_000),
});
const result = await response.json();
console.log(response.status, result.ok ? result.submissionUid : result.error.code);

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";

const response = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    // Keep the key out of your code. A test is stored apart and emails nobody.
    "X-Formerie-Test-Key": process.env.FORMERIE_TEST_KEY,
  },
  body: JSON.stringify({
    fields: { name: "Jane Example", email: "jane@example.com", message: "Just a test" },
  }),
  signal: AbortSignal.timeout(10_000),
});
const result = await response.json();
console.log(response.status, result.ok ? result.submissionUid : result.error.code);

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";

// Checks answers and stores nothing. With no step, only the fields you send are checked.
async function checkAnswers(fields, step) {
  const response = await fetch(`${RUNTIME_URL}/${FORM}/validate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(step ? { mode: "step", step, fields } : { mode: "partial", fields }),
    signal: AbortSignal.timeout(10_000),
  });
  const result = await response.json();
  if (!result.ok && result.error.code !== "VALIDATION_FAILED") {
    throw new Error(result.error.code);
  }
  return result;
}

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";

async function submitAnswers(fields) {
  const response = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ fields }),
    signal: AbortSignal.timeout(10_000),
  });
  return response.json();
}

const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);

// Finds the visitor's answer for a path such as contact.email, so the form can show it again.
const answerAt = (answers, path) => path.split(".").reduce((value, part) => (Object.hasOwn(Object(value), part) ? value[part] : ""), answers);

// One input with its answer kept and its first message under it.
function renderField(path, answers, result) {
  const message = result.error?.fields?.[path]?.[0]?.message;
  const error = message ? `<p class="error">${escapeHtml(message)}</p>` : "";
  return `<input name="${escapeHtml(path)}" value="${escapeHtml(answerAt(answers, path))}">${error}`;
}

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";
const MAX_ATTEMPTS = 3;
const LONGEST_WAIT = 30;
const TEMPORARY_CODES = new Set(["FORM_MAINTENANCE", "QUEUE_FAILED", "INTERNAL_ERROR"]);

// One attempt. Says what happened, and whether another attempt could help.
async function sendOnce(fields, key) {
  let response;
  try {
    response = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ fields, metadata: { idempotencyKey: key } }),
      signal: AbortSignal.timeout(10_000),
    });
  } catch {
    return { outcome: "retry-later", reason: "network", again: true };
  }

  // Only the short-term limit sends Retry-After. A form's own limit can last an hour, so don't wait for it.
  if (response.status === 429) {
    const header = response.headers.get("Retry-After") ?? "";
    const after = /^\d+$/.test(header) ? Number(header) : null;
    return { outcome: "retry-later", reason: "rate-limited", after, again: after !== null && after <= LONGEST_WAIT };
  }

  // Something in front of Formerie may answer without JSON, so look at the status first.
  let result;
  try {
    result = await response.json();
  } catch {
    return { outcome: "retry-later", reason: "bad-response", again: [502, 503, 504].includes(response.status) };
  }

  if (result.ok) {
    return { outcome: "accepted", id: result.submissionUid };
  }
  const { code, message, issues } = result.error;
  if (code === "DUPLICATE_SUBMISSION") {
    // The first send worked, and only its answer was lost.
    return { outcome: "accepted", duplicate: true };
  }
  if (TEMPORARY_CODES.has(code)) {
    return { outcome: "retry-later", reason: code, again: true };
  }
  if (code === "VALIDATION_FAILED") {
    return { outcome: "invalid", code, issues };
  }
  return { outcome: "rejected", code, message };
}

// One key per submission, the same on every retry. Store it with the answers if you retry later.
async function submitWithRetries(fields, key = crypto.randomUUID()) {
  for (let attempt = 1; ; attempt += 1) {
    const { again, ...answer } = await sendOnce(fields, key);
    if (!again || attempt === MAX_ATTEMPTS) {
      return { ...answer, key, attempts: attempt };
    }
    const backoff = Math.random() * Math.min(250 * 2 ** attempt, 4_000);
    await new Promise((resolve) => setTimeout(resolve, Math.max((answer.after ?? 0) * 1_000, backoff)));
  }
}

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";

// posted is what your form sent. origin is the Origin header of the visitor's request.
async function submitVerified(posted, origin) {
  const { "cf-turnstile-response": verificationToken, ...fields } = posted;
  const response = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      // Without the visitor's Origin, the provider's hostname can't match, and the check fails.
      ...(origin ? { Origin: origin } : {}),
    },
    body: JSON.stringify({ fields, verificationToken }),
    signal: AbortSignal.timeout(10_000),
  });
  return response.json();
}

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";

async function submitWithMetadata(fields, startedAt, visitorId) {
  const response = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      fields,
      metadata: {
        idempotencyKey: crypto.randomUUID(),
        // When the visitor opened the form, for the minimum submit time check.
        startedAt: startedAt.toISOString(),
        pageUrl: "https://www.example.com/contact",
        // Your own visitor ID, for a limit rule with the deviceToken scope.
        deviceToken: visitorId,
      },
    }),
    signal: AbortSignal.timeout(10_000),
  });
  return response.json();
}

npm install @formerie/client

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

// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";
const [workspace, form] = FORM.split("/");

const formerie = new FormerieRuntimeClient({
  endpoint: process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com",
});

// Name the fields you send, so a visitor can't add others. Keep the key across retries of one submission.
async function submitContact({ name, email, message }, key = crypto.randomUUID()) {
  return formerie.submit(workspace, form, {
    fields: { name, email, message },
    metadata: { idempotencyKey: key },
  });
}

npm install express

import express from "express";

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";
const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/contact", async (request, response) => {
  // Name the fields you send, so a visitor can't add others.
  const { name, email, message } = request.body;
  try {
    const answer = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ fields: { name, email, message } }),
      signal: AbortSignal.timeout(10_000),
    });
    const result = await answer.json();
    if (result.ok) {
      response.status(202).json({ id: result.submissionUid });
    } else {
      const errors = Object.fromEntries(
        Object.entries(result.error.fields ?? {}).map(([path, issues]) => [path, issues.map((issue) => issue.message)]),
      );
      response.status(answer.status).json({ code: result.error.code, errors });
    }
  } catch {
    // No connection, a timeout, or an answer that isn't JSON. Keep the visitor's answers on screen.
    response.status(503).json({ code: "TRY_AGAIN" });
  }
});

app.listen(process.env.PORT ?? 3000);

npm install fastify @fastify/formbody

import formbody from "@fastify/formbody";
import Fastify from "fastify";

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";
const app = Fastify();
await app.register(formbody);

app.post("/contact", async (request, reply) => {
  // Name the fields you send, so a visitor can't add others.
  const { name, email, message } = request.body;
  try {
    const answer = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ fields: { name, email, message } }),
      signal: AbortSignal.timeout(10_000),
    });
    const result = await answer.json();
    if (result.ok) {
      return reply.code(202).send({ id: result.submissionUid });
    }
    const errors = Object.fromEntries(
      Object.entries(result.error.fields ?? {}).map(([path, issues]) => [path, issues.map((issue) => issue.message)]),
    );
    return reply.code(answer.status).send({ code: result.error.code, errors });
  } catch {
    // No connection, a timeout, or an answer that isn't JSON. Keep the visitor's answers on screen.
    return reply.code(503).send({ code: "TRY_AGAIN" });
  }
});

await app.listen({ port: Number(process.env.PORT ?? 3000) });

npm install hono @hono/node-server

import { serve } from "@hono/node-server";
import { Hono } from "hono";

const RUNTIME_URL = process.env.FORMERIE_RUNTIME_URL ?? "https://forms.formerie.com";
// Your form. This is the only line that names it.
const FORM = process.env.FORMERIE_FORM ?? "acme/contact";
const app = new Hono();

app.post("/contact", async (context) => {
  // Name the fields you send, so a visitor can't add others.
  const { name, email, message } = await context.req.parseBody();
  try {
    const answer = await fetch(`${RUNTIME_URL}/${FORM}/submit`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ fields: { name, email, message } }),
      signal: AbortSignal.timeout(10_000),
    });
    const result = await answer.json();
    if (result.ok) {
      return context.json({ id: result.submissionUid }, 202);
    }
    const errors = Object.fromEntries(
      Object.entries(result.error.fields ?? {}).map(([path, issues]) => [path, issues.map((issue) => issue.message)]),
    );
    return context.json({ code: result.error.code, errors }, answer.status);
  } catch {
    // No connection, a timeout, or an answer that isn't JSON. Keep the visitor's answers on screen.
    return context.json({ code: "TRY_AGAIN" }, 503);
  }
});

serve({ fetch: app.fetch, port: Number(process.env.PORT ?? 3000) });