apira-guard 0.1.0

package/README.md

@@ -0,0 +1,296 @@
+# Apira
+
+Catches bots, abuse, and broken flows after Cloudflare, before PostHog.
+
+Detect fake signups, risky actions, API abuse, and silent backend failures — locally, with no API key.
+
+```bash
+npm install apira-guard
+```
+
+Apira is a local, no-network layer. **`watchActions()`** and **`watchAccess()`** attach `riskScore`, `riskLevel`, and `reasons` to matched form submits and HTTP requests. **`watchSignups()`** / **`watchForms()`** listen for conversion submits and fire `signupguard:submit` with intent metadata (no risk payload). **`protectForms()`** blocks obvious bad email and phone values before submit.
+
+No account. No dashboard. No outbound calls.
+
+---
+
+## Common use cases
+
+Use Apira to:
+
+* block or flag fake or junk signups (`protectForms`, then optional `watchActions` risk)
+* detect disposable emails and fake-looking phones at submit time (`protectForms`)
+* score checkout, password reset, account update, invite, waitlist, demo request, and contact sales forms (`watchActions` — match by form copy or `data-signup-guard-form`)
+* detect forms submitted unrealistically fast (`watchActions`)
+* detect repeated form submissions (`watchActions`)
+* add request-risk scoring to Express, Next.js, or Node APIs
+* detect request velocity
+* detect sudden traffic spikes
+* detect simple API enumeration like `/api/users/1`, `/api/users/2`, `/api/users/3`
+* send risk events to your own logs, database, Sentry, PostHog, or analytics stack
+
+---
+
+## Add one line
+
+### Signup forms
+
+```ts
+import { watchSignups } from "apira-guard";
+
+watchSignups();
+```
+
+Auto-detects signup forms with email or phone fields and fires `signupguard:submit` on submit (detail: `intent`, `timestamp`, `metadata`). It does **not** inject `signupGuardRisk` — use `watchActions({ action: "signup" })` (plus matching form text or `data-signup-guard-form="signup"`) when you want the same risk JSON on signup flows.
+
+Use `protectForms()` if you want to block obvious bad submissions (invalid / disposable email, bad phone shapes).
+
+---
+
+### Important actions
+
+Protect conversion-critical forms like checkout, password reset, account update, invite, waitlist, demo request, and contact sales.
+
+```ts
+import { watchActions } from "apira-guard";
+
+watchActions({ action: "checkout" });
+```
+
+Apira watches the matching form, computes risk on submit, injects `signupGuardRisk` into the form body, and fires `signupguard:action`.
+
+```ts
+watchActions({
+  action: "checkout",
+  onAction(event) {
+    console.log(event.action, event.risk);
+  }
+});
+```
+
+Target a form explicitly:
+
+```html
+<form data-signup-guard-form="checkout">
+  ...
+</form>
+```
+
+---
+
+### API routes
+
+Watch server-side requests for lightweight API abuse signals.
+
+```ts
+import { watchAccess } from "apira-guard/server";
+
+app.use(watchAccess());
+```
+
+Apira attaches risk directly to the request:
+
+```ts
+app.get("/api/users/:id", (req, res) => {
+  if (req.signupGuardRisk?.riskLevel === "high") {
+    return res.status(429).json({ error: "rate limited" });
+  }
+
+  res.json({ ok: true });
+});
+```
+
+Configure velocity and spike detection:
+
+```ts
+watchAccess({
+  velocityThreshold: 60,
+  spikeThreshold: 20,
+  velocityWindowMs: 60_000
+});
+```
+
+---
+
+## Risk output
+
+**`watchActions()`** and **`watchAccess()`** both use the same payload shape:
+
+```ts
+{
+  riskScore: 85,
+  riskLevel: "high",
+  reasons: ["velocity", "fast_action", "enumeration"]
+}
+```
+
+| Reason                   | Where          | What it means |
+| ------------------------ | -------------- | ------------- |
+| `velocity`               | forms (`watchActions`), APIs | Too many submits or requests in the sliding window (default 60 s on the server; client `watchActions` uses a stricter per-form threshold) |
+| `fast_action`            | forms (`watchActions`) | Submitted faster than the fast-action threshold after the watcher attached |
+| `retry`                  | forms (`watchActions`) | Same form submitted again |
+| `enumeration`            | APIs           | Sequential numeric IDs in the URL path (run ≥ 3) |
+| `spike`                  | APIs           | Burst of requests in a 10 s window |
+| `endpoint_concentration` | APIs           | Same normalised endpoint hit repeatedly in the velocity window |
+| `probing`                | APIs           | High 4xx rate from this client (after enough samples) |
+| `flow_anomaly`           | APIs           | Write request with no prior read on the same key (bot-style shortcut) |
+
+Score thresholds: **low** < 40 · **medium** 40–69 · **high** ≥ 70.
+
+---
+
+## Can Apira block risk?
+
+Yes. Apira can run as a signal layer or a blocking layer.
+
+Signal mode: **`watchActions()`** injects a hidden `signupGuardRisk` JSON field on submit; **`watchAccess()`** sets `req.signupGuardRisk` on each request.
+
+```ts
+const risk = JSON.parse(req.body.signupGuardRisk ?? "{}");
+```
+
+Block mode stops obvious bad activity before it continues.
+
+```ts
+import { protectForms } from "apira-guard";
+
+protectForms();
+```
+
+For APIs, block high-risk requests in middleware:
+
+```ts
+app.use(watchAccess());
+
+app.use((req, res, next) => {
+  if (req.signupGuardRisk?.riskLevel === "high") {
+    return res.status(429).json({ error: "Too many suspicious requests" });
+  }
+
+  next();
+});
+```
+
+Apira can reduce obvious abuse. It does not guarantee fraud prevention or stop sophisticated attackers.
+
+---
+
+## Reading risk on the server
+
+**`watchActions()`** injects a hidden field on matched forms:
+
+```ts
+app.post("/checkout", (req, res) => {
+  const risk = JSON.parse(req.body.signupGuardRisk ?? "{}");
+
+  if (risk.riskLevel === "high") {
+    return res.status(422).json({ error: "Suspicious request" });
+  }
+
+  res.json({ ok: true });
+});
+```
+
+API routes get risk directly:
+
+```ts
+req.signupGuardRisk;
+```
+
+For TypeScript Express apps:
+
+```ts
+declare global {
+  namespace Express {
+    interface Request {
+      signupGuardRisk?: import("apira-guard/server").RiskResult;
+    }
+  }
+}
+```
+
+---
+
+## Signup-first, conversion-ready
+
+`watchSignups()` is shorthand for:
+
+```ts
+watchForms({ intent: "signup" });
+```
+
+For any conversion-critical form, use `watchForms()`:
+
+```ts
+import { watchForms } from "apira-guard";
+
+watchForms({
+  intent: "demo_request",
+  metadata: { page: "pricing" },
+  onSubmit(event) {
+    console.log(event.intent, event.timestamp, event.metadata);
+  }
+});
+```
+
+Opt a form in or out:
+
+```html
+<form data-signup-guard-form="checkout">...</form>
+<form data-signup-guard-ignore>...</form>
+```
+
+---
+
+## What protectForms() blocks
+
+```ts
+import { protectForms } from "apira-guard";
+
+protectForms();
+```
+
+Blocks obvious garbage at submit time using browser validation messages:
+
+* invalid email formats
+* disposable email domains
+* invalid phone formats
+* fake-looking phones like `0000000000`, `1234567890`, and `555-01xx`
+
+---
+
+## What ships in npm
+
+* `watchSignups()`
+* `watchForms()`
+* `watchActions()`
+* `protectForms()`
+* `watchAccess()`
+* shared risk payloads
+* local scoring rules
+* reason codes
+* TypeScript types
+
+Everything runs inside your app. Apira does not call external services.
+
+---
+
+## What is not included
+
+Not included today:
+
+* hosted dashboard
+* shared reputation network
+* external IP reputation checks
+* external email verification APIs
+* ML fraud models
+
+These may become optional later. The npm package works without them.
+
+---
+
+## What Apira is not
+
+Apira is not a CAPTCHA, identity verification system, hosted fraud platform, or replacement for server-side validation.
+
+It is a local first line of defense for forms, actions, and API routes — the layer between edge protection and your analytics/logging stack.

package/demo/index.html

@@ -0,0 +1,168 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Apira Demo</title>
+    <style>
+      *, *::before, *::after { box-sizing: border-box; }
+      body { font-family: system-ui, sans-serif; margin: 2rem auto; max-width: 44rem; }
+      h2 { margin-top: 2.5rem; }
+      label { display: block; margin-block: 0.75rem 0.2rem; font-size: 0.9rem; color: #555; }
+      input { padding: 0.5rem 0.6rem; width: 100%; border: 1px solid #ccc; border-radius: 4px; font: inherit; }
+      button { margin-top: 0.9rem; padding: 0.55rem 1rem; font: inherit; cursor: pointer; border: 1px solid #ccc; border-radius: 4px; background: #fff; }
+      button:hover { background: #f3f4f6; }
+      pre {
+        background: #111827; color: #f9fafb; border-radius: 6px;
+        overflow: auto; padding: 1rem; font-size: 0.85rem; min-height: 3rem;
+      }
+      .badge {
+        display: inline-block; padding: 0.2rem 0.6rem; border-radius: 999px;
+        font-size: 0.75rem; font-weight: 600; text-transform: uppercase; margin-left: 0.5rem;
+        vertical-align: middle;
+      }
+      .low    { background: #dcfce7; color: #166534; }
+      .medium { background: #fef9c3; color: #713f12; }
+      .high   { background: #fee2e2; color: #991b1b; }
+      hr { margin-block: 2.5rem; border: none; border-top: 1px solid #e5e7eb; }
+      .buttons { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 1rem; }
+    </style>
+  </head>
+  <body>
+    <h1>Apira Demo</h1>
+    <p>Local behaviour engine — no network calls, no API keys.</p>
+
+    <!-- ── A) protectForms ──────────────────────────────────────────── -->
+    <h2>A) <code>protectForms()</code></h2>
+    <p>Blocks fake inputs at the browser level. Try submitting as-is.</p>
+    <form id="signup-form">
+      <label for="email">Email</label>
+      <input id="email" name="email" value="test@mailinator.com" />
+      <label for="phone">Phone</label>
+      <input id="phone" name="phone" value="1111111111" />
+      <button type="submit">Create account</button>
+    </form>
+    <pre id="protect-result">→ submit to see what gets blocked</pre>
+
+    <hr />
+
+    <!-- ── B) watchActions ──────────────────────────────────────────── -->
+    <h2>
+      B) <code>watchActions({ action: "checkout" })</code>
+      <span id="risk-badge" class="badge" style="display:none"></span>
+    </h2>
+    <p>
+      Click <strong>Checkout</strong> several times in a row.
+      Watch the risk score climb: <em>fast_action</em> → <em>retry</em> → <em>velocity</em>.
+    </p>
+    <form id="checkout-form" data-signup-guard-form="checkout">
+      <label for="card">Card number</label>
+      <input id="card" name="card" placeholder="4242 4242 4242 4242" />
+      <button type="submit">Checkout</button>
+    </form>
+    <pre id="actions-result">→ submit the form to see risk signals</pre>
+
+    <hr />
+
+    <!-- ── C) watchAccess simulation ───────────────────────────────── -->
+    <h2>C) <code>watchAccess()</code> — API abuse patterns</h2>
+    <p>
+      In production this runs server-side as <code>app.use("/api", watchAccess())</code>.
+      Here we run the same engine in-browser to show the signals.
+    </p>
+    <div class="buttons">
+      <button id="btn-normal">Normal user</button>
+      <button id="btn-enum">Enumerator</button>
+      <button id="btn-scraper">Scraper</button>
+      <button id="btn-bot">Bot (no browse)</button>
+      <button id="btn-brute">Brute force</button>
+    </div>
+    <pre id="access-result">→ pick a pattern above</pre>
+
+    <!-- ── scripts ──────────────────────────────────────────────────── -->
+    <script type="module">
+      import { protectForms, watchActions } from "../dist/index.js";
+
+      // A) protect forms
+      const signupForm  = document.querySelector("#signup-form");
+      const protectOut  = document.querySelector("#protect-result");
+
+      protectForms();
+      signupForm.addEventListener("signupguard:block", (e) => {
+        protectOut.textContent = JSON.stringify(e.detail, null, 2);
+      });
+      signupForm.addEventListener("submit", (e) => {
+        e.preventDefault();
+        protectOut.textContent = "✓ valid — submission would continue";
+      });
+
+      // B) watch actions
+      const actionsOut = document.querySelector("#actions-result");
+      const badge      = document.querySelector("#risk-badge");
+
+      watchActions({
+        action: "checkout",
+        onAction({ risk }) {
+          actionsOut.textContent = JSON.stringify(risk, null, 2);
+          badge.textContent      = risk.riskLevel;
+          badge.className        = `badge ${risk.riskLevel}`;
+          badge.style.display    = "inline-block";
+        }
+      });
+
+      document.querySelector("#checkout-form").addEventListener("submit", (e) => {
+        e.preventDefault();
+      });
+    </script>
+
+    <script type="module">
+      // C) watchAccess simulation — same engine the server uses
+      import { createEngine } from "../dist/engine.js";
+      import { buildRiskResult } from "../dist/risk.js";
+
+      const accessOut = document.querySelector("#access-result");
+
+      function simulate(label, requests) {
+        // One engine per simulation (mirrors one watchAccess() mount per route)
+        const engine = createEngine({ velocityThreshold: 5, spikeThreshold: 5, concThreshold: 5 });
+        const log = [];
+
+        for (const [ip, method, url] of requests) {
+          const reasons = engine.track(ip, { url, method });
+          log.push({ url, method, ...buildRiskResult(reasons) });
+        }
+
+        const last    = log.at(-1);
+        const signals = [...new Set(log.flatMap(r => r.reasons))];
+
+        accessOut.textContent =
+          `Pattern : ${label}\n` +
+          `Requests: ${requests.length}\n\n` +
+          `Last request:\n${JSON.stringify(last, null, 2)}\n\n` +
+          `All signals fired: ${signals.length ? signals.join(", ") : "none (clean traffic)"}`;
+      }
+
+      const ip = "demo-ip";
+
+      document.querySelector("#btn-normal").onclick = () =>
+        simulate("Normal user", [
+          [ip, "GET",  "/api/products"],
+          [ip, "GET",  "/api/product/42"],
+          [ip, "GET",  "/api/checkout"],
+          [ip, "POST", "/api/checkout"],
+        ]);
+
+      document.querySelector("#btn-enum").onclick = () =>
+        simulate("Enumerator", [1,2,3,4,5,6,7].map(n => [ip, "GET", `/api/user/${n}`]));
+
+      document.querySelector("#btn-scraper").onclick = () =>
+        simulate("Scraper", Array.from({ length: 8 }, () => [ip, "GET", "/api/products"]));
+
+      document.querySelector("#btn-bot").onclick = () =>
+        simulate("Bot (no browse)", Array.from({ length: 4 }, () => [ip, "POST", "/api/checkout"]));
+
+      document.querySelector("#btn-brute").onclick = () =>
+        simulate("Brute force", Array.from({ length: 8 }, () => [ip, "POST", "/api/login"]));
+    </script>
+  </body>
+</html>

package/dist/engine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * O(1) behaviour detection engine — shared by all surfaces.
+ *
+ * All counters use fixed-window arithmetic so every operation is constant time:
+ * no timestamp arrays, no filter/scan, no history queries.
+ */
+import type { RiskReason } from "./risk.js";
+export type TrackEvent = {
+    now?: number;
+    /**
+     * Milliseconds since the watcher was attached (submit surface).
+     * Presence of this field marks the event as a submit-surface event:
+     *   - enables fast_action and retry signals
+     *   - disables enumeration / endpoint_concentration / flow_anomaly
+     */
+    elapsed?: number;
+    /**
+     * Request URL (access surface).
+     * Presence of this field marks the event as an access-surface event:
+     *   - enables enumeration, endpoint_concentration, flow_anomaly
+     *   - disables retry
+     */
+    url?: string;
+    /** HTTP method — required for flow_anomaly (access surface only). */
+    method?: string;
+};
+export type EngineOptions = {
+    /** Requests per velocityWindowMs before "velocity" fires. Default: 60. */
+    velocityThreshold?: number;
+    /** Sliding window for velocity. Default: 60 000 ms. */
+    velocityWindowMs?: number;
+    /** Requests per 10 s before "spike" fires. Default: 20. */
+    spikeThreshold?: number;
+    /** Requests to the same normalised endpoint before "endpoint_concentration" fires. Default: 20. */
+    concThreshold?: number;
+    /** Minimum error rate (0–1) before "probing" fires (needs ≥ 5 requests). Default: 0.5. */
+    errorRateThreshold?: number;
+    /** Elapsed ms threshold for "fast_action". Default: 3 000. */
+    fastActionMs?: number;
+};
+export type Engine = {
+    track(key: string, event: TrackEvent): RiskReason[];
+    /** Call after a 4xx / 5xx response to feed the probing detector. */
+    reportError(key: string): void;
+};
+export declare function createEngine(opts?: EngineOptions): Engine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAI5C,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IACpD,oEAAoE;IACpE,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AA0CF,wBAAgB,YAAY,CAAC,IAAI,GAAE,aAAkB,GAAG,MAAM,CA6F7D"}

package/dist/engine.js

@@ -0,0 +1,125 @@
+/**
+ * O(1) behaviour detection engine — shared by all surfaces.
+ *
+ * All counters use fixed-window arithmetic so every operation is constant time:
+ * no timestamp arrays, no filter/scan, no history queries.
+ */
+const NUMERIC_ID_RE = /\/(\d+)(?:\/|$|\?)/u;
+function makeState(now) {
+    return {
+        winStart: now, winCount: 0,
+        spikeStart: now, spikeCount: 0,
+        totalCount: 0,
+        lastPathNum: null, seqRun: 0,
+        epWinStart: now, epCounts: new Map(),
+        reqCount: 0, errCount: 0,
+        hasGet: false
+    };
+}
+// ─── factory ─────────────────────────────────────────────────────────────────
+export function createEngine(opts = {}) {
+    const velocityThreshold = opts.velocityThreshold ?? 60;
+    const velocityWindowMs = opts.velocityWindowMs ?? 60_000;
+    const spikeThreshold = opts.spikeThreshold ?? 20;
+    const concThreshold = opts.concThreshold ?? 20;
+    const errorRateThreshold = opts.errorRateThreshold ?? 0.5;
+    const fastActionMs = opts.fastActionMs ?? 3_000;
+    const store = new Map();
+    function state(key, now) {
+        let s = store.get(key);
+        if (!s) {
+            s = makeState(now);
+            store.set(key, s);
+        }
+        return s;
+    }
+    return {
+        track(key, event) {
+            const now = event.now ?? Date.now();
+            const s = state(key, now);
+            const reasons = [];
+            // ── Velocity (O(1) fixed window) ───────────────────────────────────────
+            if (now - s.winStart >= velocityWindowMs) {
+                s.winStart = now;
+                s.winCount = 0;
+            }
+            s.winCount++;
+            if (s.winCount > velocityThreshold)
+                reasons.push("velocity");
+            // ── Spike (O(1) fixed 10 s window) ────────────────────────────────────
+            if (now - s.spikeStart >= 10_000) {
+                s.spikeStart = now;
+                s.spikeCount = 0;
+            }
+            s.spikeCount++;
+            if (s.spikeCount > spikeThreshold)
+                reasons.push("spike");
+            s.totalCount++;
+            // ── Fast action (submit surface) ───────────────────────────────────────
+            if (event.elapsed !== undefined && event.elapsed < fastActionMs) {
+                reasons.push("fast_action");
+            }
+            if (event.url !== undefined) {
+                // ── Access-surface signals ─────────────────────────────────────────
+                // Enumeration (O(1) sequential-run counter)
+                const m = NUMERIC_ID_RE.exec(event.url);
+                if (m) {
+                    const num = parseInt(m[1], 10);
+                    s.seqRun = (s.lastPathNum !== null && Math.abs(num - s.lastPathNum) <= 5)
+                        ? s.seqRun + 1
+                        : 1;
+                    s.lastPathNum = num;
+                }
+                else {
+                    s.lastPathNum = null;
+                    s.seqRun = 0;
+                }
+                if (s.seqRun >= 3)
+                    reasons.push("enumeration");
+                // Endpoint concentration (O(1) per-endpoint window counter)
+                if (now - s.epWinStart >= velocityWindowMs) {
+                    s.epCounts.clear();
+                    s.epWinStart = now;
+                }
+                const ep = normalizeEndpoint(event.url);
+                const epCount = (s.epCounts.get(ep) ?? 0) + 1;
+                s.epCounts.set(ep, epCount);
+                if (epCount > concThreshold)
+                    reasons.push("endpoint_concentration");
+                // Flow anomaly (O(1) method tracker — POST/PUT/DELETE with no prior GET)
+                if (event.method) {
+                    const method = event.method.toUpperCase();
+                    if (method === "GET") {
+                        s.hasGet = true;
+                    }
+                    else if (!s.hasGet && s.totalCount > 2) {
+                        reasons.push("flow_anomaly");
+                    }
+                }
+                // Probing (O(1) error rate — evaluated on next request after reportError calls)
+                s.reqCount++;
+                if (s.reqCount >= 5 && s.errCount / s.reqCount > errorRateThreshold) {
+                    reasons.push("probing");
+                }
+            }
+            else {
+                // ── Submit-surface signals ─────────────────────────────────────────
+                // Retry (second or later submit to the same form)
+                if (s.totalCount > 1)
+                    reasons.push("retry");
+            }
+            return reasons;
+        },
+        reportError(key) {
+            const s = store.get(key);
+            if (s) {
+                s.errCount++;
+            }
+        }
+    };
+}
+// ─── helpers ─────────────────────────────────────────────────────────────────
+function normalizeEndpoint(url) {
+    // Strip query string, collapse numeric path segments to :id
+    return url.split("?")[0].replace(/\/\d+/gu, "/:id");
+}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { type RiskResult } from "./risk.js";
+export type { RiskReason, RiskLevel, RiskResult } from "./risk.js";
+export type ConversionFormIntent = "signup" | "checkout" | "demo_request" | "waitlist" | "lead_capture" | "contact_sales" | "invite";
+export type WatchFormsEvent = {
+    intent: ConversionFormIntent;
+    timestamp: string;
+    metadata: Record<string, unknown>;
+};
+export type WatchFormsOptions = {
+    /** Root node to search. Defaults to document. */
+    root?: ParentNode;
+    /** Revenue-critical flow being watched. Defaults to signup. */
+    intent?: ConversionFormIntent;
+    /** Optional metadata copied into the submit event. */
+    metadata?: Record<string, unknown>;
+    /** Called when a watched form submits. */
+    onSubmit?: (event: WatchFormsEvent) => void;
+};
+export type WatchFormsController = {
+    /** Number of forms watched by this call. */
+    watchedForms: number;
+    /** Remove submit listeners added by this call. */
+    destroy: () => void;
+};
+export type ProtectFormsController = {
+    /** Number of forms protected by this call. */
+    protectedForms: number;
+    /** Remove submit listeners added by this call. */
+    destroy: () => void;
+};
+export type WatchActionsOptions = {
+    /** Action being watched — e.g. "checkout", "reset", "update". */
+    action: string;
+    /** Root node to search. Defaults to document. */
+    root?: ParentNode;
+    /** Called on each action with the risk result. */
+    onAction?: (event: WatchActionsEvent) => void;
+};
+export type WatchActionsEvent = {
+    action: string;
+    risk: RiskResult;
+    timestamp: string;
+};
+export type WatchActionsController = {
+    /** Number of forms watched by this call. */
+    watchedForms: number;
+    /** Remove submit listeners added by this call. */
+    destroy: () => void;
+};
+export declare function watchSignups(options?: Omit<WatchFormsOptions, "intent">): WatchFormsController;
+export declare function watchForms(options?: WatchFormsOptions): WatchFormsController;
+export declare function watchActions(options: WatchActionsOptions): WatchActionsController;
+export declare function protectForms(root?: ParentNode): ProtectFormsController;
+//# sourceMappingURL=index.d.ts.map