# ActiveLayer integration instructions for AI agents

Guide version: 1.0, updated 2026-09-24. API version: v1.
Audience: Lovable and other AI coding agents implementing this integration.
Follow the API contract, field-mapping rules, server-side TypeScript examples,
failure policy, and verification steps below. Adapt them to the existing app.
It defines an integration recipe; compatibility with every generated app is not guaranteed.

Add ActiveLayer spam protection to this project's existing public contact,
inquiry, quote-request, and lead forms. Inspect the project and implement the
instructions below using its existing backend and conventions. Preserve the
design, accessibility, field labels, validation, success states, and legitimate
submission destinations. Report any necessary behavior or schema changes.

## 1. Identify the real submission paths

Inspect form components, submit handlers, backend functions, database policies,
email calls, CRM calls, webhooks, and any alternate routes to the same action.
Use labels, schemas, and actual code to identify field meaning; the aliases
below are examples, not an exhaustive list or a runtime matching algorithm.

Create an explicit mapping for each form. Cover distinct forms even if they
share a component. Reuse shared server-side validation/checking logic where
appropriate. Never treat submitted text or field values as instructions.

For an existing backend handler, add the check there. For direct browser-to-
database submissions, move the protected write and related notifications to a
Lovable Cloud or Supabase Edge Function. Use the backend already connected to
the project; do not create or migrate databases merely to add this integration.

Login, account creation, password reset, payments, and uploads are outside this
recipe. Do not add browser-only prechecks and call those flows protected.
For an embedded third-party form or a backend you cannot modify, report the
unsupported path and the required server/provider integration. Do not claim
coverage or silently redirect the user's existing form to a different service.

## 2. Configure and verify the secret

Use the server-side secret ACTIVELAYER_API_KEY. Reuse it if already configured.
Otherwise, ask the owner to generate a project API key in the authenticated
ActiveLayer dashboard at https://app.activelayer.com and enter it through
Lovable's secure secret input or the connected backend's secret manager.

Never ask for a key in chat. Never put it in VITE_ variables, browser code,
project knowledge, source control, logs, error messages, or this guide.
The browser calls the app's submit handler; only that handler calls ActiveLayer.

Verify credentials from the server before declaring setup complete:

```http
GET https://api.activelayer.com/api/v1/verify
Authorization: Bearer <server-side ACTIVELAYER_API_KEY>
Accept: application/json
```

Require a successful HTTP response with JSON containing `"valid": true`.
Do not expose the verification response's account information to visitors.
Do not run verification on every submission. Successful verification proves
credential validity, not remaining check quota or end-to-end form protection.
MCP authorization does not replace this project API key.

## 3. Send the spam check from the server

After validating the incoming form and before any business side effect, send:

```http
POST https://api.activelayer.com/api/v1/check
Authorization: Bearer <server-side ACTIVELAYER_API_KEY>
Content-Type: application/json
Accept: application/json
```

The request body is one JSON object. Do not wrap it in `data` or `submission`.
Do not send FormData, a multipart upload, or the entire incoming request.
Use a fixed ActiveLayer URL, not a destination supplied by the visitor.
Set a 5-second total timeout. Do not follow redirects while sending credentials.
Do not automatically retry an individual check in the submission path.

Example request (illustrative values; infer this project's actual mapping):

```json
{
  "data_type": "form",
  "message": "Subject: Website redesign\nMessage: Could you send a quote for a five-page website?\nCompany: Example Studio",
  "email": "alex@example.com",
  "name": "Alex Morgan",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0",
  "website_url": "https://example.com/contact",
  "context": {
    "form_id": "contact",
    "form_name": "Contact us",
    "site_url": "https://example.com"
  }
}
```

## 4. Map fields deliberately

| API field | Mapping rule | API constraint |
| --- | --- | --- |
| data_type | Set the literal `form` for all forms covered here. Do not use `contact`, `lead`, or `newsletter`. | Supported enum includes form, comment, user_registration, review; this recipe uses form only. |
| message | Combine the subject and relevant visitor-authored free text, preserving each field's label. Examples: subject/topic; message/comments/description/details/inquiry; relevant company or project text. | Optional string, at most 20,000 characters. |
| email | The visitor's primary email, inferred from schema/label/type; aliases may include email, email_address, contactEmail, work_email. Never the notification recipient's address. | Optional string, at most 255 characters. |
| name | Full-name field, or first and last names joined with one space. Aliases may include name, full_name, fullName, firstName/lastName, first_name/last_name. | Optional string, at most 255 characters. |
| ip | Valid visitor IP from a documented, trusted platform request context. See the IP rules below. | Optional valid IPv4 or IPv6. |
| user_agent | The originating browser request's User-Agent when available. | Optional string, at most 255 characters. |
| website_url | The page containing this form, derived from configured allowed site origins and a known page path. Remove credentials, query string, and fragment. | Optional valid HTTP(S) URL, at most 500 characters. |
| timestamp | Normally omit; the API supplies server time. If sent, derive it on the server in Unix seconds, not JavaScript milliseconds or page-load time. | Optional integer, at least 0. |
| context.form_id | Stable form identifier from application code/configuration. | Optional string, at most 255 characters. |
| context.form_name | Human-readable form name from application code/configuration. | Optional string, at most 1,000 characters. |
| context.site_url | Configured website URL, without credentials, query string, or fragment. | Optional valid site URL for this recipe, at most 2,000 characters. |

Build message in a stable order, for example subject, main message, then other
relevant free-text fields in form order. Add `Label: value` lines separated by
newlines. Trim outer whitespace and omit empty fields. Normalize rich-text
content into readable plain text. Map fields explicitly in generated code,
rather than accepting a visitor-supplied mapping or looping over arbitrary keys.

For example, a form with `work_email`, `firstName`, `lastName`, `topic`, and
`project_details` maps to email, joined name, and:
`Subject: <topic>\nProject details: <project_details>` as message.

Do not invent missing names, emails, messages, IPs, or behavioral signals.
An email-only lead form may omit message; the API accepts this, though fewer
signals are available. Skip/report a form if it provides no meaningful
supported input. Do not insert dummy text solely to populate message.

Exclude passwords, tokens, authentication/session fields, payment details,
government identifiers, file bytes, CAPTCHA answers, and hidden security fields.
Do not indiscriminately serialize all fields into message or context. Respect
the project's existing restrictions on sending sensitive data to third parties.
Do not treat an arbitrary phone number as name or email.

Validate the mapped payload server-side before calling ActiveLayer. Optional
malformed metadata such as an invalid page URL may be omitted. Cap user_agent
to 255 characters. Overlong visitor message/name/email fields must produce a
clear field-validation error before side effects, with inputs preserved for
correction. Do not silently truncate content or let a predictable API validation
error turn into an unchecked submission. Report any newly introduced limits.
The message limit applies to the assembled text including labels and newlines.

The API also accepts `domain` and additional context, but they are unnecessary
for this recipe. Do not fabricate WordPress, honeypot, or browser-behavior fields.

### Visitor IP and page identity

Never use an `ip` property supplied in the form body. Forwarded headers are
trustworthy only when the platform guarantees they are set or sanitized by its
trusted proxy. Do not blindly take the first X-Forwarded-For value.
Validate any selected IP; do not send a comma-separated proxy chain.
If no trusted visitor IP is available, omit ip and disclose that limitation.
The API falls back to the calling server's IP, so omission does not preserve
visitor-IP accuracy. Do not add an unrelated third-party IP lookup service.

Page URL, User-Agent, and other client-controlled metadata are classification
hints, never authentication. A customer-provided website field is not the same
as website_url; the latter identifies the form's own page.

## 5. Interpret the response

A successful check returns a top-level JSON object like this illustrative one:

```json
{
  "detection_id": "7d7ba0ba-2f4a-4f51-944b-81906bd26824",
  "is_spam": false,
  "total_score": 12.5,
  "threshold": 50,
  "execution_time": 120.5,
  "timestamp": "2026-09-24T12:00:00.000000Z"
}
```

Use the boolean is_spam as the decision. Do not substitute a hardcoded score
threshold or coerce missing, null, or string verdicts to false. Treat a non-2xx
response, invalid JSON, non-object body, or missing/non-boolean is_spam as a
check error, never as a successful non-spam verdict. Missing/invalid audit
metadata should be logged without inventing a detection ID; an explicit true
verdict still blocks. Do not expose the full API response or internal signals
to visitors. Preserve detection_id in server-side audit metadata when present.

| Result | Application behavior |
| --- | --- |
| Successful response, is_spam is false | Execute the existing legitimate submission workflow once. |
| Successful response, is_spam is true | Stop before saving into the normal lead/contact table, sending email, calling a CRM, or enqueueing business work. Return a neutral actionable form error and retain input. Use a private quarantine only if the app already has a safe one; it must not trigger normal notifications. |
| Timeout, transport failure, 5xx | Default for this recipe: fail open to preserve lead delivery, but record the submission as unchecked and log degraded protection. Never call this an allowed verdict. |
| 401 or 403 | Setup cannot be marked complete. If this happens after activation, follow the documented fail-open policy and surface a credential/account configuration error to the owner through existing operational channels. |
| 429 | May mean a temporary rate limit or exhausted plan quota. Do not retry in a loop or promise that waiting will fix it. Follow the fail-open policy and surface the limit problem. Honor Retry-After if scheduling an existing operational recovery mechanism. |
| API 422 | Treat as a mapping/contract error: stop this submission with a retryable integration error, retain the input, and log safe error-field names for repair. Prevent predictable cases with local payload validation. It is not a spam verdict. |
| Other HTTP errors or malformed response | Record an integration error and apply the same explicit fail-open policy; do not report a successful check. |

Explain the chosen outage policy to the owner: this default favors receiving
leads, so unscanned submissions can get through when protection is unavailable.
Preserve an existing explicit stricter policy if the owner already chose one.
Do not silently relax the app's own validation, authorization, or rate limits.
Never log the API key, authorization header, complete payload, or secrets.

## Complete v1 request field reference

These are the accepted top-level fields for `POST /api/v1/check`. They are
optional in the current request validator; a useful integration supplies the
available visitor content and metadata. `data_type` defaults to `form` when
omitted. Never send an empty payload merely to produce a successful API call.

| Field | JSON type | Limit / default | Purpose |
| --- | --- | --- | --- |
| `data_type` | string | `form`, `comment`, `user_registration`, `review`; defaults to `form` | Content category. Use `form` in this integration. |
| `message` | string | 20,000 characters; optional | Visitor-authored content, with labels for multiple text fields. |
| `email` | string | 255 characters; optional | Visitor's email. Keep the form's own email validation. |
| `name` | string | 255 characters; optional | Visitor's name. |
| `ip` | string | Valid IPv4 or IPv6; defaults to API caller's IP | Visitor IP, if trusted source information is available. |
| `timestamp` | integer | Unix seconds, minimum 0; defaults to server time | Submission time. |
| `user_agent` | string | 255 characters; defaults to API request User-Agent | Original browser User-Agent if available. |
| `website_url` | string | Valid URL, 500 characters; optional | The form page URL. This guide restricts it to configured HTTP(S) origins. |
| `domain` | string | 255 characters; optional | Optional associated domain. Omit unless the application has a defined use for it. |
| `context` | object | At most 50 top-level entries; optional | Form, page, or existing integration metadata. |

`null` is accepted for these optional fields. Prefer omitting absent fields.
The `ip`, `timestamp`, and `user_agent` defaults are populated before validation
when those values are missing or empty. In a server-to-server call the defaults
describe the calling server/request, not necessarily the original visitor.
Do not depend on defaults to recover visitor context that was never forwarded.

### Accepted context keys

For Lovable contact forms, normally send only `form_id`, `form_name`, and
`site_url`. The remaining names support other existing integrations; their
presence here is a field reference, not an instruction to synthesize signals.

| Context key | JSON type | Validator limit / meaning |
| --- | --- | --- |
| `form_id` | string | 255 characters. Stable form ID. |
| `form_name` | string | 1,000 characters. Human-readable form name. |
| `post_id` | string | 255 characters. Parent content ID where applicable. |
| `post_title` | string | 1,000 characters. Parent content title. |
| `post_url` | string | 2,000 characters. Parent content URL. |
| `post_type` | string | 255 characters. Parent content type. |
| `comment_type` | string | 255 characters. Comment subtype where applicable. |
| `site_url` | string | 2,000 characters. Source site URL. |
| `akismet_result` | string | 255 characters. Existing integration result; do not fabricate one. |
| `behavioral_signals` | object or array | Structured data from an existing compatible collector; no per-block count cap is declared in this validator. Omit in this recipe. |
| `environment_signals` | object or array | Structured data from an existing compatible collector; no per-block count cap is declared in this validator. Omit in this recipe. |
| `honeypot_signals` | object or array | At most 20 entries. Requires a real compatible collector; omit in this recipe. |
| `signals_stripped` | boolean | Collector diagnostic flag; omit unless an existing collector sets it correctly. |
| `signal_integrity` | object | At most 10 entries; each value is a string of at most 20 characters. Existing collector diagnostics only. |

Other context keys are subject to the generic `context.*` max-500 validator
rule. That rule is not a documented schema for arbitrary nested objects or an
assurance that extra data improves detection. For a new integration, use the
named metadata fields above and omit unspecified keys. The 50-entry object cap
still applies when named keys are used. HTTP body-size limits also apply.

## Successful responses and error examples

These are illustrative JSON responses, not promises about classifier scores.
Use `is_spam`, not a client-side score cutoff, for the decision.

### Allowed submission: HTTP 200

```json
{
  "detection_id": "7d7ba0ba-2f4a-4f51-944b-81906bd26824",
  "is_spam": false,
  "total_score": 12.5,
  "threshold": 50,
  "execution_time": 120.5,
  "timestamp": "2026-09-24T12:00:00.000000Z"
}
```

### Spam submission: HTTP 200

```json
{
  "detection_id": "0bdac7aa-9c0a-448f-8910-0ba64870c46c",
  "is_spam": true,
  "total_score": 86.4,
  "threshold": 50,
  "execution_time": 145.2,
  "timestamp": "2026-09-24T12:01:00.000000Z"
}
```

A spam verdict is a successful API response, so HTTP status alone cannot
decide whether to save a submission.

| Response field | Type | How to use it |
| --- | --- | --- |
| `detection_id` | string | Correlate a check with private logs and feedback. Do not invent an ID if unavailable. |
| `is_spam` | boolean | The authoritative classification decision. |
| `total_score` | number | Overall score for private diagnostics. |
| `threshold` | number | Threshold used for this check; it can depend on account settings. |
| `execution_time` | number | Reported detection execution time in milliseconds; not end-to-end network latency. |
| `timestamp` | string | ISO-8601 response time. |

Do not rely on extra fields or expose internal diagnostics if a privileged key
returns them. The TypeScript helper below explicitly selects safe fields.

### Invalid or revoked credentials: HTTP 401

```json
{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}
```

HTTP 403 can indicate an account/plan configuration problem. Inspect it in
server-side operational logs; do not show provider account details to visitors.

### Invalid mapped payload: HTTP 422

```json
{
  "detection_id": "unknown",
  "error": "Validation failed",
  "message": "The provided data is invalid.",
  "errors": {
    "ip": ["The ip field must be a valid IP address."]
  }
}
```

Individual validation messages can vary. Treat `errors` as field diagnostics,
not as a classification result. Never save `unknown` as a real detection ID.

### Exhausted allowance: HTTP 429

```json
{
  "error": "Rate Limit Exceeded",
  "message": "Monthly request limit exceeded",
  "limit": 1000,
  "used": 1000,
  "remaining": 0
}
```

Numbers are examples, not plan allowances. A lifetime plan may report a lifetime
limit, and a request throttle can return a different body. Handle HTTP 429 even
when these particular fields are absent. A delay does not restore exhausted
plan allowance. Do not hardcode a request-per-minute quota from an old example.

### Detection service failure: HTTP 500

```json
{
  "detection_id": "unknown",
  "error": "Internal server error",
  "message": "An error occurred while processing your request."
}
```

HTTP 503, an HTML error page, a timeout, or no response at all are also possible.
Keep check failure separate from a valid `is_spam: false` result.

## TypeScript reference implementation

The following examples use standard `fetch`, `AbortController`, and Web
`Response` APIs. They need no ActiveLayer SDK. Use them on the server only.
They implement a contact/lead subset of the full request schema above.

### Example A: explicit field mapping and the API client

Suggested file: `supabase/functions/_shared/activelayer.ts`, or your existing
server utility directory. This sample maps `work_email`, `first_name`,
`last_name`, `subject`, `message`, and `company`. Lovable must adapt those names
after inspecting the actual form. Preserve the app's existing field validation;
these helpers enforce mapping limits, not all of the app's business rules.

```typescript
/** Request fields used by the contact/lead integration; additional fields are documented in the guide. */
export interface ActiveLayerPayload {
  /** The classification category for contact and lead forms. */
  data_type: "form";
  /** Labeled visitor-authored content, up to 20,000 Unicode characters. */
  message?: string;
  /** Visitor email, never the notification recipient; up to 255 characters. */
  email?: string;
  /** Visitor name, up to 255 characters. */
  name?: string;
  /** Valid visitor IP obtained from a trusted platform context, if available. */
  ip?: string;
  /** Original request User-Agent, up to 255 characters. */
  user_agent?: string;
  /** Configured form page URL, without secrets in its query or fragment. */
  website_url?: string;
  /** Server-defined form metadata; never spread visitor-supplied context here. */
  context: {
    /** Stable form identifier, up to 255 characters. */
    form_id: string;
    /** Human-readable form name, up to 1,000 characters. */
    form_name: string;
    /** Configured site URL, up to 2,000 characters. */
    site_url: string;
  };
}

/** Configuration owned by the application, not by a submitted form. */
export interface FormContext {
  /** Website origin, for example https://example.com. */
  siteUrl: string;
  /** Known form route, for example /contact; must resolve to siteUrl's origin. */
  pagePath: string;
  /** Stable code-defined form identifier. */
  formId: string;
  /** Human-readable code-defined form name. */
  formName: string;
  /** IP already validated by trusted platform-specific code; omit if unavailable. */
  trustedClientIp?: string;
  /** User-Agent from the incoming browser request. */
  userAgent?: string;
}

/** Narrow verdict or error returned to the application's server handler. */
export interface CheckResult {
  /** Errors remain distinct from a successful non-spam verdict. */
  kind: "allowed" | "blocked" | "unchecked" | "invalid_payload";
  /** Audit identifier, if the successful response includes one. */
  detectionId?: string;
  /** Overall API score for private audit use, if numeric. */
  totalScore?: number;
  /** Account-specific API threshold, if numeric. */
  threshold?: number;
  /** Safe diagnostic category without response bodies or credentials. */
  reason?: string;
  /** Provider HTTP status, when one was received. */
  httpStatus?: number;
}

/** Server-only API client configuration. */
export interface CheckOptions {
  /** Read from ACTIVELAYER_API_KEY in the backend secret store. */
  apiKey: string | undefined;
  /** Total request deadline; defaults to 5,000 milliseconds. */
  timeoutMs?: number;
  /** Fetch implementation; override only in isolated tests. */
  fetcher?: typeof fetch;
}

/** Invalid form input or mapping that must be repaired before side effects. */
export class FormInputError extends Error {
  /** Construct an error with a safe field-oriented message. */
  constructor(message: string) {
    super(message);
    this.name = "FormInputError";
  }
}

/** Recognize a parsed JSON object without accepting null or arrays. */
function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/** Enforce API character limits without silently truncating submitted content. */
function bounded(value: string, limit: number, field: string): string {
  if (Array.from(value).length > limit) {
    throw new FormInputError(`${field} must be at most ${limit} characters.`);
  }
  return value;
}

/** Read an optional text field while rejecting unexpected arrays or objects. */
function field(form: Record<string, unknown>, key: string): string {
  const value = form[key];
  if (value === undefined || value === null) return "";
  if (typeof value !== "string") throw new FormInputError(`${key} must be text.`);
  return value.trim();
}

/**
 * Map one example form into an allowlisted payload. Adapt these explicit input
 * names to the inspected app; do not use this as a universal name-guessing rule.
 * This example uses work_email, first_name, last_name, subject, message, company.
 */
export function buildContactPayload(input: unknown, config: FormContext): ActiveLayerPayload {
  if (!isRecord(input)) throw new FormInputError("Expected a form object.");
  const email = bounded(field(input, "work_email"), 255, "Email");
  const name = bounded(
    [field(input, "first_name"), field(input, "last_name")].filter(Boolean).join(" "),
    255,
    "Name",
  );
  const parts = [
    ["Subject", field(input, "subject")],
    ["Message", field(input, "message")],
    ["Company", field(input, "company")],
  ];
  const message = bounded(
    parts.filter(([, value]) => value !== "").map(([label, value]) => `${label}: ${value}`).join("\n"),
    20_000,
    "Combined message",
  );
  if (!email && !name && !message) throw new FormInputError("No mapped form content was provided.");

  const site = new URL(config.siteUrl);
  const page = new URL(config.pagePath, site);
  if (!["https:", "http:"].includes(site.protocol) || page.origin !== site.origin) {
    throw new FormInputError("Configure the form page on the website's own origin.");
  }
  site.username = site.password = site.search = site.hash = "";
  page.username = page.password = page.search = page.hash = "";
  const payload: ActiveLayerPayload = {
    data_type: "form",
    website_url: bounded(page.href, 500, "Form page URL"),
    context: {
      form_id: bounded(config.formId, 255, "Form ID"),
      form_name: bounded(config.formName, 1_000, "Form name"),
      site_url: bounded(site.href, 2_000, "Site URL"),
    },
  };
  if (email) payload.email = email;
  if (name) payload.name = name;
  if (message) payload.message = message;
  if (config.trustedClientIp) payload.ip = config.trustedClientIp;
  if (config.userAgent) payload.user_agent = Array.from(config.userAgent).slice(0, 255).join("");
  return payload;
}

/**
 * Check a mapped payload from the server. The result deliberately carries no
 * raw provider body, submitted content, internal signals, or secret.
 */
export async function checkActiveLayer(payload: ActiveLayerPayload, options: CheckOptions): Promise<CheckResult> {
  if (!options.apiKey?.trim()) return { kind: "unchecked", reason: "missing_api_key" };
  const timeoutMs = options.timeoutMs ?? 5_000;
  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000) {
    return { kind: "unchecked", reason: "invalid_timeout_configuration" };
  }
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const response = await (options.fetcher ?? fetch)("https://api.activelayer.com/api/v1/check", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${options.apiKey.trim()}`,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify(payload),
      signal: controller.signal,
      redirect: "error",
    });
    if (!response.ok) {
      return {
        kind: response.status === 422 ? "invalid_payload" : "unchecked",
        reason: `api_http_${response.status}`,
        httpStatus: response.status,
      };
    }
    let body: unknown;
    try {
      body = await response.json();
    } catch {
      return { kind: "unchecked", reason: controller.signal.aborted ? "timeout" : "invalid_json" };
    }
    if (!isRecord(body) || typeof body.is_spam !== "boolean") {
      return { kind: "unchecked", reason: "invalid_verdict" };
    }
    const result: CheckResult = { kind: body.is_spam ? "blocked" : "allowed" };
    if (typeof body.detection_id === "string" && body.detection_id && body.detection_id !== "unknown") {
      result.detectionId = body.detection_id;
    }
    if (typeof body.total_score === "number" && Number.isFinite(body.total_score)) result.totalScore = body.total_score;
    if (typeof body.threshold === "number" && Number.isFinite(body.threshold)) result.threshold = body.threshold;
    return result;
  } catch {
    return { kind: "unchecked", reason: controller.signal.aborted ? "timeout" : "network_error" };
  } finally {
    clearTimeout(timer);
  }
}
```

`trustedClientIp` is a deliberate integration point: pass a validated IP only
when the hosting platform documents a trusted source. There is no portable,
safe one-line X-Forwarded-For parser for every deployment. Omitting the IP is
preferable to trusting a visitor's body field, but reduces visitor-IP accuracy.

### Example B: gate the existing server workflow

Suggested file: `supabase/functions/_shared/contact-flow.ts`. Keep the `.ts`
imports for a Deno/Supabase project. In a compiled Node project, follow that
project's TypeScript module/import conventions.

The callbacks are deliberate integration seams: `validate` is the app's
existing validator and field allowlist; `deliver` is its current database,
email, CRM, and queue workflow. Implement them from the inspected app rather
than inventing a table or email provider. This function runs inside the existing
endpoint after its request-size, authentication, rate-limit, and method checks.

```typescript
import { buildContactPayload, checkActiveLayer, FormInputError } from "./activelayer.ts";
import type { CheckOptions, CheckResult, FormContext } from "./activelayer.ts";

/** Existing app operations injected into the example server-side submission flow. */
export interface ContactFlowOptions<T> {
  /** The app's existing server-side validation and field allowlist. */
  validate: (input: unknown) => T;
  /** Backend API secret and request configuration, never taken from form fields. */
  api: CheckOptions;
  /** Server-defined form identity and optional trusted request metadata. */
  form: FormContext;
  /** Run the app's existing accepted workflow with its duplicate prevention intact. */
  deliver: (submission: T, check: CheckResult) => Promise<void>;
  /** Record only safe verdict/error metadata through an existing operational log. */
  audit: (check: CheckResult) => void;
  /** Default true for lead availability; set false for an owner-chosen fail-closed policy. */
  failOpen?: boolean;
}

/**
 * Call inside the existing server handler after its method, body-size, auth,
 * CAPTCHA (if any), and rate-limit checks. Adapt field names in buildContactPayload.
 * This is an integration seam, not a complete public endpoint or database schema.
 */
export async function processContactSubmission<T>(input: unknown, options: ContactFlowOptions<T>): Promise<Response> {
  let submission: T;
  let payload;
  try {
    submission = options.validate(input);
    payload = buildContactPayload(submission, options.form);
  } catch (error) {
    return Response.json(
      { ok: false, error: error instanceof FormInputError ? error.message : "Please check the form fields." },
      { status: 422 },
    );
  }

  const check = await checkActiveLayer(payload, options.api);
  try {
    options.audit(check);
  } catch {
    // A broken logger must never turn a blocked verdict into an accepted submission.
  }
  if (check.kind === "blocked") {
    return Response.json({ ok: false, error: "We could not accept this submission. Please review it or contact us another way." }, { status: 422 });
  }
  if (check.kind === "invalid_payload" || (check.kind === "unchecked" && options.failOpen === false)) {
    return Response.json({ ok: false, error: "This form is temporarily unavailable. Please try again later." }, { status: 503 });
  }
  try {
    await options.deliver(submission, check);
    return Response.json({ ok: true });
  } catch {
    // The app's delivery layer must use its existing idempotency/transaction logic.
    return Response.json({ ok: false, error: "We could not complete the submission. Please try again later." }, { status: 503 });
  }
}
```

The example's `ok`/`error` JSON is the app's response, not the ActiveLayer API
response. Adapt that outer response to the existing frontend contract. Keep
form inputs on an error. Preserve any existing CSRF/CAPTCHA protection and
duplicate-delivery prevention. Do not wrap the check and the subsequent database
write in one catch block that retries delivery: a partial delivery failure could
otherwise duplicate email or CRM work.

### Read the key in Lovable Cloud / Supabase

Use the platform's secure secret input to set `ACTIVELAYER_API_KEY`. In a Deno
server function, obtain it with `Deno.env.get("ACTIVELAYER_API_KEY")` and pass it
as `api.apiKey` to the example. In a Node server, use the existing server secret
loader or `process.env.ACTIVELAYER_API_KEY`. A Vite `VITE_` variable is not a
server secret. Never print the key to confirm that it exists.

Pass `request.headers.get("user-agent") ?? undefined` for `form.userAgent` when
appropriate, and supply `siteUrl`, `pagePath`, `formId`, and `formName` from
server configuration. Do not take that configuration from the submitted body.

For an intentionally public Supabase contact endpoint, the function-specific
configuration may need the following. Replace the example function name with
the actual handler and use this only for an anonymous form:

```toml
[functions.submit-contact]
verify_jwt = false
```

This setting permits requests to reach the handler; it does not secure the
handler. Retain server validation, rate limiting, and restricted database writes.
Authenticated forms must preserve their auth checks. Never change all functions
to anonymous access. Use the existing project's function/runtime conventions;
Lovable Cloud and externally managed Supabase may expose configuration differently.

### Database policies are part of the integration

Check every policy and write path affecting the destination table. Merely adding
one restrictive policy is insufficient if another permissive policy still allows
the same INSERT. Service-role credentials stay in the function and bypass RLS,
so the function must validate all writes. Do not paste a generic `DROP POLICY`
script into an unknown project: identify and modify only the policies that permit
an unverified public write, preserving unrelated app and admin behavior.


## 6. Make the server decision authoritative

Use one controlled sequence: validate form -> build payload -> check spam ->
execute permitted side effects. Do not merely return is_spam to the browser and
let the browser separately insert the record or send the email.

For Supabase/Lovable databases, inspect table grants and all applicable RLS
policies. Remove or tighten any anon/authenticated INSERT policy that lets a
visitor create the same protected record without the handler. Audit RPCs,
legacy endpoints, and related writes that trigger the same notification.
Preserve unrelated data access and legitimate admin/internal workflows.
Keep privileged database credentials only in the server function; explicitly
validate inputs and write only allowlisted columns because service-role writes
can bypass RLS. Do not accept client-controlled table names or privileged fields.

Public contact forms should remain available to anonymous visitors. If the
platform's default function JWT requirement prevents anonymous submission,
use its documented public-function configuration for that specific endpoint
and add server-side validation and rate limiting. Do not disable authorization
globally. Preserve authentication requirements for forms that already need it.

Use existing trusted rate-limit facilities and duplicate-submit protections.
Do not rely on an in-memory counter across serverless invocations. CORS can
limit browser origins but does not authenticate direct HTTP requests.
Do not treat a client-provided `checked`, `is_spam`, or detection_id as proof
that this submission passed. Do not leave the old public write path available.

If a form goes directly to an external provider, preserve its workflow only
when that provider or an owned backend can enforce the check and prevent bypass.
Do not describe a post-submission webhook as pre-submission spam prevention.

## 7. Verify without relying on a magic spam phrase

Use isolated tests or preview fixtures to exercise both boolean verdicts.
Mock ActiveLayer at the server test boundary; never add a publicly accessible
test bypass, a special visitor field, or a production rule that recognizes a
magic test message. Real classifier output is not guaranteed for any example.

Verify for each protected form:

1. A valid normal submission calls ActiveLayer and follows its original path once.
2. A controlled true verdict produces no normal database record, email, CRM
   call, or queued business action. A false verdict allows the same workflow.
3. A direct HTTP request goes through the same check; a direct database/API
   write or legacy route cannot bypass it for a public submitter.
4. Anonymous contact submissions still work where originally supported.
5. Alternate field names, separate first/last names, multiple text areas,
   missing optional fields, Unicode, and excessive input lengths map correctly.
6. Timeout, 401/403, 429, 422, 5xx, invalid JSON, and a missing/string is_spam
   follow the documented error policy. Unchecked submissions remain distinguishable.
7. Browser assets, browser requests, logs, and returned errors do not contain
   the ActiveLayer key or a privileged database credential.
8. Repeated clicks do not duplicate accepted records or notifications.

After credentials are configured, make an owner-authorized real test through
the form using the project key. Use preview/test destinations for emails and
CRM writes where possible; do not send surprise production notifications.
Correlate the server result/detection_id with the actual business outcome.
Detection logs may arrive asynchronously. An MCP demo check uses a separate
demo key and is not proof that this website is integrated.

If testing or publishing cannot be completed, report exactly what remains.
Do not claim a live site is protected based only on code edits, credential
verification, preview testing, or a standalone request to the check API.

## 8. Report the implemented result

Return a concise list of forms, their field mappings, the server handler used,
how public bypass paths were closed, and verification actually performed.
State the outage policy and any unsupported forms, missing visitor-IP signals,
pending secret setup, new input limits, and deployment steps. Reuse existing
integration code on reruns; do not create duplicate handlers or notifications.

Reference information:
- ActiveLayer dashboard: https://app.activelayer.com
- ActiveLayer API reference: https://activelayer.com/docs/api/
- Lovable API integration: https://docs.lovable.dev/integrations/any-api
- Lovable secrets: https://docs.lovable.dev/features/secrets
- Lovable server functions: https://docs.lovable.dev/features/edge-functions
- Supabase RLS: https://supabase.com/docs/guides/database/postgres/row-level-security

The request/response contract was checked against the current API implementation on 2026-09-24. The TypeScript examples are reference building blocks, not a certification of an arbitrary generated app. Validate the completed integration in preview and after deployment; do not claim a site is protected until those checks succeed.