@klariton/beacon

Server-side reach beacon for Klariton. One tiny middleware hook reports page views from your own domain, and Klariton turns them into two insights:

• Agentic Reach: which AI agents and search bots (GPTBot, ClaudeBot, PerplexityBot, ...) actually read which pages of your site.
• Company visits: which companies visit your site, resolved server-side from the visitor IP. The IP is used transiently for a single lookup and is never stored. Anonymous visitors produce no event at all.

No client-side script, no cookies, no impact on page load: the beacon fires fire-and-forget from your server middleware and never delays a response.

Install

npm install @klariton/beacon

Next.js quickstart

If your project has no middleware.ts yet:

// middleware.ts
import { createKlaritonMiddleware } from '@klariton/beacon/next';

export default createKlaritonMiddleware({
  tenant: 'your-org-slug',
  key: process.env.KLARITON_BEACON_KEY ?? '',
});

export const config = {
  matcher: ['/((?!_next/|api/|.*\\..*).*)'],
};

If you already have a middleware, add one call inside it:

// middleware.ts
import type { NextFetchEvent, NextRequest } from 'next/server';
import { reportToKlariton } from '@klariton/beacon/next';

export function middleware(req: NextRequest, event: NextFetchEvent) {
  reportToKlariton(
    { tenant: 'your-org-slug', key: process.env.KLARITON_BEACON_KEY ?? '' },
    req,
    event,
  );
  // ... your existing logic
}

Set the KLARITON_BEACON_KEY environment variable in your production environment only. Without a key the SDK is a silent no-op, so local dev and preview deployments stay quiet. The key is a server-side secret: never expose it to the browser and never commit it.

Hono quickstart

Works on every Hono runtime — Cloudflare Workers, Deno, Bun, and Node via @hono/node-server:

import { Hono } from 'hono';
import { klaritonBeacon } from '@klariton/beacon/hono';

const app = new Hono();

app.use(
  '*',
  klaritonBeacon({
    tenant: 'your-org-slug',
    key: process.env.KLARITON_BEACON_KEY ?? '',
  }),
);

On edge runtimes the beacon is fired through executionCtx.waitUntil; on Node it falls back to plain fire-and-forget. Either way it never delays your response. To report from inside an existing handler instead of mounting middleware, call reportToKlaritonHono(config, c).

Other environments

The core is framework-agnostic and dependency-free. Anything that can run fetch can report:

import { sendReachBeacon } from '@klariton/beacon';

await sendReachBeacon(
  { tenant: 'your-org-slug', key: process.env.KLARITON_BEACON_KEY ?? '' },
  {
    host: 'www.example.com',
    path: '/services',
    userAgent: requestUserAgent,
    clientIp: visitorIp, // optional, enables company resolution
    query: rawQueryString, // optional, enables utm attribution
    referrerDomain: 'chatgpt.com', // optional
  },
);

Framework adapters beyond Next.js and Hono (SvelteKit, Nuxt, Express, ...) follow the same pattern on top of sendReachBeacon.

Schema.org JSON-LD (AI-visible structured data)

@klariton/beacon/schema fetches the Klariton schema-export and returns the JSON-LD @graph string for server-side embedding — so AI crawlers (GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot) can read it. They do not run JavaScript, so client-injected JSON-LD is invisible to them: render it in a Server Component.

// Next.js server component, e.g. app/services/[slug]/page.tsx
import { fetchKlaritonSchema } from '@klariton/beacon/schema';

export default async function ServicePage({ params }: { params: { slug: string } }) {
  const jsonLd = await fetchKlaritonSchema('your-org-slug', `${params.slug}-leistungen`);
  return (
    <>
      {jsonLd && (
        <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLd }} />
      )}
      {/* ...page content... */}
    </>
  );
}

fetchKlaritonSchema(org, product, options?) is framework-agnostic and fail-open (any error → null, never throws). listKlaritonSchemaSlugs(org) returns the available product slugs. The schema data itself is authored in the Klariton Studio; the SDK only fetches + you render it server-side.

Privacy

• The visitor IP is optional, transmitted server-to-server only, used for one company lookup and never persisted or logged.
• Visits only surface when a company is identified; anonymous traffic creates no event.
• Bot detection is based on the request User-Agent, not on people.

Docs

Full documentation: docs.klariton.com