@searkin/next 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Searkin
+
+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,99 @@
-# Temporary Holding Version
+# @searkin/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.
+Ce paquet relie un site **Next.js sans CMS** à [Searkin](https://app.searkin.com). Searkin conserve les titres, descriptions, canonicals, consignes d'indexation et redirections de chaque page, et le site les lit au moment du rendu. Quand une valeur change dans Searkin, Searkin envoie au site une demande de rafraîchissement signée, si bien qu'aucun redéploiement n'est nécessaire.
+
+Compatible avec Next.js 13.4 à 16, en App Router comme en Pages Router.
+
+## Installation
+
+```bash
+npm install @searkin/next
+npx @searkin/next init --key sks_…
+```
+
+`init` commence par détecter si le projet utilise l'App Router ou le Pages Router, et s'il a un dossier `src/`. Il effectue ensuite les opérations suivantes :
+
+- il écrit `SEARKIN_KEY` dans `.env.local`, ainsi que `SEARKIN_SITE_URL` s'il peut la déduire de `NEXT_PUBLIC_SERVER_URL` / `NEXT_PUBLIC_SITE_URL` (ou de l'option `--site-url`) ;
+- il crée la route `app/api/searkin/[...searkin]/route.ts`, ou `pages/api/searkin/[...searkin].ts` en Pages Router ;
+- il crée `middleware.ts` (`proxy.ts` à partir de Next 16). Si ce fichier existe déjà, il n'y touche pas et affiche les deux lignes à ajouter ;
+- il affiche un exemple de `generateMetadata`, sans modifier vos pages.
+
+Vous pouvez relancer `init` sans risque. Tout fichier modifié est d'abord sauvegardé en `*.searkin-<date>.bak`. Pensez aussi à déclarer `SEARKIN_KEY` dans les variables d'environnement de votre hébergeur.
+
+## Variables d'environnement
+
+| Variable | Rôle |
+|---|---|
+| `SEARKIN_KEY` | Clé de site `sks_…` générée par Searkin. Elle sert seulement à lire les valeurs de ce site et à vérifier les rafraîchissements |
+| `SEARKIN_SITE_URL` | URL publique, pour rendre les canonicals absolus (à défaut : `NEXT_PUBLIC_SERVER_URL`, puis `NEXT_PUBLIC_SITE_URL`) |
+| `SEARKIN_API` | Facultatif (par défaut : `https://app.searkin.com/api/proxy`) |
+| `SEARKIN_OUTPUT` | `export` si le site est exporté de manière statique (valeur renvoyée par le ping) |
+
+## App Router
+
+```ts
+// app/[slug]/page.tsx
+import type { Metadata } from 'next'
+import { searkinMetadata } from '@searkin/next'
+
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const { slug } = await params
+  return searkinMetadata(`/${slug}`, { title: 'Titre par défaut', description: '…' })
+}
+```
+
+`searkinMetadata(path, base?)` lit `GET /site-api/v1/seo?path=…`. La lecture est mise en cache 300 s avec le tag `searkin`. Chaque valeur que Searkin renvoie remplace celle de `base` :
+
+- `title` et `description` ;
+- `alternates.canonical`, rendu absolu ;
+- `robots` : `noindex` donne `{index:false, follow:true}`, `index` donne `{index:true, follow:true}`.
+
+Si la clé est absente ou si Searkin est injoignable, `base` est renvoyé tel quel et un message est journalisé une seule fois.
+
+`getSearkinSeo(path)` renvoie les valeurs brutes. On peut l'appeler partout, y compris dans `getServerSideProps` et `getStaticProps`.
+
+## Pages Router
+
+```tsx
+import { SearkinHead, getSearkinSeo } from '@searkin/next/pages'
+
+export async function getServerSideProps({ resolvedUrl }) {
+  return { props: { seo: await getSearkinSeo(resolvedUrl), path: resolvedUrl } }
+}
+
+export default function Page({ seo, path }) {
+  return (<><SearkinHead seo={seo} path={path} />…</>)
+}
+```
+
+La clé ne doit jamais atteindre le navigateur. `SearkinHead` reçoit donc les valeurs déjà lues côté serveur, au lieu de les lire lui-même. Si Searkin ne définit pas de canonical, c'est `path` qui sert de canonical.
+
+## Redirections
+
+- **Sans redéploiement**, avec le middleware créé par `init` : `searkinMiddleware(req)` renvoie une redirection quand une règle correspond, sinon `undefined`. Les règles viennent de `/site-api/v1/redirects` et restent 60 s en mémoire. Le middleware fonctionne en Edge (Web Crypto, aucun module Node).
+- **Au build**, avec `searkinRedirects()` :
+
+```js
+// next.config.mjs
+import { searkinRedirects } from '@searkin/next'
+export default { async redirects() { return searkinRedirects() } }
+```
+
+Next ne connaît que `permanent` : avec `searkinRedirects()`, les codes 301/308 deviennent 308 et les codes 302/307 deviennent 307. Le middleware, lui, conserve le code exact.
+
+## Rafraîchissement par Searkin
+
+Les deux routes ci-dessous sont installées par `init`. Searkin les appelle avec l'en-tête `X-Searkin-Signature: t=<unix>,v1=<hex HMAC-SHA256(SEARKIN_KEY, t + "." + corps)>`.
+
+- `GET /api/searkin/ping`. Sans signature, la réponse est `{ok, version}`. Avec une signature valide, elle devient `{ok, version, framework:'next', router, output}`.
+- `POST /api/searkin/revalidate` `{tags:['searkin'], paths:[…]}`. Le site appelle alors `revalidateTag` et `revalidatePath` (en Pages Router, `res.revalidate`) et répond `{ok, revalidated}`.
+
+Les signatures invalides, de plus de 5 minutes ou déjà utilisées sont refusées avec une erreur 401. Seuls les tags `searkin` et `searkin:*` sont acceptés.
+
+## Export statique (`output: 'export'`)
+
+Les valeurs sont figées au moment du build, et il n'y a ni route `/api` ni middleware. Pour que les nouvelles valeurs soient prises en compte, Searkin déclenche le *deploy hook* configuré dans ses Réglages (Vercel, Netlify, Cloudflare…). Les redirections, elles, sont à gérer chez l'hébergeur.
+
+## Licence
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * npx @searkin/next init --key sks_… [--dir <projet>] [--site-url https://…] [--dry-run]
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { VERSION } from './shared.js';
+function parseArgs(argv) {
+    const a = { dir: process.cwd(), dryRun: false };
+    for (let i = 0; i < argv.length; i++) {
+        const v = argv[i];
+        if (v === '--key')
+            a.key = argv[++i];
+        else if (v.startsWith('--key='))
+            a.key = v.slice(6);
+        else if (v === '--site-url')
+            a.siteUrl = argv[++i];
+        else if (v === '--dir')
+            a.dir = resolve(argv[++i] || '.');
+        else if (v === '--dry-run')
+            a.dryRun = true;
+        else if (v === '--version' || v === '-v')
+            a.cmd = 'version';
+        else if (!v.startsWith('-') && !a.cmd)
+            a.cmd = v;
+    }
+    return a;
+}
+const log = (s = '') => {
+    process.stdout.write(s + '\n');
+};
+function backup(file) {
+    const dest = `${file}.searkin-${new Date().toISOString().replace(/[:.]/g, '-')}.bak`;
+    copyFileSync(file, dest);
+    return dest;
+}
+function write(root, file, content, dryRun) {
+    if (dryRun) {
+        log(`  (simulation) ${relative(root, file)}`);
+        return;
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    if (existsSync(file))
+        log(`  sauvegarde : ${relative(root, backup(file))}`);
+    writeFileSync(file, content);
+}
+/** Met à jour (ou ajoute) des variables dans un fichier .env, sans toucher aux autres lignes. */
+function upsertEnv(root, file, vars, dryRun) {
+    const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    let next = current;
+    const changed = [];
+    for (const [k, v] of Object.entries(vars)) {
+        const line = `${k}=${v}`;
+        const re = new RegExp(`^${k}=.*$`, 'm');
+        if (next.split(/\r?\n/).includes(line))
+            continue;
+        if (re.test(next))
+            next = next.replace(re, line);
+        else
+            next = next + (next && !next.endsWith('\n') ? '\n' : '') + line + '\n';
+        changed.push(k);
+    }
+    if (changed.length)
+        write(root, file, next, dryRun);
+    return changed;
+}
+function readEnvValue(root, names) {
+    for (const f of ['.env.local', '.env.production', '.env']) {
+        const p = join(root, f);
+        if (!existsSync(p))
+            continue;
+        for (const name of names) {
+            const m = new RegExp(`^${name}=["']?([^"'\\n]+)`, 'm').exec(readFileSync(p, 'utf8'));
+            if (m && /^https?:\/\//.test(m[1]))
+                return m[1].trim().replace(/\/+$/, '');
+        }
+    }
+    return undefined;
+}
+function nextMajor(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+        const v = pkg.dependencies?.next || pkg.devDependencies?.next || '';
+        const m = /(\d+)/.exec(v);
+        if (m)
+            return Number(m[1]);
+    }
+    catch {
+        /* inconnu */
+    }
+    try {
+        return Number(JSON.parse(readFileSync(join(root, 'node_modules/next/package.json'), 'utf8')).version.split('.')[0]);
+    }
+    catch {
+        return 15;
+    }
+}
+function outputExport(root) {
+    for (const f of ['next.config.ts', 'next.config.mjs', 'next.config.js', 'next.config.cjs']) {
+        const p = join(root, f);
+        if (existsSync(p) && /output\s*:\s*['"]export['"]/.test(readFileSync(p, 'utf8')))
+            return true;
+    }
+    return false;
+}
+const MIDDLEWARE = (fn) => `import type { NextRequest } from 'next/server.js'
+import { searkinMiddleware } from '@searkin/next/middleware'
+
+// Redirections Searkin actives sans redéploiement (règles gardées 60 s en mémoire).
+export async function ${fn}(req: NextRequest) {
+  return searkinMiddleware(req)
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)'],
+}
+`;
+const METADATA_EXAMPLE = `// app/[slug]/page.tsx
+import type { Metadata } from 'next'
+import { searkinMetadata } from '@searkin/next'
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
+  const { slug } = await params
+  return searkinMetadata(\`/\${slug}\`, { title: 'Titre par défaut', description: 'Description par défaut' })
+}`;
+const PAGES_EXAMPLE = `// pages/[slug].tsx
+import { SearkinHead, getSearkinSeo } from '@searkin/next/pages'
+
+export async function getServerSideProps({ resolvedUrl }) {
+  return { props: { seo: await getSearkinSeo(resolvedUrl) } }
+}
+
+export default function Page({ seo }) {
+  return <><SearkinHead seo={seo} />…</>
+}`;
+function init(args) {
+    const root = args.dir;
+    log(`@searkin/next ${VERSION} — init${args.dryRun ? ' (simulation)' : ''}`);
+    if (!existsSync(join(root, 'package.json'))) {
+        log('package.json introuvable : lancez la commande à la racine du projet Next (ou --dir).');
+        return 1;
+    }
+    const base = existsSync(join(root, 'src', 'app')) || existsSync(join(root, 'src', 'pages')) ? join(root, 'src') : root;
+    const hasApp = existsSync(join(base, 'app'));
+    const hasPages = existsSync(join(base, 'pages'));
+    const ts = existsSync(join(root, 'tsconfig.json'));
+    const ext = ts ? 'ts' : 'js';
+    const isExport = outputExport(root);
+    const major = nextMajor(root);
+    log(`Projet : ${hasApp ? 'App Router' : ''}${hasApp && hasPages ? ' + ' : ''}${hasPages ? 'Pages Router' : ''}${!hasApp && !hasPages ? 'aucun dossier app/ ni pages/' : ''}${base !== root ? ' (src/)' : ''}, Next ${major}${isExport ? ', output: export' : ''}`);
+    if (!hasApp && !hasPages)
+        return 1;
+    // 1. Variables d'environnement.
+    if (args.key) {
+        if (!/^sks_[A-Za-z0-9_-]{16,}$/.test(args.key))
+            log('Attention : la clé ne ressemble pas à une clé de site Searkin (sks_…).');
+        const vars = { SEARKIN_KEY: args.key };
+        const siteUrl = args.siteUrl || readEnvValue(root, ['SEARKIN_SITE_URL', 'NEXT_PUBLIC_SERVER_URL', 'NEXT_PUBLIC_SITE_URL', 'SITE_URL']);
+        if (siteUrl)
+            vars.SEARKIN_SITE_URL = siteUrl;
+        const changed = upsertEnv(root, join(root, '.env.local'), vars, args.dryRun);
+        log(changed.length ? `.env.local : ${changed.join(', ')} écrit(s).` : '.env.local : déjà à jour.');
+        if (!siteUrl)
+            log('  SEARKIN_SITE_URL non déduit : ajoutez l’URL publique du site (canonicals absolus).');
+    }
+    // 2. Route /api/searkin/*.
+    if (isExport) {
+        log('output: export : pas de route /api (les valeurs sont figées au build ; Searkin déclenchera votre deploy hook).');
+    }
+    else if (hasApp) {
+        const file = join(base, 'app', 'api', 'searkin', '[...searkin]', `route.${ext}`);
+        const content = "export { GET, POST } from '@searkin/next/route'\n";
+        if (existsSync(file) && readFileSync(file, 'utf8').includes('@searkin/next/route'))
+            log(`Route déjà présente : ${relative(root, file)}`);
+        else {
+            write(root, file, content, args.dryRun);
+            log(`Route créée : ${relative(root, file)}`);
+        }
+    }
+    else {
+        const file = join(base, 'pages', 'api', 'searkin', `[...searkin].${ext}`);
+        const content = "export { default, config } from '@searkin/next/pages'\n";
+        if (existsSync(file) && readFileSync(file, 'utf8').includes('@searkin/next/pages'))
+            log(`Route déjà présente : ${relative(root, file)}`);
+        else {
+            write(root, file, content, args.dryRun);
+            log(`Route créée : ${relative(root, file)}`);
+        }
+    }
+    // 3. Middleware (proxy à partir de Next 16).
+    if (!isExport) {
+        const name = major >= 16 ? 'proxy' : 'middleware';
+        const existing = [`${name}.ts`, `${name}.js`, 'middleware.ts', 'middleware.js'].map((f) => join(base, f)).find((f) => existsSync(f));
+        if (existing && readFileSync(existing, 'utf8').includes('searkinMiddleware')) {
+            log(`Middleware déjà branché : ${relative(root, existing)}`);
+        }
+        else if (existing) {
+            log(`${relative(root, existing)} existe déjà : ajoutez à la main, en tête de la fonction :`);
+            log("  import { searkinMiddleware } from '@searkin/next/middleware'");
+            log('  const redirect = await searkinMiddleware(req); if (redirect) return redirect');
+        }
+        else {
+            const file = join(base, `${name}.${ext}`);
+            write(root, file, MIDDLEWARE(name), args.dryRun);
+            log(`${name === 'proxy' ? 'Proxy' : 'Middleware'} créé : ${relative(root, file)}`);
+        }
+    }
+    // 4. Exemple d'intégration (jamais écrit dans vos pages).
+    log();
+    log('Exemple à intégrer :');
+    log(hasApp ? METADATA_EXAMPLE : PAGES_EXAMPLE);
+    if (isExport) {
+        log();
+        log("output: 'export' : ni middleware ni redirects() de next.config ne s'appliquent ; configurez les redirections chez l'hébergeur.");
+    }
+    log();
+    log('Ensuite : redéployez avec SEARKIN_KEY dans les variables d’environnement de l’hébergeur.');
+    return 0;
+}
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.cmd === 'version') {
+        log(VERSION);
+        return 0;
+    }
+    if (!args.cmd || args.cmd === 'init')
+        return init(args);
+    log('Usage : npx @searkin/next init --key sks_… [--site-url https://…] [--dir <projet>] [--dry-run]');
+    return 1;
+}
+process.exitCode = main();

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { Metadata } from 'next';
+import { type SearkinSeo } from './shared.js';
+export type { SearkinSeo, SearkinRobots, SearkinRedirectRule } from './shared.js';
+export { VERSION, CACHE_TAG } from './shared.js';
+/**
+ * Valeurs SEO brutes de Searkin pour un chemin ({} si rien n'est défini, null si l'API est
+ * indisponible ou la clé absente). Utilisable partout : generateMetadata, getServerSideProps, getStaticProps…
+ */
+export declare function getSearkinSeo(path: string): Promise<SearkinSeo | null>;
+/** Fusionne les valeurs Searkin dans un objet Metadata ; les valeurs Searkin présentes l'emportent. */
+export declare function applySearkinSeo(seo: SearkinSeo | null | undefined, base?: Metadata): Metadata;
+/**
+ * App Router, côté serveur : à appeler dans generateMetadata.
+ * En cas d'erreur réseau ou de clé absente, `base` est renvoyé intact.
+ */
+export declare function searkinMetadata(path: string, base?: Metadata): Promise<Metadata>;
+/** Redirections pour `async redirects()` de next.config (lues au build). */
+export declare function searkinRedirects(): Promise<{
+    source: string;
+    destination: string;
+    permanent: boolean;
+}[]>;

package/dist/index.js

@@ -0,0 +1,41 @@
+import { absoluteUrl, CACHE_TAG, config, fetchRedirectRules, isPermanent, normalizePath, robotsFor, searkinGet, } from './shared.js';
+export { VERSION, CACHE_TAG } from './shared.js';
+/**
+ * Valeurs SEO brutes de Searkin pour un chemin ({} si rien n'est défini, null si l'API est
+ * indisponible ou la clé absente). Utilisable partout : generateMetadata, getServerSideProps, getStaticProps…
+ */
+export async function getSearkinSeo(path) {
+    const p = normalizePath(path);
+    return searkinGet(`/site-api/v1/seo?path=${encodeURIComponent(p)}`, {
+        next: { revalidate: 300, tags: [CACHE_TAG] },
+    });
+}
+/** Fusionne les valeurs Searkin dans un objet Metadata ; les valeurs Searkin présentes l'emportent. */
+export function applySearkinSeo(seo, base = {}) {
+    if (!seo)
+        return base;
+    const out = { ...base };
+    if (seo.title)
+        out.title = seo.title;
+    if (seo.description)
+        out.description = seo.description;
+    if (seo.canonical) {
+        out.alternates = { ...(base.alternates || {}), canonical: absoluteUrl(seo.canonical, config().siteUrl) };
+    }
+    const robots = robotsFor(seo.robots);
+    if (robots)
+        out.robots = robots;
+    return out;
+}
+/**
+ * App Router, côté serveur : à appeler dans generateMetadata.
+ * En cas d'erreur réseau ou de clé absente, `base` est renvoyé intact.
+ */
+export async function searkinMetadata(path, base = {}) {
+    return applySearkinSeo(await getSearkinSeo(path), base);
+}
+/** Redirections pour `async redirects()` de next.config (lues au build). */
+export async function searkinRedirects() {
+    const rules = await fetchRedirectRules({ cache: 'no-store' });
+    return (rules || []).map((r) => ({ source: r.source, destination: r.destination, permanent: isPermanent(r.code) }));
+}

package/dist/middleware.d.ts

@@ -0,0 +1,8 @@
+import { NextResponse, type NextRequest } from 'next/server.js';
+/**
+ * Redirige si une règle Searkin correspond au chemin demandé, sinon renvoie undefined.
+ * Règles lues sur /site-api/v1/redirects, gardées 60 s en mémoire.
+ */
+export declare function searkinMiddleware(req: NextRequest): Promise<NextResponse | undefined>;
+/** Vide le cache des règles (tests). */
+export declare const resetSearkinRedirectCache: () => void;

package/dist/middleware.js

@@ -0,0 +1,52 @@
+// Edge compatible : aucun module Node.
+import { NextResponse } from 'next/server.js';
+import { fetchRedirectRules, normalizePath } from './shared.js';
+const TTL_MS = 60_000;
+let cache = null;
+let pending = null;
+async function load() {
+    if (cache && Date.now() - cache.at < TTL_MS)
+        return cache.rules;
+    if (!pending) {
+        pending = (async () => {
+            const rules = await fetchRedirectRules({ cache: 'no-store' });
+            if (rules) {
+                cache = { at: Date.now(), rules: new Map(rules.map((r) => [normalizePath(r.source), r])) };
+            }
+            else if (cache) {
+                cache = { ...cache, at: Date.now() }; // garde les dernières règles connues
+            }
+            else {
+                cache = { at: Date.now(), rules: new Map() };
+            }
+        })().finally(() => {
+            pending = null;
+        });
+    }
+    await pending;
+    return cache.rules;
+}
+const CODES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Redirige si une règle Searkin correspond au chemin demandé, sinon renvoie undefined.
+ * Règles lues sur /site-api/v1/redirects, gardées 60 s en mémoire.
+ */
+export async function searkinMiddleware(req) {
+    const path = normalizePath(req.nextUrl.pathname);
+    if (path.startsWith('/_next') || path.startsWith('/api/searkin'))
+        return undefined;
+    const rules = await load();
+    const rule = rules.get(path);
+    if (!rule)
+        return undefined;
+    const destination = new URL(rule.destination, req.nextUrl.origin);
+    if (!/^https?:\/\//i.test(rule.destination) && req.nextUrl.search && !destination.search)
+        destination.search = req.nextUrl.search;
+    if (destination.toString() === req.nextUrl.toString())
+        return undefined;
+    return NextResponse.redirect(destination, CODES.has(rule.code) ? rule.code : 301);
+}
+/** Vide le cache des règles (tests). */
+export const resetSearkinRedirectCache = () => {
+    cache = null;
+};

package/dist/pages.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ReactElement } from 'react';
+import { type SearkinSeo } from './shared.js';
+export { getSearkinSeo } from './index.js';
+export type SearkinHeadProps = {
+    /** Valeurs lues par getSearkinSeo() dans getServerSideProps / getStaticProps. */
+    seo: SearkinSeo | null | undefined;
+    /** Chemin de la page : sert de canonical quand Searkin n'en définit pas. */
+    path?: string;
+};
+/** Balises <title>, description, canonical et robots dans next/head. */
+export declare function SearkinHead({ seo, path }: SearkinHeadProps): ReactElement | null;
+type ApiReq = IncomingMessage & {
+    query?: Record<string, string | string[]>;
+    url?: string;
+};
+type ApiRes = ServerResponse & {
+    revalidate?: (path: string) => Promise<void>;
+};
+/** Le corps brut est nécessaire pour vérifier la signature. */
+export declare const config: {
+    api: {
+        bodyParser: boolean;
+    };
+};
+export default function searkinPagesHandler(req: ApiReq, res: ApiRes): Promise<void>;

package/dist/pages.js

@@ -0,0 +1,78 @@
+import HeadModule from 'next/head.js';
+import { createElement, Fragment } from 'react';
+import { absoluteUrl, config as env, outputMode, parseRevalidateBody, verifySignature, VERSION } from './shared.js';
+export { getSearkinSeo } from './index.js';
+// next/head est un module CommonJS : selon le chargeur, le composant est l'export par défaut ou son .default.
+const Head = (HeadModule.default ?? HeadModule);
+/** Balises <title>, description, canonical et robots dans next/head. */
+export function SearkinHead({ seo, path }) {
+    if (!seo)
+        return null;
+    const siteUrl = env().siteUrl;
+    const children = [];
+    if (seo.title)
+        children.push(createElement('title', { key: 'searkin-title' }, seo.title));
+    if (seo.description)
+        children.push(createElement('meta', { key: 'searkin-description', name: 'description', content: seo.description }));
+    const canonical = seo.canonical || (path ? path : null);
+    if (canonical)
+        children.push(createElement('link', { key: 'searkin-canonical', rel: 'canonical', href: absoluteUrl(canonical, siteUrl) }));
+    if (seo.robots === 'noindex')
+        children.push(createElement('meta', { key: 'searkin-robots', name: 'robots', content: 'noindex, follow' }));
+    else if (seo.robots === 'index')
+        children.push(createElement('meta', { key: 'searkin-robots', name: 'robots', content: 'index, follow' }));
+    if (!children.length)
+        return null;
+    return createElement(Head, null, createElement(Fragment, null, ...children));
+}
+const send = (res, status, data) => {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(JSON.stringify(data));
+};
+const readRaw = async (req) => {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(typeof c === 'string' ? Buffer.from(c) : c);
+    return Buffer.concat(chunks).toString('utf8');
+};
+/** Le corps brut est nécessaire pour vérifier la signature. */
+export const config = { api: { bodyParser: false } };
+export default async function searkinPagesHandler(req, res) {
+    const action = /\/api\/searkin\/([^/?#]+)/.exec(req.url || '')?.[1] || '';
+    try {
+        if (req.method === 'GET' && action === 'ping') {
+            const header = req.headers['x-searkin-signature'];
+            if (!header)
+                return send(res, 200, { ok: true, version: VERSION });
+            const check = await verifySignature(header, '');
+            if (!check.ok)
+                return send(res, 401, { ok: false, message: check.reason });
+            return send(res, 200, { ok: true, version: VERSION, framework: 'next', router: 'pages', output: outputMode() });
+        }
+        if (req.method === 'POST' && action === 'revalidate') {
+            const raw = await readRaw(req);
+            const check = await verifySignature(req.headers['x-searkin-signature'], raw);
+            if (!check.ok)
+                return send(res, 401, { ok: false, message: check.reason });
+            const { tags, paths } = parseRevalidateBody(raw);
+            const done = [];
+            const failed = {};
+            for (const path of paths) {
+                try {
+                    await res.revalidate?.(path);
+                    done.push(path);
+                }
+                catch (err) {
+                    failed[path] = err.message;
+                }
+            }
+            return send(res, 200, { ok: true, revalidated: { tags, paths: done }, ...(Object.keys(failed).length ? { failed } : {}) });
+        }
+        return send(res, 404, { ok: false, message: 'Route inconnue.' });
+    }
+    catch (err) {
+        return send(res, 500, { ok: false, message: err.message });
+    }
+}

package/dist/route.d.ts

@@ -0,0 +1,3 @@
+export declare const dynamic = "force-dynamic";
+export declare function GET(req: Request): Promise<Response>;
+export declare function POST(req: Request): Promise<Response>;

package/dist/route.js

@@ -0,0 +1,35 @@
+// Gestionnaire App Router : `export { GET, POST } from '@searkin/next/route'`
+// dans app/api/searkin/[...searkin]/route.ts
+import { revalidatePath, revalidateTag } from 'next/cache.js';
+import { outputMode, parseRevalidateBody, verifySignature, VERSION } from './shared.js';
+const json = (data, status = 200) => new Response(JSON.stringify(data), { status, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } });
+const action = (req) => {
+    const m = /\/api\/searkin\/([^/?#]+)/.exec(new URL(req.url).pathname);
+    return m ? m[1] : '';
+};
+export const dynamic = 'force-dynamic';
+export async function GET(req) {
+    if (action(req) !== 'ping')
+        return json({ ok: false, message: 'Route inconnue.' }, 404);
+    const header = req.headers.get('x-searkin-signature');
+    if (!header)
+        return json({ ok: true, version: VERSION });
+    const check = await verifySignature(header, '');
+    if (!check.ok)
+        return json({ ok: false, message: check.reason }, 401);
+    return json({ ok: true, version: VERSION, framework: 'next', router: 'app', output: outputMode() });
+}
+export async function POST(req) {
+    if (action(req) !== 'revalidate')
+        return json({ ok: false, message: 'Route inconnue.' }, 404);
+    const raw = await req.text();
+    const check = await verifySignature(req.headers.get('x-searkin-signature'), raw);
+    if (!check.ok)
+        return json({ ok: false, message: check.reason }, 401);
+    const { tags, paths } = parseRevalidateBody(raw);
+    for (const tag of tags)
+        revalidateTag(tag);
+    for (const path of paths)
+        revalidatePath(path);
+    return json({ ok: true, revalidated: { tags, paths } });
+}

package/dist/shared.d.ts

@@ -0,0 +1,60 @@
+export declare const VERSION = "0.1.0";
+export declare const CACHE_TAG = "searkin";
+export type SearkinRobots = 'default' | 'index' | 'noindex' | null;
+export type SearkinSeo = {
+    path?: string;
+    title?: string | null;
+    description?: string | null;
+    canonical?: string | null;
+    robots?: SearkinRobots;
+    updated_at?: string | null;
+};
+export type SearkinRedirectRule = {
+    source: string;
+    destination: string;
+    code: number;
+};
+export declare const config: () => {
+    key: string | undefined;
+    api: string;
+    siteUrl: string | undefined;
+};
+export declare function logOnce(message: string): void;
+/** Chemin normalisé : commence par /, sans requête ni ancre, sans / final (sauf racine). */
+export declare function normalizePath(path: string): string;
+type FetchInit = RequestInit & {
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+};
+/** GET authentifié vers l'API site de Searkin. Renvoie null (et journalise une fois) en cas d'échec. */
+export declare function searkinGet<T>(path: string, init?: FetchInit, missingKey?: string): Promise<T | null>;
+export declare const absoluteUrl: (value: string, siteUrl?: string) => string;
+export declare const robotsFor: (robots: SearkinRobots | undefined) => {
+    index: boolean;
+    follow: boolean;
+} | undefined;
+export declare function fetchRedirectRules(init?: FetchInit): Promise<SearkinRedirectRule[] | null>;
+export declare const isPermanent: (code: number | undefined) => code is 301 | 308 | undefined;
+export declare const SIGNATURE_WINDOW_S = 300;
+export declare function hmacHex(key: string, message: string): Promise<string>;
+export type SignatureCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Vérifie `X-Searkin-Signature: t=<unix>,v1=<hex HMAC-SHA256(SEARKIN_KEY, t + "." + corps brut)>`.
+ * Fenêtre de 5 minutes, rejeux refusés (mémoire du processus).
+ */
+export declare function verifySignature(header: string | null | undefined, rawBody: string, now?: number): Promise<SignatureCheck>;
+export type RevalidatePayload = {
+    tags: string[];
+    paths: string[];
+};
+/** Valide le corps de /revalidate : tags préfixés « searkin », chemins commençant par /. */
+export declare function parseRevalidateBody(raw: string): RevalidatePayload;
+export declare const outputMode: () => "server" | "export";
+export {};

package/dist/shared.js

@@ -0,0 +1,163 @@
+// Code commun, sans dépendance Node : utilisable côté serveur, en Edge (middleware) et au build.
+export const VERSION = '0.1.0';
+export const CACHE_TAG = 'searkin';
+const DEFAULT_API = 'https://app.searkin.com/api/proxy';
+const env = (name) => {
+    try {
+        const v = process.env[name];
+        return v && v.trim() ? v.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const config = () => ({
+    key: env('SEARKIN_KEY'),
+    api: (env('SEARKIN_API') || DEFAULT_API).replace(/\/+$/, ''),
+    siteUrl: (env('SEARKIN_SITE_URL') || env('NEXT_PUBLIC_SERVER_URL') || env('NEXT_PUBLIC_SITE_URL') || '').replace(/\/+$/, '') || undefined,
+});
+const logged = new Set();
+export function logOnce(message) {
+    if (logged.has(message))
+        return;
+    logged.add(message);
+    console.warn(`[searkin] ${message}`);
+}
+/** Chemin normalisé : commence par /, sans requête ni ancre, sans / final (sauf racine). */
+export function normalizePath(path) {
+    let p = (path || '/').split('#')[0].split('?')[0];
+    if (/^https?:\/\//i.test(p)) {
+        try {
+            p = new URL(p).pathname;
+        }
+        catch {
+            /* garde tel quel */
+        }
+    }
+    if (!p.startsWith('/'))
+        p = '/' + p;
+    p = p.replace(/\/{2,}/g, '/');
+    if (p.length > 1)
+        p = p.replace(/\/+$/, '');
+    return p;
+}
+/** GET authentifié vers l'API site de Searkin. Renvoie null (et journalise une fois) en cas d'échec. */
+export async function searkinGet(path, init = {}, missingKey = 'SEARKIN_KEY absent : les valeurs Searkin ne sont pas appliquées.') {
+    const { key, api } = config();
+    if (!key) {
+        logOnce(missingKey);
+        return null;
+    }
+    try {
+        const res = await fetch(api + path, {
+            ...init,
+            headers: { Accept: 'application/json', Authorization: `Bearer ${key}`, ...(init.headers || {}) },
+        });
+        if (!res.ok) {
+            logOnce(`API Searkin : HTTP ${res.status} sur ${path.split('?')[0]}${res.status === 401 ? ' (clé refusée)' : ''}.`);
+            return null;
+        }
+        return (await res.json());
+    }
+    catch (err) {
+        logOnce(`API Searkin injoignable (${err.message}).`);
+        return null;
+    }
+}
+export const absoluteUrl = (value, siteUrl) => {
+    if (/^https?:\/\//i.test(value))
+        return value;
+    if (!siteUrl)
+        return value;
+    try {
+        return new URL(value, siteUrl + '/').toString();
+    }
+    catch {
+        return value;
+    }
+};
+export const robotsFor = (robots) => robots === 'noindex' ? { index: false, follow: true } : robots === 'index' ? { index: true, follow: true } : undefined;
+export async function fetchRedirectRules(init = {}) {
+    const data = await searkinGet('/site-api/v1/redirects', init, 'SEARKIN_KEY absent : les redirections Searkin sont inactives.');
+    if (!data)
+        return null;
+    return (data.items || []).filter((r) => r && typeof r.source === 'string' && typeof r.destination === 'string');
+}
+export const isPermanent = (code) => code === 301 || code === 308 || code === undefined;
+// ---------- Signature HMAC (Web Crypto, Edge et Node) ----------
+const enc = new TextEncoder();
+const seen = new Map();
+export const SIGNATURE_WINDOW_S = 300;
+async function subtle() {
+    const c = globalThis.crypto;
+    if (c?.subtle)
+        return c.subtle;
+    // Node 18 sans globalThis.crypto : on passe par webcrypto, chargé dynamiquement (jamais en Edge).
+    const mod = 'node:crypto';
+    const nodeCrypto = (await import(/* webpackIgnore: true */ mod));
+    return nodeCrypto.webcrypto.subtle;
+}
+const toHex = (buf) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, '0')).join('');
+export async function hmacHex(key, message) {
+    const s = await subtle();
+    const k = await s.importKey('raw', enc.encode(key), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return toHex(await s.sign('HMAC', k, enc.encode(message)));
+}
+const safeEqual = (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;
+};
+/**
+ * Vérifie `X-Searkin-Signature: t=<unix>,v1=<hex HMAC-SHA256(SEARKIN_KEY, t + "." + corps brut)>`.
+ * Fenêtre de 5 minutes, rejeux refusés (mémoire du processus).
+ */
+export async function verifySignature(header, rawBody, now = Date.now()) {
+    const { key } = config();
+    if (!key)
+        return { ok: false, reason: 'SEARKIN_KEY absent sur le site' };
+    if (!header)
+        return { ok: false, reason: 'signature absente' };
+    const parts = Object.fromEntries(header.split(',').map((p) => {
+        const i = p.indexOf('=');
+        return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
+    }));
+    const t = Number(parts.t);
+    const v1 = (parts.v1 || '').toLowerCase();
+    if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(v1))
+        return { ok: false, reason: 'signature mal formée' };
+    if (Math.abs(now / 1000 - t) > SIGNATURE_WINDOW_S)
+        return { ok: false, reason: 'signature expirée' };
+    const expected = await hmacHex(key, `${t}.${rawBody}`);
+    if (!safeEqual(expected, v1))
+        return { ok: false, reason: 'signature invalide' };
+    for (const [sig, exp] of seen)
+        if (exp < now)
+            seen.delete(sig);
+    if (seen.has(v1))
+        return { ok: false, reason: 'signature déjà utilisée (rejeu)' };
+    seen.set(v1, now + SIGNATURE_WINDOW_S * 1000 * 2);
+    return { ok: true };
+}
+/** Valide le corps de /revalidate : tags préfixés « searkin », chemins commençant par /. */
+export function parseRevalidateBody(raw) {
+    let body = {};
+    if (raw.trim()) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            body = {};
+        }
+    }
+    const tags = (Array.isArray(body.tags) ? body.tags : [CACHE_TAG]).filter((t) => typeof t === 'string' && (t === CACHE_TAG || t.startsWith(CACHE_TAG + ':')));
+    const paths = (Array.isArray(body.paths) ? body.paths : [])
+        .filter((p) => typeof p === 'string' && p.startsWith('/'))
+        .slice(0, 500)
+        .map(normalizePath);
+    return { tags: tags.length ? Array.from(new Set(tags)) : [CACHE_TAG], paths: Array.from(new Set(paths)) };
+}
+export const outputMode = () => (process.env.SEARKIN_OUTPUT === 'export' ? 'export' : 'server');

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@searkin/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Searkin pour les sites Next.js sans CMS : métadonnées SEO, redirections et rafraîchissement signé, pilotés depuis Searkin.",
+  "license": "MIT",
+  "type": "module",
+  "author": "Searkin",
+  "homepage": "https://app.searkin.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zakaru-Studio/searkin.git",
+    "directory": "packages/next-plugin"
+  },
+  "keywords": [
+    "next",
+    "nextjs",
+    "seo",
+    "searkin",
+    "metadata",
+    "redirects"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./route": {
+      "types": "./dist/route.d.ts",
+      "import": "./dist/route.js",
+      "default": "./dist/route.js"
+    },
+    "./pages": {
+      "types": "./dist/pages.d.ts",
+      "import": "./dist/pages.js",
+      "default": "./dist/pages.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js",
+      "default": "./dist/middleware.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "searkin-next": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "peerDependencies": {
+    "next": ">=13.4.0 <17",
+    "react": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "next": "15.5.29",
+    "react": "19.1.1",
+    "react-dom": "19.1.1",
+    "typescript": "~5.7.3"
+  }
+}