Nuxt SignupGate

A Nuxt module for SignupGate.

• ✨  Release Notes

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-signupgate

That's it! You can now use Nuxt SignupGate in your Nuxt app ✨

Configuration

Environment Variables

The module requires the following environment variable to be set:

• NUXT_PRIVATE_SIGNUP_GATE_API_KEY - Your SignupGate API key (required)

You can set this in your .env file:

NUXT_PRIVATE_SIGNUP_GATE_API_KEY=your_api_key_here

Module Options

Configure the module in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-signupgate'],
  signupGate: {
    // Configure at which risk level the signup gate should be triggered
    // Options: 'low' | 'medium' | 'high' | 'none'
    // Default: 'high'
    riskLevel: 'high'
  }
})

Options

• riskLevel (default: 'high') - Configure at which risk level the signup gate should block requests:
  • 'high' - Only block high-risk subjects
  • 'medium' - Block medium and high-risk subjects
  • 'low' - Block low, medium, and high-risk subjects
  • 'none' - Don't block any subjects (monitoring only)

Server auto-import: checkRiskLevel

The module exposes a server-side helper checkRiskLevel which is auto-imported and available in your server routes (no import required). Use this when you want to call SignupGate from server middleware or API routes directly.

What it does:

• Validates the input (q) — must be a non-empty string (email, domain or IP).
• Calls the SignupGate API using the private API key from runtime config.
• Throws a 500 error when the upstream API request fails.
• Throws a 403 when the subject should be blocked according to your configured riskLevel.
• Returns an object with subject, subjectType, and riskLevel when successful.

Example server route using the auto-imported helper:

export default defineEventHandler(async (event) => {
  // no import required — `checkRiskLevel` is auto-imported by the module
  const q = 'example@domain.com'
  const result = await checkRiskLevel(event, q)

  // result -> { subject: string, subjectType: string, riskLevel: 'none'|'low'|'medium'|'high' }
  return result
})

Check IP address risk level

If you want to check the risk level of the request's IP address, you can use the getRequestIP helper from h3 to get the IP from the request and pass it to checkRiskLevel:

export default defineEventHandler(async (event) => {
  const ip = getRequestIP(event)
  if (ip) {
    await checkRiskLevel(event, ip)
  }
})

Check domain risk level

If you want to check the risk level of the request's referer domain, you can use the getRequestHeader helper from h3 to get the referer header and pass it to checkRiskLevel:

export default defineEventHandler(async (event) => {
  const referer = getRequestHeader(event, 'referer')
  if (referer) {
    await checkRiskLevel(event, referer)
  }
})

Client usage

For client-side calls (from components or composables), continue to use the provided API endpoint GET /api/signupgate/check which performs the same check server-side for you. Example:

const { data, error } = await useFetch('/api/signupgate/check', {
  query: { q: 'example@domain.com' }
})

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release