silgi 0.0.14 → 0.1.0-beta.10

package/dist/plugins/analytics.d.mts

@@ -0,0 +1,236 @@
+import { FetchHandler } from "../core/handler.mjs";
+
+//#region src/plugins/analytics.d.ts
+/**
+ * Built-in analytics plugin — zero-dependency monitoring with deep error tracing.
+ *
+ * - Per-procedure metrics (count, errors, latency percentiles) via ring buffers
+ * - Full error log with input, headers, stack trace, custom spans
+ * - `trace()` helper for measuring DB queries, API calls, etc.
+ * - "Copy for AI" — one-click markdown export of any error
+ * - HTTP-level request tracking with procedure grouping (batch support)
+ * - Unique request IDs via `x-request-id` response header
+ *
+ * Dashboard at /analytics, JSON API at /analytics/api, errors at /analytics/errors.
+ */
+interface TimeWindow {
+  time: number;
+  count: number;
+  errors: number;
+}
+type SpanKind = 'db' | 'http' | 'cache' | 'queue' | 'email' | 'ai' | 'custom';
+interface TraceSpan {
+  name: string;
+  kind: SpanKind;
+  durationMs: number;
+  startOffsetMs?: number;
+  detail?: string;
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+  /** Structured key-value attributes (db.name, auth.operation, user.id, etc.) */
+  attributes?: Record<string, string | number | boolean>;
+}
+interface ErrorEntry {
+  id: number;
+  /** Links back to the RequestEntry that produced this error. */
+  requestId: string;
+  timestamp: number;
+  procedure: string;
+  error: string;
+  code: string;
+  status: number;
+  stack: string;
+  input: unknown;
+  headers: Record<string, string>;
+  durationMs: number;
+  spans: TraceSpan[];
+}
+/** A single procedure call within an HTTP request. */
+interface ProcedureCall {
+  procedure: string;
+  durationMs: number;
+  status: number;
+  input: unknown;
+  output: unknown;
+  spans: TraceSpan[];
+  error?: string;
+}
+/** An HTTP request containing one or more procedure calls. */
+interface RequestEntry {
+  id: number;
+  /** Unique request ID (returned in x-request-id response header). */
+  requestId: string;
+  /** Persistent session ID (from cookie — survives browser restart). */
+  sessionId: string;
+  timestamp: number;
+  durationMs: number;
+  method: string;
+  path: string;
+  ip: string;
+  headers: Record<string, string>;
+  responseHeaders: Record<string, string>;
+  userAgent: string;
+  status: number;
+  procedures: ProcedureCall[];
+  isBatch: boolean;
+}
+/** A background task execution record. */
+interface TaskExecution {
+  id: number;
+  taskName: string;
+  trigger: 'dispatch' | 'cron' | 'http';
+  timestamp: number;
+  durationMs: number;
+  status: 'success' | 'error';
+  error?: string;
+  input?: unknown;
+  output?: unknown;
+  spans: TraceSpan[];
+}
+interface AnalyticsOptions {
+  /** Latency samples to keep per procedure (default: 1024) */
+  bufferSize?: number;
+  /** Time-series history in seconds (default: 120) */
+  historySeconds?: number;
+  /** Max error entries to keep (default: 100) */
+  maxErrors?: number;
+  /** Max recent request entries to keep (default: 200) */
+  maxRequests?: number;
+  /** Max task execution entries to keep (default: 200) */
+  maxTasks?: number;
+  /**
+   * Protect dashboard access.
+   * - `string` — secret token checked against `Authorization: Bearer <token>` header or `?token=` query param
+   * - `(req: Request) => boolean | Promise<boolean>` — custom auth function
+   * - `undefined` — no auth (open access, NOT recommended in production)
+   */
+  auth?: string | ((req: Request) => boolean | Promise<boolean>);
+  /** Interval in ms between storage flushes (default: 5000) */
+  flushInterval?: number;
+}
+interface ProcedureSnapshot {
+  count: number;
+  errors: number;
+  errorRate: number;
+  latency: {
+    avg: number;
+    p50: number;
+    p95: number;
+    p99: number;
+  };
+  lastError: string | null;
+  lastErrorTime: number | null;
+}
+interface TaskSnapshot {
+  totalRuns: number;
+  totalErrors: number;
+  tasks: Record<string, {
+    runs: number;
+    errors: number;
+    avgDurationMs: number;
+    lastRun: number | null;
+  }>;
+}
+interface AnalyticsSnapshot {
+  uptime: number;
+  totalRequests: number;
+  totalErrors: number;
+  errorRate: number;
+  requestsPerSecond: number;
+  avgLatency: number;
+  procedures: Record<string, ProcedureSnapshot>;
+  timeSeries: TimeWindow[];
+  tasks: TaskSnapshot;
+}
+declare class RequestTrace {
+  spans: TraceSpan[];
+  /** Procedure-level input — set via `setProcedureInput()` or `trace(..., { procedure: { input } })` */
+  procedureInput: unknown;
+  /** Procedure-level output — set via `setProcedureOutput()` or `trace(..., { procedure: { output } })` */
+  procedureOutput: unknown;
+  /** @internal Start time — used by integrations (drizzle etc.) for span offset calculation */
+  readonly t0: number;
+  trace<T>(name: string, fn: () => T | Promise<T>, opts?: {
+    kind?: SpanKind;
+    detail?: string;
+    input?: unknown;
+    output?: unknown | ((result: T) => unknown);
+    procedure?: {
+      input?: unknown;
+      output?: unknown | ((result: T) => unknown);
+    };
+  }): Promise<T>;
+  totalByKind(kind: SpanKind): number;
+}
+/**
+ * Standalone trace function — works with or without analytics.
+ *
+ * ```ts
+ * import { trace } from 'silgi/analytics'
+ *
+ * const listUsers = s.$resolve(async ({ ctx }) => {
+ *   return await trace(ctx, 'db.users.findMany', () => db.users.findMany())
+ *   // or with explicit kind:
+ *   return await trace(ctx, 'findUsers', () => db.users.findMany(), { kind: 'db', detail: 'SELECT * FROM users' })
+ * })
+ * ```
+ */
+declare function trace<T>(ctx: Record<string, unknown>, name: string, fn: () => T | Promise<T>, opts?: {
+  kind?: SpanKind;
+  detail?: string;
+  input?: unknown;
+  output?: unknown | ((result: T) => unknown);
+  procedure?: {
+    input?: unknown;
+    output?: unknown | ((result: T) => unknown);
+  };
+}): Promise<T>;
+declare class AnalyticsCollector {
+  #private;
+  constructor(options?: AnalyticsOptions);
+  record(path: string, durationMs: number): void;
+  recordError(path: string, durationMs: number, errorMsg: string): void;
+  recordDetailedError(entry: Omit<ErrorEntry, 'id'>): void;
+  recordDetailedRequest(entry: Omit<RequestEntry, 'id'>): void;
+  recordTask(entry: Omit<TaskExecution, 'id'>): void;
+  getTaskExecutions(): Promise<TaskExecution[]>;
+  getErrors(): Promise<ErrorEntry[]>;
+  getRequests(): Promise<RequestEntry[]>;
+  dispose(): Promise<void>;
+  toJSON(): AnalyticsSnapshot;
+}
+declare class RequestAccumulator {
+  #private;
+  readonly requestId: string;
+  readonly sessionId: string;
+  /** True if a new session cookie needs to be set. */
+  readonly isNewSession: boolean;
+  t0: number;
+  constructor(request: Request, collector: AnalyticsCollector);
+  addProcedure(call: ProcedureCall): void;
+  /** Get Set-Cookie header value (only if new session). */
+  getSessionCookie(): string | null;
+  /** Flush with response headers extracted from the actual Response object. */
+  flushWithResponse(res: Response): void;
+  /** Whether any procedures have been recorded. */
+  get hasProcedures(): boolean;
+}
+declare function errorToMarkdown(e: ErrorEntry): string;
+declare function requestToMarkdown(r: RequestEntry): string;
+declare function analyticsHTML(): string;
+declare function checkAnalyticsAuth(request: Request, auth: string | ((req: Request) => boolean | Promise<boolean>)): boolean | Promise<boolean>;
+declare function sanitizeHeaders(headers: Headers): Record<string, string>;
+/** Return auth-failure response for analytics routes. */
+declare function analyticsAuthResponse(pathname: string): Response;
+/** Serve analytics dashboard and API routes. */
+declare function serveAnalyticsRoute(pathname: string, collector: AnalyticsCollector, dashboardHtml: string | undefined): Promise<Response>;
+/**
+ * Wrap a fetch handler with analytics collection.
+ * Intercepts analytics dashboard routes and instruments every request.
+ */
+declare function wrapWithAnalytics(handler: FetchHandler, options?: AnalyticsOptions): FetchHandler;
+/** WeakMap to pass analytics trace to context without coupling handler to analytics. */
+declare const analyticsTraceMap: WeakMap<Request, RequestTrace>;
+//#endregion
+export { AnalyticsCollector, AnalyticsOptions, AnalyticsSnapshot, ErrorEntry, ProcedureCall, ProcedureSnapshot, RequestAccumulator, RequestEntry, RequestTrace, SpanKind, TaskExecution, TaskSnapshot, TraceSpan, analyticsAuthResponse, analyticsHTML, analyticsTraceMap, checkAnalyticsAuth, errorToMarkdown, requestToMarkdown, sanitizeHeaders, serveAnalyticsRoute, trace, wrapWithAnalytics };