searvia-next 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 Searvia
+
+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

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# searvia-next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Apply the SEO fixes you approve in [Searvia](https://searvia.com) to a Next.js (App Router) site: titles, meta
+descriptions, canonical tags, robots, hreflang alternates and JSON-LD are rendered on the server, so Google and AI
+crawlers see them; image alt text and internal links are applied in the browser.
+
+The fix list is signed by Searvia (HMAC-SHA256) and cached by Next.js for five minutes. If Searvia cannot be reached or
+the signature does not match, your pages render as they are.
+
+## Install
+
+```bash
+npm install searvia-next
+```
+
+In Searvia open **SEO › Site fixes**, choose **Next.js** and copy the site key. Then set:
+
+```bash
+SEARVIA_SITE_KEY=xxxxxxxxxxxxxxxxxxxxxxxx.yyyyyyyy   # the site key from Searvia
+SEARVIA_SITE_URL=https://www.example.com             # optional, shown in Searvia
+SEARVIA_WEBHOOK_URL=https://www.example.com/api/searvia  # optional, instant refresh (see below)
+```
+
+## Use
+
+**1. Middleware** (passes the current path to your layout). `middleware.ts`:
+
+```ts
+export { middleware } from 'searvia-next/middleware';
+```
+
+Already have a middleware? Wrap your response: `return withSearviaPath(request, response)`, and to apply approved redirects first add `const redirect = await searviaRedirect(request); if (redirect) return redirect;`.
+
+**2. Root layout** (`app/layout.tsx`):
+
+```tsx
+import { SearviaHead, searviaMetadata, getSearviaFixes, currentPath } from 'searvia-next';
+import { SearviaClientFixes } from 'searvia-next/client';
+
+export async function generateMetadata() {
+  return searviaMetadata({ title: 'My site', description: 'Default description' });
+}
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const { pathname, search } = await currentPath();
+  const fixes = await getSearviaFixes(pathname, search);
+
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <SearviaHead pathname={pathname} search={search} />
+        <SearviaClientFixes fixes={fixes} />
+      </body>
+    </html>
+  );
+}
+```
+
+Pages that set their own `generateMetadata` can wrap it the same way: `return searviaMetadata(myMetadata)`.
+
+The connection turns active in Searvia on the first page your site renders.
+
+**3. Instant refresh (optional).** `app/api/searvia/route.ts`:
+
+```ts
+export { searviaWebhook as POST } from 'searvia-next';
+```
+
+Set `SEARVIA_WEBHOOK_URL` to that address on your own domain. Searvia calls it (signed) whenever you approve or roll
+back a fix, and the list refreshes at once instead of within five minutes.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,8 @@
+import type { Fix } from './feed';
+/**
+ * Image alt text and internal link fixes, applied in the browser after the page renders (they change the page body,
+ * which Next.js renders from your components). Pass the fixes from `getSearviaFixes()`.
+ */
+export declare function SearviaClientFixes({ fixes }: {
+    fixes: Fix[];
+}): null;

package/dist/client.js

@@ -0,0 +1,65 @@
+'use client';
+import { useEffect } from 'react';
+const SKIP = ['A', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'BUTTON', 'SCRIPT', 'STYLE', 'NAV', 'HEADER', 'FOOTER', 'FIGCAPTION'];
+function inline(href, anchor) {
+    const escaped = anchor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+    const pattern = new RegExp('(^|[^\\p{L}\\p{N}])(' + escaped + ')(?![\\p{L}\\p{N}])', 'iu');
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    let node;
+    while ((node = walker.nextNode())) {
+        let inText = false;
+        let blocked = false;
+        for (let element = node.parentElement; element; element = element.parentElement) {
+            if (SKIP.includes(element.tagName)) {
+                blocked = true;
+                break;
+            }
+            if (element.tagName === 'P' || element.tagName === 'LI')
+                inText = true;
+        }
+        const match = !blocked && inText ? pattern.exec(node.nodeValue ?? '') : null;
+        if (match) {
+            const word = node.splitText(match.index + match[1].length);
+            word.splitText(match[2].length);
+            const link = document.createElement('a');
+            link.href = href;
+            word.parentNode?.replaceChild(link, word);
+            link.appendChild(word);
+            return;
+        }
+    }
+}
+/**
+ * Image alt text and internal link fixes, applied in the browser after the page renders (they change the page body,
+ * which Next.js renders from your components). Pass the fixes from `getSearviaFixes()`.
+ */
+export function SearviaClientFixes({ fixes }) {
+    useEffect(() => {
+        for (const fix of fixes) {
+            if (fix.t === 'image_alt') {
+                for (const image of fix.v.images) {
+                    document.querySelectorAll('img').forEach((img) => {
+                        const src = img.getAttribute('src') || img.getAttribute('data-src');
+                        if (src === image.src && !img.hasAttribute('alt'))
+                            img.setAttribute('alt', image.alt);
+                    });
+                }
+            }
+            else if (fix.t === 'internal_link' && fix.v.mode === 'inline') {
+                inline(fix.v.href, fix.v.anchor);
+            }
+            else if (fix.t === 'internal_link' && !document.querySelector(`a.searvia-related[href="${CSS.escape(fix.v.href)}"]`)) {
+                const target = document.querySelector('main') || document.querySelector('article') || document.body;
+                const paragraph = document.createElement('p');
+                const link = document.createElement('a');
+                paragraph.className = 'searvia-related';
+                link.className = 'searvia-related';
+                link.href = fix.v.href;
+                link.textContent = fix.v.anchor;
+                paragraph.appendChild(link);
+                target.appendChild(paragraph);
+            }
+        }
+    }, [fixes]);
+    return null;
+}

package/dist/feed.d.ts

@@ -0,0 +1,26 @@
+export declare const VERSION = "0.2.0";
+export type Fix = {
+    t: string;
+    v: Record<string, any>;
+};
+export type Feed = {
+    v: string;
+    generated: string;
+    fixes: Record<string, Fix[]>;
+};
+type Config = {
+    channel: string;
+    secret: string;
+    base: string;
+    site: string;
+    webhook: string;
+};
+export declare function config(): Config | null;
+export declare function sign(body: string, secret: string): Promise<string>;
+/** Constant-time comparison of two signatures. */
+export declare function same(a: string, b: string): boolean;
+/** The fix list, cached by Next.js for five minutes (tag "searvia"). Returns null when the key is missing or the signature does not match. */
+export declare function getSearviaFeed(): Promise<Feed | null>;
+/** Fixes for one address: path with query first, then the path alone. */
+export declare function getSearviaFixes(pathname: string, search?: string): Promise<Fix[]>;
+export {};

package/dist/feed.js

@@ -0,0 +1,55 @@
+// Searvia fix feed: signed (HMAC-SHA256) list of approved fixes keyed by path. Works in the Node.js and Edge runtimes.
+export const VERSION = '0.2.0';
+export function config() {
+    const [channel, secret] = (process.env.SEARVIA_SITE_KEY ?? '').split('.', 2);
+    if (!channel || !secret || !/^[a-z0-9]{24}$/.test(channel)) {
+        return null;
+    }
+    return {
+        channel,
+        secret,
+        base: (process.env.SEARVIA_URL ?? 'https://searvia.com').replace(/\/$/, ''),
+        site: process.env.SEARVIA_SITE_URL ?? process.env.NEXT_PUBLIC_SITE_URL ?? '',
+        webhook: process.env.SEARVIA_WEBHOOK_URL ?? '',
+    };
+}
+export async function sign(body, secret) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const digest = new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(body)));
+    return 'sha256=' + Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Constant-time comparison of two signatures. */
+export function same(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** The fix list, cached by Next.js for five minutes (tag "searvia"). Returns null when the key is missing or the signature does not match. */
+export async function getSearviaFeed() {
+    const settings = config();
+    if (!settings)
+        return null;
+    try {
+        const response = await fetch(`${settings.base}/fixes/${settings.channel}/feed`, {
+            headers: { 'User-Agent': `SearviaNext/${VERSION}`, 'X-Searvia-Site': settings.site, 'X-Searvia-Version': VERSION, 'X-Searvia-Webhook': settings.webhook },
+            next: { revalidate: 300, tags: ['searvia'] },
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.text();
+        return same(await sign(body, settings.secret), response.headers.get('x-searvia-signature') ?? '') ? JSON.parse(body) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Fixes for one address: path with query first, then the path alone. */
+export async function getSearviaFixes(pathname, search = '') {
+    const feed = await getSearviaFeed();
+    const query = search && !search.startsWith('?') ? `?${search}` : search;
+    return feed?.fixes[pathname + query] ?? feed?.fixes[pathname] ?? [];
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { Metadata } from 'next';
+export { getSearviaFeed, getSearviaFixes, type Fix, type Feed } from './feed';
+/** Current address set by the Searvia middleware ("/" when the middleware is not installed). */
+export declare function currentPath(): Promise<{
+    pathname: string;
+    search: string;
+}>;
+/**
+ * Merges approved fixes into your page metadata: title, description, canonical, robots and hreflang alternates.
+ * Use it in `generateMetadata` of the root layout (or a page): `return searviaMetadata({ title: 'My site' })`.
+ */
+export declare function searviaMetadata(base?: Metadata, path?: {
+    pathname: string;
+    search?: string;
+}): Promise<Metadata>;
+/** Structured data fixes as JSON-LD script tags. Put it once in the root layout's <body>. */
+export declare function SearviaHead({ pathname, search }?: {
+    pathname?: string;
+    search?: string;
+}): Promise<import("react").JSX.Element>;
+/**
+ * Route handler for Searvia's change notice: when you approve or roll back a fix, Searvia calls it and the fix list is
+ * refreshed at once. In app/api/searvia/route.ts: `export { searviaWebhook as POST } from 'searvia-next'`, and set
+ * SEARVIA_WEBHOOK_URL to that address on your own domain.
+ */
+export declare function searviaWebhook(request: Request): Promise<Response>;

package/dist/index.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { revalidateTag } from 'next/cache';
+import { headers } from 'next/headers';
+import { config, getSearviaFixes, same, sign } from './feed';
+import { PATH_HEADER } from './middleware';
+export { getSearviaFeed, getSearviaFixes } from './feed';
+/** Current address set by the Searvia middleware ("/" when the middleware is not installed). */
+export async function currentPath() {
+    const value = (await headers()).get(PATH_HEADER) ?? '/';
+    const [pathname, search = ''] = value.split('?', 2);
+    return { pathname, search: search ? `?${search}` : '' };
+}
+function first(fixes, type) {
+    return fixes.find((fix) => fix.t === type)?.v;
+}
+/**
+ * Merges approved fixes into your page metadata: title, description, canonical, robots and hreflang alternates.
+ * Use it in `generateMetadata` of the root layout (or a page): `return searviaMetadata({ title: 'My site' })`.
+ */
+export async function searviaMetadata(base = {}, path) {
+    const { pathname, search } = path ?? (await currentPath());
+    const fixes = await getSearviaFixes(pathname, search ?? '');
+    const title = first(fixes, 'title');
+    const description = first(fixes, 'meta_description');
+    const canonical = first(fixes, 'canonical');
+    const robots = first(fixes, 'robots');
+    const hreflang = first(fixes, 'hreflang');
+    return {
+        ...base,
+        ...(title ? { title: { absolute: title.text } } : {}),
+        ...(description ? { description: description.text } : {}),
+        ...(robots ? { robots: robots.content } : {}),
+        alternates: {
+            ...(base.alternates ?? {}),
+            ...(canonical ? { canonical: canonical.href } : {}),
+            ...(hreflang ? { languages: Object.fromEntries(hreflang.links.map((link) => [link.hreflang, link.href])) } : {}),
+        },
+    };
+}
+/** Structured data fixes as JSON-LD script tags. Put it once in the root layout's <body>. */
+export async function SearviaHead({ pathname, search } = {}) {
+    const path = pathname ? { pathname, search: search ?? '' } : await currentPath();
+    const fixes = (await getSearviaFixes(path.pathname, path.search)).filter((fix) => fix.t === 'json_ld');
+    return (_jsx(_Fragment, { children: fixes.map((fix, index) => (_jsx("script", { type: "application/ld+json", "data-searvia": "fix", dangerouslySetInnerHTML: { __html: JSON.stringify(fix.v.data).replace(/</g, '\\u003c') } }, index))) }));
+}
+/**
+ * Route handler for Searvia's change notice: when you approve or roll back a fix, Searvia calls it and the fix list is
+ * refreshed at once. In app/api/searvia/route.ts: `export { searviaWebhook as POST } from 'searvia-next'`, and set
+ * SEARVIA_WEBHOOK_URL to that address on your own domain.
+ */
+export async function searviaWebhook(request) {
+    const settings = config();
+    const body = await request.text();
+    if (!settings || !same(await sign(body, settings.secret), request.headers.get('x-searvia-signature') ?? '')) {
+        return new Response(null, { status: 401 });
+    }
+    revalidateTag('searvia');
+    return Response.json({ ok: true });
+}

package/dist/middleware.d.ts

@@ -0,0 +1,14 @@
+import { NextResponse, type NextRequest } from 'next/server';
+/** Request header that carries the current address to Server Components (App Router layouts do not know the path). */
+export declare const PATH_HEADER = "x-searvia-path";
+/**
+ * A redirect approved in Searvia (a broken or merged page) for this request, or null. Call it from your own middleware:
+ * `const redirect = await searviaRedirect(request); if (redirect) return redirect;`
+ */
+export declare function searviaRedirect(request: NextRequest): Promise<NextResponse | null>;
+/**
+ * Middleware that passes the path to `searviaMetadata()` and `<SearviaHead />`. Use it as your middleware, or call it from
+ * your own: `return withSearviaPath(request, NextResponse.next(...))`.
+ */
+export declare function withSearviaPath(request: NextRequest, response?: NextResponse): NextResponse;
+export declare function middleware(request: NextRequest): Promise<NextResponse>;

package/dist/middleware.js

@@ -0,0 +1,53 @@
+import { NextResponse } from 'next/server';
+import { config, same, sign, VERSION } from './feed.js';
+/** Request header that carries the current address to Server Components (App Router layouts do not know the path). */
+export const PATH_HEADER = 'x-searvia-path';
+const TTL = 300_000;
+let cached = null;
+/** The fix list for redirects, kept in memory for five minutes (middleware fetches are not cached by Next.js). */
+async function feed() {
+    const settings = config();
+    if (!settings)
+        return null;
+    if (cached && Date.now() - cached.at < TTL)
+        return cached.feed;
+    try {
+        const response = await fetch(`${settings.base}/fixes/${settings.channel}/feed`, { headers: { 'User-Agent': `SearviaNext/${VERSION} (middleware)` } });
+        const body = response.ok ? await response.text() : '';
+        const valid = body !== '' && same(await sign(body, settings.secret), response.headers.get('x-searvia-signature') ?? '');
+        cached = { feed: valid ? JSON.parse(body) : (cached?.feed ?? null), at: Date.now() };
+    }
+    catch {
+        cached = { feed: cached?.feed ?? null, at: Date.now() };
+    }
+    return cached.feed;
+}
+/**
+ * A redirect approved in Searvia (a broken or merged page) for this request, or null. Call it from your own middleware:
+ * `const redirect = await searviaRedirect(request); if (redirect) return redirect;`
+ */
+export async function searviaRedirect(request) {
+    if (request.method !== 'GET')
+        return null;
+    const { pathname, search } = request.nextUrl;
+    const list = (await feed())?.fixes;
+    const fix = (list?.[pathname + search] ?? list?.[pathname] ?? []).find((item) => item.t === 'redirect');
+    if (!fix || typeof fix.v.href !== 'string')
+        return null;
+    const target = new URL(fix.v.href, request.url);
+    return target.href === request.nextUrl.href ? null : NextResponse.redirect(target, [301, 302, 308].includes(fix.v.status) ? fix.v.status : 301);
+}
+/**
+ * Middleware that passes the path to `searviaMetadata()` and `<SearviaHead />`. Use it as your middleware, or call it from
+ * your own: `return withSearviaPath(request, NextResponse.next(...))`.
+ */
+export function withSearviaPath(request, response) {
+    const headers = new Headers(request.headers);
+    headers.set(PATH_HEADER, request.nextUrl.pathname + request.nextUrl.search);
+    const next = NextResponse.next({ request: { headers } });
+    response?.headers.forEach((value, key) => next.headers.set(key, value));
+    return next;
+}
+export async function middleware(request) {
+    return (await searviaRedirect(request)) ?? withSearviaPath(request);
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "searvia-next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Apply the SEO fixes you approve in Searvia (titles, descriptions, canonical, robots, hreflang, structured data, alt text, internal links) to a Next.js App Router site.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "seo",
+    "nextjs",
+    "searvia",
+    "metadata",
+    "json-ld",
+    "hreflang"
+  ],
+  "homepage": "https://searvia.com/help/site-fixes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/searvia/searvia-next.git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "next": ">=14.2",
+    "react": ">=18.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}