SDK-Referenz

@ikiform/sdk ist ein kleines TypeScript-Paket zum Absenden von Formularen, Lesen von Daten aus der REST-API und Verifizieren von Webhooks. Es hat keine Abhängigkeiten und nutzt nur fetch, FormData und Web Crypto, daher läuft es in Browsern, Node 20+, Bun, Deno und Cloudflare Workers. Es wird als ESM mit Typdeklarationen ausgeliefert.

npm install @ikiform/sdk

submit

submit(formId, data, options?) sendet an /f/:formId und liefert ein Ergebnis. Es wirft nie: HTTP-Fehler geben die Fehlerhülle zurück, Netzwerkfehler den Code network_error und Abbrüche aborted.

type SubmitResult =
  | { ok: true; id: string }
  | {
      ok: false;
      error: { code: string; message: string; fields?: Record<string, string[]> };
      status: number | null;
      requestId: string | null;
    };

• Die Felder $ACTION_ von React werden aus FormData entfernt.
• Der Rückgabewert erfüllt auch den Form-Action-Typ von React, daher funktioniert action={(data) => submit(id, data)}.
• submit sendet Accept: application/json. Es sendet keinen Header Authorization; nutze fetch, um mit einem API-Schlüssel zu senden.

import { submit } from "@ikiform/sdk";

const result = await submit("frm_xxxxxxxxxxxxxxxx", { email: "ada@example.com" }, {
  idempotencyKey: crypto.randomUUID(),
  signal: AbortSignal.timeout(10_000),
});

if (!result.ok) console.error(result.error.code, result.error.fields);

challenge

Für Formulare, deren Spamprüfung Ikiform ist. challenge(formId, options?) bindet einen 300 Pixel breiten ikiform.com-Frame ein, der auf null Höhe bleibt, außer Turnstile braucht einen Klick, liefert ein Token und entfernt den Frame. Tokens sind einmalig gültig und leben 300 Sekunden, also ruf es einmal pro Absenden auf.

Es lehnt mit ChallengeError ab, dessen code challenge_failed, challenge_timeout oder aborted ist.

import { challenge, ChallengeError, submit } from "@ikiform/sdk";

async function send(form) {
  try {
    const turnstileToken = await challenge("frm_xxxxxxxxxxxxxxxx", { timeoutMs: 60_000 });
    return submit("frm_xxxxxxxxxxxxxxxx", new FormData(form), { turnstileToken });
  } catch (error) {
    if (!(error instanceof ChallengeError) || error.code !== "challenge_failed") throw error;
    const turnstileToken = await challenge("frm_xxxxxxxxxxxxxxxx", { mode: "popup" });
    return submit("frm_xxxxxxxxxxxxxxxx", new FormData(form), { turnstileToken });
  }
}

getSchema

getSchema(formId, options?) ruft das öffentliche Schema des Formulars ab: seine veröffentlichten Felder, Anzeigeeinstellungen, den Honeypot-Namen und den Challenge-Modus. Wie submit wirft es nie und liefert { ok: true, schema } oder ein Fehlerergebnis. Optionen sind baseUrl, signal und fetch. Die Antwort ist auf der shadcn/ui-Seite beschrieben.

validate

validate(fields, data) prüft FormData oder ein einfaches Objekt gegen Felddefinitionen und gibt Record<string, string> zurück, eine Meldung pro ungültigem Feld, oder ein leeres Objekt. Es nutzt für alle 12 Feldtypen dieselben Regeln und Meldungen wie der Server. validateField(field, value) prüft einen Wert und gibt eine Meldung oder undefined zurück.

import { getSchema, submit, validate } from "@ikiform/sdk";

const result = await getSchema("frm_xxxxxxxxxxxxxxxx");

if (result.ok) {
  const errors = validate(result.schema.fields, new FormData(form));
  if (Object.keys(errors).length === 0) {
    await submit("frm_xxxxxxxxxxxxxxxx", new FormData(form));
  }
}

createClient

createClient({ apiKey, baseUrl?, fetch? }) gibt einen Client für die REST-API zurück. Es wirft einen TypeError, wenn der Schlüssel kein Secret Key ist, also lass ihn auf dem Server.

Fehler werfen IkiformError mit code, status, requestId, message, dazu fields, falls vorhanden, und retryAfter in Sekunden bei 429. Netzwerkfehler werfen mit code: "network_error" und status: 0.

import { createClient, IkiformError } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });

const forms = await ikiform.forms.list({ limit: 10 });
const form = await ikiform.forms.get("frm_xxxxxxxxxxxxxxxx");

for await (const submission of ikiform.submissions.iterate({ formId: form.id, status: "received" })) {
  console.log(submission.id, submission.fields);
}

try {
  await ikiform.submissions.delete("sub_01k7v2c9t3e8m5q4x6z0a1b2c3");
} catch (error) {
  if (error instanceof IkiformError && error.status === 429) {
    console.log(`Retry in ${error.retryAfter} seconds`);
  }
}

verifyWebhook

verifyWebhook({ payload, headers, secret, toleranceSeconds? }) verifiziert eine Webhook-Signatur und gibt das geparste Event zurück. Übergib den rohen Body-String. Die Standardtoleranz beträgt 300 Sekunden in beide Richtungen.

import { verifyWebhook, type WebhookEvent } from "@ikiform/sdk/webhooks";

const event = await verifyWebhook<WebhookEvent>({
  payload: rawBody,
  headers: request.headers,
  secret: process.env.IKIFORM_WEBHOOK_SECRET!,
  toleranceSeconds: 300,
});

Verifizierungsfehler