@farm.js/core 0.1.25 → 0.1.26

package/dist/observability-BupkiN0m.d.ts

@@ -0,0 +1,447 @@
+import { Attributes, SpanKind } from '@opentelemetry/api';
+
+/**
+ * Recognizes AI agents and crawlers by the token they put in User-Agent.
+ *
+ * These are declarations, not proof of identity: any client can send them. Use
+ * the result to understand traffic and tailor responses, never to grant access.
+ */
+interface FarmAgentIdentity {
+    family: "unknown" | "openai" | "anthropic" | "google" | "microsoft" | "perplexity" | "other";
+    /** `crawler` indexes or trains; `agent` fetches on a person's request. */
+    category: "unknown" | "crawler" | "agent" | "harness";
+    identity: "unknown" | "self-reported";
+}
+/** Classifies a User-Agent header value. Ambiguous or unknown values are `unknown`. */
+declare function classifyFarmAgent(userAgent: string | null | undefined): FarmAgentIdentity;
+
+type FarmTraceSpanKind = "request" | "render" | "middleware" | "api" | "integration" | "storage" | "ppr" | "build" | "plugin";
+interface FarmTracingConfig {
+    /** Enable Farm's OpenTelemetry spans. */
+    enabled?: boolean;
+    /** Span families to record. All families are enabled by default. */
+    spans?: readonly FarmTraceSpanKind[];
+    /** Add Farm lifecycle events to the active span. Defaults to true. */
+    recordEvents?: boolean;
+    /** Static attributes added to every Farm-created span. */
+    attributes?: Attributes;
+    /** Path prefixes that should not create request spans. */
+    ignorePaths?: readonly string[];
+}
+type FarmTracingUserConfig = boolean | FarmTracingConfig;
+interface FarmResolvedTracingConfig {
+    enabled: boolean;
+    spans: ReadonlySet<FarmTraceSpanKind>;
+    recordEvents: boolean;
+    attributes: Attributes;
+    ignorePaths: readonly string[];
+}
+interface FarmTraceContext {
+    traceId: string;
+    spanId: string;
+    traceSampled: boolean;
+}
+interface FarmRequestSpanOptions {
+    getStatusCode?: () => number | undefined;
+    onStart?: () => void;
+    onComplete?: (status: number, durationMs: number) => void;
+    onError?: (error: unknown, durationMs: number) => void;
+}
+interface FarmSpanOptions {
+    kind?: FarmTraceSpanKind;
+    attributes?: Attributes;
+    spanKind?: SpanKind;
+}
+declare function normalizeFarmTracingConfig(config: FarmTracingUserConfig | undefined): FarmResolvedTracingConfig;
+declare function configureFarmTracing(config: FarmTracingUserConfig | FarmResolvedTracingConfig | undefined): void;
+declare function getFarmTraceContext(): FarmTraceContext | undefined;
+declare function runWithFarmSpan<T>(name: string, handler: () => T | Promise<T>, options?: FarmSpanOptions): Promise<T>;
+
+type FarmEventLevel = "debug" | "info" | "warn" | "error";
+interface FarmEventBase {
+    type: string;
+    timestamp: number;
+    level: FarmEventLevel;
+    requestId?: string;
+    traceId?: string;
+    spanId?: string;
+    traceSampled?: boolean;
+    route?: string;
+    pathname?: string;
+}
+type FarmRequestEvent = (FarmEventBase & {
+    type: "request.start";
+    method: string;
+    pathname: string;
+}) | (FarmEventBase & {
+    type: "request.complete";
+    method: string;
+    pathname: string;
+    status: number;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "request.error";
+    method: string;
+    pathname: string;
+    durationMs: number;
+    error: unknown;
+});
+type FarmServerEvent = (FarmEventBase & {
+    type: "server.start";
+    mode: "dev" | "preview" | "production";
+    port?: number;
+}) | (FarmEventBase & {
+    type: "server.ready";
+    url?: string;
+}) | (FarmEventBase & {
+    type: "server.shutdown";
+    reason?: string;
+});
+type FarmRouteEvent = (FarmEventBase & {
+    type: "route.discovered";
+    route: string;
+    filePath: string;
+}) | (FarmEventBase & {
+    type: "route.matched";
+    pathname: string;
+    route: string;
+    params?: Record<string, string>;
+}) | (FarmEventBase & {
+    type: "route.notFound";
+    pathname: string;
+}) | (FarmEventBase & {
+    type: "route.redirect";
+    from: string;
+    to: string;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "route.rewrite";
+    from: string;
+    to: string;
+});
+type FarmRenderEvent = (FarmEventBase & {
+    type: "render.start";
+    route: string;
+    pathname?: string;
+}) | (FarmEventBase & {
+    type: "render.complete";
+    route: string;
+    durationMs: number;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "render.error";
+    route?: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "render.stream.start";
+    route: string;
+}) | (FarmEventBase & {
+    type: "render.stream.shellReady";
+    route: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "render.stream.complete";
+    route: string;
+    durationMs: number;
+});
+type FarmCacheEvent = (FarmEventBase & {
+    type: "cache.hit";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+    stale?: boolean;
+}) | (FarmEventBase & {
+    type: "cache.miss";
+    key: string;
+    route?: string;
+    reason?: string;
+}) | (FarmEventBase & {
+    type: "cache.set";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+}) | (FarmEventBase & {
+    type: "cache.dedupe";
+    key: string;
+}) | (FarmEventBase & {
+    type: "cache.bypass";
+    key?: string;
+    route?: string;
+    reason: string;
+}) | (FarmEventBase & {
+    type: "cache.stale";
+    key: string;
+    route?: string;
+    tags?: readonly string[];
+    revalidate?: number | false;
+}) | (FarmEventBase & {
+    type: "cache.revalidatePath";
+    path: string;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.revalidateTag";
+    tag: string;
+    profile?: unknown;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.updateTag";
+    tag: string;
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.invalidated";
+    key?: string;
+    route?: string;
+    tag?: string;
+    reason?: string;
+    count?: number;
+}) | (FarmEventBase & {
+    type: "cache.delete";
+    key: string;
+    deleted: boolean;
+}) | (FarmEventBase & {
+    type: "cache.clear";
+    count: number;
+}) | (FarmEventBase & {
+    type: "cache.error";
+    key?: string;
+    operation: "get" | "set" | "delete" | "revalidate";
+    error: unknown;
+});
+type FarmPPREvent = (FarmEventBase & {
+    type: "ppr.shell.hit";
+    route: string;
+    key: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.miss";
+    route: string;
+    key: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.cached";
+    route: string;
+    key: string;
+    revalidate?: number;
+}) | (FarmEventBase & {
+    type: "ppr.shell.bypass";
+    route: string;
+    reason: string;
+}) | (FarmEventBase & {
+    type: "ppr.shell.invalidated";
+    route: string;
+    reason?: string;
+    count?: number;
+}) | (FarmEventBase & {
+    type: "ppr.suspense.holeDetected";
+    route: string;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.start";
+    route: string;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.complete";
+    route: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "ppr.refresh.error";
+    route: string;
+    error: unknown;
+});
+type FarmAPIEvent = (FarmEventBase & {
+    type: "api.request.start";
+    route: string;
+    method: string;
+}) | (FarmEventBase & {
+    type: "api.request.complete";
+    route: string;
+    method: string;
+    status: number;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "api.validation.failed";
+    route: string;
+    method: string;
+    issues?: unknown;
+}) | (FarmEventBase & {
+    type: "api.error";
+    route: string;
+    method: string;
+    durationMs: number;
+    error: unknown;
+});
+type FarmIntegrationEvent = (FarmEventBase & {
+    type: "integration.registered";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.config.validated";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.ready";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.disposed";
+    name: string;
+}) | (FarmEventBase & {
+    type: "integration.api.call.start";
+    integration: string;
+    operation: string;
+}) | (FarmEventBase & {
+    type: "integration.api.call.complete";
+    integration: string;
+    operation: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "integration.api.call.error";
+    integration: string;
+    operation: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "integration.webhook.received";
+    integration: string;
+    event?: string;
+}) | (FarmEventBase & {
+    type: "integration.webhook.verified";
+    integration: string;
+    event?: string;
+}) | (FarmEventBase & {
+    type: "integration.webhook.failed";
+    integration: string;
+    reason: string;
+});
+/** A registered MCP tool callback completed; not an HTTP response or an agent run. */
+type FarmMCPEvent = FarmEventBase & {
+    type: "mcp.tool.complete";
+    /** Configured transport path, never a raw request URL. */
+    route: string;
+    server: string;
+    tool: string;
+    outcome: "success" | "error";
+    durationMs: number;
+};
+/**
+ * An agent surface answered a request: a Markdown mirror or `page.md`, llms.txt,
+ * llms-full.txt, or the API catalog. `agent` is what the User-Agent declares,
+ * not a verified identity.
+ */
+type FarmAgentEvent = FarmEventBase & {
+    type: "agent.read";
+    surface: "markdown" | "llms" | "llms-full" | "api-catalog";
+    /** The path served, such as `/pricing.md`; never the query string. */
+    route: string;
+    /** For Markdown, the partial view asked for. */
+    view?: "outline" | "section" | "parts" | "actions";
+    status: number;
+    agent: FarmAgentIdentity;
+};
+type FarmMiddlewareEvent = (FarmEventBase & {
+    type: "middleware.start";
+    route?: string;
+    name?: string;
+}) | (FarmEventBase & {
+    type: "middleware.complete";
+    route?: string;
+    name?: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "middleware.shortCircuit";
+    route?: string;
+    name?: string;
+    status?: number;
+}) | (FarmEventBase & {
+    type: "middleware.error";
+    route?: string;
+    name?: string;
+    error: unknown;
+});
+type FarmStorageEvent = (FarmEventBase & {
+    type: "storage.query.start";
+    integration?: string;
+    operation: string;
+}) | (FarmEventBase & {
+    type: "storage.query.complete";
+    integration?: string;
+    operation: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "storage.query.error";
+    integration?: string;
+    operation: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "storage.schema.ready";
+    integration?: string;
+}) | (FarmEventBase & {
+    type: "storage.schema.error";
+    integration?: string;
+    error: unknown;
+});
+type FarmBuildEvent = (FarmEventBase & {
+    type: "build.start";
+    target?: string;
+}) | (FarmEventBase & {
+    type: "build.complete";
+    target?: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "build.error";
+    target?: string;
+    error: unknown;
+}) | (FarmEventBase & {
+    type: "routes.generated";
+    pageCount: number;
+    apiCount?: number;
+}) | (FarmEventBase & {
+    type: "types.generated";
+    filePath: string;
+}) | (FarmEventBase & {
+    type: "manifest.generated";
+    routeCount: number;
+});
+type FarmPluginEvent = (FarmEventBase & {
+    type: "plugin.hook.start";
+    plugin: string;
+    hook: string;
+}) | (FarmEventBase & {
+    type: "plugin.hook.complete";
+    plugin: string;
+    hook: string;
+    durationMs: number;
+}) | (FarmEventBase & {
+    type: "plugin.hook.error";
+    plugin: string;
+    hook: string;
+    error: unknown;
+});
+type FarmErrorEvent = FarmEventBase & {
+    type: "error";
+    source: string;
+    error: unknown;
+    route?: string;
+};
+type FarmEvent = FarmRequestEvent | FarmServerEvent | FarmRouteEvent | FarmRenderEvent | FarmCacheEvent | FarmPPREvent | FarmAPIEvent | FarmIntegrationEvent | FarmMCPEvent | FarmAgentEvent | FarmMiddlewareEvent | FarmStorageEvent | FarmBuildEvent | FarmPluginEvent | FarmErrorEvent;
+type FarmEventType = FarmEvent["type"];
+type FarmEventHandler = (event: FarmEvent) => void | Promise<void>;
+type FarmEventInput = FarmEvent extends infer T ? T extends FarmEvent ? Omit<T, "timestamp" | "level"> & Partial<Pick<T, "timestamp" | "level">> : never : never;
+type FarmObservabilityUserConfig = boolean | {
+    logs?: boolean;
+    onEvent?: FarmEventHandler | readonly FarmEventHandler[];
+    events?: readonly FarmEventType[];
+    tracing?: FarmTracingUserConfig;
+};
+interface FarmResolvedObservabilityConfig {
+    logs: boolean;
+    handlers: FarmEventHandler[];
+    events?: Set<FarmEventType>;
+    tracing: FarmResolvedTracingConfig;
+}
+interface FarmEventSubscriptionOptions {
+    /** Receive events even when they are excluded by `observability.events`. */
+    unfiltered?: boolean;
+}
+declare function configureFarmObservability(config: FarmObservabilityUserConfig | undefined): void;
+declare function normalizeFarmObservabilityConfig(config: FarmObservabilityUserConfig | undefined): FarmResolvedObservabilityConfig;
+declare function onFarmEvent(handler: FarmEventHandler, options?: FarmEventSubscriptionOptions): () => void;
+declare function resetFarmObservability(): void;
+declare function emitFarmEvent(input: FarmEventInput): FarmEvent;
+declare function runWithFarmRequestSpan<T>(request: Request, handler: () => T | Promise<T>, options?: FarmRequestSpanOptions): Promise<T>;
+
+export { type FarmAgentEvent as A, type FarmMiddlewareEvent as B, type FarmStorageEvent as C, type FarmBuildEvent as D, type FarmPluginEvent as E, type FarmAgentIdentity as F, type FarmErrorEvent as G, type FarmEvent as H, type FarmEventType as I, type FarmEventHandler as J, type FarmEventInput as K, type FarmObservabilityUserConfig as L, type FarmResolvedObservabilityConfig as M, type FarmEventSubscriptionOptions as N, normalizeFarmObservabilityConfig as O, onFarmEvent as P, resetFarmObservability as Q, classifyFarmAgent as a, configureFarmTracing as b, configureFarmObservability as c, runWithFarmSpan as d, emitFarmEvent as e, type FarmRequestSpanOptions as f, getFarmTraceContext as g, type FarmResolvedTracingConfig as h, type FarmSpanOptions as i, type FarmTraceContext as j, type FarmTraceSpanKind as k, type FarmTracingConfig as l, type FarmTracingUserConfig as m, normalizeFarmTracingConfig as n, type FarmEventLevel as o, type FarmEventBase as p, type FarmRequestEvent as q, runWithFarmRequestSpan as r, type FarmServerEvent as s, type FarmRouteEvent as t, type FarmRenderEvent as u, type FarmCacheEvent as v, type FarmPPREvent as w, type FarmAPIEvent as x, type FarmIntegrationEvent as y, type FarmMCPEvent as z };