devlogs-node 2.2.7

package/dist/build-info.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Build info helper for devlogs node client.
+ *
+ * Provides a stable build identifier that applications can use to tag
+ * every log entry without requiring git at runtime.
+ */
+/**
+ * Source of the build info.
+ */
+export type BuildInfoSource = 'file' | 'env' | 'generated';
+/**
+ * Build information resolved from file, environment, or generated.
+ */
+export interface BuildInfo {
+    /** Unique build identifier (always non-empty). */
+    buildId: string;
+    /** Git branch name, if available. */
+    branch: string | null;
+    /** UTC timestamp in format YYYYMMDDTHHMMSSZ. */
+    timestampUtc: string;
+    /** Source of the build info. */
+    source: BuildInfoSource;
+    /** File path used for build info, if any. */
+    path: string | null;
+}
+/**
+ * Build info file format (JSON).
+ */
+export interface BuildInfoFile {
+    build_id?: string;
+    branch?: string;
+    timestamp_utc?: string;
+    [key: string]: unknown;
+}
+/**
+ * Options for resolving build info.
+ */
+export interface BuildInfoOptions {
+    /** Explicit build info data (e.g., injected at build time). */
+    data?: BuildInfoFile;
+    /** Environment variable prefix (default: "DEVLOGS_"). */
+    envPrefix?: string;
+    /** Custom function to get current time (for testing). */
+    nowFn?: () => Date;
+    /** Environment variables to use. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Format a Date as compact ISO-like UTC timestamp: YYYYMMDDTHHMMSSZ.
+ */
+export declare function formatTimestamp(date: Date): string;
+/**
+ * Resolve build information from data, environment, or generate it.
+ *
+ * Priority order:
+ * 1. Environment variable BUILD_ID (highest precedence)
+ * 2. Provided build info data (from file)
+ * 3. Environment variables for branch/timestamp
+ * 4. Generated values
+ */
+export declare function resolveBuildInfo(options?: BuildInfoOptions): BuildInfo;
+/**
+ * Convenience function that returns only the build_id string.
+ */
+export declare function resolveBuildId(options?: BuildInfoOptions): string;
+/**
+ * Create build info data object for writing to .build.json during build.
+ */
+export declare function createBuildInfoData(options?: {
+    branch?: string;
+    nowFn?: () => Date;
+}): BuildInfoFile;

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Time-based circuit breaker with auto-recovery.
+ *
+ * Port of the Go SDK circuit breaker pattern:
+ * - Opens on failure, pauses indexing for `duration` (default 60s)
+ * - Auto-resets after duration expires (time-based)
+ * - Closes immediately on explicit success (RecordSuccess)
+ * - Throttles error output to once per `errorInterval` (default 10s)
+ */
+export declare class CircuitBreaker {
+    private isOpen;
+    private openUntil;
+    private lastErrorPrinted;
+    private readonly duration;
+    private readonly errorInterval;
+    private readonly stderr;
+    /**
+     * @param duration - How long to keep circuit open in ms (default: 60000)
+     * @param errorInterval - Min interval between error prints in ms (default: 10000)
+     * @param stderr - Output function for error messages (default: process.stderr.write)
+     */
+    constructor(duration?: number, errorInterval?: number, stderr?: (msg: string) => void);
+    /**
+     * Check if the circuit breaker is open (should skip indexing).
+     * Auto-resets if duration has expired.
+     */
+    shouldSkip(): boolean;
+    /**
+     * Record a failure - opens the circuit breaker.
+     */
+    recordFailure(err: unknown): void;
+    /**
+     * Record a success - closes the circuit breaker.
+     */
+    recordSuccess(): void;
+}

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import type { DevlogsConfig, LogDocument } from './types';
+import { CircuitBreaker } from './circuit-breaker';
+/**
+ * Dual-mode HTTP client for sending log documents.
+ *
+ * - OpenSearch mode: POST to /{index}/_doc with Basic auth
+ * - Collector mode: POST to / with optional Bearer token
+ * - Fire-and-forget: does not await response
+ * - Circuit breaker: stops sending on failures, auto-recovers
+ */
+export declare class DevlogsClient {
+    private readonly config;
+    private readonly cb;
+    constructor(config: DevlogsConfig, cb?: CircuitBreaker);
+    /**
+     * Send a log document. Fire-and-forget - does not block.
+     */
+    send(doc: LogDocument): void;
+}

package/dist/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parsed environment config from DEVLOGS_* vars and .env.devlogs files.
+ */
+export interface EnvConfig {
+    url?: string;
+    index?: string;
+    application?: string;
+    component?: string;
+    area?: string;
+    environment?: string;
+    version?: string;
+}
+/**
+ * Load environment variables from .env.devlogs (preferred) or .env file.
+ * Only sets variables that are not already defined in process.env.
+ * Called once automatically on first config load.
+ */
+export declare function loadDotenv(): void;
+/**
+ * Reset the loaded state (for testing).
+ */
+export declare function resetDotenvLoaded(): void;
+/**
+ * Load configuration from DEVLOGS_* environment variables.
+ * Automatically loads .env.devlogs on first call.
+ */
+export declare function loadEnvConfig(): EnvConfig;

package/dist/context.d.ts

@@ -0,0 +1,37 @@
+import type { LogContext } from './types';
+/**
+ * Set the default context values (called during init).
+ */
+export declare function setDefaultContext(ctx: Partial<LogContext>): void;
+/**
+ * Get the current logging context.
+ * Returns the AsyncLocalStorage context if inside withContext/withOperation,
+ * otherwise returns the default (module-level) context.
+ */
+export declare function getContext(): LogContext;
+/**
+ * Set the application area in the current context.
+ */
+export declare function setArea(area: string | null): void;
+/**
+ * Set the operation ID in the current context.
+ */
+export declare function setOperationId(operationId: string | null): void;
+/**
+ * Set custom fields in the current context.
+ */
+export declare function setFields(fields: Record<string, unknown>): void;
+/**
+ * Run a function with a temporary operation ID in an isolated async context.
+ * The operation ID is automatically scoped to the callback and its async children.
+ */
+export declare function withOperation<T>(operationId: string, fn: () => T): T;
+/**
+ * Run a function with a fully isolated async context.
+ * Changes made inside the callback don't affect the parent context.
+ */
+export declare function withContext<T>(overrides: Partial<LogContext>, fn: () => T): T;
+/**
+ * Reset the default context (for testing/destroy).
+ */
+export declare function resetContext(): void;