@forma/sdk

Um cliente pequeno, sem dependências. Tudo que ele faz dá para fazer com fetch — ele existe pelos tipos e pelo tratamento de erro.

Instalação

terminal

npm i @forma/sdk

baseUrl é opcional e cai em http://localhost:3000. Aponte para o seu host em produção.

submit

Envia uma Submission. Devolve o id, ou lança.

submit.ts

import { Forma } from "@forma/sdk";

const forma = new Forma({
  apiKey: "frm_...",
  baseUrl: "https://forma.app",
});

const { id } = await forma.submit({
  email: "ana@acme.com",
  satisfacao: 5,
  plano: "pro",
  recursos: ["api", "webhooks"],
});

form

Lê a definição do Form para você montar a tela sem repetir os Fields no código. É o que torna o kind survey útil — num Form feedback você normalmente não precisa.

form.ts

const { name, kind, fields } = await forma.form();

// fields:
// [
//   { key: "satisfacao", label: "Qual o seu nível de satisfação?",
//     type: "satisfaction", required: true,
//     minLabel: "Nada satisfeito", maxLabel: "Extremamente satisfeito" },
//   { key: "plano", label: "Plano", type: "select",
//     required: true, options: ["free", "pro", "business"] },
// ]

Só leitura, e nunca devolve Submissions. Usa a mesma API key do ingest, com contador de limite separado.

Survey.tsx

const { name, fields } = await forma.form();

return (
  <form onSubmit={send}>
    <h1>{name}</h1>
    {fields.map((field) => (
      <Control key={field.key} field={field} />
    ))}
  </form>
);

async function send(values) {
  await forma.submit(values);
}

A ordem dos Fields é a ordem da tela. Reordenar no Studio muda o que a pessoa vê, sem tocar no seu código.

Erros

Os dois métodos lançam FormaError com status, body e, num 429, retryAfter em segundos.

erros.ts

import { Forma, FormaError } from "@forma/sdk";

try {
  await forma.submit(values);
} catch (error) {
  if (error instanceof FormaError) {
    if (error.status === 429) {
      await wait(error.retryAfter ?? 30);
    }
    // error.message carries the key that failed
  }
}

Tipos

Forma: O cliente.
FormaError: status, body, retryAfter.
FormDefinition: id, name, kind, fields.
Field: key, label, type, required, options?, min?, max?, minLabel?, maxLabel?.
FieldType: Os oito tipos — ver Tipos de Field.
FormKind: "feedback" | "survey"