@reactll/connect 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reactor Technology
+
+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,76 @@
-# Temporary Holding Version
+# Reactll Connect for Next.js and Node.js
 
-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.
+Connects a Next.js or any Node.js site (Express, Fastify, Nuxt, Remix, Astro, Hono…) to its [Reactll](https://reactll.com) dashboard: visits, calls, WhatsApp and
+directions clicks, form leads and site health. Built and maintained by **Reactor Technology**.
+
+## Install
+
+```bash
+npm i @reactll/connect
+```
+
+```dotenv
+REACTLL_CONNECT_TOKEN=rcc_…   # Reactll → Sites → the site → Install (server-side only)
+```
+
+**1. The script** — once, in `app/layout.tsx`:
+
+```tsx
+import { ReactllConnect } from '@reactll/connect';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <ReactllConnect />
+      </body>
+    </html>
+  );
+}
+```
+
+Cookieless; client-side navigations count as page views. Only the public site key reaches the browser.
+
+**2. Health** — Reactll asks hourly (signed, nothing else can call it). `app/api/reactll/health/route.ts`:
+
+```ts
+export { GET } from '@reactll/connect/server';
+```
+
+**3. Form leads** — after your server action validated and saved the form:
+
+```ts
+'use server';
+import { headers } from 'next/headers';
+import { submitLeadFromFormData } from '@reactll/connect/server';
+
+export async function contact(formData: FormData) {
+  // …validate and save…
+  await submitLeadFromFormData('Contact', formData, { headers: await headers() });
+}
+```
+
+The script stamps every form with the page view id (`_rc_pv`), so Reactll ties the lead to the visit it
+came from. `submitLead(form, fields, options)` takes a plain object instead. Neither ever throws.
+
+## Any other Node.js app
+
+The same package, without Next.js or React (they are optional):
+
+```js
+import { scriptTag, expressHealth, submitLead } from '@reactll/connect/server';
+
+app.use(expressHealth());                       // Express / Connect / node:http — GET /api/reactll/health
+res.render('page', { reactll: scriptTag() });   // put {{{ reactll }}} / <%- reactll %> in the <head>
+
+// after your form was validated and saved:
+await submitLead('Contact', { name, email, message }, { pv: req.body._rc_pv, page: req.get('referer') });
+```
+
+Frameworks on web `Request`/`Response` (Hono, Remix, Nuxt/h3, Astro, Bun, Deno): route
+`GET /api/reactll/health` to `health(request)` from `@reactll/connect/server`.
+
+## License
+
+MIT © Reactor Technology

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { VERSION } from './token.js';
+/**
+ * The Reactll Connect script. Put it once in your root layout (a server component):
+ *
+ *   <ReactllConnect />
+ *
+ * It reads REACTLL_CONNECT_TOKEN on the server and renders nothing when it is missing. Cookieless;
+ * client-side navigations are counted as page views.
+ */
+export declare function ReactllConnect({ token }: {
+    token?: string;
+}): import("react").JSX.Element | null;
+export default ReactllConnect;

package/dist/index.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Script from 'next/script';
+import { credentials } from './token.js';
+export { VERSION } from './token.js';
+/**
+ * The Reactll Connect script. Put it once in your root layout (a server component):
+ *
+ *   <ReactllConnect />
+ *
+ * It reads REACTLL_CONNECT_TOKEN on the server and renders nothing when it is missing. Cookieless;
+ * client-side navigations are counted as page views.
+ */
+export function ReactllConnect({ token }) {
+    const c = credentials(token ?? process.env.REACTLL_CONNECT_TOKEN);
+    if (!c)
+        return null;
+    return _jsx(Script, { id: "reactll-connect", src: `${c.u}/c.js`, "data-site": c.k, strategy: "afterInteractive" });
+}
+export default ReactllConnect;

package/dist/server.d.ts

@@ -0,0 +1,58 @@
+export { VERSION, credentials } from './token.js';
+type Fields = Record<string, unknown>;
+interface LeadOptions {
+    /** The page view id the script stamps into every form as `_rc_pv`. */
+    pv?: string | null;
+    /** The page the form was sent from. */
+    page?: string | null;
+    /** Your own id for this submission, so a retry never doubles it. */
+    id?: string;
+    token?: string;
+}
+/**
+ * Send a form your site accepted to Reactll as a lead (from a server action or route handler, after
+ * validating and saving it). Never throws: false when Reactll could not be reached.
+ */
+export declare function submitLead(form: string, fields: Fields, options?: LeadOptions): Promise<boolean>;
+/**
+ * The same from a FormData (a server action's argument): `_rc_pv` is read from it, and the page from
+ * the request's Referer when you pass `headers()`.
+ */
+export declare function submitLeadFromFormData(form: string, data: FormData, options?: LeadOptions & {
+    headers?: Headers;
+}): Promise<boolean>;
+/**
+ * The script tag for any server-rendered page (Express/EJS, Handlebars, Fastify, Nuxt, Astro…), or ''
+ * when not connected. Put it in the <head>. Only the public site key is in it.
+ */
+export declare function scriptTag(token?: string): string;
+/**
+ * Hourly health check, asked by Reactll (Next.js has no scheduler of its own). Export it from
+ * app/api/reactll/health/route.ts:
+ *
+ *   export { GET } from '@reactll/connect/server';
+ *
+ * Only Reactll can call it: the request is signed with the site's secret.
+ */
+export declare function GET(request: Request): Promise<Response>;
+export declare const dynamic = "force-dynamic";
+/** The health answer as plain data (platform and versions), for any framework. */
+export declare function health(request: Request): Promise<Response>;
+type NodeReq = {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+};
+type NodeRes = {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+};
+/**
+ * Express / Connect (and plain node:http) middleware answering Reactll's hourly health question at
+ * GET /api/reactll/health. Other requests pass through.
+ *
+ *   app.use(expressHealth());
+ */
+export declare function expressHealth(path?: string): (req: NodeReq, res: NodeRes, next?: () => void) => Promise<void>;

package/dist/server.js

@@ -0,0 +1,145 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { credentials, VERSION } from './token.js';
+export { VERSION, credentials } from './token.js';
+const DROP = /pass(word)?|card|cvv|cvc|token|nonce|captcha|^_rc_pv$|^\$ACTION/i;
+function sign(secret, payload) {
+    const ts = String(Math.floor(Date.now() / 1000));
+    return { ts, signature: createHmac('sha256', secret).update(`${ts}.${payload}`).digest('hex') };
+}
+/**
+ * Send a form your site accepted to Reactll as a lead (from a server action or route handler, after
+ * validating and saving it). Never throws: false when Reactll could not be reached.
+ */
+export async function submitLead(form, fields, options = {}) {
+    const c = credentials(options.token);
+    if (!c)
+        return false;
+    const clean = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (DROP.test(key) || value === undefined || value === null || typeof value === 'function')
+            continue;
+        clean[key] = typeof value === 'string' ? value : typeof value === 'object' ? JSON.stringify(value) : String(value);
+    }
+    const pv = options.pv && /^[0-9a-f-]{36}$/i.test(options.pv) ? options.pv : null;
+    const body = JSON.stringify({
+        id: options.id ?? `${form.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${randomUUID()}`,
+        form,
+        page: options.page ?? null,
+        pv,
+        submitted_at: new Date().toISOString(),
+        fields: clean,
+    });
+    const { ts, signature } = sign(c.s, body);
+    try {
+        const response = await fetch(`${c.u}/submissions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                'X-Reactll-Key': c.k,
+                'X-Reactll-Timestamp': ts,
+                'X-Reactll-Signature': signature,
+                'User-Agent': `ReactllConnect/${VERSION} Next.js`,
+            },
+            body,
+            signal: AbortSignal.timeout(4000),
+            cache: 'no-store',
+        });
+        return response.ok || response.status === 409;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The same from a FormData (a server action's argument): `_rc_pv` is read from it, and the page from
+ * the request's Referer when you pass `headers()`.
+ */
+export async function submitLeadFromFormData(form, data, options = {}) {
+    const fields = {};
+    data.forEach((value, key) => {
+        if (typeof value === 'string')
+            fields[key] = value;
+    });
+    const pv = typeof data.get('_rc_pv') === 'string' ? data.get('_rc_pv') : null;
+    return submitLead(form, fields, { ...options, pv: options.pv ?? pv, page: options.page ?? options.headers?.get('referer') ?? null });
+}
+/**
+ * The script tag for any server-rendered page (Express/EJS, Handlebars, Fastify, Nuxt, Astro…), or ''
+ * when not connected. Put it in the <head>. Only the public site key is in it.
+ */
+export function scriptTag(token) {
+    const c = credentials(token);
+    return c ? `<script src="${c.u}/c.js" data-site="${c.k}" defer></script>` : '';
+}
+function versionOf(pkg) {
+    try {
+        return createRequire(import.meta.url)(`${pkg}/package.json`).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Hourly health check, asked by Reactll (Next.js has no scheduler of its own). Export it from
+ * app/api/reactll/health/route.ts:
+ *
+ *   export { GET } from '@reactll/connect/server';
+ *
+ * Only Reactll can call it: the request is signed with the site's secret.
+ */
+export async function GET(request) {
+    const c = credentials();
+    if (!c)
+        return Response.json({ error: 'not connected' }, { status: 404 });
+    const ts = request.headers.get('x-reactll-timestamp') ?? '';
+    const given = request.headers.get('x-reactll-signature') ?? '';
+    const expected = createHmac('sha256', c.s).update(`${ts}.health`).digest('hex');
+    const fresh = /^\d+$/.test(ts) && Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
+    if (!fresh || given.length !== expected.length || !timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
+        return Response.json({ error: 'unauthorized' }, { status: 401 });
+    }
+    return Response.json({
+        platform: versionOf('next') ? 'next' : 'node',
+        version: VERSION,
+        runtime: Object.fromEntries(Object.entries({
+            next: versionOf('next'),
+            react: versionOf('react'),
+            node: process.version.replace(/^v/, ''),
+            environment: process.env.VERCEL_ENV ?? process.env.NODE_ENV,
+            host: process.env.VERCEL ? 'Vercel' : undefined,
+        }).filter(([, v]) => v)),
+    }, { headers: { 'Cache-Control': 'no-store' } });
+}
+export const dynamic = 'force-dynamic';
+/** The health answer as plain data (platform and versions), for any framework. */
+export async function health(request) {
+    return GET(request);
+}
+/**
+ * Express / Connect (and plain node:http) middleware answering Reactll's hourly health question at
+ * GET /api/reactll/health. Other requests pass through.
+ *
+ *   app.use(expressHealth());
+ */
+export function expressHealth(path = '/api/reactll/health') {
+    return async (req, res, next) => {
+        const url = (req.originalUrl ?? req.url ?? '').split('?')[0];
+        if ((req.method ?? 'GET') !== 'GET' || url !== path) {
+            next?.();
+            return;
+        }
+        const header = (name) => {
+            const v = req.headers[name];
+            return Array.isArray(v) ? v[0] : (v ?? '');
+        };
+        const answer = await GET(new Request('http://localhost' + path, {
+            headers: { 'x-reactll-timestamp': header('x-reactll-timestamp'), 'x-reactll-signature': header('x-reactll-signature') },
+        }));
+        res.statusCode = answer.status;
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Cache-Control', 'no-store');
+        res.end(await answer.text());
+    };
+}

package/dist/token.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reactll Connect for Next.js — built and maintained by Reactor Technology.
+ *
+ * The connection token (REACTLL_CONNECT_TOKEN, from Reactll → Sites → the site → Install) holds the
+ * endpoint, the site's public key and its secret. Only the endpoint and the public key ever reach
+ * the browser.
+ */
+export declare const VERSION = "1.0.0";
+export interface Credentials {
+    /** Endpoint, e.g. https://connect.reactll.com/v1 */
+    u: string;
+    /** Public site key (rc_…) */
+    k: string;
+    /** Secret: server only */
+    s: string;
+}
+export declare function credentials(token?: string | undefined | null): Credentials | null;

package/dist/token.js

@@ -0,0 +1,23 @@
+/**
+ * Reactll Connect for Next.js — built and maintained by Reactor Technology.
+ *
+ * The connection token (REACTLL_CONNECT_TOKEN, from Reactll → Sites → the site → Install) holds the
+ * endpoint, the site's public key and its secret. Only the endpoint and the public key ever reach
+ * the browser.
+ */
+export const VERSION = '1.0.0';
+export function credentials(token = process.env.REACTLL_CONNECT_TOKEN) {
+    const raw = (token ?? '').trim();
+    if (!raw.startsWith('rcc_'))
+        return null;
+    try {
+        const json = Buffer.from(raw.slice(4).replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+        const data = JSON.parse(json);
+        if (!data.u || !data.k || !data.s)
+            return null;
+        return { u: data.u.replace(/\/+$/, ''), k: data.k, s: data.s };
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@reactll/connect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Reactll Connect for Next.js and any Node.js app: visits, clicks, form leads and site health for your Reactll dashboard.",
+  "keywords": [
+    "nextjs",
+    "nodejs",
+    "express",
+    "analytics",
+    "leads",
+    "reactll"
+  ],
+  "homepage": "https://reactll.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Reactll/connect-next.git"
+  },
+  "license": "MIT",
+  "author": "Reactor Technology (https://reactll.com)",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/",
+    "prepare": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "next": ">=13.4",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "next": "^15.5.0",
+    "react": "^19.0.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}