@devminister/applog-client 0.0.1

package/README.md

@@ -0,0 +1,214 @@
+# @devminister/applog-client
+
+Application log client for the **Monitoring** platform. Send structured business logs (auth, payments, orders, notifications) with buffered, batched delivery, retry, and duration tracking.
+
+Works as a **standalone Node.js client** or as a **NestJS module**.
+
+## Install
+
+```bash
+pnpm add @devminister/applog-client
+```
+
+## Quick Start
+
+### Standalone (Express, Fastify, any Node.js app)
+
+```typescript
+import { createAppLogClient } from '@devminister/applog-client';
+
+const appLog = createAppLogClient({
+  apiUrl: 'https://monitor.example.com',
+  clientId: process.env.MONITOR_CLIENT_ID!,
+  clientSecret: process.env.MONITOR_CLIENT_SECRET!,
+});
+
+// Simple logging
+appLog.info('auth', 'user.login', {
+  message: 'User logged in',
+  userId: 'user-123',
+  metadata: { method: 'oauth', provider: 'google' },
+  tags: ['web'],
+});
+
+appLog.error('payment', 'charge.failed', {
+  message: 'Card declined',
+  userId: 'user-123',
+  metadata: { reason: 'insufficient_funds', amount: 99.99 },
+});
+
+// Duration tracking
+const end = appLog.startTimer('payment', 'payment.charge');
+await processPayment(order);
+end({ userId: order.userId, metadata: { orderId: order.id } });
+
+// Shutdown (flushes remaining buffer)
+process.on('SIGTERM', async () => {
+  await appLog.shutdown();
+  process.exit(0);
+});
+```
+
+### NestJS Module
+
+```typescript
+// app.module.ts
+import { AppLogModule } from '@devminister/applog-client';
+
+@Module({
+  imports: [
+    AppLogModule.register({
+      apiUrl: process.env.MONITOR_API_URL,
+      clientId: process.env.APPLOG_CLIENT_ID,
+      clientSecret: process.env.APPLOG_CLIENT_SECRET,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### With ConfigService (async)
+
+```typescript
+AppLogModule.registerAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    apiUrl: config.get('MONITOR_API_URL'),
+    clientId: config.get('APPLOG_CLIENT_ID'),
+    clientSecret: config.get('APPLOG_CLIENT_SECRET'),
+    defaultCategory: 'my-service',
+    defaultTags: ['production'],
+  }),
+})
+```
+
+#### Inject and use in services
+
+```typescript
+import { AppLogNestService } from '@devminister/applog-client';
+
+@Injectable()
+export class PaymentService {
+  constructor(private readonly appLog: AppLogNestService) {}
+
+  async charge(order: Order) {
+    const end = this.appLog.startTimer('payment', 'payment.charge', {
+      userId: order.userId,
+    });
+
+    try {
+      const result = await this.stripe.charge(order);
+      end({ message: `Charged $${order.total}`, metadata: { orderId: order.id } });
+      return result;
+    } catch (err) {
+      this.appLog.error('payment', 'payment.charge.failed', {
+        message: err.message,
+        userId: order.userId,
+        metadata: { orderId: order.id, error: err.message },
+      });
+      throw err;
+    }
+  }
+}
+```
+
+#### Auto-log all HTTP requests (interceptor)
+
+```typescript
+import { AppLogInterceptor } from '@devminister/applog-client';
+
+// app.module.ts
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: AppLogInterceptor,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+This will automatically log every request with controller name, handler, method, path, status code, duration, and userId.
+
+## API
+
+### Log Methods
+
+```typescript
+appLog.debug(category, action, options?)
+appLog.info(category, action, options?)
+appLog.warn(category, action, options?)
+appLog.error(category, action, options?)
+appLog.fatal(category, action, options?)
+```
+
+### Options
+
+| Field      | Type     | Description                              |
+|------------|----------|------------------------------------------|
+| `message`  | string   | Human-readable log message               |
+| `metadata` | object   | Any structured data (JSON)               |
+| `userId`   | string   | User identifier                          |
+| `duration` | number   | Duration in milliseconds                 |
+| `tags`     | string[] | Searchable tags                          |
+
+### Timer
+
+```typescript
+const end = appLog.startTimer(category, action, options?);
+// ... do work ...
+end(extraOptions?); // logs with duration automatically
+```
+
+### Low-level
+
+```typescript
+appLog.push(payload)     // Push a raw AppLogPayload
+appLog.flush()           // Force flush buffer
+appLog.shutdown()        // Stop timer + flush
+appLog.bufferSize        // Current buffer length
+```
+
+## Configuration
+
+| Option             | Type     | Default | Description                                      |
+|--------------------|----------|---------|--------------------------------------------------|
+| `apiUrl`           | string   | —       | Monitoring API base URL (required)               |
+| `clientId`         | string   | —       | Environment client ID (required)                 |
+| `clientSecret`     | string   | —       | Environment client secret (required)             |
+| `batchSize`        | number   | `50`    | Auto-flush when buffer reaches this size         |
+| `flushInterval`    | number   | `5000`  | Flush interval in ms                             |
+| `maxBufferSize`    | number   | `1000`  | Max buffer size (oldest logs dropped when full)  |
+| `timeout`          | number   | `10000` | HTTP request timeout in ms                       |
+| `maxRetries`       | number   | `3`     | Retry attempts with exponential backoff          |
+| `defaultCategory`  | string   | —       | Default category when none specified             |
+| `defaultTags`      | string[] | `[]`    | Tags added to every log                          |
+| `disabled`         | boolean  | `false` | Disable all logging                              |
+| `logger`           | object   | console | Custom logger `{ debug, warn, error }`           |
+
+## Category & Action Conventions
+
+| Category       | Example Actions                                              |
+|----------------|--------------------------------------------------------------|
+| `auth`         | `user.login`, `user.logout`, `user.register`, `token.refresh` |
+| `payment`      | `payment.charge`, `payment.refund`, `subscription.create`     |
+| `order`        | `order.create`, `order.update`, `order.cancel`, `order.ship`  |
+| `notification` | `email.send`, `sms.send`, `push.send`                        |
+| `file`         | `file.upload`, `file.download`, `file.delete`                 |
+| `admin`        | `user.ban`, `config.update`, `data.export`                    |
+| `integration`  | `webhook.receive`, `api.call`, `sync.complete`                |
+
+## How It Works
+
+1. Logs are buffered in memory
+2. Buffer is flushed when it reaches `batchSize` or every `flushInterval` ms
+3. Logs are sent as a batch POST to `/api/app-logs/ingest` with Basic Auth
+4. On failure, retries with exponential backoff (200ms, 400ms, 800ms)
+5. Failed batches are re-added to the buffer if space is available
+6. Buffer has a hard cap (`maxBufferSize`) — oldest logs are dropped when full
+7. On shutdown, remaining buffer is flushed
+
+## License
+
+MIT

package/dist/applog-nestjs.service.d.ts

@@ -0,0 +1,11 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import { AppLogClientConfig } from './interfaces/applog-config.interface';
+import { AppLogClientService } from './applog.service';
+/**
+ * NestJS-managed AppLog service. Wraps AppLogClientService with
+ * NestJS lifecycle hooks and the NestJS Logger.
+ */
+export declare class AppLogNestService extends AppLogClientService implements OnModuleDestroy {
+    constructor(config: AppLogClientConfig);
+    onModuleDestroy(): Promise<void>;
+}

package/dist/applog-nestjs.service.js

@@ -0,0 +1,44 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppLogNestService = void 0;
+const common_1 = require("@nestjs/common");
+const applog_config_interface_1 = require("./interfaces/applog-config.interface");
+const applog_service_1 = require("./applog.service");
+/**
+ * NestJS-managed AppLog service. Wraps AppLogClientService with
+ * NestJS lifecycle hooks and the NestJS Logger.
+ */
+let AppLogNestService = class AppLogNestService extends applog_service_1.AppLogClientService {
+    constructor(config) {
+        const nestLogger = new common_1.Logger('AppLog');
+        super({
+            ...config,
+            logger: {
+                debug: (msg) => nestLogger.debug(msg),
+                warn: (msg) => nestLogger.warn(msg),
+                error: (msg) => nestLogger.error(msg),
+            },
+        });
+    }
+    async onModuleDestroy() {
+        await this.shutdown();
+    }
+};
+exports.AppLogNestService = AppLogNestService;
+exports.AppLogNestService = AppLogNestService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(applog_config_interface_1.APPLOG_CLIENT_CONFIG)),
+    __metadata("design:paramtypes", [Object])
+], AppLogNestService);

package/dist/applog.interceptor.d.ts

@@ -0,0 +1,24 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { AppLogNestService } from './applog-nestjs.service';
+/**
+ * NestJS interceptor that automatically logs every HTTP request as an app log.
+ *
+ * Captures: controller name, handler name, method, path, status, duration, userId.
+ * Errors are logged at level 'error', successful requests at 'info'.
+ *
+ * @example
+ * // Global interceptor
+ * app.useGlobalInterceptors(app.get(AppLogInterceptor));
+ *
+ * // Or via module providers
+ * { provide: APP_INTERCEPTOR, useClass: AppLogInterceptor }
+ *
+ * // Or per-controller
+ * @UseInterceptors(AppLogInterceptor)
+ */
+export declare class AppLogInterceptor implements NestInterceptor {
+    private readonly appLog;
+    constructor(appLog: AppLogNestService);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+}

package/dist/applog.interceptor.js

@@ -0,0 +1,80 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppLogInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+const applog_nestjs_service_1 = require("./applog-nestjs.service");
+/**
+ * NestJS interceptor that automatically logs every HTTP request as an app log.
+ *
+ * Captures: controller name, handler name, method, path, status, duration, userId.
+ * Errors are logged at level 'error', successful requests at 'info'.
+ *
+ * @example
+ * // Global interceptor
+ * app.useGlobalInterceptors(app.get(AppLogInterceptor));
+ *
+ * // Or via module providers
+ * { provide: APP_INTERCEPTOR, useClass: AppLogInterceptor }
+ *
+ * // Or per-controller
+ * @UseInterceptors(AppLogInterceptor)
+ */
+let AppLogInterceptor = class AppLogInterceptor {
+    constructor(appLog) {
+        this.appLog = appLog;
+    }
+    intercept(context, next) {
+        if (this.appLog.getConfig().disabled)
+            return next.handle();
+        const ctx = context.switchToHttp();
+        const request = ctx.getRequest();
+        const controller = context.getClass().name;
+        const handler = context.getHandler().name;
+        const start = Date.now();
+        const userId = request.user?.id || request.user?.sub || undefined;
+        return next.handle().pipe((0, operators_1.tap)(() => {
+            const response = ctx.getResponse();
+            this.appLog.info('api', `${controller}.${handler}`, {
+                userId,
+                duration: Date.now() - start,
+                metadata: {
+                    method: request.method,
+                    path: request.url,
+                    statusCode: response.statusCode,
+                },
+            });
+        }), (0, operators_1.catchError)((error) => {
+            const statusCode = error instanceof common_1.HttpException
+                ? error.getStatus()
+                : common_1.HttpStatus.INTERNAL_SERVER_ERROR;
+            this.appLog.error('api', `${controller}.${handler}`, {
+                message: error.message,
+                userId,
+                duration: Date.now() - start,
+                metadata: {
+                    method: request.method,
+                    path: request.url,
+                    statusCode,
+                    error: error.message,
+                },
+            });
+            return (0, rxjs_1.throwError)(() => error);
+        }));
+    }
+};
+exports.AppLogInterceptor = AppLogInterceptor;
+exports.AppLogInterceptor = AppLogInterceptor = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [applog_nestjs_service_1.AppLogNestService])
+], AppLogInterceptor);

package/dist/applog.module.d.ts

@@ -0,0 +1,33 @@
+import { DynamicModule } from '@nestjs/common';
+import { AppLogClientConfig } from './interfaces/applog-config.interface';
+export declare class AppLogModule {
+    /**
+     * Register the app log client with static config.
+     *
+     * @example
+     * AppLogModule.register({
+     *   apiUrl: 'http://localhost:4000',
+     *   clientId: 'your-client-id',
+     *   clientSecret: 'your-client-secret',
+     * })
+     */
+    static register(config: AppLogClientConfig): DynamicModule;
+    /**
+     * Register the app log client with async config (e.g. from ConfigService).
+     *
+     * @example
+     * AppLogModule.registerAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config: ConfigService) => ({
+     *     apiUrl: config.get('MONITOR_API_URL'),
+     *     clientId: config.get('APPLOG_CLIENT_ID'),
+     *     clientSecret: config.get('APPLOG_CLIENT_SECRET'),
+     *   }),
+     * })
+     */
+    static registerAsync(options: {
+        inject?: any[];
+        useFactory: (...args: any[]) => AppLogClientConfig | Promise<AppLogClientConfig>;
+        imports?: any[];
+    }): DynamicModule;
+}

package/dist/applog.module.js

@@ -0,0 +1,71 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var AppLogModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppLogModule = void 0;
+const common_1 = require("@nestjs/common");
+const applog_config_interface_1 = require("./interfaces/applog-config.interface");
+const applog_nestjs_service_1 = require("./applog-nestjs.service");
+const applog_interceptor_1 = require("./applog.interceptor");
+let AppLogModule = AppLogModule_1 = class AppLogModule {
+    /**
+     * Register the app log client with static config.
+     *
+     * @example
+     * AppLogModule.register({
+     *   apiUrl: 'http://localhost:4000',
+     *   clientId: 'your-client-id',
+     *   clientSecret: 'your-client-secret',
+     * })
+     */
+    static register(config) {
+        return {
+            module: AppLogModule_1,
+            providers: [
+                { provide: applog_config_interface_1.APPLOG_CLIENT_CONFIG, useValue: config },
+                applog_nestjs_service_1.AppLogNestService,
+                applog_interceptor_1.AppLogInterceptor,
+            ],
+            exports: [applog_nestjs_service_1.AppLogNestService, applog_interceptor_1.AppLogInterceptor],
+        };
+    }
+    /**
+     * Register the app log client with async config (e.g. from ConfigService).
+     *
+     * @example
+     * AppLogModule.registerAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config: ConfigService) => ({
+     *     apiUrl: config.get('MONITOR_API_URL'),
+     *     clientId: config.get('APPLOG_CLIENT_ID'),
+     *     clientSecret: config.get('APPLOG_CLIENT_SECRET'),
+     *   }),
+     * })
+     */
+    static registerAsync(options) {
+        return {
+            module: AppLogModule_1,
+            imports: [...(options.imports || [])],
+            providers: [
+                {
+                    provide: applog_config_interface_1.APPLOG_CLIENT_CONFIG,
+                    inject: options.inject || [],
+                    useFactory: options.useFactory,
+                },
+                applog_nestjs_service_1.AppLogNestService,
+                applog_interceptor_1.AppLogInterceptor,
+            ],
+            exports: [applog_nestjs_service_1.AppLogNestService, applog_interceptor_1.AppLogInterceptor],
+        };
+    }
+};
+exports.AppLogModule = AppLogModule;
+exports.AppLogModule = AppLogModule = AppLogModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], AppLogModule);

package/dist/applog.service.d.ts

@@ -0,0 +1,55 @@
+import { AppLogClientConfig } from './interfaces/applog-config.interface';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface AppLogPayload {
+    level: LogLevel;
+    category: string;
+    action: string;
+    message?: string;
+    metadata?: Record<string, any>;
+    userId?: string;
+    duration?: number;
+    tags?: string[];
+    createdAt?: string;
+}
+export interface AppLogOptions {
+    message?: string;
+    metadata?: Record<string, any>;
+    userId?: string;
+    duration?: number;
+    tags?: string[];
+}
+export declare class AppLogClientService {
+    private readonly config;
+    private buffer;
+    private flushTimer;
+    private flushing;
+    private readonly authHeader;
+    private readonly batchSize;
+    private readonly maxBufferSize;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly defaultCategory?;
+    private readonly defaultTags;
+    private readonly log;
+    constructor(config: AppLogClientConfig);
+    debug(category: string, action: string, opts?: AppLogOptions): void;
+    info(category: string, action: string, opts?: AppLogOptions): void;
+    warn(category: string, action: string, opts?: AppLogOptions): void;
+    error(category: string, action: string, opts?: AppLogOptions): void;
+    fatal(category: string, action: string, opts?: AppLogOptions): void;
+    /**
+     * Start a timer. Returns a function that, when called, logs the action with the elapsed duration.
+     *
+     * @example
+     * const end = appLog.startTimer('payment', 'payment.charge', { userId: 'u1' });
+     * await processPayment();
+     * end(); // logs with duration automatically
+     */
+    startTimer(category: string, action: string, opts?: Omit<AppLogOptions, 'duration'>): (extra?: Partial<AppLogOptions>) => void;
+    push(log: AppLogPayload): void;
+    flush(): Promise<void>;
+    private sendWithRetry;
+    shutdown(): Promise<void>;
+    get bufferSize(): number;
+    getConfig(): AppLogClientConfig;
+}

package/dist/applog.service.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppLogClientService = void 0;
+// ─── Core Client ────────────────────────────────────────
+class AppLogClientService {
+    constructor(config) {
+        this.config = config;
+        this.buffer = [];
+        this.flushTimer = null;
+        this.flushing = false;
+        this.batchSize = config.batchSize ?? 50;
+        this.maxBufferSize = config.maxBufferSize ?? 1000;
+        this.timeout = config.timeout ?? 10000;
+        this.maxRetries = config.maxRetries ?? 3;
+        this.defaultCategory = config.defaultCategory;
+        this.defaultTags = config.defaultTags ?? [];
+        this.log = {
+            debug: config.logger?.debug ?? (() => { }),
+            warn: config.logger?.warn ?? console.warn.bind(console),
+            error: config.logger?.error ?? console.error.bind(console),
+        };
+        if (config.disabled) {
+            this.authHeader = '';
+            return;
+        }
+        this.authHeader =
+            'Basic ' + Buffer.from(`${config.clientId}:${config.clientSecret}`).toString('base64');
+        const interval = config.flushInterval ?? 5000;
+        this.flushTimer = setInterval(() => this.flush(), interval);
+    }
+    // ─── Convenience Methods ────────────────────────────────
+    debug(category, action, opts) {
+        this.push({ level: 'debug', category, action, ...opts });
+    }
+    info(category, action, opts) {
+        this.push({ level: 'info', category, action, ...opts });
+    }
+    warn(category, action, opts) {
+        this.push({ level: 'warn', category, action, ...opts });
+    }
+    error(category, action, opts) {
+        this.push({ level: 'error', category, action, ...opts });
+    }
+    fatal(category, action, opts) {
+        this.push({ level: 'fatal', category, action, ...opts });
+    }
+    // ─── Duration Tracking ─────────────────────────────────
+    /**
+     * Start a timer. Returns a function that, when called, logs the action with the elapsed duration.
+     *
+     * @example
+     * const end = appLog.startTimer('payment', 'payment.charge', { userId: 'u1' });
+     * await processPayment();
+     * end(); // logs with duration automatically
+     */
+    startTimer(category, action, opts) {
+        const start = Date.now();
+        return (extra) => {
+            const duration = Date.now() - start;
+            this.info(category, action, { ...opts, ...extra, duration });
+        };
+    }
+    // ─── Core Push ──────────────────────────────────────────
+    push(log) {
+        if (this.config.disabled)
+            return;
+        // Apply defaults
+        if (this.defaultCategory && !log.category) {
+            log.category = this.defaultCategory;
+        }
+        if (this.defaultTags.length > 0) {
+            log.tags = [...this.defaultTags, ...(log.tags ?? [])];
+        }
+        this.buffer.push(log);
+        // Enforce max buffer size — drop oldest
+        if (this.buffer.length > this.maxBufferSize) {
+            const dropped = this.buffer.length - this.maxBufferSize;
+            this.buffer = this.buffer.slice(dropped);
+            this.log.warn(`[AppLog] Buffer full, dropped ${dropped} oldest logs`);
+        }
+        if (this.buffer.length >= this.batchSize) {
+            this.flush().catch(() => { });
+        }
+    }
+    // ─── Flush ──────────────────────────────────────────────
+    async flush() {
+        if (this.buffer.length === 0 || this.flushing)
+            return;
+        if (!this.config.clientId || !this.config.clientSecret) {
+            this.log.warn('[AppLog] Credentials not configured, skipping flush');
+            return;
+        }
+        this.flushing = true;
+        const batch = this.buffer.splice(0, Math.min(this.buffer.length, 1000));
+        try {
+            await this.sendWithRetry(batch);
+            this.log.debug(`[AppLog] Flushed ${batch.length} logs`);
+        }
+        catch (err) {
+            this.log.error(`[AppLog] Failed to flush ${batch.length} logs after ${this.maxRetries} retries: ${err.message}`);
+            // Re-add failed batch if space available
+            const available = this.maxBufferSize - this.buffer.length;
+            if (available > 0) {
+                this.buffer.unshift(...batch.slice(0, available));
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    // ─── Retry Logic ────────────────────────────────────────
+    async sendWithRetry(batch, attempt = 1) {
+        try {
+            const res = await fetch(`${this.config.apiUrl}/api/app-logs/ingest`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: this.authHeader,
+                },
+                body: JSON.stringify({ logs: batch }),
+                signal: AbortSignal.timeout(this.timeout),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                throw new Error(`HTTP ${res.status}: ${body.slice(0, 200)}`);
+            }
+        }
+        catch (err) {
+            if (attempt < this.maxRetries) {
+                // Exponential backoff: 200ms, 400ms, 800ms...
+                const delay = 200 * Math.pow(2, attempt - 1);
+                await new Promise((r) => setTimeout(r, delay));
+                return this.sendWithRetry(batch, attempt + 1);
+            }
+            throw err;
+        }
+    }
+    // ─── Shutdown ───────────────────────────────────────────
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+    // ─── Stats ──────────────────────────────────────────────
+    get bufferSize() {
+        return this.buffer.length;
+    }
+    getConfig() {
+        return this.config;
+    }
+}
+exports.AppLogClientService = AppLogClientService;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AppLogClientService, AppLogPayload, AppLogOptions, LogLevel } from './applog.service';
+export { AppLogClientConfig, APPLOG_CLIENT_CONFIG } from './interfaces/applog-config.interface';
+export { createAppLogClient } from './standalone';
+export { AppLogModule } from './applog.module';
+export { AppLogNestService } from './applog-nestjs.service';
+export { AppLogInterceptor } from './applog.interceptor';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppLogInterceptor = exports.AppLogNestService = exports.AppLogModule = exports.createAppLogClient = exports.APPLOG_CLIENT_CONFIG = exports.AppLogClientService = void 0;
+// Core client (works anywhere)
+var applog_service_1 = require("./applog.service");
+Object.defineProperty(exports, "AppLogClientService", { enumerable: true, get: function () { return applog_service_1.AppLogClientService; } });
+var applog_config_interface_1 = require("./interfaces/applog-config.interface");
+Object.defineProperty(exports, "APPLOG_CLIENT_CONFIG", { enumerable: true, get: function () { return applog_config_interface_1.APPLOG_CLIENT_CONFIG; } });
+var standalone_1 = require("./standalone");
+Object.defineProperty(exports, "createAppLogClient", { enumerable: true, get: function () { return standalone_1.createAppLogClient; } });
+// NestJS integration
+var applog_module_1 = require("./applog.module");
+Object.defineProperty(exports, "AppLogModule", { enumerable: true, get: function () { return applog_module_1.AppLogModule; } });
+var applog_nestjs_service_1 = require("./applog-nestjs.service");
+Object.defineProperty(exports, "AppLogNestService", { enumerable: true, get: function () { return applog_nestjs_service_1.AppLogNestService; } });
+var applog_interceptor_1 = require("./applog.interceptor");
+Object.defineProperty(exports, "AppLogInterceptor", { enumerable: true, get: function () { return applog_interceptor_1.AppLogInterceptor; } });

package/dist/interfaces/applog-config.interface.d.ts

@@ -0,0 +1,31 @@
+export interface AppLogClientConfig {
+    /** The monitoring API base URL (e.g. http://localhost:4000) */
+    apiUrl: string;
+    /** Client ID from the monitoring environment credentials */
+    clientId: string;
+    /** Client Secret from the monitoring environment credentials */
+    clientSecret: string;
+    /** Batch size before auto-flushing (default: 50) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Max buffer size to prevent memory leaks (default: 1000) */
+    maxBufferSize?: number;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
+    /** Max retry attempts on failure (default: 3) */
+    maxRetries?: number;
+    /** Default category for logs (optional) */
+    defaultCategory?: string;
+    /** Default tags added to every log (optional) */
+    defaultTags?: string[];
+    /** Disable all logging when true */
+    disabled?: boolean;
+    /** Custom logger for internal messages (default: console) */
+    logger?: {
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}
+export declare const APPLOG_CLIENT_CONFIG = "APPLOG_CLIENT_CONFIG";

package/dist/interfaces/applog-config.interface.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLOG_CLIENT_CONFIG = void 0;
+exports.APPLOG_CLIENT_CONFIG = 'APPLOG_CLIENT_CONFIG';

package/dist/standalone.d.ts

@@ -0,0 +1,19 @@
+import { AppLogClientConfig } from './interfaces/applog-config.interface';
+import { AppLogClientService } from './applog.service';
+/**
+ * Create a standalone AppLog client (no NestJS required).
+ * Works in any Node.js application, Express, Fastify, etc.
+ *
+ * @example
+ * const appLog = createAppLogClient({
+ *   apiUrl: 'https://monitor.example.com',
+ *   clientId: process.env.MONITOR_CLIENT_ID,
+ *   clientSecret: process.env.MONITOR_CLIENT_SECRET,
+ * });
+ *
+ * appLog.info('auth', 'user.login', { userId: 'u1', message: 'Logged in' });
+ *
+ * // On app shutdown:
+ * await appLog.shutdown();
+ */
+export declare function createAppLogClient(config: AppLogClientConfig): AppLogClientService;

package/dist/standalone.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAppLogClient = createAppLogClient;
+const applog_service_1 = require("./applog.service");
+/**
+ * Create a standalone AppLog client (no NestJS required).
+ * Works in any Node.js application, Express, Fastify, etc.
+ *
+ * @example
+ * const appLog = createAppLogClient({
+ *   apiUrl: 'https://monitor.example.com',
+ *   clientId: process.env.MONITOR_CLIENT_ID,
+ *   clientSecret: process.env.MONITOR_CLIENT_SECRET,
+ * });
+ *
+ * appLog.info('auth', 'user.login', { userId: 'u1', message: 'Logged in' });
+ *
+ * // On app shutdown:
+ * await appLog.shutdown();
+ */
+function createAppLogClient(config) {
+    return new applog_service_1.AppLogClientService(config);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@devminister/applog-client",
+  "version": "0.0.1",
+  "description": "Application log client for the Monitoring platform. Buffered, batched delivery with retry. Works standalone or as a NestJS module.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "nestjs",
+    "logging",
+    "monitoring",
+    "application-logs",
+    "observability",
+    "audit-trail",
+    "structured-logging"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "rxjs": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": { "optional": true },
+    "@nestjs/core": { "optional": true },
+    "rxjs": { "optional": true }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.3",
+    "@nestjs/core": "^11.1.3",
+    "@types/node": "^24.0.0",
+    "rxjs": "^7.8.2",
+    "typescript": "^5.8.3"
+  }
+}