@farm.js/telemetry 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Farming Labs
+
+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,155 @@
-# Temporary Holding Version
+# Farm.js telemetry
 
-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.
+Server-only, opt-in request and native MCP metadata collection for Farm Infra.
+Requires **Farm.js core 0.1.2 or later**. Native MCP correlation additionally requires
+**`@farm.js/mcp` 0.1.0-beta.2 or later**; older MCP packages do not emit the required
+request-scoped tool outcomes. Keep your app's shared Farm packages on the same version.
+
+This is a release candidate. Publish the matching framework versions before publishing
+this package or advertising the following install command as available.
+
+```sh
+pnpm add @farm.js/telemetry@beta
+```
+
+In your server-side `farm.config.ts`:
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { telemetry } from "@farm.js/telemetry";
+
+export default defineConfig({
+  plugins: [telemetry({ projectId: "proj_…" })], // the project ID shown in Farm Infra
+});
+```
+
+Then set the key in the server environment and redeploy the app directory:
+
+```sh
+FARMJS_API_KEY=farmjs_…   # an account-wide Farm Infra API key
+FARMJS_API_URL=https://…  # only if Farm Infra isn't at https://infra.farmjs.dev
+```
+
+The plugin reads both itself; pass `key` or `endpoint` to override them. Without a key it
+stays off and installs no hooks, so local development needs no setup. Farm evaluates the
+config when it builds and again when the server starts, so make the key available to both
+(Vercel environment variables are). `enabled: true` turns a missing key into an error.
+
+The key's owner must be a member of the project's organization, and that is checked on
+every batch, so the key can't write to another organization's project whatever `projectId`
+says. Preview-only (project-restricted) keys are refused. The environment defaults to
+Vercel's (`preview` counts as `staging`), then `NODE_ENV`; set
+`environment: "production" | "staging" | "development"` to choose it yourself.
+
+An account key belongs to a person: it stops sending if they revoke it or leave the
+organization, and on a server it can also start previews and run site checks as them.
+For a credential that only writes telemetry, create a write-only key for the project and
+environment in Infra and set that as `FARMJS_API_KEY` instead; it names its own project and
+environment, so `projectId` isn't needed.
+
+Nothing automatically enables collection, changes MCP authorization, or proxies the app
+through Infra. Omit the plugin or set `enabled: false` to install no runtime hooks.
+
+## What is collected
+
+- Request UUID, matched route **template**, method, response status and time to the
+  runtime response boundary (not streamed-body duration or proof of client delivery).
+- Native registered MCP tool callback completion, tool name, duration and actual
+  success/error outcome. An MCP error inside HTTP 200 remains a tool error.
+- Tool and request records share a server-generated UUID held in private plugin
+  context. No extra request/response headers are added. Other app instances and
+  unscoped MCP events are excluded.
+- Incoming user-agent tokens can produce **self-reported**, never verified identities.
+  Initial detection covers OpenAI's GPTBot/OAI-SearchBot/ChatGPT-User and Anthropic's
+  ClaudeBot/Claude-SearchBot/Claude-User. See the
+  [OpenAI crawler reference](https://developers.openai.com/api/docs/bots) and
+  [Anthropic crawler reference](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler).
+  Missing, ambiguous, browser, curl and unrecognized harness identifiers stay Unknown.
+  This does not verify IP ranges, signatures, identity, citations or agent runs.
+
+No raw URLs, parameters, query strings, user agents, IPs, cookies, authorization,
+headers, bodies, prompts, tool arguments/results, or exception messages are exported.
+Configured route templates and tool names are metadata; do not put secrets in their
+definitions. Unmatched routes use `/[unmatched]`.
+
+## Delivery and coverage
+
+At most 500 events in memory, batches of 50 (128 KiB ceiling), five attempts per event,
+five-minute queue age, two-second fetch deadlines and five-second flush budgets.
+The runtime hook registers each drain with Farm's `waitUntil`, without awaiting it in
+the response path. Retries retain IDs for receiver deduplication. A longer Retry-After
+pauses delivery until later traffic triggers a flush; it does not hold serverless
+requests open for minutes/hours. Queued events may expire first. Shutdown unregisters
+the listener, attempts a bounded flush and releases the queue. This is best-effort,
+not a durable audit log; process termination and runtime lifetime limits can drop events.
+Transport failures never change an application response. `onDiagnostic` optionally
+reports only a small code, count and HTTP status; observer errors are contained.
+
+Invalid keys/config fail clearly when enabling the plugin. Receiver 400/401/403/404/413/415
+disable that sender instance until reconfigured/restarted. Requests use HTTPS (or
+explicit loopback HTTP for development), reject redirects, and do not read/log response
+bodies. Ingestion keys never appear in a URL or browser config.
+
+Only traffic reaching Farm's hooked runtime is visible. CDN/static hits, WAF blocks,
+provider-side traffic and outside agent runs are not covered. Global request hooks can
+affect Farm's runtime/static optimization eligibility; disabled collection adds no hooks.
+Assets are excluded. Unhandled errors without a final Response at this boundary are
+not assigned invented HTTP status codes. MCP authorization/SDK rejections before a
+registered tool callback do not become tool executions. Renderers share the server
+hooks; the initial sender targets Node-compatible runtimes. Edge portability is not claimed.
+
+## Verify
+
+```sh
+pnpm --filter @farm.js/telemetry test
+pnpm --filter @farm.js/telemetry type-check
+pnpm --filter @farm.js/telemetry build
+```
+
+Tests exercise the actual Farm plugin manager, concurrent request scopes, metadata
+compatibility with the receiver, bounded delivery/retries and shutdown. Runtime smoke
+verification uses a matching built Farm checkout and a loopback receiver only; no
+production credentials, database or destination are needed.
+
+```sh
+FARM_TELEMETRY_FRAMEWORK_DIR=/absolute/path/to/matching/farm.js \
+  pnpm --filter @farm.js/telemetry test:runtime
+```
+
+Build core and MCP in that checkout first. The check packs the SDK, verifies its file
+allowlist, installs that tarball into an isolated fixture and checks its JavaScript
+and declarations without accessing the SDK sources. It starts a real Vite app, builds and
+loads its Vercel function, sends HTTP requests and an authenticated native MCP call,
+and validates received metadata against Infra's v1 contract. It checks route-template
+redaction, caller labels, correlated tool errors under HTTP 200, and the absence of
+fixture credentials in client JavaScript. The receiver is loopback-only and in-memory;
+receiver database authorization/retention is covered by the separate PostgreSQL suite.
+
+To verify the complete path through a running Infra server, start Infra against an
+isolated, migrated **local test database**, then run:
+
+```sh
+DATABASE_URL=postgresql://localhost/YOUR_ISOLATED_TEST_DATABASE \
+INFRA_TEST_URL=http://localhost:3013 \
+TELEMETRY_RUNTIME_BROWSER_E2E=1 \
+FARM_TELEMETRY_FRAMEWORK_DIR=/absolute/path/to/matching/farm.js \
+  pnpm --dir apps/web exec playwright test tests/browser/telemetry-runtime.e2e.spec.ts
+```
+
+This creates a fixture account and project-scoped ingestion key, runs both Farm
+execution modes, forwards the recorded exporter batches unchanged into the real
+ingestion API, and checks PostgreSQL records and the dashboard's correlated MCP
+error details. It seeds only the repository snapshot: it does **not** verify GitHub
+App installation or repository authorization. The project and its events/keys are
+removed afterward; the disposable account remains in the isolated test database.
+The optional runtime-driver forwarding URL accepts only loopback HTTP, and its
+ephemeral key is passed through the child process environment, never command arguments.
+
+## Publishing
+
+Publish only a reviewed, committed package after the checks above pass against the
+matching released core and MCP versions. From this directory, run `npm publish --tag beta`.
+The `prepack` hook builds declarations and JavaScript; the explicit `files` allowlist
+excludes tests and local configuration. Verify the exact version on npm and install it
+in a separate app before announcing availability. Do not promote this early-access
+sender to `latest` as part of the framework's independent release process.

package/dist/exporter.d.ts

@@ -0,0 +1,26 @@
+import type { MetadataEvent } from "./metadata.js";
+export type Diagnostic = {
+    code: "dropped" | "retry" | "disabled";
+    count?: number;
+    status?: number;
+};
+export type Environment = "production" | "staging" | "development";
+export interface ExporterOptions {
+    endpoint: string;
+    /** A Farm Infra API key (`farmjs_…`), or a project's write-only ingestion key (`fti_…`). */
+    key: string;
+    /** The project ID shown in Farm Infra. Needed with an API key; an ingestion key names its own. */
+    projectId?: string;
+    /** Defaults to Vercel's environment (preview counts as staging), then NODE_ENV. */
+    environment?: Environment;
+    onDiagnostic?: (event: Diagnostic) => void | Promise<void>;
+}
+/** Where the app is running, when the config doesn't say. */
+export declare function defaultEnvironment(env?: Record<string, string | undefined>): Environment;
+export declare function validateDestination(options: ExporterOptions): void;
+/** Bounded best-effort delivery. Never retain a Request, Response, or payload body. */
+export declare function createExporter(options: ExporterOptions, send?: typeof fetch): {
+    enqueue: (event: MetadataEvent) => void;
+    flush: () => Promise<void>;
+    close: () => Promise<void>;
+};

package/dist/exporter.js

@@ -0,0 +1,210 @@
+const INGESTION_KEY = /^fti_[A-Za-z0-9_-]{43}$/;
+const API_KEY = /^farmjs_[A-Za-z0-9_-]{32}$/;
+const PROJECT = /^proj_[0-9a-f-]{36}$/;
+const ENVIRONMENTS = ["production", "staging", "development"];
+/** Where the app is running, when the config doesn't say. */
+export function defaultEnvironment(env = process.env) {
+    if (env.VERCEL_ENV === "production")
+        return "production";
+    if (env.VERCEL_ENV === "preview")
+        return "staging";
+    if (env.VERCEL_ENV === "development")
+        return "development";
+    return env.NODE_ENV === "production" ? "production" : "development";
+}
+const MAX_QUEUE = 500;
+const MAX_AGE = 300_000;
+const MAX_ATTEMPTS = 5;
+const FLUSH_BUDGET = 5_000;
+const TIMEOUT = 2_000;
+const encoder = new TextEncoder();
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function validateDestination(options) {
+    const url = new URL(options.endpoint);
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/api/telemetry/v1/events") {
+        throw new TypeError("Use the HTTPS Farm Infra /api/telemetry/v1/events endpoint (HTTP is local-only).");
+    }
+    if (INGESTION_KEY.test(options.key))
+        return;
+    if (!API_KEY.test(options.key)) {
+        throw new TypeError("Set FARMJS_API_KEY to a Farm Infra API key (farmjs_…), or pass `key` (an API key or a write-only fti_… key).");
+    }
+    if (!options.projectId || !PROJECT.test(options.projectId)) {
+        throw new TypeError("Set `projectId` to the project ID shown in Farm Infra (proj_…).");
+    }
+    if (options.environment !== undefined && !ENVIRONMENTS.includes(options.environment)) {
+        throw new TypeError("Set `environment` to production, staging or development.");
+    }
+}
+/** Request headers: an API key also names the project and environment it writes to. */
+function headers(options) {
+    const base = { "content-type": "application/json", authorization: `Bearer ${options.key}` };
+    if (INGESTION_KEY.test(options.key))
+        return base;
+    return {
+        ...base,
+        "x-farm-project": options.projectId,
+        "x-farm-environment": options.environment ?? defaultEnvironment(),
+    };
+}
+function retryAt(value, now) {
+    if (!value)
+        return now;
+    if (/^\d+$/.test(value.trim()))
+        return now + Math.min(Number(value), 86_400) * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(now, Math.min(date, now + 86_400_000)) : now;
+}
+/** Bounded best-effort delivery. Never retain a Request, Response, or payload body. */
+export function createExporter(options, send = fetch) {
+    validateDestination(options);
+    const requestHeaders = headers(options);
+    const queue = [];
+    let stopped = false;
+    let closing = false;
+    let pending;
+    let notBefore = 0;
+    let active;
+    let inFlight = new Set();
+    const diagnostic = (event) => {
+        try {
+            void Promise.resolve(options.onDiagnostic?.(event)).catch(() => { });
+        }
+        catch {
+            /* Optional observer. */
+        }
+    };
+    function prune() {
+        const now = Date.now();
+        const expired = queue.filter((item) => !inFlight.has(item) && (now - item.enqueuedAt >= MAX_AGE || item.attempts >= MAX_ATTEMPTS));
+        if (expired.length) {
+            for (let i = queue.length - 1; i >= 0; i--) {
+                if (!inFlight.has(queue[i]) &&
+                    (now - queue[i].enqueuedAt >= MAX_AGE || queue[i].attempts >= MAX_ATTEMPTS))
+                    queue.splice(i, 1);
+            }
+            diagnostic({ code: "dropped", count: expired.length });
+        }
+    }
+    function remove(batch) {
+        const sent = new Set(batch);
+        for (let i = queue.length - 1; i >= 0; i--)
+            if (sent.has(queue[i]))
+                queue.splice(i, 1);
+    }
+    function enqueue(event) {
+        if (stopped || closing)
+            return;
+        prune();
+        if (queue.length >= MAX_QUEUE) {
+            diagnostic({ code: "dropped", count: 1 });
+            return;
+        }
+        queue.push({ event, enqueuedAt: Date.now(), attempts: 0 });
+    }
+    async function drain() {
+        const deadline = Date.now() + FLUSH_BUDGET;
+        // Coalesce simultaneous completions while keeping the entire drain in waitUntil.
+        await sleep(25);
+        while (!stopped && queue.length && Date.now() < deadline) {
+            prune();
+            if (!queue.length)
+                break;
+            if (notBefore >= deadline)
+                break;
+            if (notBefore > Date.now())
+                await sleep(notBefore - Date.now());
+            if (stopped || Date.now() >= deadline)
+                break;
+            const batch = queue.slice(0, 50);
+            const body = JSON.stringify({ schemaVersion: 1, events: batch.map(({ event }) => event) });
+            if (encoder.encode(body).length > 128 * 1024) {
+                queue.splice(0, batch.length);
+                diagnostic({ code: "dropped", count: batch.length });
+                continue;
+            }
+            for (const item of batch)
+                item.attempts++;
+            inFlight = new Set(batch);
+            active = new AbortController();
+            const timeout = setTimeout(() => active?.abort(), Math.min(TIMEOUT, deadline - Date.now()));
+            let status;
+            try {
+                const response = await send(options.endpoint, {
+                    method: "POST",
+                    redirect: "error",
+                    signal: active.signal,
+                    headers: requestHeaders,
+                    body,
+                });
+                status = response.status;
+                // The receipt body is not needed; never wait for or log arbitrary response text.
+                void response.body?.cancel().catch(() => { });
+                if (response.ok) {
+                    remove(batch);
+                    continue;
+                }
+                if (status === 401 ||
+                    status === 403 ||
+                    // An API key naming a project its owner can't reach.
+                    status === 404 ||
+                    status === 400 ||
+                    status === 413 ||
+                    status === 415 ||
+                    (status >= 300 && status < 400)) {
+                    stopped = true;
+                    queue.length = 0;
+                    diagnostic({ code: "disabled", status });
+                    break;
+                }
+                if (status !== 408 && status !== 429 && status < 500) {
+                    remove(batch);
+                    diagnostic({ code: "dropped", count: batch.length, status });
+                    continue;
+                }
+                notBefore = Math.max(notBefore, retryAt(response.headers.get("retry-after"), Date.now()));
+            }
+            catch {
+                /* Network failure or deadline: keep the same event IDs for a bounded retry. */
+            }
+            finally {
+                clearTimeout(timeout);
+                active = undefined;
+                inFlight.clear();
+            }
+            notBefore = Math.max(notBefore, Date.now() + Math.min(30_000, 500 * 2 ** (batch[0].attempts - 1)));
+            diagnostic({ code: "retry", ...(status === undefined ? {} : { status }) });
+        }
+    }
+    function flush() {
+        if (stopped || !queue.length || notBefore > Date.now() + FLUSH_BUDGET)
+            return pending ?? Promise.resolve();
+        if (!pending)
+            pending = drain()
+                .catch(() => { })
+                .finally(() => {
+                pending = undefined;
+            });
+        return pending;
+    }
+    async function close() {
+        if (closing) {
+            await pending;
+            return;
+        }
+        closing = true;
+        await flush();
+        stopped = true;
+        active?.abort();
+        if (queue.length)
+            diagnostic({ code: "dropped", count: queue.length });
+        queue.length = 0;
+    }
+    return { enqueue, flush, close };
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { FarmPlugin } from "@farm.js/core/plugin";
+import { createExporter, type ExporterOptions } from "./exporter.js";
+export type { Diagnostic, Environment } from "./exporter.js";
+/**
+ * Everything is optional: the key comes from FARMJS_API_KEY and Farm Infra's address from
+ * FARMJS_API_URL, so an app usually passes only its `projectId`. Without a key the plugin
+ * stays off (unless `enabled: true`, which then fails clearly).
+ */
+export type TelemetryOptions = Partial<ExporterOptions> & {
+    enabled?: boolean;
+};
+/** The options with the key and endpoint the environment provides filled in. */
+export declare function resolveOptions(options: TelemetryOptions, env?: Record<string, string | undefined>): ExporterOptions;
+interface State {
+    exporter: ReturnType<typeof createExporter>;
+    unsubscribe?: () => void;
+}
+/** Server-only, explicitly configured project telemetry. No browser client or automatic destination. */
+export declare function telemetry(input?: TelemetryOptions): FarmPlugin<State>;

package/dist/index.js

@@ -0,0 +1,115 @@
+import { randomUUID } from "node:crypto";
+import { onFarmEvent } from "@farm.js/core/observability";
+import { getCurrentRequest } from "@farm.js/core/request";
+import { createExporter, validateDestination } from "./exporter.js";
+import { classifyAgent, duration, isToolEvent, routeTemplate } from "./metadata.js";
+const DEFAULT_URL = "https://infra.farmjs.dev";
+/** The options with the key and endpoint the environment provides filled in. */
+export function resolveOptions(options, env = process.env) {
+    let endpoint = options.endpoint;
+    if (endpoint === undefined) {
+        try {
+            endpoint = new URL("/api/telemetry/v1/events", env.FARMJS_API_URL || DEFAULT_URL).href;
+        }
+        catch {
+            throw new TypeError("Set FARMJS_API_URL to Farm Infra's URL, like https://infra.farmjs.dev.");
+        }
+    }
+    return { ...options, endpoint, key: options.key ?? env.FARMJS_API_KEY ?? "" };
+}
+/** Server-only, explicitly configured project telemetry. No browser client or automatic destination. */
+export function telemetry(input = {}) {
+    // A disabled plugin installs no request hooks, so it does not change static eligibility.
+    // Farm evaluates the config at build and at server start, so the key must exist at both.
+    if (input.enabled === false)
+        return { name: "farm-infra-telemetry" };
+    const options = resolveOptions(input);
+    if (input.enabled === undefined && !options.key)
+        return { name: "farm-infra-telemetry" };
+    validateDestination(options);
+    const contextKey = `farm.infra.telemetry.${randomUUID()}`;
+    return {
+        name: "farm-infra-telemetry",
+        enforce: "post",
+        setup(context) {
+            const state = { exporter: createExporter(options) };
+            context.lifecycle.onShutdown(async () => {
+                state.unsubscribe?.();
+                await state.exporter.close();
+            });
+            return state;
+        },
+        runtime: {
+            start(context) {
+                const { exporter } = context.state;
+                // The listener is scoped by a private, per-plugin key, never caller-controlled headers.
+                context.state.unsubscribe = onFarmEvent((event) => {
+                    if (!isToolEvent(event))
+                        return;
+                    let request;
+                    try {
+                        request = getCurrentRequest();
+                    }
+                    catch {
+                        return;
+                    }
+                    const metadata = context.requestContext.get(request, contextKey);
+                    // Streaming MCP transports can return their HTTP Response before the tool finishes.
+                    if (!metadata)
+                        return;
+                    exporter.enqueue({
+                        id: randomUUID(),
+                        requestId: metadata.id,
+                        timestamp: new Date().toISOString(),
+                        route: metadata.route,
+                        agent: metadata.agent,
+                        kind: "mcp.tool",
+                        tool: event.tool,
+                        outcome: event.outcome,
+                        durationMs: duration(event.durationMs),
+                    });
+                    metadata.waitUntil(exporter.flush());
+                }, { unfiltered: true });
+            },
+            before(event) {
+                if (event.kind === "asset" || !event.state)
+                    return;
+                event.req.set(contextKey, {
+                    id: randomUUID(),
+                    agent: classifyAgent(event.request.headers.get("user-agent")),
+                    route: routeTemplate(event.route?.pattern),
+                    completed: false,
+                    waitUntil: event.waitUntil,
+                });
+            },
+            after(event) {
+                const metadata = event.req.get(contextKey);
+                if (!metadata || metadata.completed || !event.state)
+                    return;
+                metadata.completed = true;
+                if (!["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "QUERY"].includes(event.request.method))
+                    return;
+                event.state.exporter.enqueue({
+                    id: randomUUID(),
+                    requestId: metadata.id,
+                    timestamp: new Date().toISOString(),
+                    route: metadata.route,
+                    agent: metadata.agent,
+                    kind: "request",
+                    method: event.request.method,
+                    status: event.response.status,
+                    durationMs: duration(event.durationMs),
+                });
+                event.waitUntil(event.state.exporter.flush());
+            },
+            // Unhandled exceptions have no final HTTP status at this boundary. Do not fabricate a 500.
+            error(event) {
+                const metadata = event.req.get(contextKey);
+                if (metadata)
+                    metadata.completed = true;
+                if (event.state)
+                    event.waitUntil(event.state.exporter.flush());
+            },
+        },
+    };
+}

package/dist/metadata.d.ts

@@ -0,0 +1,32 @@
+export interface AgentIdentity {
+    family: "unknown" | "openai" | "anthropic" | "google" | "microsoft" | "perplexity" | "other";
+    category: "unknown" | "crawler" | "agent" | "harness";
+    identity: "unknown" | "self-reported";
+}
+interface EventBase {
+    id: string;
+    timestamp: string;
+    durationMs: number;
+    route: string;
+    requestId: string;
+    agent: AgentIdentity;
+}
+export type MetadataEvent = EventBase & ({
+    kind: "request";
+    method: string;
+    status: number;
+} | {
+    kind: "mcp.tool";
+    tool: string;
+    outcome: "success" | "error";
+});
+export declare function classifyAgent(userAgent: string | null): AgentIdentity;
+export declare function routeTemplate(pattern: unknown): string;
+export declare function duration(value: number): number;
+export declare function isToolEvent(value: unknown): value is {
+    type: "mcp.tool.complete";
+    tool: string;
+    outcome: "success" | "error";
+    durationMs: number;
+};
+export {};

package/dist/metadata.js

@@ -0,0 +1,46 @@
+// These are declarations, NOT proof of identity. Keep raw headers out of the event.
+// Sources and the deliberately limited initial coverage are documented in README.md.
+const tokens = [
+    ["ChatGPT-User", "openai", "agent"],
+    ["OAI-SearchBot", "openai", "crawler"],
+    ["GPTBot", "openai", "crawler"],
+    ["Claude-User", "anthropic", "agent"],
+    ["Claude-SearchBot", "anthropic", "crawler"],
+    ["ClaudeBot", "anthropic", "crawler"],
+];
+const patterns = tokens.map(([token, family, category]) => ({
+    pattern: new RegExp(`(?:^|[\\s;(])${token}(?=[/\\s;)]|$)`, "i"),
+    family,
+    category,
+}));
+export function classifyAgent(userAgent) {
+    const value = (userAgent ?? "").slice(0, 2048);
+    const matches = patterns.filter(({ pattern }) => pattern.test(value));
+    // Conflicting tokens are ambiguous, rather than a reason to guess a vendor.
+    if (matches.length === 1) {
+        const { family, category } = matches[0];
+        return { family, category, identity: "self-reported" };
+    }
+    return { family: "unknown", category: "unknown", identity: "unknown" };
+}
+export function routeTemplate(pattern) {
+    return typeof pattern === "string" &&
+        pattern.length <= 256 &&
+        /^\/(?!\/)[a-zA-Z0-9_./:[\]()*-]*$/.test(pattern)
+        ? pattern
+        : "/[unmatched]";
+}
+export function duration(value) {
+    return Number.isFinite(value) ? Math.min(86_400_000, Math.max(0, value)) : 0;
+}
+export function isToolEvent(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const event = value;
+    return (event.type === "mcp.tool.complete" &&
+        typeof event.tool === "string" &&
+        /^[a-zA-Z0-9_.:/-]{1,128}$/.test(event.tool) &&
+        (event.outcome === "success" || event.outcome === "error") &&
+        typeof event.durationMs === "number" &&
+        Number.isFinite(event.durationMs));
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@farm.js/telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "description": "Opt-in, server-only Farm Infra request and MCP metadata sender.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farmjs-infra.git",
+    "directory": "packages/telemetry"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "test:runtime": "pnpm build && node --experimental-strip-types tests/runtime.mjs",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "@farm.js/core": "0.1.1-beta.2",
+    "@types/node": "22.20.1",
+    "typescript": "^5.3.3",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@farm.js/core": ">=0.1.2"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  }
+}