SDK reference

@ikiform/sdk is a small TypeScript package for submitting forms, reading data from the REST API and verifying webhooks. It has no dependencies and uses only fetch, FormData and Web Crypto, so it runs in browsers, Node 20+, Bun, Deno and Cloudflare Workers. It ships as ESM with type declarations.

npm install @ikiform/sdk

submit

submit(formId, data, options?) posts to /f/:formId and resolves to a result. It never throws: HTTP errors return the error envelope, network failures return the code network_error and aborts return aborted.

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

• React's $ACTION_ fields are dropped from FormData.
• The return value also satisfies React's form action type, so action={(data) => submit(id, data)} works.
• submit sends Accept: application/json. It doesn't send an Authorization header; use fetch to post with an API key.

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

For forms whose spam check is Ikiform. challenge(formId, options?) mounts a 300 pixel wide ikiform.com frame that stays at zero height unless Turnstile needs a click, resolves with a token and removes the frame. Tokens are single use and live 300 seconds, so call it once per submit.

It rejects with ChallengeError, whose code is challenge_failed, challenge_timeout or aborted.

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?) fetches the form's public schema: its published fields, display settings, honeypot name and challenge mode. Like submit it never throws, resolving to { ok: true, schema } or an error result. Options are baseUrl, signal and fetch. The response is described on the shadcn/ui page.

validate

validate(fields, data) checks FormData or a plain object against field definitions and returns Record<string, string>, one message per invalid field, or an empty object. It uses the same rules and messages as the server for all 12 field types. validateField(field, value) checks one value and returns a message or undefined.

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? }) returns a client for the REST API. It throws a TypeError if the key isn't a secret key, so keep it on the server.

Failures throw IkiformError with code, status, requestId, message, plus fields when present and retryAfter in seconds on 429. Network failures throw with code: "network_error" and 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? }) verifies a webhook signature and returns the parsed event. Pass the raw body string. The default tolerance is 300 seconds in both directions.

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

Verification errors