@verivyx/paywall-next 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verivyx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @verivyx/paywall-next
+
+Next.js (App Router) adapter for the Verivyx paywall SDK — gate content from AI bots and charge agents on-chain via x402, with Vercel-aware IP resolution and async `ctx.params` support (Next 15+).
+
+Requires `@verivyx/paywall` (installed automatically as a dependency) and `next` + `react` (peer dependencies).
+
+## Install
+
+```sh
+npm i @verivyx/paywall-next
+```
+
+## Quickstart
+
+```ts
+// app/articles/[slug]/route.ts
+import { verivyxNext } from "@verivyx/paywall-next";
+
+// Create an adapter (reads VERIVYX_TOKEN + VERIVYX_DOMAIN from env)
+const vx = verivyxNext();
+
+async function handler(req: Request, ctx: { params?: Promise<Record<string, string>> }) {
+  return Response.json({ content: "..." });
+}
+
+// Export as a Next.js route handler — verified/paid requests pass through; bots get a 402
+export const GET = vx.protect(handler);
+```
+
+### With SEO preview
+
+```ts
+export const GET = vx.protect(handler, {
+  seoPreview: ({ slug }) => ({
+    title: "Article title",
+    excerpt: "A short teaser visible to search crawlers.",
+  }),
+});
+```
+
+### Proxy pre-filter (optional, defense-in-depth)
+
+```ts
+// proxy.ts (Next 16; middleware.ts on Next <=15)
+import { verivyxNext } from "@verivyx/paywall-next";
+import type { NextRequest } from "next/server";
+
+// reads VERIVYX_TOKEN + VERIVYX_DOMAIN from env (throws at startup if unset)
+const vx = verivyxNext();
+const preFilter = vx.proxy(); // coarse, network-free pre-filter — the route handler is the real gate
+
+export async function proxy(req: NextRequest) {
+  return (await preFilter(req)) ?? undefined; // 402 for clear unpaid bots, else continue
+}
+
+export const config = { matcher: ["/articles/:path*", "/api/:path*"] };
+```
+
+The proxy is defense-in-depth only — it sheds obviously-unpaid bot traffic early (no network call). The route handler (`vx.protect(handler)`) remains the authoritative gate and must always be present.
+
+## Config
+
+All options can be passed to `verivyxNext(opts)` or set via environment variables.
+
+| Env var | Required | Description |
+|---|---|---|
+| `VERIVYX_TOKEN` | yes (server-only) | Domain provisioning token from the Verivyx dashboard |
+| `VERIVYX_DOMAIN` | yes | Your site domain, e.g. `example.com` |
+| `VERIVYX_MATCH` | no | Comma-separated glob patterns to gate (e.g. `/articles/**`). Empty = gate all routes. Also accepts `string[]` in code. |
+| `VERIVYX_FAIL_MODE` | no | Behaviour when the Verivyx backend is unreachable: `teaser` (default) \| `open` \| `closed` |
+| `VERIVYX_TIMEOUT_MS` | no | Backend request timeout in milliseconds (default `800`) |
+
+Additional code-only options: `trustProxy` (default `true`), `advertise` (RSL/AIPREF discovery headers).
+
+## Docs
+
+[https://docs.verivyx.com/docs/sdk](https://docs.verivyx.com/docs/sdk)

package/dist/index.cjs

@@ -0,0 +1,135 @@
+'use strict';
+
+var paywall = require('@verivyx/paywall');
+
+// src/index.ts
+function firstHop(xff) {
+  if (xff === null || xff === "") {
+    return void 0;
+  }
+  const first = xff.split(",")[0];
+  return first !== void 0 ? first.trim() || void 0 : void 0;
+}
+function lastPathSegment(url) {
+  let pathname;
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    pathname = url;
+  }
+  const segments = pathname.split("/").filter((s) => s.length > 0);
+  const last = segments[segments.length - 1];
+  if (last === void 0) {
+    return "";
+  }
+  try {
+    return decodeURIComponent(last);
+  } catch {
+    return last;
+  }
+}
+function resolveIp(req, trustProxy) {
+  if (!trustProxy) {
+    return void 0;
+  }
+  const xff = req.headers.get("x-forwarded-for");
+  const hop = firstHop(xff);
+  if (hop !== void 0) {
+    return hop;
+  }
+  const xri = req.headers.get("x-real-ip");
+  return xri !== null && xri !== "" ? xri : void 0;
+}
+function withAdvertiseHeaders(res, advertise) {
+  if (advertise === void 0) {
+    return res;
+  }
+  const headers = new Headers(res.headers);
+  headers.append("Link", paywall.rslLinkHeader(advertise));
+  headers.set("Content-Usage", paywall.contentUsageHeader(advertise));
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+function verivyxNext(opts) {
+  const vx = opts?._core ?? paywall.verivyx(opts, {
+    verifyCrawlerDns: opts?.verifyCrawlerDns ?? paywall.createSearchCrawlerVerifier(),
+    ...opts?.verifyWebBotAuth !== void 0 ? { verifyWebBotAuth: opts.verifyWebBotAuth } : {}
+  });
+  const trustProxy = opts?.trustProxy !== false;
+  const proc = globalThis.process;
+  const env = proc?.env ?? {};
+  const cfg = paywall.resolveConfig(opts, env);
+  const proxyVerifyWebBotAuth = opts?.verifyWebBotAuth ?? paywall.verifyWebBotAuth;
+  return {
+    protect(handler, o) {
+      return async function verivyxNextGuard(req, ctx) {
+        const ip = resolveIp(req, trustProxy);
+        let coreReq;
+        if (ip !== void 0) {
+          const headers = new Headers(req.headers);
+          headers.set("x-real-ip", ip);
+          coreReq = new Request(req.url, {
+            method: req.method,
+            headers
+            // Do not attach body to coreReq — core classify reads headers only.
+          });
+        } else {
+          const headers = new Headers(req.headers);
+          headers.delete("x-real-ip");
+          headers.delete("x-forwarded-for");
+          coreReq = new Request(req.url, {
+            method: req.method,
+            headers
+          });
+        }
+        const resolvedSlug = o?.slug?.(req) ?? (ctx.params !== void 0 ? (await ctx.params).slug : void 0) ?? lastPathSegment(req.url);
+        const decision = await vx.protect(coreReq, { slug: resolvedSlug });
+        if (!decision.allowed) {
+          const isPreviewCandidate = decision.reason === "crawler" || decision.reason === "human-unverified";
+          if (isPreviewCandidate && o?.seoPreview !== void 0) {
+            return withAdvertiseHeaders(
+              paywall.buildSeoPreviewResponse(resolvedSlug, req.url, o.seoPreview),
+              opts?.advertise
+            );
+          }
+          return withAdvertiseHeaders(decision.response(), opts?.advertise);
+        }
+        const res = await handler(req, ctx);
+        return withAdvertiseHeaders(
+          paywall.attachPaymentResponse(res, decision.paymentResponse),
+          opts?.advertise
+        );
+      };
+    },
+    proxy() {
+      return async function verivyxProxy(req) {
+        const hasPaymentHeader = req.headers.has("payment-signature") || req.headers.has("x-payment");
+        if (hasPaymentHeader) {
+          return void 0;
+        }
+        let classification;
+        try {
+          const result = await paywall.classify(req, cfg, {
+            verifyWebBotAuth: proxyVerifyWebBotAuth
+          });
+          classification = result.classification;
+        } catch {
+          return void 0;
+        }
+        if (classification === "ai-bot" || classification === "signed-agent") {
+          return new Response(
+            JSON.stringify({ error: "payment_required" }),
+            {
+              status: 402,
+              headers: { "content-type": "application/json" }
+            }
+          );
+        }
+        return void 0;
+      };
+    }
+  };
+}
+
+exports.verivyxNext = verivyxNext;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["rslLinkHeader","contentUsageHeader","verivyx","createSearchCrawlerVerifier","resolveConfig","coreVerifyWebBotAuth","buildSeoPreviewResponse","attachPaymentResponse","classify"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @verivyx/paywall-next\n *\n * Next.js (App Router) adapter for the Verivyx paywall SDK.\n *\n * Thin layer — all gate logic lives in @verivyx/paywall core.\n * This module handles:\n *   1. IP resolution from Next.js / Vercel proxy headers.\n *   2. Awaiting the Next 15+ async `ctx.params` Promise.\n *   3. Calling core `protect()` (decision overload).\n *   4. Returning `decision.response()` when denied (handler NOT called).\n *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.\n *   6. SEO preview: when the caller supplies `seoPreview`, the adapter builds\n *      the preview HTML itself (using the core-exported `buildPreviewHtml` /\n *      `buildPaywallJsonLd`) and returns it for crawler/human-unverified\n *      decisions. This approach is used because the core's decision overload\n *      (`protect(req, {slug})`) does not forward previewBuilders — only the\n *      wrap overload (`protect(handler, {seoPreview})`) does. Using core\n *      exports directly keeps this adapter on the decision overload while still\n *      delivering the preview.\n *\n * @example\n * ```ts\n * import { verivyxNext } from \"@verivyx/paywall-next\";\n * const vx = verivyxNext({ domain: \"example.com\", token: process.env.VX_TOKEN });\n * export const GET = vx.protect(myHandler, {\n *   seoPreview: ({ slug }) => ({ title: \"Article\", excerpt: \"Read more...\" }),\n * });\n * ```\n */\n\nimport {\n  verivyx,\n  resolveConfig,\n  createSearchCrawlerVerifier,\n  classify,\n  verifyWebBotAuth as coreVerifyWebBotAuth,\n  buildSeoPreviewResponse,\n  attachPaymentResponse,\n  rslLinkHeader,\n  contentUsageHeader,\n} from \"@verivyx/paywall\";\nimport type { VerivyxOptions, Verivyx, DiscoveryOptions } from \"@verivyx/paywall\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the Next.js adapter.\n * Extends core VerivyxOptions with Next-specific controls.\n */\nexport interface NextAdapterOptions extends VerivyxOptions {\n  /**\n   * When true (default), read the client IP from `X-Forwarded-For` /\n   * `X-Real-IP` headers (set by Vercel / a trusted reverse proxy).\n   * Set to false if running without a proxy, to ignore those headers.\n   */\n  trustProxy?: boolean;\n\n  /**\n   * Override the reverse-DNS search-crawler verifier injected into the core.\n   * When omitted, `createSearchCrawlerVerifier()` is used (the Node.js impl).\n   */\n  verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;\n\n  /**\n   * Override the Web Bot Auth verifier injected into the core.\n   * When omitted, the core's bundled RFC 9421 verifier is used.\n   */\n  verifyWebBotAuth?: (req: Request) => Promise<boolean>;\n\n  /**\n   * @internal\n   * Inject a pre-built `Verivyx` core instance. Used in tests via\n   * `verivyx.mock({...})` to avoid any network access. Production code\n   * should never set this; omit it and the adapter constructs the real core.\n   */\n  _core?: Verivyx;\n\n  /**\n   * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both\n   * the denied (402) and allowed handler responses.\n   * Default undefined = OFF (no headers added; existing behavior unchanged).\n   */\n  advertise?: DiscoveryOptions;\n}\n\n/**\n * A Next.js App Router route handler signature (Next 15+).\n * `ctx.params` is a Promise in Next 15+ (async route segments).\n */\ntype RouteHandler = (\n  req: Request,\n  ctx: { params?: Promise<Record<string, string>> },\n) => Promise<Response> | Response;\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract the first (client-most) hop from an `X-Forwarded-For` header.\n */\nfunction firstHop(xff: string | null): string | undefined {\n  if (xff === null || xff === \"\") {\n    return undefined;\n  }\n  const first = xff.split(\",\")[0];\n  return first !== undefined ? first.trim() || undefined : undefined;\n}\n\n/**\n * Extract the last non-empty path segment from a URL string.\n * Used as a fallback slug when `ctx.params.slug` is unavailable.\n */\nfunction lastPathSegment(url: string): string {\n  let pathname: string;\n  try {\n    pathname = new URL(url).pathname;\n  } catch {\n    pathname = url;\n  }\n  const segments = pathname.split(\"/\").filter((s) => s.length > 0);\n  const last = segments[segments.length - 1];\n  if (last === undefined) {\n    return \"\";\n  }\n  try {\n    return decodeURIComponent(last);\n  } catch {\n    return last;\n  }\n}\n\n/**\n * Resolve the client IP from a Web Request.\n *\n * Precedence (when trustProxy !== false):\n *   1. `X-Forwarded-For` first hop (Vercel / nginx upstream).\n *   2. `X-Real-IP` header.\n * Returns undefined when trustProxy === false or no header is present.\n */\nfunction resolveIp(\n  req: Request,\n  trustProxy: boolean,\n): string | undefined {\n  if (!trustProxy) {\n    return undefined;\n  }\n  const xff = req.headers.get(\"x-forwarded-for\");\n  const hop = firstHop(xff);\n  if (hop !== undefined) {\n    return hop;\n  }\n  const xri = req.headers.get(\"x-real-ip\");\n  return (xri !== null && xri !== \"\") ? xri : undefined;\n}\n\n// (buildSeoPreviewResponse and attachPaymentResponse are imported from @verivyx/paywall)\n\n/**\n * Attach RSL + AIPREF discovery headers to a Web Response by cloning it.\n * Appends to any existing `Link` (preserves prior values); sets `Content-Usage`.\n * Returns the same Response unchanged when `advertise` is undefined.\n */\nfunction withAdvertiseHeaders(res: Response, advertise: DiscoveryOptions | undefined): Response {\n  if (advertise === undefined) {\n    return res;\n  }\n  const headers = new Headers(res.headers);\n  headers.append(\"Link\", rslLinkHeader(advertise));\n  headers.set(\"Content-Usage\", contentUsageHeader(advertise));\n  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });\n}\n\n// ---------------------------------------------------------------------------\n// Adapter factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a Verivyx Next.js adapter.\n *\n * Returns an object with:\n *   - `protect(handler, o)` — wrap a route handler behind the Verivyx gate.\n *   - `proxy()` — a coarse pre-filter for `proxy.ts` (defense-in-depth only).\n *\n * ```ts\n * const vx = verivyxNext({ domain: \"example.com\", token: \"...\" });\n * export const GET = vx.protect(myHandler);\n * ```\n */\nexport function verivyxNext(opts?: NextAdapterOptions): {\n  protect(\n    handler: RouteHandler,\n    o?: {\n      seoPreview?: (c: { slug: string }) => { title: string; excerpt: string };\n      slug?: (req: Request) => string;\n    },\n  ): RouteHandler;\n  proxy(): (req: Request) => Promise<Response | undefined>;\n} {\n  // Resolve the core: use the injected `_core` (tests) or build the real one.\n  // Only pass `verifyWebBotAuth` to the core deps when the caller overrode it;\n  // the core bundled default is correct otherwise.\n  const vx: Verivyx =\n    opts?._core ??\n    verivyx(opts, {\n      verifyCrawlerDns:\n        opts?.verifyCrawlerDns ?? createSearchCrawlerVerifier(),\n      ...(opts?.verifyWebBotAuth !== undefined\n        ? { verifyWebBotAuth: opts.verifyWebBotAuth }\n        : {}),\n    });\n\n  const trustProxy = opts?.trustProxy !== false; // default true\n\n  // Build a real resolved config once for use by proxy()'s classify call.\n  // resolveConfig throws ConfigError when domain/token are absent — same\n  // behaviour as verivyx() itself, so verivyxNext always requires them.\n  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;\n  const env: Record<string, string | undefined> = proc?.env ?? {};\n  const cfg = resolveConfig(opts, env);\n\n  // The verifyWebBotAuth dep used by proxy() mirrors what the core uses:\n  // caller override if supplied, otherwise the bundled RFC 9421 verifier.\n  const proxyVerifyWebBotAuth = opts?.verifyWebBotAuth ?? coreVerifyWebBotAuth;\n\n  return {\n    protect(handler, o) {\n      return async function verivyxNextGuard(\n        req: Request,\n        ctx: { params?: Promise<Record<string, string>> },\n      ): Promise<Response> {\n        // 1. Resolve trusted client IP and inject into a cloned request so the\n        //    core classifier reads a reliable address regardless of edge hop.\n        //\n        //    Security invariant:\n        //      trustProxy !== false → resolve IP from proxy headers and set\n        //        x-real-ip on the cloned request (overrides any client value).\n        //      trustProxy === false  → no trustworthy socket IP is available in\n        //        Next.js route handlers; strip both x-real-ip and x-forwarded-for\n        //        so a client cannot spoof an IP into the core classifier\n        //        (core sees no IP → safe default).\n        const ip = resolveIp(req, trustProxy);\n        let coreReq: Request;\n        if (ip !== undefined) {\n          const headers = new Headers(req.headers);\n          headers.set(\"x-real-ip\", ip);\n          // Clone the Request with updated headers. For GET/HEAD this is safe;\n          // for bodies we do NOT re-attach a body here (the core classify path\n          // reads headers only — body stays with the original `req`).\n          coreReq = new Request(req.url, {\n            method: req.method,\n            headers,\n            // Do not attach body to coreReq — core classify reads headers only.\n          });\n        } else {\n          // trustProxy === false: strip forwarding headers so the client cannot\n          // inject a spoofed IP into the core.\n          const headers = new Headers(req.headers);\n          headers.delete(\"x-real-ip\");\n          headers.delete(\"x-forwarded-for\");\n          coreReq = new Request(req.url, {\n            method: req.method,\n            headers,\n          });\n        }\n\n        // 2. Resolve slug.\n        //    Priority: caller override > ctx.params.slug > last URL segment.\n        //    ctx.params is a Promise in Next 15+ — always await it (guard undefined).\n        const resolvedSlug: string =\n          o?.slug?.(req) ??\n          (ctx.params !== undefined ? (await ctx.params).slug : undefined) ??\n          lastPathSegment(req.url);\n\n        // 3. Ask the core to evaluate the request (decision overload).\n        const decision = await vx.protect(coreReq, { slug: resolvedSlug });\n\n        // 4a. Denied — check if this is a crawler/human-unverified that we can\n        //     serve an SEO preview to instead of a bare 402.\n        if (!decision.allowed) {\n          const isPreviewCandidate =\n            decision.reason === \"crawler\" || decision.reason === \"human-unverified\";\n          if (isPreviewCandidate && o?.seoPreview !== undefined) {\n            return withAdvertiseHeaders(\n              buildSeoPreviewResponse(resolvedSlug, req.url, o.seoPreview),\n              opts?.advertise,\n            );\n          }\n          // Handler is NOT called — return the gate response (402 or preview).\n          return withAdvertiseHeaders(decision.response(), opts?.advertise);\n        }\n\n        // 4b. Allowed — call the original handler.\n        const res = await handler(req, ctx);\n\n        // 5. Attach the settlement receipt header when a payment was processed,\n        //    then attach discovery headers (single clone when both apply).\n        return withAdvertiseHeaders(\n          attachPaymentResponse(res, decision.paymentResponse),\n          opts?.advertise,\n        );\n      };\n    },\n\n    proxy() {\n      /**\n       * Coarse pre-filter for `proxy.ts` — defense-in-depth ONLY.\n       *\n       * proxy() uses the real core classify() function directly (no mock).\n       * It is a coarse, network-free pre-filter: shed obviously-unpaid bot\n       * traffic early before it reaches the route handler. The route handler\n       * (via protect()) remains the authoritative gate.\n       *\n       * Returns a 402 Response only when the request looks like a clear\n       * unpaid bot (ai-bot / signed-agent UA with no payment header).\n       * Returns `undefined` in all other cases — let the request continue to\n       * the route handler which will make the authoritative decision.\n       */\n      return async function verivyxProxy(\n        req: Request,\n      ): Promise<Response | undefined> {\n        // Quick check: if there is any payment signal, skip the pre-filter\n        // and let the route handler handle authorization properly.\n        const hasPaymentHeader =\n          req.headers.has(\"payment-signature\") || req.headers.has(\"x-payment\");\n        if (hasPaymentHeader) {\n          return undefined;\n        }\n\n        // Use the core's exported classify with a real resolved config.\n        // No crawler DNS verification at this layer (proxy does NOT need it —\n        // crawler → preview is the route handler's job, not the proxy's).\n        let classification: string;\n        try {\n          const result = await classify(req, cfg, {\n            verifyWebBotAuth: proxyVerifyWebBotAuth,\n          });\n          classification = result.classification;\n        } catch {\n          // classify error → pass through to route handler.\n          return undefined;\n        }\n\n        if (classification === \"ai-bot\" || classification === \"signed-agent\") {\n          // Return a minimal 402 — the route handler's full 402 body (with\n          // payment requirements) is not built here to keep this lightweight.\n          return new Response(\n            JSON.stringify({ error: \"payment_required\" }),\n            {\n              status: 402,\n              headers: { \"content-type\": \"application/json\" },\n            },\n          );\n        }\n\n        // All other classifications → pass through.\n        return undefined;\n      };\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,101 @@
+import { VerivyxOptions, Verivyx, DiscoveryOptions } from '@verivyx/paywall';
+
+/**
+ * @verivyx/paywall-next
+ *
+ * Next.js (App Router) adapter for the Verivyx paywall SDK.
+ *
+ * Thin layer — all gate logic lives in @verivyx/paywall core.
+ * This module handles:
+ *   1. IP resolution from Next.js / Vercel proxy headers.
+ *   2. Awaiting the Next 15+ async `ctx.params` Promise.
+ *   3. Calling core `protect()` (decision overload).
+ *   4. Returning `decision.response()` when denied (handler NOT called).
+ *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.
+ *   6. SEO preview: when the caller supplies `seoPreview`, the adapter builds
+ *      the preview HTML itself (using the core-exported `buildPreviewHtml` /
+ *      `buildPaywallJsonLd`) and returns it for crawler/human-unverified
+ *      decisions. This approach is used because the core's decision overload
+ *      (`protect(req, {slug})`) does not forward previewBuilders — only the
+ *      wrap overload (`protect(handler, {seoPreview})`) does. Using core
+ *      exports directly keeps this adapter on the decision overload while still
+ *      delivering the preview.
+ *
+ * @example
+ * ```ts
+ * import { verivyxNext } from "@verivyx/paywall-next";
+ * const vx = verivyxNext({ domain: "example.com", token: process.env.VX_TOKEN });
+ * export const GET = vx.protect(myHandler, {
+ *   seoPreview: ({ slug }) => ({ title: "Article", excerpt: "Read more..." }),
+ * });
+ * ```
+ */
+
+/**
+ * Options for the Next.js adapter.
+ * Extends core VerivyxOptions with Next-specific controls.
+ */
+interface NextAdapterOptions extends VerivyxOptions {
+    /**
+     * When true (default), read the client IP from `X-Forwarded-For` /
+     * `X-Real-IP` headers (set by Vercel / a trusted reverse proxy).
+     * Set to false if running without a proxy, to ignore those headers.
+     */
+    trustProxy?: boolean;
+    /**
+     * Override the reverse-DNS search-crawler verifier injected into the core.
+     * When omitted, `createSearchCrawlerVerifier()` is used (the Node.js impl).
+     */
+    verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;
+    /**
+     * Override the Web Bot Auth verifier injected into the core.
+     * When omitted, the core's bundled RFC 9421 verifier is used.
+     */
+    verifyWebBotAuth?: (req: Request) => Promise<boolean>;
+    /**
+     * @internal
+     * Inject a pre-built `Verivyx` core instance. Used in tests via
+     * `verivyx.mock({...})` to avoid any network access. Production code
+     * should never set this; omit it and the adapter constructs the real core.
+     */
+    _core?: Verivyx;
+    /**
+     * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both
+     * the denied (402) and allowed handler responses.
+     * Default undefined = OFF (no headers added; existing behavior unchanged).
+     */
+    advertise?: DiscoveryOptions;
+}
+/**
+ * A Next.js App Router route handler signature (Next 15+).
+ * `ctx.params` is a Promise in Next 15+ (async route segments).
+ */
+type RouteHandler = (req: Request, ctx: {
+    params?: Promise<Record<string, string>>;
+}) => Promise<Response> | Response;
+/**
+ * Create a Verivyx Next.js adapter.
+ *
+ * Returns an object with:
+ *   - `protect(handler, o)` — wrap a route handler behind the Verivyx gate.
+ *   - `proxy()` — a coarse pre-filter for `proxy.ts` (defense-in-depth only).
+ *
+ * ```ts
+ * const vx = verivyxNext({ domain: "example.com", token: "..." });
+ * export const GET = vx.protect(myHandler);
+ * ```
+ */
+declare function verivyxNext(opts?: NextAdapterOptions): {
+    protect(handler: RouteHandler, o?: {
+        seoPreview?: (c: {
+            slug: string;
+        }) => {
+            title: string;
+            excerpt: string;
+        };
+        slug?: (req: Request) => string;
+    }): RouteHandler;
+    proxy(): (req: Request) => Promise<Response | undefined>;
+};
+
+export { type NextAdapterOptions, verivyxNext };

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { VerivyxOptions, Verivyx, DiscoveryOptions } from '@verivyx/paywall';
+
+/**
+ * @verivyx/paywall-next
+ *
+ * Next.js (App Router) adapter for the Verivyx paywall SDK.
+ *
+ * Thin layer — all gate logic lives in @verivyx/paywall core.
+ * This module handles:
+ *   1. IP resolution from Next.js / Vercel proxy headers.
+ *   2. Awaiting the Next 15+ async `ctx.params` Promise.
+ *   3. Calling core `protect()` (decision overload).
+ *   4. Returning `decision.response()` when denied (handler NOT called).
+ *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.
+ *   6. SEO preview: when the caller supplies `seoPreview`, the adapter builds
+ *      the preview HTML itself (using the core-exported `buildPreviewHtml` /
+ *      `buildPaywallJsonLd`) and returns it for crawler/human-unverified
+ *      decisions. This approach is used because the core's decision overload
+ *      (`protect(req, {slug})`) does not forward previewBuilders — only the
+ *      wrap overload (`protect(handler, {seoPreview})`) does. Using core
+ *      exports directly keeps this adapter on the decision overload while still
+ *      delivering the preview.
+ *
+ * @example
+ * ```ts
+ * import { verivyxNext } from "@verivyx/paywall-next";
+ * const vx = verivyxNext({ domain: "example.com", token: process.env.VX_TOKEN });
+ * export const GET = vx.protect(myHandler, {
+ *   seoPreview: ({ slug }) => ({ title: "Article", excerpt: "Read more..." }),
+ * });
+ * ```
+ */
+
+/**
+ * Options for the Next.js adapter.
+ * Extends core VerivyxOptions with Next-specific controls.
+ */
+interface NextAdapterOptions extends VerivyxOptions {
+    /**
+     * When true (default), read the client IP from `X-Forwarded-For` /
+     * `X-Real-IP` headers (set by Vercel / a trusted reverse proxy).
+     * Set to false if running without a proxy, to ignore those headers.
+     */
+    trustProxy?: boolean;
+    /**
+     * Override the reverse-DNS search-crawler verifier injected into the core.
+     * When omitted, `createSearchCrawlerVerifier()` is used (the Node.js impl).
+     */
+    verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;
+    /**
+     * Override the Web Bot Auth verifier injected into the core.
+     * When omitted, the core's bundled RFC 9421 verifier is used.
+     */
+    verifyWebBotAuth?: (req: Request) => Promise<boolean>;
+    /**
+     * @internal
+     * Inject a pre-built `Verivyx` core instance. Used in tests via
+     * `verivyx.mock({...})` to avoid any network access. Production code
+     * should never set this; omit it and the adapter constructs the real core.
+     */
+    _core?: Verivyx;
+    /**
+     * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both
+     * the denied (402) and allowed handler responses.
+     * Default undefined = OFF (no headers added; existing behavior unchanged).
+     */
+    advertise?: DiscoveryOptions;
+}
+/**
+ * A Next.js App Router route handler signature (Next 15+).
+ * `ctx.params` is a Promise in Next 15+ (async route segments).
+ */
+type RouteHandler = (req: Request, ctx: {
+    params?: Promise<Record<string, string>>;
+}) => Promise<Response> | Response;
+/**
+ * Create a Verivyx Next.js adapter.
+ *
+ * Returns an object with:
+ *   - `protect(handler, o)` — wrap a route handler behind the Verivyx gate.
+ *   - `proxy()` — a coarse pre-filter for `proxy.ts` (defense-in-depth only).
+ *
+ * ```ts
+ * const vx = verivyxNext({ domain: "example.com", token: "..." });
+ * export const GET = vx.protect(myHandler);
+ * ```
+ */
+declare function verivyxNext(opts?: NextAdapterOptions): {
+    protect(handler: RouteHandler, o?: {
+        seoPreview?: (c: {
+            slug: string;
+        }) => {
+            title: string;
+            excerpt: string;
+        };
+        slug?: (req: Request) => string;
+    }): RouteHandler;
+    proxy(): (req: Request) => Promise<Response | undefined>;
+};
+
+export { type NextAdapterOptions, verivyxNext };

package/dist/index.js

@@ -0,0 +1,133 @@
+import { verivyx, createSearchCrawlerVerifier, resolveConfig, verifyWebBotAuth, classify, buildSeoPreviewResponse, attachPaymentResponse, rslLinkHeader, contentUsageHeader } from '@verivyx/paywall';
+
+// src/index.ts
+function firstHop(xff) {
+  if (xff === null || xff === "") {
+    return void 0;
+  }
+  const first = xff.split(",")[0];
+  return first !== void 0 ? first.trim() || void 0 : void 0;
+}
+function lastPathSegment(url) {
+  let pathname;
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    pathname = url;
+  }
+  const segments = pathname.split("/").filter((s) => s.length > 0);
+  const last = segments[segments.length - 1];
+  if (last === void 0) {
+    return "";
+  }
+  try {
+    return decodeURIComponent(last);
+  } catch {
+    return last;
+  }
+}
+function resolveIp(req, trustProxy) {
+  if (!trustProxy) {
+    return void 0;
+  }
+  const xff = req.headers.get("x-forwarded-for");
+  const hop = firstHop(xff);
+  if (hop !== void 0) {
+    return hop;
+  }
+  const xri = req.headers.get("x-real-ip");
+  return xri !== null && xri !== "" ? xri : void 0;
+}
+function withAdvertiseHeaders(res, advertise) {
+  if (advertise === void 0) {
+    return res;
+  }
+  const headers = new Headers(res.headers);
+  headers.append("Link", rslLinkHeader(advertise));
+  headers.set("Content-Usage", contentUsageHeader(advertise));
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+function verivyxNext(opts) {
+  const vx = opts?._core ?? verivyx(opts, {
+    verifyCrawlerDns: opts?.verifyCrawlerDns ?? createSearchCrawlerVerifier(),
+    ...opts?.verifyWebBotAuth !== void 0 ? { verifyWebBotAuth: opts.verifyWebBotAuth } : {}
+  });
+  const trustProxy = opts?.trustProxy !== false;
+  const proc = globalThis.process;
+  const env = proc?.env ?? {};
+  const cfg = resolveConfig(opts, env);
+  const proxyVerifyWebBotAuth = opts?.verifyWebBotAuth ?? verifyWebBotAuth;
+  return {
+    protect(handler, o) {
+      return async function verivyxNextGuard(req, ctx) {
+        const ip = resolveIp(req, trustProxy);
+        let coreReq;
+        if (ip !== void 0) {
+          const headers = new Headers(req.headers);
+          headers.set("x-real-ip", ip);
+          coreReq = new Request(req.url, {
+            method: req.method,
+            headers
+            // Do not attach body to coreReq — core classify reads headers only.
+          });
+        } else {
+          const headers = new Headers(req.headers);
+          headers.delete("x-real-ip");
+          headers.delete("x-forwarded-for");
+          coreReq = new Request(req.url, {
+            method: req.method,
+            headers
+          });
+        }
+        const resolvedSlug = o?.slug?.(req) ?? (ctx.params !== void 0 ? (await ctx.params).slug : void 0) ?? lastPathSegment(req.url);
+        const decision = await vx.protect(coreReq, { slug: resolvedSlug });
+        if (!decision.allowed) {
+          const isPreviewCandidate = decision.reason === "crawler" || decision.reason === "human-unverified";
+          if (isPreviewCandidate && o?.seoPreview !== void 0) {
+            return withAdvertiseHeaders(
+              buildSeoPreviewResponse(resolvedSlug, req.url, o.seoPreview),
+              opts?.advertise
+            );
+          }
+          return withAdvertiseHeaders(decision.response(), opts?.advertise);
+        }
+        const res = await handler(req, ctx);
+        return withAdvertiseHeaders(
+          attachPaymentResponse(res, decision.paymentResponse),
+          opts?.advertise
+        );
+      };
+    },
+    proxy() {
+      return async function verivyxProxy(req) {
+        const hasPaymentHeader = req.headers.has("payment-signature") || req.headers.has("x-payment");
+        if (hasPaymentHeader) {
+          return void 0;
+        }
+        let classification;
+        try {
+          const result = await classify(req, cfg, {
+            verifyWebBotAuth: proxyVerifyWebBotAuth
+          });
+          classification = result.classification;
+        } catch {
+          return void 0;
+        }
+        if (classification === "ai-bot" || classification === "signed-agent") {
+          return new Response(
+            JSON.stringify({ error: "payment_required" }),
+            {
+              status: 402,
+              headers: { "content-type": "application/json" }
+            }
+          );
+        }
+        return void 0;
+      };
+    }
+  };
+}
+
+export { verivyxNext };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["coreVerifyWebBotAuth"],"mappings":";;;AAwGA,SAAS,SAAS,GAAA,EAAwC;AACxD,EAAA,IAAI,GAAA,KAAQ,IAAA,IAAQ,GAAA,KAAQ,EAAA,EAAI;AAC9B,IAAA,OAAO,MAAA;AAAA,EACT;AACA,EAAA,MAAM,KAAA,GAAQ,GAAA,CAAI,KAAA,CAAM,GAAG,EAAE,CAAC,CAAA;AAC9B,EAAA,OAAO,KAAA,KAAU,MAAA,GAAY,KAAA,CAAM,IAAA,MAAU,MAAA,GAAY,MAAA;AAC3D;AAMA,SAAS,gBAAgB,GAAA,EAAqB;AAC5C,EAAA,IAAI,QAAA;AACJ,EAAA,IAAI;AACF,IAAA,QAAA,GAAW,IAAI,GAAA,CAAI,GAAG,CAAA,CAAE,QAAA;AAAA,EAC1B,CAAA,CAAA,MAAQ;AACN,IAAA,QAAA,GAAW,GAAA;AAAA,EACb;AACA,EAAA,MAAM,QAAA,GAAW,QAAA,CAAS,KAAA,CAAM,GAAG,CAAA,CAAE,OAAO,CAAC,CAAA,KAAM,CAAA,CAAE,MAAA,GAAS,CAAC,CAAA;AAC/D,EAAA,MAAM,IAAA,GAAO,QAAA,CAAS,QAAA,CAAS,MAAA,GAAS,CAAC,CAAA;AACzC,EAAA,IAAI,SAAS,MAAA,EAAW;AACtB,IAAA,OAAO,EAAA;AAAA,EACT;AACA,EAAA,IAAI;AACF,IAAA,OAAO,mBAAmB,IAAI,CAAA;AAAA,EAChC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAUA,SAAS,SAAA,CACP,KACA,UAAA,EACoB;AACpB,EAAA,IAAI,CAAC,UAAA,EAAY;AACf,IAAA,OAAO,MAAA;AAAA,EACT;AACA,EAAA,MAAM,GAAA,GAAM,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,iBAAiB,CAAA;AAC7C,EAAA,MAAM,GAAA,GAAM,SAAS,GAAG,CAAA;AACxB,EAAA,IAAI,QAAQ,MAAA,EAAW;AACrB,IAAA,OAAO,GAAA;AAAA,EACT;AACA,EAAA,MAAM,GAAA,GAAM,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA;AACvC,EAAA,OAAQ,GAAA,KAAQ,IAAA,IAAQ,GAAA,KAAQ,EAAA,GAAM,GAAA,GAAM,MAAA;AAC9C;AASA,SAAS,oBAAA,CAAqB,KAAe,SAAA,EAAmD;AAC9F,EAAA,IAAI,cAAc,MAAA,EAAW;AAC3B,IAAA,OAAO,GAAA;AAAA,EACT;AACA,EAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,GAAA,CAAI,OAAO,CAAA;AACvC,EAAA,OAAA,CAAQ,MAAA,CAAO,MAAA,EAAQ,aAAA,CAAc,SAAS,CAAC,CAAA;AAC/C,EAAA,OAAA,CAAQ,GAAA,CAAI,eAAA,EAAiB,kBAAA,CAAmB,SAAS,CAAC,CAAA;AAC1D,EAAA,OAAO,IAAI,QAAA,CAAS,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,GAAA,CAAI,MAAA,EAAQ,UAAA,EAAY,GAAA,CAAI,UAAA,EAAY,OAAA,EAAS,CAAA;AAC3F;AAkBO,SAAS,YAAY,IAAA,EAS1B;AAIA,EAAA,MAAM,EAAA,GACJ,IAAA,EAAM,KAAA,IACN,OAAA,CAAQ,IAAA,EAAM;AAAA,IACZ,gBAAA,EACE,IAAA,EAAM,gBAAA,IAAoB,2BAAA,EAA4B;AAAA,IACxD,GAAI,MAAM,gBAAA,KAAqB,MAAA,GAC3B,EAAE,gBAAA,EAAkB,IAAA,CAAK,gBAAA,EAAiB,GAC1C;AAAC,GACN,CAAA;AAEH,EAAA,MAAM,UAAA,GAAa,MAAM,UAAA,KAAe,KAAA;AAKxC,EAAA,MAAM,OAAQ,UAAA,CAA0E,OAAA;AACxF,EAAA,MAAM,GAAA,GAA0C,IAAA,EAAM,GAAA,IAAO,EAAC;AAC9D,EAAA,MAAM,GAAA,GAAM,aAAA,CAAc,IAAA,EAAM,GAAG,CAAA;AAInC,EAAA,MAAM,qBAAA,GAAwB,MAAM,gBAAA,IAAoBA,gBAAA;AAExD,EAAA,OAAO;AAAA,IACL,OAAA,CAAQ,SAAS,CAAA,EAAG;AAClB,MAAA,OAAO,eAAe,gBAAA,CACpB,GAAA,EACA,GAAA,EACmB;AAWnB,QAAA,MAAM,EAAA,GAAK,SAAA,CAAU,GAAA,EAAK,UAAU,CAAA;AACpC,QAAA,IAAI,OAAA;AACJ,QAAA,IAAI,OAAO,MAAA,EAAW;AACpB,UAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,GAAA,CAAI,OAAO,CAAA;AACvC,UAAA,OAAA,CAAQ,GAAA,CAAI,aAAa,EAAE,CAAA;AAI3B,UAAA,OAAA,GAAU,IAAI,OAAA,CAAQ,GAAA,CAAI,GAAA,EAAK;AAAA,YAC7B,QAAQ,GAAA,CAAI,MAAA;AAAA,YACZ;AAAA;AAAA,WAED,CAAA;AAAA,QACH,CAAA,MAAO;AAGL,UAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,GAAA,CAAI,OAAO,CAAA;AACvC,UAAA,OAAA,CAAQ,OAAO,WAAW,CAAA;AAC1B,UAAA,OAAA,CAAQ,OAAO,iBAAiB,CAAA;AAChC,UAAA,OAAA,GAAU,IAAI,OAAA,CAAQ,GAAA,CAAI,GAAA,EAAK;AAAA,YAC7B,QAAQ,GAAA,CAAI,MAAA;AAAA,YACZ;AAAA,WACD,CAAA;AAAA,QACH;AAKA,QAAA,MAAM,YAAA,GACJ,CAAA,EAAG,IAAA,GAAO,GAAG,MACZ,GAAA,CAAI,MAAA,KAAW,MAAA,GAAA,CAAa,MAAM,IAAI,MAAA,EAAQ,IAAA,GAAO,MAAA,CAAA,IACtD,eAAA,CAAgB,IAAI,GAAG,CAAA;AAGzB,QAAA,MAAM,QAAA,GAAW,MAAM,EAAA,CAAG,OAAA,CAAQ,SAAS,EAAE,IAAA,EAAM,cAAc,CAAA;AAIjE,QAAA,IAAI,CAAC,SAAS,OAAA,EAAS;AACrB,UAAA,MAAM,kBAAA,GACJ,QAAA,CAAS,MAAA,KAAW,SAAA,IAAa,SAAS,MAAA,KAAW,kBAAA;AACvD,UAAA,IAAI,kBAAA,IAAsB,CAAA,EAAG,UAAA,KAAe,MAAA,EAAW;AACrD,YAAA,OAAO,oBAAA;AAAA,cACL,uBAAA,CAAwB,YAAA,EAAc,GAAA,CAAI,GAAA,EAAK,EAAE,UAAU,CAAA;AAAA,cAC3D,IAAA,EAAM;AAAA,aACR;AAAA,UACF;AAEA,UAAA,OAAO,oBAAA,CAAqB,QAAA,CAAS,QAAA,EAAS,EAAG,MAAM,SAAS,CAAA;AAAA,QAClE;AAGA,QAAA,MAAM,GAAA,GAAM,MAAM,OAAA,CAAQ,GAAA,EAAK,GAAG,CAAA;AAIlC,QAAA,OAAO,oBAAA;AAAA,UACL,qBAAA,CAAsB,GAAA,EAAK,QAAA,CAAS,eAAe,CAAA;AAAA,UACnD,IAAA,EAAM;AAAA,SACR;AAAA,MACF,CAAA;AAAA,IACF,CAAA;AAAA,IAEA,KAAA,GAAQ;AAcN,MAAA,OAAO,eAAe,aACpB,GAAA,EAC+B;AAG/B,QAAA,MAAM,gBAAA,GACJ,IAAI,OAAA,CAAQ,GAAA,CAAI,mBAAmB,CAAA,IAAK,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,WAAW,CAAA;AACrE,QAAA,IAAI,gBAAA,EAAkB;AACpB,UAAA,OAAO,MAAA;AAAA,QACT;AAKA,QAAA,IAAI,cAAA;AACJ,QAAA,IAAI;AACF,UAAA,MAAM,MAAA,GAAS,MAAM,QAAA,CAAS,GAAA,EAAK,GAAA,EAAK;AAAA,YACtC,gBAAA,EAAkB;AAAA,WACnB,CAAA;AACD,UAAA,cAAA,GAAiB,MAAA,CAAO,cAAA;AAAA,QAC1B,CAAA,CAAA,MAAQ;AAEN,UAAA,OAAO,MAAA;AAAA,QACT;AAEA,QAAA,IAAI,cAAA,KAAmB,QAAA,IAAY,cAAA,KAAmB,cAAA,EAAgB;AAGpE,UAAA,OAAO,IAAI,QAAA;AAAA,YACT,IAAA,CAAK,SAAA,CAAU,EAAE,KAAA,EAAO,oBAAoB,CAAA;AAAA,YAC5C;AAAA,cACE,MAAA,EAAQ,GAAA;AAAA,cACR,OAAA,EAAS,EAAE,cAAA,EAAgB,kBAAA;AAAmB;AAChD,WACF;AAAA,QACF;AAGA,QAAA,OAAO,MAAA;AAAA,MACT,CAAA;AAAA,IACF;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @verivyx/paywall-next\n *\n * Next.js (App Router) adapter for the Verivyx paywall SDK.\n *\n * Thin layer — all gate logic lives in @verivyx/paywall core.\n * This module handles:\n *   1. IP resolution from Next.js / Vercel proxy headers.\n *   2. Awaiting the Next 15+ async `ctx.params` Promise.\n *   3. Calling core `protect()` (decision overload).\n *   4. Returning `decision.response()` when denied (handler NOT called).\n *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.\n *   6. SEO preview: when the caller supplies `seoPreview`, the adapter builds\n *      the preview HTML itself (using the core-exported `buildPreviewHtml` /\n *      `buildPaywallJsonLd`) and returns it for crawler/human-unverified\n *      decisions. This approach is used because the core's decision overload\n *      (`protect(req, {slug})`) does not forward previewBuilders — only the\n *      wrap overload (`protect(handler, {seoPreview})`) does. Using core\n *      exports directly keeps this adapter on the decision overload while still\n *      delivering the preview.\n *\n * @example\n * ```ts\n * import { verivyxNext } from \"@verivyx/paywall-next\";\n * const vx = verivyxNext({ domain: \"example.com\", token: process.env.VX_TOKEN });\n * export const GET = vx.protect(myHandler, {\n *   seoPreview: ({ slug }) => ({ title: \"Article\", excerpt: \"Read more...\" }),\n * });\n * ```\n */\n\nimport {\n  verivyx,\n  resolveConfig,\n  createSearchCrawlerVerifier,\n  classify,\n  verifyWebBotAuth as coreVerifyWebBotAuth,\n  buildSeoPreviewResponse,\n  attachPaymentResponse,\n  rslLinkHeader,\n  contentUsageHeader,\n} from \"@verivyx/paywall\";\nimport type { VerivyxOptions, Verivyx, DiscoveryOptions } from \"@verivyx/paywall\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the Next.js adapter.\n * Extends core VerivyxOptions with Next-specific controls.\n */\nexport interface NextAdapterOptions extends VerivyxOptions {\n  /**\n   * When true (default), read the client IP from `X-Forwarded-For` /\n   * `X-Real-IP` headers (set by Vercel / a trusted reverse proxy).\n   * Set to false if running without a proxy, to ignore those headers.\n   */\n  trustProxy?: boolean;\n\n  /**\n   * Override the reverse-DNS search-crawler verifier injected into the core.\n   * When omitted, `createSearchCrawlerVerifier()` is used (the Node.js impl).\n   */\n  verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;\n\n  /**\n   * Override the Web Bot Auth verifier injected into the core.\n   * When omitted, the core's bundled RFC 9421 verifier is used.\n   */\n  verifyWebBotAuth?: (req: Request) => Promise<boolean>;\n\n  /**\n   * @internal\n   * Inject a pre-built `Verivyx` core instance. Used in tests via\n   * `verivyx.mock({...})` to avoid any network access. Production code\n   * should never set this; omit it and the adapter constructs the real core.\n   */\n  _core?: Verivyx;\n\n  /**\n   * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both\n   * the denied (402) and allowed handler responses.\n   * Default undefined = OFF (no headers added; existing behavior unchanged).\n   */\n  advertise?: DiscoveryOptions;\n}\n\n/**\n * A Next.js App Router route handler signature (Next 15+).\n * `ctx.params` is a Promise in Next 15+ (async route segments).\n */\ntype RouteHandler = (\n  req: Request,\n  ctx: { params?: Promise<Record<string, string>> },\n) => Promise<Response> | Response;\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract the first (client-most) hop from an `X-Forwarded-For` header.\n */\nfunction firstHop(xff: string | null): string | undefined {\n  if (xff === null || xff === \"\") {\n    return undefined;\n  }\n  const first = xff.split(\",\")[0];\n  return first !== undefined ? first.trim() || undefined : undefined;\n}\n\n/**\n * Extract the last non-empty path segment from a URL string.\n * Used as a fallback slug when `ctx.params.slug` is unavailable.\n */\nfunction lastPathSegment(url: string): string {\n  let pathname: string;\n  try {\n    pathname = new URL(url).pathname;\n  } catch {\n    pathname = url;\n  }\n  const segments = pathname.split(\"/\").filter((s) => s.length > 0);\n  const last = segments[segments.length - 1];\n  if (last === undefined) {\n    return \"\";\n  }\n  try {\n    return decodeURIComponent(last);\n  } catch {\n    return last;\n  }\n}\n\n/**\n * Resolve the client IP from a Web Request.\n *\n * Precedence (when trustProxy !== false):\n *   1. `X-Forwarded-For` first hop (Vercel / nginx upstream).\n *   2. `X-Real-IP` header.\n * Returns undefined when trustProxy === false or no header is present.\n */\nfunction resolveIp(\n  req: Request,\n  trustProxy: boolean,\n): string | undefined {\n  if (!trustProxy) {\n    return undefined;\n  }\n  const xff = req.headers.get(\"x-forwarded-for\");\n  const hop = firstHop(xff);\n  if (hop !== undefined) {\n    return hop;\n  }\n  const xri = req.headers.get(\"x-real-ip\");\n  return (xri !== null && xri !== \"\") ? xri : undefined;\n}\n\n// (buildSeoPreviewResponse and attachPaymentResponse are imported from @verivyx/paywall)\n\n/**\n * Attach RSL + AIPREF discovery headers to a Web Response by cloning it.\n * Appends to any existing `Link` (preserves prior values); sets `Content-Usage`.\n * Returns the same Response unchanged when `advertise` is undefined.\n */\nfunction withAdvertiseHeaders(res: Response, advertise: DiscoveryOptions | undefined): Response {\n  if (advertise === undefined) {\n    return res;\n  }\n  const headers = new Headers(res.headers);\n  headers.append(\"Link\", rslLinkHeader(advertise));\n  headers.set(\"Content-Usage\", contentUsageHeader(advertise));\n  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });\n}\n\n// ---------------------------------------------------------------------------\n// Adapter factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a Verivyx Next.js adapter.\n *\n * Returns an object with:\n *   - `protect(handler, o)` — wrap a route handler behind the Verivyx gate.\n *   - `proxy()` — a coarse pre-filter for `proxy.ts` (defense-in-depth only).\n *\n * ```ts\n * const vx = verivyxNext({ domain: \"example.com\", token: \"...\" });\n * export const GET = vx.protect(myHandler);\n * ```\n */\nexport function verivyxNext(opts?: NextAdapterOptions): {\n  protect(\n    handler: RouteHandler,\n    o?: {\n      seoPreview?: (c: { slug: string }) => { title: string; excerpt: string };\n      slug?: (req: Request) => string;\n    },\n  ): RouteHandler;\n  proxy(): (req: Request) => Promise<Response | undefined>;\n} {\n  // Resolve the core: use the injected `_core` (tests) or build the real one.\n  // Only pass `verifyWebBotAuth` to the core deps when the caller overrode it;\n  // the core bundled default is correct otherwise.\n  const vx: Verivyx =\n    opts?._core ??\n    verivyx(opts, {\n      verifyCrawlerDns:\n        opts?.verifyCrawlerDns ?? createSearchCrawlerVerifier(),\n      ...(opts?.verifyWebBotAuth !== undefined\n        ? { verifyWebBotAuth: opts.verifyWebBotAuth }\n        : {}),\n    });\n\n  const trustProxy = opts?.trustProxy !== false; // default true\n\n  // Build a real resolved config once for use by proxy()'s classify call.\n  // resolveConfig throws ConfigError when domain/token are absent — same\n  // behaviour as verivyx() itself, so verivyxNext always requires them.\n  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;\n  const env: Record<string, string | undefined> = proc?.env ?? {};\n  const cfg = resolveConfig(opts, env);\n\n  // The verifyWebBotAuth dep used by proxy() mirrors what the core uses:\n  // caller override if supplied, otherwise the bundled RFC 9421 verifier.\n  const proxyVerifyWebBotAuth = opts?.verifyWebBotAuth ?? coreVerifyWebBotAuth;\n\n  return {\n    protect(handler, o) {\n      return async function verivyxNextGuard(\n        req: Request,\n        ctx: { params?: Promise<Record<string, string>> },\n      ): Promise<Response> {\n        // 1. Resolve trusted client IP and inject into a cloned request so the\n        //    core classifier reads a reliable address regardless of edge hop.\n        //\n        //    Security invariant:\n        //      trustProxy !== false → resolve IP from proxy headers and set\n        //        x-real-ip on the cloned request (overrides any client value).\n        //      trustProxy === false  → no trustworthy socket IP is available in\n        //        Next.js route handlers; strip both x-real-ip and x-forwarded-for\n        //        so a client cannot spoof an IP into the core classifier\n        //        (core sees no IP → safe default).\n        const ip = resolveIp(req, trustProxy);\n        let coreReq: Request;\n        if (ip !== undefined) {\n          const headers = new Headers(req.headers);\n          headers.set(\"x-real-ip\", ip);\n          // Clone the Request with updated headers. For GET/HEAD this is safe;\n          // for bodies we do NOT re-attach a body here (the core classify path\n          // reads headers only — body stays with the original `req`).\n          coreReq = new Request(req.url, {\n            method: req.method,\n            headers,\n            // Do not attach body to coreReq — core classify reads headers only.\n          });\n        } else {\n          // trustProxy === false: strip forwarding headers so the client cannot\n          // inject a spoofed IP into the core.\n          const headers = new Headers(req.headers);\n          headers.delete(\"x-real-ip\");\n          headers.delete(\"x-forwarded-for\");\n          coreReq = new Request(req.url, {\n            method: req.method,\n            headers,\n          });\n        }\n\n        // 2. Resolve slug.\n        //    Priority: caller override > ctx.params.slug > last URL segment.\n        //    ctx.params is a Promise in Next 15+ — always await it (guard undefined).\n        const resolvedSlug: string =\n          o?.slug?.(req) ??\n          (ctx.params !== undefined ? (await ctx.params).slug : undefined) ??\n          lastPathSegment(req.url);\n\n        // 3. Ask the core to evaluate the request (decision overload).\n        const decision = await vx.protect(coreReq, { slug: resolvedSlug });\n\n        // 4a. Denied — check if this is a crawler/human-unverified that we can\n        //     serve an SEO preview to instead of a bare 402.\n        if (!decision.allowed) {\n          const isPreviewCandidate =\n            decision.reason === \"crawler\" || decision.reason === \"human-unverified\";\n          if (isPreviewCandidate && o?.seoPreview !== undefined) {\n            return withAdvertiseHeaders(\n              buildSeoPreviewResponse(resolvedSlug, req.url, o.seoPreview),\n              opts?.advertise,\n            );\n          }\n          // Handler is NOT called — return the gate response (402 or preview).\n          return withAdvertiseHeaders(decision.response(), opts?.advertise);\n        }\n\n        // 4b. Allowed — call the original handler.\n        const res = await handler(req, ctx);\n\n        // 5. Attach the settlement receipt header when a payment was processed,\n        //    then attach discovery headers (single clone when both apply).\n        return withAdvertiseHeaders(\n          attachPaymentResponse(res, decision.paymentResponse),\n          opts?.advertise,\n        );\n      };\n    },\n\n    proxy() {\n      /**\n       * Coarse pre-filter for `proxy.ts` — defense-in-depth ONLY.\n       *\n       * proxy() uses the real core classify() function directly (no mock).\n       * It is a coarse, network-free pre-filter: shed obviously-unpaid bot\n       * traffic early before it reaches the route handler. The route handler\n       * (via protect()) remains the authoritative gate.\n       *\n       * Returns a 402 Response only when the request looks like a clear\n       * unpaid bot (ai-bot / signed-agent UA with no payment header).\n       * Returns `undefined` in all other cases — let the request continue to\n       * the route handler which will make the authoritative decision.\n       */\n      return async function verivyxProxy(\n        req: Request,\n      ): Promise<Response | undefined> {\n        // Quick check: if there is any payment signal, skip the pre-filter\n        // and let the route handler handle authorization properly.\n        const hasPaymentHeader =\n          req.headers.has(\"payment-signature\") || req.headers.has(\"x-payment\");\n        if (hasPaymentHeader) {\n          return undefined;\n        }\n\n        // Use the core's exported classify with a real resolved config.\n        // No crawler DNS verification at this layer (proxy does NOT need it —\n        // crawler → preview is the route handler's job, not the proxy's).\n        let classification: string;\n        try {\n          const result = await classify(req, cfg, {\n            verifyWebBotAuth: proxyVerifyWebBotAuth,\n          });\n          classification = result.classification;\n        } catch {\n          // classify error → pass through to route handler.\n          return undefined;\n        }\n\n        if (classification === \"ai-bot\" || classification === \"signed-agent\") {\n          // Return a minimal 402 — the route handler's full 402 body (with\n          // payment requirements) is not built here to keep this lightweight.\n          return new Response(\n            JSON.stringify({ error: \"payment_required\" }),\n            {\n              status: 402,\n              headers: { \"content-type\": \"application/json\" },\n            },\n          );\n        }\n\n        // All other classifications → pass through.\n        return undefined;\n      };\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@verivyx/paywall-next",
+  "version": "0.1.0",
+  "description": "Next.js adapter for the Verivyx paywall SDK",
+  "type": "module",
+  "license": "MIT",
+  "author": "Verivyx",
+  "sideEffects": false,
+  "keywords": ["paywall", "x402", "ai", "bot", "stellar", "verivyx"],
+  "homepage": "https://docs.verivyx.com/docs/sdk",
+  "bugs": { "url": "https://github.com/VerivyX/verivyx-monorepo/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VerivyX/verivyx-monorepo.git",
+    "directory": "services/publisher-sdk/packages/next"
+  },
+  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@verivyx/paywall": "^0.1.0"
+  },
+  "peerDependencies": {
+    "next": ">=15 <17",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "next": "^15.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}