SDK 레퍼런스

@ikiform/sdk 패키지: submit, challenge, getSchema, validate, createClient, verifyWebhook.

@ikiform/sdk는 폼 제출, REST API 데이터 조회, 웹훅 검증을 위한 작은 TypeScript 패키지입니다. 의존성이 없고 fetch, FormData, Web Crypto만 사용하므로 브라우저, Node 20+, Bun, Deno, Cloudflare Workers에서 실행됩니다. 타입 선언과 함께 ESM으로 배포됩니다.

Terminal

npm install @ikiform/sdk

가져올 항목	패키지	실행 환경
`submit`	`@ikiform/sdk`	브라우저 또는 서버
`challenge`, `ChallengeError`	`@ikiform/sdk`	브라우저
`getSchema`, `validate`, `validateField`	`@ikiform/sdk`	브라우저 또는 서버
`createClient`, `IkiformError`	`@ikiform/sdk`	서버 전용
`verifyWebhook`, `WebhookVerificationError`	`@ikiform/sdk/webhooks`	서버

submit

submit(formId, data, options?)는 /f/:formId로 POST하고 결과로 resolve됩니다. 예외를 던지지 않습니다. HTTP 오류는 오류 형식을 반환하고, 네트워크 오류는 network_error 코드를, 중단은 aborted를 반환합니다.

SubmitResult

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

data	전송 형식
텍스트만 있는 `FormData`	`application/x-www-form-urlencoded`
`File`이 있는 `FormData`	`multipart/form-data`, 업로드 기능이 나오기 전까지 Ikiform이 거부
`URLSearchParams`	`application/x-www-form-urlencoded`
일반 객체	`application/json`

FormData에서 React의 $ACTION_ 필드는 제거됩니다.
반환 값은 React의 폼 액션 타입도 만족하므로 action={(data) => submit(id, data)}가 작동합니다.
submit은 Accept: application/json을 보냅니다. Authorization 헤더는 보내지 않으므로, API 키로 POST하려면 fetch를 사용하세요.

옵션	설명
`baseUrl`	기본값은 `https://ikiform.com`입니다.
`signal`	요청을 취소하는 `AbortSignal`.
`idempotencyKey`	`Idempotency-Key` 헤더로 전송됩니다.
`turnstileToken`	어떤 본문 형식을 쓰든 `cf-turnstile-response`로 전송됩니다.
`fetch`	커스텀 `fetch` 구현.

submit.ts

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

스팸 검사가 Ikiform인 폼용입니다. challenge(formId, options?)는 너비 300픽셀의 ikiform.com 프레임을 마운트하며, Turnstile에 클릭이 필요할 때까지 높이가 없는 상태로 유지됩니다. 토큰으로 resolve된 뒤 프레임을 제거합니다. 토큰은 한 번만 쓸 수 있고 300초 동안 유효하므로 제출마다 한 번씩 호출하세요.

옵션	설명
`container`	프레임을 마운트할 위치. 기본값은 `document.body`입니다.
`mode`	`"frame"`(기본값) 또는 프레임을 막는 브라우저용 `"popup"`. 팝업은 클릭으로 열어야 합니다.
`timeoutMs`	이 밀리초가 지나면 reject합니다. 기본값은 시간 제한 없음입니다.
`signal`	`AbortSignal`.
`baseUrl`	기본값은 `https://ikiform.com`입니다.

code가 challenge_failed, challenge_timeout, aborted 중 하나인 ChallengeError로 reject됩니다.

challenge.ts

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?)는 폼의 공개 스키마를 가져옵니다. 게시된 필드, 표시 설정, 허니팟 이름, 챌린지 모드가 포함됩니다. submit처럼 예외를 던지지 않으며 { ok: true, schema } 또는 오류 결과로 resolve됩니다. 옵션은 baseUrl, signal, fetch입니다. 응답은 shadcn/ui 페이지에 설명되어 있습니다.

validate

validate(fields, data)는 FormData나 일반 객체를 필드 정의와 비교해 확인하고, 유효하지 않은 필드마다 메시지 하나씩 담은 Record<string, string> 또는 빈 객체를 반환합니다. 12가지 필드 타입 모두에서 서버와 같은 규칙과 메시지를 사용합니다. validateField(field, value)는 값 하나를 확인하고 메시지나 undefined를 반환합니다.

validate.ts

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? })는 REST API용 클라이언트를 반환합니다. 키가 시크릿 키가 아니면 TypeError를 던지므로 서버에서만 사용하세요.

메서드	요청
`forms.list({ limit, cursor })`	`GET /forms`
`forms.get(formId)`	`GET /forms/:formId`
`forms.iterate({ limit })`	커서를 따라가며 모든 폼
`submissions.list({ formId, status, limit, cursor })`	`GET /submissions`
`submissions.get(id)`	`GET /submissions/:id`
`submissions.iterate({ formId, status, limit })`	커서를 따라가며 모든 제출
`submissions.markSpam(id)`	`POST /submissions/:id/spam`
`submissions.markNotSpam(id)`	`POST /submissions/:id/not-spam`
`submissions.delete(id)`	`DELETE /submissions/:id`

실패하면 code, status, requestId, message, 그리고 있으면 fields, 429에서는 초 단위의 retryAfter가 담긴 IkiformError를 던집니다. 네트워크 오류는 code: "network_error"와 status: 0으로 던집니다.

client.ts

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? })는 웹훅 서명을 검증하고 파싱된 이벤트를 반환합니다. 원본 본문 문자열을 전달하세요. 기본 허용 오차는 양방향 300초입니다.

webhook.ts

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

검증 오류

reason	의미
`invalid_secret`	시크릿이 `whsec_` 뒤에 base64가 붙는 형식이 아님
`missing_headers`	`webhook-id`, `webhook-timestamp`, `webhook-signature` 중 하나가 없음
`invalid_timestamp`	`webhook-timestamp`가 정수 Unix 초가 아님
`timestamp_too_old`	`toleranceSeconds`보다 더 전에 서명됨. 예: 재생된 요청
`timestamp_too_new`	미래 시각으로 서명됨. 서버 시계를 확인하세요
`no_matching_signature`	일치하는 `v1` 서명이 없음. 시크릿이 틀렸거나 본문이 바뀜
`invalid_payload`	서명은 일치하지만 본문이 JSON이 아님

이벤트 타입은 WebhookEvent, SubmissionCreatedEvent, EndpointTestEvent로 export됩니다. 전체 페이로드는 웹훅을 참고하세요.