SDK

Overview

The formr SDK is a universal JavaScript/TypeScript library that works in Node.js, Edge runtimes, and browsers. It provides a simple interface for interacting with the Form Platform API.

Installation

npm install formr
# or
pnpm add formr
# or
yarn add formr

Quick Start

Server-side

import { Formr } from 'formr';

const formr = new Formr({ 
  apiKey: process.env.FORMR_KEY 
});

// Fetch form schema
const form = await formr.forms.get('contact-form');

// Submit form
await formr.forms.submit('contact-form', { 
  email: '[e-mail]',
  name: 'John Doe'
}, { 
  idempotencyKey: req.headers['x-idempotency-key'] 
});

// List responses (server)
const { items, nextCursor } = await formr.responses.list({ 
  formId: 'contact-form' 
});

Client-side

import { Formr } from 'formr';

const formr = new Formr(); // apiKey optional on client

await formr.forms.submit('contact-form', {
  email: '[e-mail]',
  name: 'John Doe',
  sessionId: 'session_123'
});

Configuration

const formr = new Formr({
  apiKey?: string;        // API key (optional on client)
  baseUrl?: string;       // Base URL (default: https://api.formr.dev)
  retries?: number;       // Number of retries (default: 3)
  retryDelay?: number;    // Initial retry delay in ms (default: 1000)
});

API Methods

Forms

formr.forms.get(formId)

Fetch a form schema.

const form = await formr.forms.get('contact-form');

formr.forms.create(form)

Create a new form (requires API key).

const form = await formr.forms.create({
  id: 'contact-form',
  title: 'Contact Form',
  fields: [...]
});

formr.forms.update(formId, form)

Update an existing form (requires API key).

const form = await formr.forms.update('contact-form', {
  title: 'Updated Contact Form'
});

formr.forms.submit(formId, data, options?)

Submit form data.

await formr.forms.submit('contact-form', {
  email: '[e-mail]',
  name: 'John Doe',
  sessionId: 'session_123' // Optional
}, {
  idempotencyKey: 'unique-key-123' // Optional
});

Parameters:

• formId: Form ID

• data.answers: Form field answers

• data.sessionId: Session ID (optional)

• options.idempotencyKey: Idempotency key (optional)

Responses

formr.responses.list(params)

List form responses (requires API key).

const { items, nextCursor } = await formr.responses.list({ 
  formId: 'contact-form',
  limit: 50,
  cursor: 'pagination-cursor'
});

Parameters:

• formId: Filter by form ID

• limit: Limit results (default: 50)

• cursor: Pagination cursor

formr.responses.get(responseId)

Get a specific response (requires API key).

const response = await formr.responses.get('rsp_123');

Webhooks

Formr.webhooks.verify(signature, rawBody, secret)

Verify webhook signature.

import { Formr } from 'formr';

const isValid = await Formr.webhooks.verify(
  signature,
  rawBody,
  process.env.FORMR_WHSEC
);

Error Handling

The SDK throws FormrError for API errors:

import { Formr, FormrError } from 'formr';

try {
  await formr.forms.submit('contact-form', { email: '[e-mail]' });
} catch (error) {
  if (error instanceof FormrError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
  }
}

Features

• ✅ Auth: API key based authentication

• ✅ Automatic Retries: Exponential backoff retry logic

• ✅ Idempotency: Idempotency key support

• ✅ Webhook Verification: HMAC SHA-256 signature verification

• ✅ TypeScript: Full TypeScript support

• ✅ Tree-shakeable: ESM-only, sideEffects: false

• ✅ Universal: Works in Node.js, Edge runtimes, and browsers

Examples

Next.js API Route

import { Formr } from 'formr';
import type { NextApiRequest, NextApiResponse } from 'next';

const formr = new Formr({ apiKey: process.env.FORMR_KEY });

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method === 'POST') {
    const { formId, answers } = req.body;
    
    try {
      const result = await formr.forms.submit(formId, { answers }, {
        idempotencyKey: req.headers['x-idempotency-key'] as string
      });
      res.status(201).json(result);
    } catch (error) {
      res.status(500).json({ error: 'Submission failed' });
    }
  }
}

Webhook Handler

import { Formr } from 'formr';
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const signature = req.headers['x-webhook-signature'] as string;
  const rawBody = JSON.stringify(req.body);
  const secret = process.env.FORMR_WHSEC!;

  const isValid = await Formr.webhooks.verify(signature, rawBody, secret);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
  res.status(200).json({ received: true });
}

Next Steps

• Development Tools - Other development tools

• React Components - React components

• API Reference - Complete API documentation