@formtress/server

Server-side SDK for Formtress spam filtering.

Use this package in your server-side code (Node.js, Deno, Edge runtimes, etc.) to check submissions for spam without saving them.

Installation

npm install @formtress/server

Quick start

import { Formtress } from '@formtress/server'

const formtress = new Formtress({
  apiKey: process.env.FORMTRESS_API_KEY!, // starts with ft_
})

const result = await formtress.filter({
  ip: '1.2.3.4',
  headers: Object.fromEntries(request.headers),
  fields: [
    { name: 'email', value: '[email protected]', type: 'email' },
    { name: 'message', value: 'Hello world', type: 'text' },
  ],
  blockFreeEmailProviders: true,
})

if (result.isSpam) {
  console.log('Spam detected — score:', result.score)
  if (result.fieldErrors) {
    console.log('Field errors:', result.fieldErrors)
  }
}

API

new Formtress(options)

Create a client instance.

| Option | Type | Required | Description | |----------|----------|----------|--------------------------------| | apiKey | string | Yes | Your Formtress API key (ft_…)|

formtress.filter(options)

Check a submission for spam. Returns a FilterResult. No data is stored.

| Option | Type | Required | Default | Description | |---------------------------|-----------------|----------|---------|--------------------------------------------------| | ip | string | Yes | — | End-user's IP address (used for rate limiting) | | headers | Record<string,string> | Yes | — | Forwarded request headers from the end-user | | fields | FilterField[] | No | — | Field values for content-level spam detection | | blockFreeEmailProviders | boolean | No | false | Flag free email providers (e.g. gmail.com) |

FilterResult

| Property | Type | Description | |---------------|---------------------------|--------------------------------------------------| | isSpam | boolean | Whether the submission was detected as spam | | score | number | Spam confidence score (0–1) | | rateLimited | boolean | Whether the end-user was rate limited | | fieldErrors | Record<string,string>? | Per-field spam errors, keyed by field name |

FormtressError

Thrown when the API returns a non-2xx status. Contains:

• message — error description
• status — HTTP status code
• body — raw response body

Type exports

All types are exported for your own type safety:

import type {
  FilterField,
  FilterOptions,
  FilterResult,
  FormtressOptions,
} from '@formtress/server'

Requirements

• Node.js 18+ (uses native fetch)

License

MIT