@aj-2000-test/goodlogs-sdk 0.1.20 → 0.3.0

package/dist/index.d.cts

@@ -1,102 +1,290 @@
-type Severity = "debug" | "info" | "warn" | "error" | "fatal";
-interface GoodLogsOptions {
-    /** API key (gl_sk_... for logs, gl_pk_... for events only) */
+import { G as GoodLogs } from './client-w3t1Yzjd.cjs';
+export { C as CaptureContext, E as ErrorBreadcrumb, a as ErrorEntry, b as ErrorFrame, c as EventEntry, d as GoodLogsOptions, L as LogEntry, S as Severity } from './client-w3t1Yzjd.cjs';
+
+interface LogRecord {
+    id: number;
+    severity: string;
+    message: string;
+    properties: Record<string, unknown>;
+    timestamp: string;
+}
+interface GqlResult {
+    query: string;
+    data: unknown[];
+    columns?: string[];
+    source?: string;
+    error?: string;
+}
+interface GqlBatchResult {
+    status: "ok" | "error";
+    query?: unknown;
+    data?: unknown;
+    error?: string;
+}
+interface GqlAutocompleteResult {
+    suggestions: string[];
+    valid: boolean;
+    error?: string;
+    parsed?: Record<string, unknown>;
+}
+interface Nl2GqlResult {
+    gql: string;
+    valid: boolean;
+    error?: string;
+    parsed?: Record<string, unknown>;
+}
+interface SchemaField {
+    name: string;
+    type: string;
+    count?: number;
+}
+interface SchemaResponse {
+    events: SchemaField[];
+    properties: SchemaField[];
+    log_properties: SchemaField[];
+    [key: string]: unknown;
+}
+interface AlertRule {
+    id: string;
+    project_id: string;
+    name: string;
+    metric: string;
+    alert_type: string;
+    status: string;
+    severity: string;
+    threshold: number;
+    window_minutes: number;
+    cooldown_minutes: number;
+    notify_email: boolean;
+    webhook_url?: string;
+    enabled: boolean;
+    pattern?: string;
+    change_percent?: number;
+    muted_until?: string;
+    message_template?: string;
+    notify_channels: NotifyChannel[];
+    last_triggered_at?: string;
+    last_value?: number;
+    anomaly_sigma?: number;
+    composite_rules: string[];
+    composite_operator?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface NotifyChannel {
+    type: string;
+    url?: string;
+    to?: string;
+    secret?: string;
+}
+interface CreateAlertRule {
+    name: string;
+    metric: string;
+    threshold: number;
+    window_minutes?: number;
+    notify_email?: boolean;
+    webhook_url?: string;
+    alert_type?: string;
+    pattern?: string;
+    change_percent?: number;
+    message_template?: string;
+    notify_channels?: NotifyChannel[];
+    severity?: string;
+    cooldown_minutes?: number;
+    anomaly_sigma?: number;
+    composite_rules?: string[];
+    composite_operator?: string;
+}
+interface UpdateAlertRule {
+    name?: string;
+    metric?: string;
+    threshold?: number;
+    window_minutes?: number;
+    notify_email?: boolean;
+    webhook_url?: string;
+    enabled?: boolean;
+    pattern?: string;
+    change_percent?: number;
+    message_template?: string;
+    notify_channels?: NotifyChannel[];
+    severity?: string;
+    cooldown_minutes?: number;
+    anomaly_sigma?: number;
+}
+interface MuteAlertRequest {
+    minutes: number;
+}
+interface SloDefinition {
+    id: string;
+    project_id: string;
+    name: string;
+    description?: string;
+    metric: string;
+    status: string;
+    target_percent: number;
+    threshold?: number;
+    window_days: number;
+    current_percent?: number;
+    budget_remaining?: number;
+    budget_burn_rate?: number;
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateSlo {
+    name: string;
+    description?: string;
+    metric?: string;
+    target_percent?: number;
+    threshold?: number;
+    window_days?: number;
+}
+interface UpdateSlo {
+    name?: string;
+    description?: string;
+    target_percent?: number;
+    threshold?: number;
+    window_days?: number;
+    enabled?: boolean;
+}
+interface AiChatRequest {
+    message: string;
+    session_id?: string;
+}
+interface AiChatResponse {
+    reply: string;
+    session_id: string;
+    tool_calls?: AiToolCall[];
+}
+interface AiToolCall {
+    tool: string;
+    input: Record<string, unknown>;
+    result: unknown;
+}
+interface ProjectInfo {
+    project: {
+        id: string;
+        name: string;
+        slug: string;
+        region: string;
+    };
+    org: {
+        id: string;
+        name: string;
+        plan: string;
+    };
+    usage?: Record<string, unknown>;
+    keys?: {
+        count: number;
+    };
+}
+interface GoodLogsClientOptions {
+    /** Secret API key (gl_sk_...) — required for all read/write operations */
     apiKey: string;
     /** API endpoint (default: auto-resolved from API key region) */
     endpoint?: string;
-    /** Flush interval in ms (default: 5000) */
-    flushInterval?: number;
-    /** Max batch size before auto-flush (default: 50) */
-    batchSize?: number;
-    /** Default context merged into every log/event */
-    defaultContext?: Record<string, unknown>;
-    /** Called on flush errors */
-    onError?: (error: Error) => void;
-    /** Disable SDK (useful for tests) */
-    disabled?: boolean;
-    /** Send SDK diagnostics to platform logs (default: true) */
-    telemetry?: boolean;
-    /** Auto-capture click events on elements with data-gl-event attribute (default: true in browser) */
-    autocapture?: boolean;
-}
-interface LogEntry {
-    severity: Severity;
-    message: string;
-    properties?: Record<string, unknown>;
-    timestamp?: string;
-}
-interface EventEntry {
-    event: string;
-    distinctId?: string;
-    properties?: Record<string, unknown>;
-    timestamp?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
 }
 
-declare class GoodLogs {
-    private apiKey;
-    private endpoint;
-    private flushInterval;
-    private batchSize;
-    private defaultContext;
-    private onError;
-    private disabled;
-    private telemetry;
-    private logBuffer;
-    private eventBuffer;
-    private timer;
-    private visibilityHandler;
-    private clickHandler;
-    private lastPath;
-    private anonymousId;
-    private sessionId;
-    constructor(options: GoodLogsOptions);
-    log(severity: Severity, message: string, properties?: Record<string, unknown>): void;
-    debug(message: string, properties?: Record<string, unknown>): void;
-    info(message: string, properties?: Record<string, unknown>): void;
-    warn(message: string, properties?: Record<string, unknown>): void;
-    error(message: string, properties?: Record<string, unknown>): void;
-    fatal(message: string, properties?: Record<string, unknown>): void;
-    /** Set the user ID for all subsequent events. Replaces the anonymous ID. */
-    identify(userId: string): void;
-    /** Get the current anonymous/user ID. */
-    getDistinctId(): string;
-    /** Reset identity — generates a new anonymous ID (e.g., on logout). */
-    reset(): void;
-    /** Get the current session ID. */
-    getSessionId(): string;
-    /** Start a new session (e.g., on navigation reset). */
-    newSession(): void;
-    /** Set a specific session ID. */
-    setSessionId(id: string): void;
-    track(event: string, properties?: Record<string, unknown> & {
-        distinctId?: string;
-    }): void;
-    flush(): Promise<void>;
-    /** Flush remaining data and stop the timer */
-    shutdown(): Promise<void>;
-    private sendLogs;
-    private sendEvents;
-    private postWithRetry;
-    private startTimer;
-    private stopTimer;
+/**
+ * GoodLogs programmatic API client.
+ *
+ * Provides typed access to all /v1 read & write endpoints:
+ * analytics, logs, GQL queries, alerts, SLOs, AI chat, and schema.
+ *
+ * Requires a **secret** API key (`gl_sk_...`) with appropriate scopes.
+ *
+ * ```ts
+ * import { GoodLogsClient } from "@aj-2000-test/goodlogs-sdk";
+ *
+ * const client = new GoodLogsClient({ apiKey: "gl_sk_us_..." });
+ *
+ * // Query logs
+ * const { logs, total } = await client.logs.list({ severity: "error", limit: 10 });
+ *
+ * // Run GQL query
+ * const result = await client.gql("count | where severity = 'error' | last 1h");
+ *
+ * // Manage alerts
+ * const alerts = await client.alerts.list();
+ * await client.alerts.create({ name: "High Errors", metric: "error_count", threshold: 100 });
+ * ```
+ */
+declare class GoodLogsClient {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly timeout;
+    /** Alert CRUD methods */
+    readonly alerts: AlertsApi;
+    /** SLO CRUD methods */
+    readonly slos: SlosApi;
+    /** AI chat methods */
+    readonly ai: AiApi;
+    constructor(options: GoodLogsClientOptions);
+    /** @internal */
+    _request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** @internal */
+    _get<T>(path: string): Promise<T>;
+    /** @internal */
+    _post<T>(path: string, body?: unknown): Promise<T>;
+    /** @internal */
+    _put<T>(path: string, body?: unknown): Promise<T>;
+    /** @internal */
+    _delete<T>(path: string): Promise<T>;
+    /** Get project info, org, usage, and key count */
+    info(): Promise<ProjectInfo>;
+    /** Get full schema (event names, property fields, log properties) */
+    schema(): Promise<SchemaResponse>;
+    /** Run a single GQL query */
+    gql(query: string): Promise<GqlResult>;
     /**
-     * In browsers: flush via fetch+keepalive when page goes hidden or closes.
-     * keepalive lets the request complete even after the page unloads,
-     * while still supporting custom headers (unlike sendBeacon).
+     * Run multiple GQL queries in a single request.
+     * Returns an array of results (same index as input).
+     * Each result has `status: "ok"` with `data`, or `status: "error"` with `error`.
      */
-    private attachPageLifecycle;
-    /** Auto-capture Core Web Vitals using PerformanceObserver */
-    private captureWebVitals;
-    /** Auto-capture page views on route changes (SPA-aware via History API) */
-    private attachPageviewCapture;
-    /** Auto-capture clicks on elements with text content or data-gl-event */
-    private attachClickCapture;
-    private detachClickCapture;
-    private detachPageLifecycle;
-    /** Fire-and-forget flush using fetch with keepalive — survives page unload */
-    private keepaliveFlush;
-    /** Fire-and-forget telemetry to platform logs. Never throws, never recurses. */
-    private sendTelemetry;
+    gqlBatch(queries: string[]): Promise<GqlBatchResult[]>;
+    /** Get GQL autocomplete suggestions */
+    gqlAutocomplete(query: string, cursor?: number): Promise<GqlAutocompleteResult>;
+    /** Convert natural language to GQL */
+    nl2gql(prompt: string, mode?: string): Promise<Nl2GqlResult>;
+}
+declare class AlertsApi {
+    private client;
+    constructor(client: GoodLogsClient);
+    /** List all alert rules */
+    list(): Promise<AlertRule[]>;
+    /** Create a new alert rule */
+    create(rule: CreateAlertRule): Promise<AlertRule>;
+    /** Update an alert rule */
+    update(alertId: string, rule: UpdateAlertRule): Promise<AlertRule>;
+    /** Delete an alert rule */
+    delete(alertId: string): Promise<void>;
+    /** Mute an alert for N minutes */
+    mute(alertId: string, minutes: number): Promise<void>;
+}
+declare class SlosApi {
+    private client;
+    constructor(client: GoodLogsClient);
+    /** List all SLO definitions */
+    list(): Promise<SloDefinition[]>;
+    /** Create a new SLO */
+    create(slo: CreateSlo): Promise<SloDefinition>;
+    /** Update an SLO */
+    update(sloId: string, slo: UpdateSlo): Promise<SloDefinition>;
+    /** Delete an SLO */
+    delete(sloId: string): Promise<void>;
+}
+declare class AiApi {
+    private client;
+    constructor(client: GoodLogsClient);
+    /** Send a message to AI chat */
+    chat(message: string, sessionId?: string): Promise<AiChatResponse>;
+}
+declare class GoodLogsApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
 }
 
 interface TelemetryEvent {
@@ -137,4 +325,154 @@ declare function resolveRegion(apiKey: string): string;
 /** Resolve API endpoint from key. User-provided endpoint always wins. */
 declare function resolveEndpoint(apiKey: string, userEndpoint?: string): string;
 
-export { type EventEntry, GoodLogs, type GoodLogsOptions, type LogEntry, REGION_URLS, type Severity, type TelemetryEvent, type TelemetryOptions, resolveEndpoint, resolveRegion, sendTelemetry };
+/**
+ * Node.js framework adapters for GoodLogs tracing.
+ *
+ * Each adapter accepts a GoodLogs client instance and returns a middleware /
+ * plugin / interceptor that starts a span per incoming request and finishes
+ * it when the response is sent. Adapters are structurally typed — we don't
+ * depend on express / fastify / @nestjs/common at runtime.
+ *
+ * All adapters honour W3C traceparent in incoming headers so multi-service
+ * traces stitch together.
+ */
+
+/** A subset of Express's req/res shape we actually touch. */
+interface ExpressReq {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    route?: {
+        path?: string;
+    };
+    headers?: Record<string, string | string[] | undefined>;
+}
+interface ExpressRes {
+    statusCode?: number;
+    on(event: "finish" | "close", cb: () => void): void;
+}
+type ExpressNext = (err?: unknown) => void;
+/** A subset of Fastify's request/reply shape. */
+interface FastifyRequest {
+    method?: string;
+    url?: string;
+    routerPath?: string;
+    routeOptions?: {
+        url?: string;
+    };
+    headers?: Record<string, string | string[] | undefined>;
+}
+interface FastifyReply {
+    statusCode?: number;
+    raw?: {
+        statusCode?: number;
+    };
+}
+interface FastifyInstance {
+    addHook(name: "onRequest", fn: (req: FastifyRequest, reply: FastifyReply, done: () => void) => void): void;
+    addHook(name: "onResponse", fn: (req: FastifyRequest, reply: FastifyReply, done: () => void) => void): void;
+}
+/** Parse a W3C traceparent header: 00-<trace 32>-<parent 16>-<flags 2>. */
+declare function parseTraceparent(h: string | undefined | null): {
+    trace_id: string;
+    parent_span_id: string;
+} | null;
+/**
+ * Express / Connect / Restify-compatible middleware.
+ *
+ * Usage:
+ *   import express from "express";
+ *   import { goodlogsExpress, GoodLogs } from "@goodlogs/sdk";
+ *   const gl = new GoodLogs({ apiKey: "...", useEnvelope: true });
+ *   const app = express();
+ *   app.use(goodlogsExpress(gl));
+ */
+declare function goodlogsExpress(gl: GoodLogs): (req: ExpressReq, res: ExpressRes, next: ExpressNext) => void;
+/**
+ * Fastify plugin. Registers onRequest + onResponse hooks.
+ *
+ * Usage:
+ *   import Fastify from "fastify";
+ *   import { goodlogsFastify, GoodLogs } from "@goodlogs/sdk";
+ *   const gl = new GoodLogs({ apiKey: "...", useEnvelope: true });
+ *   const app = Fastify();
+ *   app.register(goodlogsFastify(gl));
+ */
+declare function goodlogsFastify(gl: GoodLogs): (fastify: FastifyInstance, _opts: unknown, done: () => void) => void;
+/**
+ * NestJS interceptor.
+ *
+ * Usage:
+ *   import { Module } from "@nestjs/common";
+ *   import { goodlogsNestInterceptor, GoodLogs } from "@goodlogs/sdk";
+ *   const gl = new GoodLogs({ apiKey: "...", useEnvelope: true });
+ *   @Module({
+ *     providers: [{ provide: APP_INTERCEPTOR, useValue: goodlogsNestInterceptor(gl) }],
+ *   })
+ *   export class AppModule {}
+ *
+ * The returned value is shaped like a NestInterceptor (`intercept(ctx, next)`).
+ * `next.handle()` must return a stream-like with `pipe()` — we use a small
+ * adapter so we don't depend on rxjs.
+ */
+interface NestExecutionContext {
+    switchToHttp(): {
+        getRequest(): ExpressReq;
+        getResponse(): ExpressRes;
+    };
+}
+interface NestCallHandler {
+    handle(): {
+        subscribe?(observer: {
+            next?: (v: unknown) => void;
+            error?: (e: unknown) => void;
+            complete?: () => void;
+        }): {
+            unsubscribe?: () => void;
+        };
+        pipe?(...args: unknown[]): unknown;
+    };
+}
+declare function goodlogsNestInterceptor(gl: GoodLogs): {
+    intercept(ctx: NestExecutionContext, next: NestCallHandler): {
+        subscribe?(observer: {
+            next?: (v: unknown) => void;
+            error?: (e: unknown) => void;
+            complete?: () => void;
+        }): {
+            unsubscribe?: () => void;
+        };
+        pipe?(...args: unknown[]): unknown;
+    } | {
+        unsubscribe: () => void | undefined;
+    };
+};
+/** Hook process.on("uncaughtException") and ("unhandledRejection") so
+ *  uncaught failures become captureException entries before the process
+ *  exits. Idempotent via a Symbol.for marker.
+ *
+ *  Important: uncaughtException is, by design, *terminal*. Node will exit
+ *  after our handler returns unless someone else also subscribed. We flush
+ *  synchronously on a best-effort basis (gl.flush returns a Promise — we
+ *  schedule a microtask via setImmediate to give the envelope POST a chance
+ *  to land before Node tears down). */
+declare function instrumentNodeProcess(gl: GoodLogs): void;
+
+/**
+ * Patch Node's built-in `http` and `https` modules so every outgoing request
+ * becomes an `op:http.client` span and injects W3C traceparent. Mirrors what
+ * the browser SDK does for `fetch` automatically.
+ *
+ * Usage:
+ *   import { instrumentNodeHttp, GoodLogs } from "@goodlogs/sdk";
+ *   const gl = new GoodLogs({ apiKey: "...", useEnvelope: true });
+ *   instrumentNodeHttp(gl);  // call once on startup
+ *
+ * Idempotent: calling twice is a no-op.
+ */
+
+declare function instrumentNodeHttp(gl: GoodLogs, opts?: {
+    endpoint?: string;
+}): void;
+
+export { type AiChatRequest, type AiChatResponse, type AiToolCall, type AlertRule, type CreateAlertRule, type CreateSlo, GoodLogs, GoodLogsApiError, GoodLogsClient, type GoodLogsClientOptions, type GqlAutocompleteResult, type GqlBatchResult, type GqlResult, type LogRecord, type MuteAlertRequest, type Nl2GqlResult, type NotifyChannel, type ProjectInfo, REGION_URLS, type SchemaField, type SchemaResponse, type SloDefinition, type TelemetryEvent, type TelemetryOptions, type UpdateAlertRule, type UpdateSlo, goodlogsExpress, goodlogsFastify, goodlogsNestInterceptor, instrumentNodeHttp, instrumentNodeProcess, parseTraceparent, resolveEndpoint, resolveRegion, sendTelemetry };