@koderlabs/tasks-sdk-nestjs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+import { NestModule, DynamicModule, MiddlewareConsumer, OnModuleInit, OnModuleDestroy, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler, NestMiddleware } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { AsyncLocalStorage } from 'async_hooks';
+
+interface Breadcrumb {
+    ts: string;
+    category: 'http' | 'console' | 'db' | 'span' | 'custom';
+    level?: 'debug' | 'info' | 'warning' | 'error';
+    message: string;
+    data?: Record<string, unknown>;
+}
+interface RequestInfo {
+    method?: string;
+    route?: string;
+    url?: string;
+    userAgent?: string;
+    ip?: string;
+    userId?: string;
+    statusCode?: number;
+}
+interface SpanRecord {
+    name: string;
+    startTime: string;
+    endTime: string;
+    durationMs: number;
+    status: 'ok' | 'error';
+    attrs?: Record<string, unknown>;
+}
+interface InstantTasksOptions {
+    apiUrl: string;
+    projectId: string;
+    managementKey: string;
+    environment?: string;
+    release?: string;
+    beforeSend?: (event: OutgoingEvent) => OutgoingEvent | null;
+    dryRun?: boolean;
+    debug?: boolean;
+    /** Capture per-request breadcrumb ring + request context middleware. Default false. */
+    captureRequestContext?: boolean;
+    /** Patch globalThis.fetch + http/https.request to record outbound HTTP as breadcrumbs. Default false. */
+    captureHttp?: boolean;
+    /** Patch console.{log,warn,error} to add breadcrumbs (output preserved). Default false. */
+    captureConsole?: boolean;
+    /** Wrap each controller method call in a span; attach span list to error events. Default false. */
+    captureSpans?: boolean;
+    /** Enable TypeORM query tracing — requires `dataSource` ref. Default false. */
+    captureTypeOrm?: boolean;
+    /** TypeORM DataSource reference (required when captureTypeOrm:true). */
+    dataSource?: any;
+    /** URL patterns to ignore for HTTP tracing (own ingest is ignored automatically). */
+    ignoreUrls?: Array<string | RegExp>;
+    /** Max breadcrumbs to keep per request. Default 50. */
+    maxBreadcrumbs?: number;
+}
+interface OutgoingEvent {
+    kind: 'error';
+    ts: string;
+    release: string;
+    environment: string;
+    url: string;
+    userAgent: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    payload: {
+        exception: {
+            type: string;
+            value: string;
+            stack?: string;
+            mechanism: 'uncaughtException' | 'unhandledrejection' | 'http' | 'notify';
+        };
+        level: 'fatal' | 'error' | 'warning';
+    };
+    user?: {
+        id?: string;
+        email?: string;
+    };
+    request?: RequestInfo;
+    breadcrumbs?: Breadcrumb[];
+    spans?: SpanRecord[];
+}
+declare const INSTANTTASKS_OPTIONS: unique symbol;
+
+declare class InstantTasksModule implements NestModule {
+    private readonly opts;
+    static forRoot(options: InstantTasksOptions): DynamicModule;
+    static forRootAsync(opts: {
+        imports?: any[];
+        inject?: any[];
+        useFactory: (...args: any[]) => InstantTasksOptions | Promise<InstantTasksOptions>;
+    }): DynamicModule;
+    private static build;
+    constructor(opts: InstantTasksOptions);
+    configure(consumer: MiddlewareConsumer): void;
+}
+
+declare class InstantTasksReporter implements OnModuleInit, OnModuleDestroy {
+    private readonly opts;
+    private readonly logger;
+    private apiUrl;
+    private projectId;
+    private managementKey;
+    private environment;
+    private release;
+    private debug;
+    private dryRun;
+    private beforeSend?;
+    private recent;
+    private readonly RECENT_WINDOW_MS;
+    private readonly RECENT_LIMIT;
+    private uncaughtHandler;
+    private rejectionHandler;
+    constructor(opts: InstantTasksOptions);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    get enabled(): boolean;
+    reportError(err: Error, ctx: {
+        mechanism: 'uncaughtException' | 'unhandledrejection' | 'http' | 'notify';
+        level?: 'fatal' | 'error' | 'warning';
+        url?: string;
+        userId?: string;
+    }): void;
+    private shouldSuppress;
+}
+
+/**
+ * Reports 5xx (or non-HttpException) crashes to InstantTasks then re-throws.
+ *
+ * IMPORTANT: a NestJS ExceptionFilter is the final stop for an exception —
+ * filters do NOT cascade. Re-throwing here means the exception escapes the
+ * filter chain and falls through to Nest's default error handler, BYPASSING
+ * any other `APP_FILTER` the host app has registered (e.g. an
+ * `AllExceptionsFilter` that formats the response envelope).
+ *
+ * Two recommended deployments:
+ *
+ *  1. **Prefer the Interceptor.** Wire `InstantTasksReportInterceptor`
+ *     instead (see `report.interceptor.ts`). Interceptors compose with
+ *     `catchError(rxjs)` — they observe the error, report it, and re-throw;
+ *     the host's existing exception filter still runs and formats the
+ *     response correctly.
+ *
+ *  2. **If you must use this filter**, it must be the ONLY filter you
+ *     register, OR your `AllExceptionsFilter` must extend it. The current
+ *     re-throw is left in place for backwards compatibility, but the
+ *     response is no longer guaranteed to match the host's envelope.
+ *
+ * @deprecated Use `InstantTasksReportInterceptor` instead. This class will
+ *             be removed in a future major release.
+ */
+declare class InstantTasksExceptionFilter implements ExceptionFilter {
+    private readonly reporter;
+    private readonly logger;
+    constructor(reporter: InstantTasksReporter);
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
+
+/**
+ * Observes errors flowing through the HTTP pipeline, reports 5xx (or
+ * non-HttpException) to InstantTasks, then re-throws so the host's exception
+ * filter chain runs unmodified. Unlike a NestJS `ExceptionFilter`, an
+ * interceptor's re-throw propagates correctly to all downstream filters —
+ * this is the recommended way to integrate InstantTasks reporting in a
+ * NestJS app that already has an `AllExceptionsFilter` that formats the
+ * response envelope.
+ *
+ * Wire with:
+ *   { provide: APP_INTERCEPTOR, useClass: InstantTasksReportInterceptor }
+ */
+declare class InstantTasksReportInterceptor implements NestInterceptor {
+    private readonly reporter;
+    private readonly logger;
+    constructor(reporter: InstantTasksReporter);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+declare class InstantTasksRequestContextMiddleware implements NestMiddleware {
+    private readonly max;
+    constructor(opts: InstantTasksOptions);
+    use(req: any, res: any, next: (err?: unknown) => void): void;
+}
+
+/**
+ * Wraps every HTTP-bound controller method call in a span. Spans are
+ * recorded into the current request's ALS ring (capped at `maxBreadcrumbs`)
+ * and attached to any error event emitted for that request.
+ *
+ * Mirrors the core SDK's `client.startSpan({ name: 'http.<method>.<route>' })`
+ * semantics — same name shape, same attr keys — but persists in-band
+ * with the request context. Out-of-band export to a span endpoint can be
+ * added later without changing this interface.
+ */
+declare class InstantTasksSpanInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+/**
+ * Per-request context captured at the start of each HTTP request and
+ * made available to any downstream code via AsyncLocalStorage. The ring is
+ * bounded — once `max` breadcrumbs are added, oldest are evicted.
+ *
+ * Concurrency: AsyncLocalStorage isolates contexts across concurrent async
+ * tasks. Two requests being processed simultaneously each see their own
+ * ring; one cannot read or evict the other's breadcrumbs.
+ *
+ * Caveats: callbacks that escape the request scope (timers scheduled
+ * before the request, queues processed elsewhere) will NOT inherit the
+ * context unless wrapped with `als.run()` at the boundary. Bull/BullMQ
+ * processors run outside the HTTP context — leaveBreadcrumb() inside them
+ * is a no-op.
+ */
+declare class RequestContextRing {
+    private readonly buf;
+    private readonly spans;
+    request: RequestInfo;
+    private readonly max;
+    constructor(request: RequestInfo, max?: number);
+    add(crumb: Breadcrumb): void;
+    addSpan(span: SpanRecord): void;
+    getBreadcrumbs(): Breadcrumb[];
+    getSpans(): SpanRecord[];
+    setUser(userId: string): void;
+}
+/**
+ * Module-level storage — single instance per process, shared by every
+ * file that imports it (the standard ALS pattern).
+ */
+declare const requestContextStorage: AsyncLocalStorage<RequestContextRing>;
+/**
+ * Add a breadcrumb to the current request's ring. No-op outside an
+ * ALS-scoped request.
+ */
+declare function leaveBreadcrumb(crumb: Omit<Breadcrumb, 'ts'> & {
+    ts?: string;
+}): void;
+/** Returns the current ring or null when outside an ALS scope. */
+declare function getCurrentContext(): RequestContextRing | null;
+
+interface HttpTracingOptions {
+    ignoreUrls?: Array<string | RegExp>;
+}
+/**
+ * Patch global `fetch` AND Node's `http.request` / `https.request` to emit
+ * an `http` breadcrumb on completion. Idempotent via wrap-sentinel.
+ *
+ * Honors `ignoreUrls` — InstantTasks' own ingest endpoint should be added
+ * by the caller (module.ts injects it automatically) to avoid recursion.
+ */
+declare function installHttpTracing(opts?: HttpTracingOptions): {
+    restore: () => void;
+};
+
+/**
+ * Patch console.{log,warn,error} to emit breadcrumbs. The original
+ * console method is always invoked, so stdout/stderr output is preserved.
+ *
+ * Skips messages that look like NestJS Logger output — those already
+ * surface in your logging stack and re-capturing them risks recursion.
+ */
+declare function installConsoleCapture(): {
+    restore: () => void;
+};
+
+declare class InstantTasksTypeOrmLogger {
+    private readonly slowQueryMs;
+    constructor(slowQueryMs?: number);
+    private emit;
+    logQuery(sql: string): void;
+    logQueryError(error: string | Error, sql: string): void;
+    logQuerySlow(time: number, sql: string): void;
+    logSchemaBuild(): void;
+    logMigration(): void;
+    log(): void;
+}
+/**
+ * Install the logger on a TypeORM DataSource. Safe to call multiple times
+ * — TypeORM accepts logger replacement on every `setOptions()` call, and
+ * we always install the same instance once installed.
+ */
+declare function installTypeOrmTracing(dataSource: any): InstantTasksTypeOrmLogger | null;
+
+export { type Breadcrumb, INSTANTTASKS_OPTIONS, InstantTasksExceptionFilter, InstantTasksModule, type InstantTasksOptions, InstantTasksReportInterceptor, InstantTasksReporter, InstantTasksRequestContextMiddleware, InstantTasksSpanInterceptor, InstantTasksTypeOrmLogger, type OutgoingEvent, RequestContextRing, type RequestInfo, type SpanRecord, getCurrentContext, installConsoleCapture, installHttpTracing, installTypeOrmTracing, leaveBreadcrumb, requestContextStorage };